实现了 api 支持

ColdeZhang · Sep 23, 2024 · a350e01 · a350e01
1 parent 5bdd15f
commit a350e01
Show file tree

Hide file tree

Showing 24 changed files with 523 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -36,6 +36,11 @@ For detail functions and features of Dominion, you can view [Introduction](intro
 > Although this plugin supports Spigot, we strongly recommend that you upgrade your core to Paper or its forked (such as
 > Purpur) for a better performance experience.
 
+## For developer
+
+Dominion provides some simple (for now) APIs for developers to build something amazing depends on Dominion. You can
+take a look at [Developer](docs/en-us/developer.md) for more details.
+
 ## Help us improve
 
 If you encounter any problems during use or have any suggestions, please feel free to open

diff --git a/README_zh.md b/README_zh.md
@@ -42,6 +42,11 @@ Dominion 是一个完全开源、免费，专为高版本开发，面向未来
 
 交流QQ群：309428300
 
+## 开发者指南
+
+Dominion 提供了一些简单（只是暂时，后续会逐步增强api）的 API 供开发者基于 Dominion
+构建一些更有趣的东西。您可以查看 [开发者指南](docs/zh-cn/developer.md) 了解更多细节。
+
 ## 整个烂活儿
 
 |         | Dominion | R插件 | G插件 |

diff --git a/api/build.gradle.kts b/api/build.gradle.kts
@@ -1,5 +1,6 @@
 plugins {
     id("java")
+    id("maven-publish")
 }
 
 java {
@@ -14,3 +15,28 @@ tasks.withType<JavaCompile> {
 dependencies {
     compileOnly("io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT")
 }
+
+tasks.jar {
+    archiveClassifier.set("sources")
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("mavenJava") {
+            groupId = "cn.lunadeer"
+            artifactId = "DominionAPI"
+            version = "1.5-SNAPSHOT"
+            from(components["java"])
+        }
+    }
+    repositories {
+        maven {
+            url = uri("https://ssl.lunadeer.cn:14454/repository/maven-snapshots/")
+            credentials {
+                // from m2 settings.xml
+                username = project.findProperty("nexusUsername")?.toString()
+                password = project.findProperty("nexusPassword")?.toString()
+            }
+        }
+    }
+}
diff --git a/api/src/main/java/cn/lunadeer/dominion/api/Dominion.java b/api/src/main/java/cn/lunadeer/dominion/api/Dominion.java
@@ -1,9 +1,19 @@
 package cn.lunadeer.dominion.api;
 
-public interface Dominion {
+import org.bukkit.Bukkit;
 
-    static Cache getInstance() throws ClassNotFoundException, NoSuchFieldException, IllegalAccessException {
-        // Cache.instance is a static field in the Cache class
-        return (Cache) Class.forName("cn.lunadeer.dominion.Cache").getDeclaredField("instance").get(null);
+public class Dominion {
+
+    public static DominionAPI getInstance() throws ClassNotFoundException, NoSuchFieldException, IllegalAccessException {
+        // 通过反射获取 Cache 类中的 instance 字段
+        var instanceField = Class.forName("cn.lunadeer.dominion.Cache").getDeclaredField("instance");
+        // 设置可访问
+        instanceField.setAccessible(true);
+        // 返回 Cache 的实例
+        return (DominionAPI) instanceField.get(null);
+    }
+
+    public static boolean isDominionEnabled() {
+        return Bukkit.getPluginManager().isPluginEnabled("Dominion");
     }
 }
diff --git a/.../java/cn/lunadeer/dominion/api/Cache.java → ...cn/lunadeer/dominion/api/DominionAPI.java b/.../java/cn/lunadeer/dominion/api/Cache.java → ...cn/lunadeer/dominion/api/DominionAPI.java
@@ -8,9 +8,18 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.List;
 import java.util.UUID;
 
-public interface Cache {
+public interface DominionAPI {
+
+    /**
+     * 获取所有领地信息
+     *
+     * @return 所有领地信息
+     */
+    @NotNull List<DominionDTO> getAllDominions();
+
     /**
      * 获取玩家当前所在领地
      *

diff --git a/api/src/main/java/cn/lunadeer/dominion/api/dtos/DominionDTO.java b/api/src/main/java/cn/lunadeer/dominion/api/dtos/DominionDTO.java
@@ -7,15 +7,39 @@
 import java.util.UUID;
 
 public interface DominionDTO {
-    // getters and setters
+    /**
+     * 获取领地 ID
+     *
+     * @return 领地 ID
+     */
     Integer getId();
 
+    /**
+     * 获取领地所有者 UUID
+     *
+     * @return 领地所有者 UUID
+     */
     UUID getOwner();
 
+    /**
+     * 获取领地名称
+     *
+     * @return 领地名称
+     */
     String getName();
 
+    /**
+     * 获取领地所在世界
+     *
+     * @return 领地所在世界  如果世界不存在，则返回null
+     */
     @Nullable World getWorld();
 
+    /**
+     * 获取领地所在世界 UUID
+     *
+     * @return 领地所在世界 UUID
+     */
     UUID getWorldUid();
 
     Integer getX1();
@@ -30,25 +54,66 @@ public interface DominionDTO {
 
     Integer getZ2();
 
+    /**
+     * 获取领地面积
+     *
+     * @return 领地面积
+     */
     Integer getSquare();
 
+    /**
+     * 获取领地体积
+     *
+     * @return 领地体积
+     */
     Integer getVolume();
 
+    /**
+     * 获取领地X轴向（东西向）宽度
+     *
+     * @return 领地X轴向（东西向）宽度
+     */
     Integer getWidthX();
 
+    /**
+     * 获取领地Y轴向（上下向）高度
+     *
+     * @return 领地Y轴向（上下向）高度
+     */
     Integer getHeight();
 
+    /**
+     * 获取领地Z轴向（南北向）宽度
+     *
+     * @return 领地Z轴向（南北向）宽度
+     */
     Integer getWidthZ();
 
+    /**
+     * 获取父领地 ID
+     *
+     * @return 父领地 ID  如果没有父领地，则返回 -1
+     */
     Integer getParentDomId();
 
     String getJoinMessage();
 
     String getLeaveMessage();
 
+    /**
+     * 获取领地某个权限的值
+     *
+     * @param flag 权限
+     * @return 权限值
+     */
     Boolean getFlagValue(Flag flag);
 
-    Location getTpLocation();
+    /**
+     * 获取领地传送点坐标
+     *
+     * @return 领地传送点坐标  如果没有设置传送点，则返回null
+     */
+    @Nullable Location getTpLocation();
 
     Location getLocation1();
 

diff --git a/api/src/main/java/cn/lunadeer/dominion/api/dtos/Flag.java b/api/src/main/java/cn/lunadeer/dominion/api/dtos/Flag.java
@@ -1,13 +1,40 @@
 package cn.lunadeer.dominion.api.dtos;
 
 public interface Flag {
+    /**
+     * 权限名称（英文）
+     *
+     * @return 权限名称
+     */
     String getFlagName();
 
+    /**
+     * 权限显示名称（中文）
+     * 该名称从languages文件中加载
+     *
+     * @return 权限显示名称
+     */
     String getDisplayName();
 
+    /**
+     * 权限描述
+     * 该描述从languages文件中加载
+     *
+     * @return 权限描述
+     */
     String getDescription();
 
+    /**
+     * 获取权限默认值
+     *
+     * @return 权限默认值
+     */
     Boolean getDefaultValue();
 
+    /**
+     * 获取权限是否启用
+     *
+     * @return 权限是否启用
+     */
     Boolean getEnable();
 }
diff --git a/api/src/main/java/cn/lunadeer/dominion/api/dtos/GroupDTO.java b/api/src/main/java/cn/lunadeer/dominion/api/dtos/GroupDTO.java
@@ -3,17 +3,53 @@
 import net.kyori.adventure.text.Component;
 
 public interface GroupDTO {
+    /**
+     * 获取权限组 ID
+     *
+     * @return 权限组 ID
+     */
     Integer getId();
 
+    /**
+     * 获取权限组所属领地 ID
+     *
+     * @return 权限组所属领地 ID
+     */
     Integer getDomID();
 
+    /**
+     * 获取权限组名称
+     *
+     * @return 权限组名称
+     */
     String getName();
 
+    /**
+     * 获取权限组名称（带颜色） kyori.adventure.text.Component
+     *
+     * @return 权限组名称（带颜色）
+     */
     Component getNameColoredComponent();
 
+    /**
+     * 获取权限组名称（带颜色） Bukkit
+     *
+     * @return 权限组名称（带颜色）
+     */
     String getNameColoredBukkit();
 
+    /**
+     * 获取权限组是否为管理员组
+     *
+     * @return 是否为管理员组
+     */
     Boolean getAdmin();
 
+    /**
+     * 获取权限组某个权限配置
+     *
+     * @param flag 权限
+     * @return 权限配置值
+     */
     Boolean getFlagValue(Flag flag);
 }
diff --git a/api/src/main/java/cn/lunadeer/dominion/api/dtos/MemberDTO.java b/api/src/main/java/cn/lunadeer/dominion/api/dtos/MemberDTO.java
@@ -3,15 +3,46 @@
 import java.util.UUID;
 
 public interface MemberDTO {
+    /**
+     * 获取成员 ID
+     *
+     * @return 成员 ID
+     */
     Integer getId();
 
+    /**
+     * 获取成员 UUID
+     *
+     * @return 成员 UUID
+     */
     UUID getPlayerUUID();
 
+    /**
+     * 成员是否为管理员
+     *
+     * @return 是否为管理员
+     */
     Boolean getAdmin();
 
+    /**
+     * 获取成员所属领地 ID
+     *
+     * @return 领地 ID
+     */
     Integer getDomID();
 
+    /**
+     * 获取成员所属权限组 ID
+     *
+     * @return 权限组 ID 如果成员不属于任何权限组，则返回-1
+     */
     Integer getGroupId();
 
+    /**
+     * 获取成员某个权限配置
+     *
+     * @param flag 权限
+     * @return 权限配置值
+     */
     Boolean getFlagValue(Flag flag);
 }
diff --git a/api/src/main/java/cn/lunadeer/dominion/api/dtos/PrivilegeTemplateDTO.java b/api/src/main/java/cn/lunadeer/dominion/api/dtos/PrivilegeTemplateDTO.java
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "cn.lunadeer"
-version = "2.8.2-beta"
+version = "2.9.0-beta"
 
 java {
     toolchain.languageVersion.set(JavaLanguageVersion.of(21))