API 参考 / capability 包：服务、状态与游玩访问

StoryAccess

剧情 / TriggerManager 控制能力（进程级）。用于在任意场景查询当前剧情节点、触发指定节点、跳过当前剧情，经 ctx.capabilities().get(StoryAccess.class) 取用。

方法速览

方法	用途
`currentNode()`	当前剧情节点（非剧情场景返回 `null`）
`trigger(String, StoryContext)`	跳转剧情场景播放指定节点
`skip()`	跳过当前剧情

java

public interface StoryAccess {

    StoryNode currentNode();

    void trigger(String nodeId, StoryContext context);

    void skip();
}

签名：

java

StoryNode currentNode();

行为：当前场景为剧情场景且正在播放节点时，返回该节点的只读视图；否则返回 null。返回节点的 isActive() 恒为 true（只有播放中才会被返回）。

示例：

java

StoryNode node = story.currentNode();
if (node != null) {
    ctx.getLogger().info("当前剧情：" + node.id());
}

签名：

java

void trigger(String nodeId, StoryContext context);

行为：压入剧情场景播放指定故事 id。nodeId 为 null 或空串时静默忽略。context.source() 透传为场景的 source 参数；context 为 null 或 source() 为 null 时使用 "mod"。

示例：

java

story.trigger("story_intro", () -> "mymod");   // StoryContext 是单方法接口

签名：

java

void skip();

行为：当前处于剧情场景时立即跳过当前剧情并推进到剧情完成 / 下一场景；不在剧情场景时无操作。

示例：

java

story.skip();

线程：源码未声明额外线程约束（宿主在调用线程直接读写场景栈与剧情场景）。

稳定性：2.0 起冻结：2.x 内只增不破。