Suite

API 概览

Suite axs-api 模块介绍、接口分层与版本管理。

API 概览

Suite 提供 axs-api 模块作为第三方开发的稳定接口层。所有公开 API 均位于 xuanmo.arcartxsuite.api 包下,第三方模块只需 compileOnly 依赖 axs-api 即可开发自定义模块。

架构分层

axs-api/  (接口层 — 模块唯一可见)
  ├── AXSModule          模块生命周期接口
  ├── AbstractAXSModule   模块抽象基类(声明式生命周期)
  ├── ModuleContext       宿主暴露给模块的上下文
  ├── ModuleDescriptor    模块元数据描述符
  ├── bridge/             桥接 API(UI/Packet/Item/Prop 等)
  ├── capability/         跨模块能力通信接口
  ├── event/              Bukkit 事件类
  ├── message/            消息外部化(MessageProvider)
  ├── crossserver/        跨服 API
  ├── config/             配置诊断规约
  ├── storage/            存储层
  ├── command/            模块命令处理
  └── ...                 其他子包
axs-core/  (宿主实现 — 模块不可见,可安全混淆)

模块通过 ModuleContext 获取基础设施能力,禁止直接引用宿主实现类(xuanmo.arcartxsuite.bridge.* 等),否则混淆后可能无法加载。

API 稳定性标记

所有公开接口使用 @ApiStability 注解标记稳定性级别:

注解含义
@ApiStability.Stable稳定 API,向后兼容,不会在小版本中破坏
@ApiStability.Experimental实验性 API,可能在未来版本中修改或移除
@ApiStability.Internal内部 API,仅供 Suite 内部模块使用,第三方不应依赖
@ApiStability.ScheduledForRemoval已弃用 API,将在下一个大版本中移除

API 总览

类 / 接口包路径说明
AXSModuleapi模块生命周期接口
AbstractAXSModuleapi模块抽象基类,封装声明式生命周期
ModuleContextapi宿主提供给模块的上下文接口
ModuleDescriptorapi模块元数据描述符
ModuleCommandHandlerapi模块命令处理接口
PacketBridgeAPIapi.bridgeUI/Packet 桥接 API
ClientBridgeAPIapi.bridge客户端桥接 API
ItemBridgeAPIapi.bridgeItemStack 序列化 API
PropBridgeAPIapi.bridgeProp/按键绑定桥接 API
WaypointBridgeAPIapi.bridge路标桥接 API
AdyeshachNpcBridgeAPIapi.bridgeAdyeshach NPC 桥接 API
WorldTextureBridgeAPIapi.bridge世界文字贴图桥接 API
SoundPlayerBridgeAPIapi.bridge音效播放器桥接 API
VanillaItemNameBridgeapi.bridge原版物品中文名称解析
ContentModeratorapi.bridge内容审核(敏感词过滤)
NavigationTarget / NavigationTargetServiceapi.util共享导航目标编排:diff 推送、到达滞回判定、命令钩子、跨世界抑制、单路标单路线(Map/QuestGPS 使用)
NavigationMarkerService / NavigationMarkerConfigapi.utilAdyeshach 私有实体路径标记链(按 navKey 多组状态、距离滞回)
Capability 接口api.capability跨模块能力通信
ModuleLifecycleEventapi.event模块生命周期 Bukkit 事件
TaczGunDamageEventapi.eventTACZ 枪械伤害事件
TaczGunKillEventapi.eventTACZ 枪械击杀事件
MessageProviderapi.message消息外部化 / i18n
CrossServerAPIapi.crossserver统一跨服 SDK

快速开始

// build.gradle.kts
dependencies {
    compileOnly(files("libs/axs-api-x.x.x.jar"))
    compileOnly("org.spigotmc:spigot-api:1.20.1-R0.1-SNAPSHOT")
}
public class MyModule extends AbstractAXSModule {
 
    @Override
    public ModuleDescriptor descriptor() {
        return ModuleDescriptor.builder("mymodule")
            .name("MyModule").version("1.0.0")
            .mainClass(getClass().getName()).build();
    }
 
    @Override
    protected void loadConfiguration(File configFile) {
        // 解析配置
    }
 
    @Override
    protected void startService() {
        PacketBridgeAPI bridge = packetBridge;
        if (bridge != null && bridge.isAvailable()) {
            // 使用桥接 API
        }
    }
 
    @Override
    protected void stopService() {
        // 释放资源
    }
}

版本管理

axs-api 采用语义化版本。module.yml 中的 api-version 字段声明模块所依赖的 API 大版本。宿主在加载模块时会检查兼容性。

API 版本关键变更
1.0基础架构:AXSModule、ModuleContext、ModuleRegistry
1.1Bridge API 接口化(PacketBridgeAPI、ClientBridgeAPI、ItemBridgeAPI)
1.2Prop/Waypoint/Adyeshach/WorldTexture 桥接;跨服 API
1.3SoundPlayer 桥接;VanillaItemNameBridge;ContentModerator
1.5ModuleContext 按 ISP 拆分为子接口;ModuleConfig/ModuleUiSpec 声明式规约
1.6SchedulerAPI 统一调度

本页目录