API 接口
基本信息
| 属性 | 值 |
|---|---|
| 主包 | serverutils（modGroup = serverutils，gradle.properties:14） |
| 子包 | events、api 门面分散在 lib.data、lib.util.permission、lib.config、lib.net、net |
| 源码文件 | 608 个 .java（git ls-files | grep -c '\.java$'） |
| 语言 | 纯 Java 608 个，.scala 0 个、.kt 0 个 |
| 字节码目标 | Java 8（enableModernJavaSyntax = jabel，gradle.properties） |
| 扩展方式 | 6 个注册表 + 8 个事件钩子 |
本模组不提供 apiPackage（gradle.properties 中 apiPackage = 为空），没有官方划定的 API 边界。以下按「静态门面类」整理实际可从外部调用的入口。
1. ServerUtilitiesRegistry — 6 个注册表
src/main/java/serverutils/ServerUtilitiesRegistry.java:65-95 是模组的中心注册点，持有 5 个公开集合与 6 个注册方法：
| 集合 | 类型 | 注册方法 | 用途 |
|---|---|---|---|
RELOAD_IDS |
Map<ResourceLocation, IReloadHandler> |
registerServerReloadHandler(id, handler)（:81） |
参与 /reload |
TEAM_GUI_ACTIONS |
Map<ResourceLocation, TeamAction> |
registerTeamAction(action)（:89） |
队伍 GUI 按钮 |
ADMIN_PANEL_ACTIONS |
Map<ResourceLocation, AdminPanelAction> |
registerAdminPanelAction(action)（:85） |
管理面板按钮 |
CONFIG_VALUE_PROVIDERS |
Map<String, ConfigValueProvider> |
registerConfigValueProvider(id, provider)（:73） |
自定义配置值来源 |
SYNCED_DATA |
Map<String, ISyncData> |
registerSyncData(mod, data)（:77） |
客户端同步数据 |
| — | — | registerInvseeInventory(inventory)（:94） |
直接转发到 InvSeeRegistry |
TeamAction 与 AdminPanelAction 都有 getType(ForgePlayer, NBTTagCompound) 与 onAction(ForgePlayer, NBTTagCompound) 两个方法（:152-157、:183-188、:242-247 等），由内建实现分别提供。
2. PermissionAPI — 权限门面
src/main/java/serverutils/lib/util/permission/PermissionAPI.java，5 个静态方法：
| 方法 | 行 | 说明 |
|---|---|---|
setPermissionHandler(IPermissionHandler) |
23 | 替换整个处理器（本模组自身安装 ServerUtilitiesPermissionHandler.INSTANCE） |
getPermissionHandler() |
32 | 取当前处理器 |
registerNode(node, level, desc) |
44 | 注册权限节点，返回节点串 |
hasPermission(GameProfile, node, IContext) |
63 | 带上下文判定 |
hasPermission(EntityPlayer, node) |
75 | 便捷重载 |
配套接口与实现：
| 类型 | 路径 |
|---|---|
IPermissionHandler |
lib/util/permission/IPermissionHandler.java |
DefaultPermissionHandler |
lib/util/permission/DefaultPermissionHandler.java（enum 单例 INSTANCE） |
DefaultPermissionLevel |
lib/util/permission/DefaultPermissionLevel.java（ALL / OP / NONE） |
| 上下文 | lib/util/permission/context/：IContext、Context、ContextKey、ContextKeys、AreaContext、BlockPosContext、PlayerContext、TargetContext、WorldContext |
3. ServerUtilitiesAPI — 运行时门面
src/main/java/serverutils/lib/data/ServerUtilitiesAPI.java，10 个静态方法：
| 方法 | 行 | 说明 |
|---|---|---|
reloadServer(universe, sender, type, id) |
36 | 驱动 /reload，遍历 RELOAD_IDS |
editServerConfig(player, group, callback) |
104 | 打开配置编辑 GUI |
createConfigValueFromId(id) |
110 | 从字符串 id 构造 ConfigValue |
sendCloseGuiPacket(player) |
121 | 通知客户端关闭 GUI |
arePlayersInSameTeam(uuid1, uuid2) |
128 | 同队判定 |
isPlayerInTeam(uuid, String team) |
145 | 按队伍 ID |
isPlayerInTeam(uuid, int team) |
159 | 按队伍数字 ID |
getTeam(uuid) |
173 | 返回队伍 ID 串 |
getTeamID(uuid) |
182 | 返回 short 型队伍 ID |
reload(MinecraftServer) |
191 | 无参重载，遍历全部 handler |
4. RankConfigAPI — rank 值门面
src/main/java/serverutils/lib/config/RankConfigAPI.java，4 个静态方法：
| 方法 | 行 | 说明 |
|---|---|---|
getHandler() |
25 | 取 IRankConfigHandler |
get(MinecraftServer, GameProfile, node) |
36 | 按 profile 取值 |
get(EntityPlayerMP, node) |
42 | 按玩家取值 |
getConfigValue(node, boolean op) |
48 | 不指定玩家，取 OP/普通玩家默认 |
配套：IRankConfigHandler、RankConfigValueInfo、DefaultRankConfigHandler、RankConfigAPI、ConfigValue 及其 15 个实现类型（ConfigBoolean、ConfigInt、ConfigLong、ConfigDouble、ConfigString、ConfigEnum、ConfigStringEnum、ConfigList、ConfigGroup、ConfigColor、ConfigRGB、ConfigFluid、ConfigItemStack、ConfigNBT、ConfigTextComponent、ConfigTeam、ConfigTeamClient、ConfigTimer、ConfigNull）。
5. InvSeeRegistry — invsee 背包注册
src/main/java/serverutils/invsee/inventories/InvSeeRegistry.java，标注 @ApiStatus.AvailableSince("2.4.0")：
| 方法 | 行 | 说明 |
|---|---|---|
registerInventory(IModdedInventory) |
48 | 追加一个可查看背包 |
getRegisteredInventories() |
52 | 取全部 |
getMainInventory() |
56 | 取 index 0 强制转 IModdedInventory |
详见 Invsee 背包查看。
6. NetworkWrapper — 自建封包通道
src/main/java/serverutils/lib/net/NetworkWrapper.java 基于 FML 的 SimpleNetworkWrapper：
| 方法 | 行 | 说明 |
|---|---|---|
NetworkWrapper.newWrapper(String id) |
25 | 按 id 建通道（内部 FMLEmbeddedChannel） |
register(MessageToClient) |
41 | 注册 S2C |
register(MessageToServer) |
53 | 注册 C2S |
registerBlank() |
37 | 注册一个不处理任何消息的占位封包 |
MessageBase（lib/net/MessageBase.java）是所有封包的基类，实现 IMessage，把 toBytes/fromBytes 转发到自定义的 writeData(DataOut) / readData(DataIn)。
本模组建了 6 条通道（net/ServerUtilitiesNetHandler.java:6-11）：
| 常量 | 通道 id | 封包数 |
|---|---|---|
GENERAL |
serverutilities |
17 |
CLAIMS |
utilities_claim |
7 |
FILES |
utilities_files |
9 |
EDIT_CONFIG |
utilities_config |
2 |
STATS |
utilities_stats |
4 |
MY_TEAM |
utilities_my_team |
5 |
合计 44 个封包，45 次注册调用（GENERAL 通道多一次 registerBlank() 占位注册）。这与 net/ 目录下 extends MessageToClient|MessageToServer 的 44 个类一一对应。详见 封包与同步。
7. 排行榜注册
ServerUtilitiesLeaderboards.registerLeaderboard(Leaderboard)（ServerUtilitiesLeaderboards.java:213-219）是 public static，外部模组可直接调用或改用 LeaderboardRegistryEvent。每次注册自动附带一个 ALL 权限节点。
4 个内置排行榜（ServerUtilitiesLeaderboards.java:37-79）：
| id | 排序依据 | 过滤条件 |
|---|---|---|
serverutilities:deaths_per_hour |
死亡数 / 游戏小时 | 游戏时长 ≥ 1 小时，否则显示 - |
serverutilities:time_active |
游戏时长 − AFK 时长 | 有效时长 ≠ 0 |
serverutilities:time_afk_percent |
AFK / 游戏时长 | ≠ 0 |
serverutilities:last_seen |
相对最后在线时间 | getLastTimeSeen() != 0；在线者显示绿色「在线」 |
另有从 config/serverutilities/server/stat_leaderboards.json 加载的统计排行榜，默认种子包含 minecraft.deaths、minecraft.kill_mob、minecraft.play_one_minute、serverutilities.afk_time、minecraft.jump（DEFAULT_STAT_LEADERBOARDS，ServerUtilitiesLeaderboards.java:30-32）。
8. 统计数据
ServerUtilitiesStats.AFK_TIME（ServerUtilitiesStats.java:11-15）是本模组注册的唯一自定义统计项，类型 StatBasic，是 AFK 计时与两个时间排行榜的数据源。init()（:17）负责注册。
9. 配置文件扩展
| 类 | 用途 |
|---|---|
ServerUtilitiesConfig |
主配置，GTNHLib @Config 驱动 |
AuroraConfig |
Aurora Web 服务器配置，@Config.ExcludeFromAutoGui |
ServerUtilitiesClientConfig |
客户端配置 |
三者都在 core/ServerUtilitiesCore 的静态初始化块中注册（ServerUtilitiesCore.java:22-26）—— 即在 FML 最早的 coremod 阶段，而非 mod 构造阶段：
static {
removeBrigadierExceptions();
ConfigurationManager.registerConfig(ServerUtilitiesConfig.class);
ConfigurationManager.registerConfig(AuroraConfig.class);
}
10. 第三方扩展点
| 扩展点 | 入口 | 关联条目 |
|---|---|---|
| 事件钩子（8 个） | MinecraftForge.EVENT_BUS |
事件 API |
| 权限处理器替换 | PermissionAPI.setPermissionHandler |
权限节点 |
| rank 处理器替换 | RegisterRankConfigHandlerEvent.setHandler |
事件 API |
| 物品 / 设备 API | 见 InvSeeRegistry |
Invsee |
无 API 边界
gradle.properties 中 apiPackage = 为空，apiPackage 的注释写明「In case your mod provides an API for other mods to implement you may declare its package here. Otherwise, you can leave this property empty.」（gradle.properties）—— 本模组没有声明正式 API 包。
同时 InvSeeRegistry 用 @ApiStatus.AvailableSince("2.4.0") 标注了版本可见性，而 ServerUtilitiesPermissions 里的 public static final Collection<NodeEntry> CUSTOM_PERM_PREFIX（:39）、earlyPermissions（:41）与 4 个白/黑名单 Set（:81-83）均为 public 可变集合，外部模组可直接改写。
相关条目
- 事件 API - 37 个事件类与 8 个扩展点
- 封包与同步 - 6 条通道的 46 个封包
- 权限节点 -
PermissionAPI管理的节点体系 - Invsee 背包查看 -
InvSeeRegistry的内置实现