API 概览
Suite axs-api 模块介绍、接口分层与版本管理。
API 概览
Suite 提供 axs-api 模块作为第三方开发的稳定接口层。所有公开 API 均位于 xuanmo.arcartxsuite.api 包下,第三方模块只需 compileOnly 依赖 axs-api 即可开发自定义模块。
架构分层
模块通过 ModuleContext 获取基础设施能力,禁止直接引用宿主实现类(xuanmo.arcartxsuite.bridge.* 等),否则混淆后可能无法加载。
API 稳定性标记
所有公开接口使用 @ApiStability 注解标记稳定性级别:
| 注解 | 含义 |
|---|---|
@ApiStability.Stable | 稳定 API,向后兼容,不会在小版本中破坏 |
@ApiStability.Experimental | 实验性 API,可能在未来版本中修改或移除 |
@ApiStability.Internal | 内部 API,仅供 Suite 内部模块使用,第三方不应依赖 |
@ApiStability.ScheduledForRemoval | 已弃用 API,将在下一个大版本中移除 |
API 总览
| 类 / 接口 | 包路径 | 说明 |
|---|---|---|
AXSModule | api | 模块生命周期接口 |
AbstractAXSModule | api | 模块抽象基类,封装声明式生命周期 |
ModuleContext | api | 宿主提供给模块的上下文接口 |
ModuleDescriptor | api | 模块元数据描述符 |
ModuleCommandHandler | api | 模块命令处理接口 |
PacketBridgeAPI | api.bridge | UI/Packet 桥接 API |
ClientBridgeAPI | api.bridge | 客户端桥接 API |
ItemBridgeAPI | api.bridge | ItemStack 序列化 API |
PropBridgeAPI | api.bridge | Prop/按键绑定桥接 API |
WaypointBridgeAPI | api.bridge | 路标桥接 API |
AdyeshachNpcBridgeAPI | api.bridge | Adyeshach NPC 桥接 API |
WorldTextureBridgeAPI | api.bridge | 世界文字贴图桥接 API |
SoundPlayerBridgeAPI | api.bridge | 音效播放器桥接 API |
VanillaItemNameBridge | api.bridge | 原版物品中文名称解析 |
ContentModerator | api.bridge | 内容审核(敏感词过滤) |
NavigationTarget / NavigationTargetService | api.util | 共享导航目标编排:diff 推送、到达滞回判定、命令钩子、跨世界抑制、单路标单路线(Map/QuestGPS 使用) |
NavigationMarkerService / NavigationMarkerConfig | api.util | Adyeshach 私有实体路径标记链(按 navKey 多组状态、距离滞回) |
| Capability 接口 | api.capability | 跨模块能力通信 |
ModuleLifecycleEvent | api.event | 模块生命周期 Bukkit 事件 |
TaczGunDamageEvent | api.event | TACZ 枪械伤害事件 |
TaczGunKillEvent | api.event | TACZ 枪械击杀事件 |
MessageProvider | api.message | 消息外部化 / i18n |
CrossServerAPI | api.crossserver | 统一跨服 SDK |
快速开始
版本管理
axs-api 采用语义化版本。module.yml 中的 api-version 字段声明模块所依赖的 API 大版本。宿主在加载模块时会检查兼容性。
| API 版本 | 关键变更 |
|---|---|
| 1.0 | 基础架构:AXSModule、ModuleContext、ModuleRegistry |
| 1.1 | Bridge API 接口化(PacketBridgeAPI、ClientBridgeAPI、ItemBridgeAPI) |
| 1.2 | Prop/Waypoint/Adyeshach/WorldTexture 桥接;跨服 API |
| 1.3 | SoundPlayer 桥接;VanillaItemNameBridge;ContentModerator |
| 1.5 | ModuleContext 按 ISP 拆分为子接口;ModuleConfig/ModuleUiSpec 声明式规约 |
| 1.6 | SchedulerAPI 统一调度 |