template/.planning/phases/03-data-completion/03-EVENT-CONTRACT.md

Phase 3 Event Built-in Contract

本文件记录 confirm-record checkpoint 的确认结果。范围只包含本阶段批准的八个 event built-ins；不加入完整 legacy 事件目录，不保留未决字段，也不把渲染行为放入 数据端函数。

Shared contract

• 每个函数都使用 (param, env) 调用形式。
• env 的类型固定为 IBlockEventEnv。目标解析顺序为：明确的 env.layer，env.map 的 eventLayer，最后是通过 env.heroFloor 从 env.state.maps 获取的地图及其 eventLayer。
• 目标、图块、勇士、事件存储或事件 id 缺失时，函数安全跳过并返回 void；不抛出 业务错误，不访问 DOM、render global 或 legacy global。
• 地图删除、移动、勇士移动和临时事件序列都等待完整的 Promise 动作；没有需要等待 的动作时同步返回 void。
• 默认注册项由 data-state/src/event 提供，CoreState 只负责把注册项传给 GameEventSystem；GameEventSystem 通过现有 AnonTokyoInterpreter 的 builtInFunctions 初始化项装配。函数实现不复制到 CoreState。
• 注册项只包含下表八个稳定名称。

Parameter contracts

eventSetBlock

interface ISetBlockEventParam {
    readonly x: number;
    readonly y: number;
    readonly tile: number | string;
}

在解析出的目标图层设置 (x, y) 的静态图块。tile 通过 env.state.tileStore 解析；图块 id、地图、图层或坐标目标不可用时安全返回 void。

eventMoveBlock

interface IMoveBlockEventParam {
    readonly x: number;
    readonly y: number;
    readonly steps: readonly ObjectMoveStep[];
    readonly safe?: boolean;
}

从 (x, y) 将静态图块转为动态图块，按 steps 完整移动，再转回静态图块。 safe 为 true 时使用 transferToStaticIfSafe，否则使用 transferToStatic。源图块、动态图块、移动控制器或目标静态图块不可用时安全返回 void；移动控制器的 onEnd 和最终转换都必须等待。

eventDeleteBlock

interface IDeleteBlockEventParam {
    readonly x: number;
    readonly y: number;
}

删除目标坐标的静态图块，并等待该坐标所有动态图块的删除 Promise。地图、图层或 坐标不可用时安全返回 void。

eventMoveHero

interface IMoveHeroEventParam {
    readonly steps: readonly ObjectMoveStep[];
}

把完整 steps 队列加入 env.state.hero.location.mover 并启动一次移动。勇士或 移动器缺失、移动已在进行中或动作无法启动时安全返回 void；启动成功后等待 IMoverController.onEnd。

eventMoveHeroStep

interface IMoveHeroStepEventParam {}

不读取额外字段，使用勇士当前移动方向执行一次 forward(1)。勇士、移动器或控制器 缺失时安全返回 void，启动成功后等待 onEnd。

eventTouchFront

interface ITouchFrontEventParam {}

不读取额外字段。以勇士当前位置和当前朝向计算面前一格，收集该坐标的点事件、静态 图块事件和动态图块事件，以 EventTrigger.OnTouch 通过现有事件执行器顺序触发。 缺少勇士、地图、图层、目标位置或事件执行器时安全返回 void；事件执行 Promise 必须等待。该函数只触发 onTouch，不移动勇士。

eventInsertEvents

interface IInsertEventsEventParam {
    readonly ids: readonly string[];
}

按 ids 顺序临时构造事件调用，复用当前 env，通过当前事件执行器执行一次；不把 这些事件写入 IGameEventStore，也不改变地图持久化数据。空序列、缺失事件存储、缺失 事件 id 或缺失执行器时安全跳过；执行 Promise 必须等待。

eventInsertEvent

interface IInsertEventEventParam {
    readonly id: string;
}

这是 eventInsertEvents 的单 id 形式：只临时执行 id 对应事件，复用当前 env， 不写入事件存储。空 id、缺失事件、缺失事件存储或缺失执行器时安全返回 void， 执行 Promise 必须等待。

Registration

data-state/src/event/index.ts 提供稳定名称对应的默认注册项，顺序为：

1. eventSetBlock
2. eventMoveBlock
3. eventDeleteBlock
4. eventMoveHero
5. eventMoveHeroStep
6. eventTouchFront
7. eventInsertEvents
8. eventInsertEvent

CoreState 在创建 GameEventSystem 时传入该注册项集合；GameEventSystem 将其 转换为 AnonTokyo 的 built-in function entries。除这八项外，本阶段不注册任何 legacy built-in。