Java API

Chronos 3.0.0 的稳定 ABI 位于 priv.seventeen.artist.arcartx.chronos.api。

获取 API 与探测能力

必须依赖 Chronos 的附属插件，在 plugin.yml 中声明 depend: [Chronos]，然后在 onEnable 获取：

ChronosAPI api = ChronosAPI.getInstanceAPI();
if (api == null) {
    throw new IllegalStateException("Chronos API unavailable");
}
 
if (!api.getCapabilities().contains("chronos:profession-runtime/1")) {
    throw new IllegalStateException("Chronos profession runtime is too old");
}

可选联动时使用 softdepend: [Chronos]，并先通过 Bukkit PluginManager 确认 Chronos 存在且已启用，再加载或调用引用 Chronos API 的独立接入类。softdepend 只安排加载顺序，不保证 Chronos 已安装、授权通过或业务初始化成功；不要在主插件入口中无条件引用它的 API 类型。

停用清理会终止待决释放、结束动作与状态、清空输入和临时覆盖，并尝试解除在线玩家的客户端控制器、恢复原版使用。外部资源预留仍按 Provider 的回滚契约处理，不能把引擎清理等同于外部存储补偿成功。

若关闭回调已经启用新实例并发布新的 API，旧实例的后续清理不会再清空新实例的客户端状态或控制器。

getInstanceAPI() 先读兼容的静态入口，再从 Bukkit ServicesManager 查找。当前能力 ID：

• chronos:profession-runtime/1
• chronos:action-instance/1
• chronos:controller-override/1
• chronos:target-selector/1
• chronos:target-selector-cancel/1
• chronos:execute-loop/1

基础状态 API

传给 setPlayerController 的 ID 不存在时等价于移除基础控制器。存在但不属于当前职业时请求被忽略。设置或移除基础控制器时，若当前状态仍在运行，实际切换会等到状态结束；若存在临时覆盖，则只更新基础目标，当前覆盖继续生效。getPlayerControllerId 返回当前实际生效的控制器，不是尚未生效的基础目标。若需要可观察的结果与自动恢复，请使用定时控制器覆盖。

受控状态的 duration 与配置时长一样，最终仍除以该状态的 speed；例如传入 1000 且 speed = 2 时，计算出的时长为 500ms。

职业与技能

String professionId = api.getPlayerProfessionId(player);
ProfessionSnapshot snapshot = api.getPlayerProfessionSnapshot(player);
 
boolean switched = api.setPlayerProfession(player, "example:warrior");
SkillCastResult cast = api.castSkill(player, "primary");
api.invalidateProfession(player);

getPlayerProfessionSnapshot 在玩家未就绪时返回 null；玩家就绪后只读取已缓存的外部快照，尚无缓存或缓存已失效时，返回当前职业的本地默认装配快照，职业等级为 1。这个 getter 不会调用 Provider，也不能用来主动刷新外部数据。setPlayerProfession 只切换 Chronos 的运行时职业，不修改外部框架的数据或持久化记录；外部 Provider 下次返回的快照仍可能把玩家切换到它声明的职业。

castSkill 接受任意非空槽位 ID，不限定名称或数量。返回状态包括 STARTED、PENDING_PROFESSION、PENDING_ADMISSION、SELECTING、REJECTED 与 NO_SKILL_IN_SLOT。它返回的是本次调用所进入的处理阶段，而不是等待整个流程结束的 future；即使 Provider 返回已完成的任务，流程已同步推进，也可能仍返回 PENDING_PROFESSION 或 PENDING_ADMISSION。NO_SKILL_IN_SLOT 既可能表示槽位未装配技能，也可能表示技能的触发阶段与本次输入不符。

SkillCastResult.instanceId() 随状态变化：STARTED 携带动作实例 ID，SELECTING 携带选择实例 ID，PENDING_ADMISSION 携带本次释放尝试的 attempt ID；其余状态为 null。入口 conditions 或冷却在检查阶段拒绝时，不会产生新动作的 Start/End 事件。外部框架还可记录自己的 selection/admission/lease 结果，但不能把 Provider 完成或 commit 成功单独视为动作已开始。

当前 Java API 的 castSkill 固定发送 PRESS 阶段，因此槽位应装配 trigger: PRESS 的技能；HOLD 与 RELEASE 技能由客户端对应输入阶段触发。Java API 没有独立的长按/松开重载。

扩展注册方法：

Registration profession = api.registerProfessionProvider(plugin, provider);
Registration selector = api.registerTargetSelector(plugin, selectorProvider);
Registration execute = api.registerExecutionHandler(plugin, "myplugin:pulse", handler);
 
// 可提前撤销；插件禁用时 Chronos 也会自动撤销。
profession.close();

同一时刻只允许一个权威 ProfessionProvider；selector 按 provider ID 注册；execute handler 按命名空间 ID 注册。具体契约见外部职业框架、特殊目标选择器和execute 循环。

Registration.close() 可重复调用。主动关闭、所属插件卸载或 Chronos 停用后，句柄的 isActive() 为 false；关闭旧句柄不会撤销后来注册的同名扩展。

Bukkit 事件

以下事件均为只读通知，不实现 Cancellable：

• PlayerControllerChangeEvent
• PlayerEnterStateEvent / PlayerLeaveStateEvent
• PlayerProfessionChangeEvent
• PlayerSkillActionStartEvent / PlayerSkillActionEndEvent
• PlayerControllerOverrideStartEvent / PlayerControllerOverrideEndEvent

技能动作事件携带动作开始时确定的 actionInstanceId、职业 ID、槽位 ID、技能 ID 和技能等级；动作结束事件另有 reason。这里提供的是实例 ID，不暴露内部 ActionInstance 对象。覆盖结束事件携带结束原因与事件发出时实际生效的控制器 ID。

PlayerSkillActionStartEvent 在入口检查通过、新动作元数据激活后发出，随后才尝试进入入口状态，因此它不等同于 PlayerEnterStateEvent。事件本身不可取消，但监听器同步调用职业/控制器等 API 可能中断动作；若后续入口启动失败，也可能紧接着发出 End。需要确认状态已进入时，观察 EnterState，而不是只看 Start 或资源 commit。