教程系统

教程包括分步引导、特定界面引导和短提示。完成记录按版本保存在本地文件中，同一游戏安装会在不同世界与服务器间共享这些记录；服务端只能请求播放，不持有教程进度。

它做什么

服务端使用 api.tutorial.TutorialAPI，客户端使用 api.client.tutorial.TutorialClientAPI。定义、步骤、目标、矩形与图片类型位于 api.client.tutorial。位于 client.tutorial 的管理器、注册表、区域报告器和编辑器是实现入口，不是公共门面。

教程在客户端初始化时通过 Java 注册，没有教程 JSON 加载器。服务端数据包 isekaiexpansion:trigger_tutorial 只携带教程标识符与重播布尔值，不传输定义或完成记录。

运行时模型

定义类型与内置教程

同时只能有一个交互教程。队列内的分步教程 ID 去重，当前已播放的 ID 不再入队。强制重播分步教程会打断当前教程，但不会清空原有队列。未知 ID 会记录警告。普通请求不能打开界面教程；重播会清除其完成记录，且仅在对应界面已打开、玩家存在、没有其他活动教程时立即开始。

管理器在客户端 tick 末尾运行。失去焦点、过场输入锁、目标上下文不可用或边界编辑器开启时，会隐藏引导并重置按住进度。HUD 步骤要求没有打开界面；界面步骤要求当前界面匹配。已安排的推进在编辑器检查后、多数上下文检查前执行，不会再次完整验证原动作。

进度存储

游戏目录中的 isekaiexpansion-tutorials.txt 使用以下文本格式：

format 1
completed isekaiexpansion:adventurer_basics 2

空行、以 # 开头的注释、格式错误的记录、无效 ID 与无效版本均忽略。写出时按 ID 排序，先写同目录 .tmp 文件，再尝试原子替换；不支持时改用普通替换。读取或写入 I/O 失败会记录警告。活动步骤与队列不保存。断开连接清空运行状态，完成记录仍然保留。

约定

定义与步骤字段

运行时沿当前界面的父类链匹配。注册顺序决定第一个匹配的界面教程，不会优先选择最具体的类。若第一个匹配项已完成，也不会继续查找其他匹配教程。

输入与时长

引导期间会消费 E 和 Escape，包括过渡后的松键保护。其他匹配绑定键与鼠标键在安排推进后仍可传递给游戏。按住 Escape 会取消待执行推进及其他按住进度。动作步骤没有 E 后备操作。松开绑定键会重置计时。

目标与插图

内部 TutorialHudBounds 保留一帧内请求 ID 的最后一个有效报告。TutorialScreenBounds 只接受同一请求界面实例的报告，并合并有效匹配矩形。两者均忽略非正尺寸。应在对应帧重置后按缩放后的 GUI 像素报告；界面报告不是持久注册。图片缺失时仍保留编写的占位与边框。

扩展方式

在客户端初始化器中注册下例，并在两个语言组装文件中提供翻译键。导入来自 api.client.tutorial、Minecraft Identifier 与 java.util.List。

public static void registerExampleTutorial() {
    Identifier tutorialId = new Identifier("example", "first_jump");
    TutorialClientAPI.register(new GuidedTutorialDefinition(
            tutorialId, 1, List.of(
                    TutorialStep.hold("tutorial.example.welcome.title",
                            "tutorial.example.welcome.body"),
                    TutorialStep.keyPress("tutorial.example.jump.title",
                            "tutorial.example.jump.body", "key.jump")
            )));
}

以上门面参数均不能为 null。播放与动作调用直接修改客户端管理器，应在客户端线程调用；跨线程分发时使用 MinecraftClient.execute。先注册再请求。不要在专用服务端初始化中引用客户端定义或类；服务端只需标识符与服务端门面。

编写相对目标时，按 Control + 重启绑定键打开边界编辑器，用鼠标左键拖出矩形，按 Enter 将 Java 目标表达式复制到剪贴板与聊天。Escape 取消。选区至少为 4 × 4 缩放像素。界面模式捕获当前界面的类名，具体界面实例变化时关闭；HUD 模式在打开界面时关闭。调整尺寸会保留归一化选区并结束拖动。工具输出 6 位小数，不会修改源码。

验证

使用权限等级 2 的命令 /ise dev tutorial show <id> [targets] 与 /ise dev tutorial replay <id> [targets]。省略目标要求执行者为玩家。补全只列出 3 个内置 ID，但允许输入任意标识符；成功数量统计数据包接收者，不代表实际显示次数。

检查普通播放、强制重播、提高版本、跳过、断线，以及同一安装切换世界的行为。检查界面关闭重开、父子类触发顺序、报告器缺失、GUI 缩放、按键绑定不可用，以及动作通知早于步骤的情况。确认结束后松开 E/Escape 不会立即打开物品栏或暂停。用专用服务端验证定义仅在客户端注册，并在完成或重启后查看进度文件。

相关页面

• 命运天平 API — 另一种由服务端持有游戏状态的客户端呈现。
• 持久状态 — 与教程完成记录不同的世界存储。