NexusCore — Fabric 服务端基础插件套件
====================================
适用版本：Minecraft Java 26.3-snapshot-9（及后续 26.3 正式版，通常只需改版本号）
加载器：Fabric Loader 0.19.3+
依赖：Fabric API 0.158.0+26.3（必须安装）
编译：Gradle 9.5.1 + Java 25


一、安装（开服即用）
--------------------
1. 安装 Java 25，下载对应版本的 Fabric 服务端（minecraft 选 26.3-snapshot-9）。
2. 把 fabric-api-*.jar 放进服务器 mods 文件夹。
3. 把编译得到的 nexuscore-*.jar 也放进 mods。
4. 启动服务端。首次启动会在：

     <服务端目录>/mods/nexuscore/

   自动生成全部分类配置和数据文件。默认已经按「生存服可直接玩」规划好：
     普通玩家：出生点 / 家 / TPA / 回城 / 随机传送 / 经济 / 聊天 / 新手礼包 / 领地 / 规则
     OP：上述全部 + 管理模式、封禁、传送点、公告、权限组等

5. 进游戏用 OP 账号执行 /setspawn，再按需改配置即可。


二、从源码编译
--------------
要求：JDK 25、能访问 maven.fabricmc.net 与 Mojang 资源。

    cd nexuscore
    ./gradlew build

产物：build/libs/nexuscore-1.0.0+26.3-snapshot-9.jar
不要用 -sources 或 -dev 那个。

Windows：gradlew.bat build
本仓库已锁定 Gradle Wrapper 9.5.1。


三、配置目录结构（全部在 mods/nexuscore/）
------------------------------------------
core/            语言、总开关
permissions/     权限组 groups.toml + 玩家数据 users.json
economy/         经济 + balances.json
teleport/        传送冷却、TPA、RTP
homes/           家上限 + data.json
warps/           传送点
spawn/           出生点与出生点保护
kits/            礼包
chat/            聊天格式、屏蔽词、禁言数据
moderation/      封禁/警告
player/          飞行/无敌/seen
world/           时间天气
protection/      领地 claims.json
announcements/   自动公告
afk/             挂机
motd/            进服提示、Tab、规则
logging/         聊天/命令/经济日志

修改 *.toml 后执行 /nexuscore reload。
缺省文件只会在「不存在」时生成，不会覆盖你改过的配置。


四、常用命令
------------
玩家：
  /spawn  /sethome [名]  /home [名]  /homes  /delhome <名>
  /tpa <玩家>  /tpahere <玩家>  /tpaccept  /tpdeny  /back  /rtp
  /warp <名>  /warps
  /balance  /pay <玩家> <金额>  /baltop
  /kit starter  /kits
  /claim  /unclaim  /trust  /untrust  /claiminfo
  /msg  /r  /rules  /afk  /list

管理（默认 OP 全权限）：
  /setspawn  /setwarp  /delwarp  /tp  /tphere
  /gamemode  /gmc /gms  /fly  /god  /heal  /feed  /speed
  /kick  /ban  /tempban  /unban  /mute  /unmute  /warn  /vanish  /freeze  /invsee
  /eco give|take|set  /perm user <玩家> group <组>
  /broadcast  /nexuscore reload


五、扩展接口（给其他 Fabric 模组）
----------------------------------
1. 依赖本模组（compileOnly 即可）。

2. 代码调用：

     NexusAPI api = NexusAPI.get();
     api.economy().deposit(uuid, 100, "quest");
     api.permissions().has(player, "my.mod.node");
     api.homes().get(uuid, "home");
     api.teleport().teleport(player, loc, "my-mod");
     api.protection().canBuild(player, level, pos);

3. 联动入口 fabric.mod.json：

     "entrypoints": {
       "nexuscore:addon": ["com.example.MyAddon"]
     }

   MyAddon 实现 dev.nexuscore.api.addon.NexusAddon
   在 onNexusReady(NexusAPI) 里订阅服务。

4. 事件钩子：

     NexusHooks.INSTANCE.onBalanceChanged((id, bal) -> {});
     NexusHooks.INSTANCE.beforeTeleport((p, from, to, cause) -> true);
     NexusHooks.INSTANCE.onChat((p, raw, rewrite) -> true);
     NexusHooks.INSTANCE.onClaim((p, action, loc) -> {});

公开包：dev.nexuscore.api.*  视为稳定面。core/modules 为内部实现。


六、26.3 正式版怎么跟
----------------------
1. 改 gradle.properties：
     minecraft_version=26.3
     fabric_api_version=<fabricmc.net/develop 上对应版本>
2. 依赖范围已写 "minecraft": ">=26.3-alpha.9"，正式版一般不用改 fabric.mod.json。
3. 与版本相关的传送、物品注册、伤害调用集中在：
     dev.nexuscore.core.mc.Players
     以及少数模块里的原版方法
   官方映射（Mojmap）+ Fabric API，避免 Yarn 中间名大改。


七、权限节点（摘录）
--------------------
nexuscore.command.<命令名>     例如 nexuscore.command.home
nexuscore.command.*            全部命令
nexuscore.kit.vip              VIP 礼包
nexuscore.chat.color           聊天颜色
nexuscore.protection.bypass    忽略领地
*                              全部（admin 组默认拥有）

组元数据（groups.toml 的 meta）：
  homes / claims / claim-radius


八、故障
--------
- 模组不加载：确认 Fabric API 版本对应 26.3，Java 是 25。
- 配置没生成：看日志是否有 NexusCore 正在初始化；目录在 mods/nexuscore 而不是 config/。
- 命令没权限：默认组已给生存命令；管理命令需要 OP 或 admin 组。
- 编译失败：必须用 Java 25（java -version），不要用 17/21。
