template/.planning/ROADMAP.md

Roadmap: 魔塔游戏引擎（mota-ts）

Overview

引擎从旧 mota-js 运行时逐步重构，渲染端已重构完成，数据端接口设计中。本路线图沿「事件系统 → 寻路 → 数据端完成 → 渲染适配 → legacy 移植 → 单元测试」的依赖顺序推进：先补齐剧情事件、自动寻路两大玩法系统，再完成数据端 L0–L3 接口落地，随后把新数据层与已重构渲染端打通并支持双布局，接着清理被新接口覆盖的 legacy，最后以单元测试兜底，使引擎能完整跑通一部魔塔。接口/架构设计由用户主导，AI 负责实现与测试；验证通过后 AI 可自行创建 git commit。

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: 事件系统 - blockly 式低代码事件定义，驱动简单场景事件流程（验证已通过，待完成阶段收尾）
• Phase 2: 寻路系统 - 自动寻路与移动端点击地图触发移动
• Phase 3: 数据端完成 - 数据端 L0–L3 接口全部落地，可在 Node 环境独立跑回放验证 (completed 2026-09-10)
• Phase 4: 渲染适配与双布局 - 新数据层 ↔ 已重构渲染端对接，支持移动端与桌面端双布局
• Phase 5: Legacy 移植 - 删除被新接口覆盖的旧系统，迁移仍需要的内容
• Phase 6: 单元测试 - 为核心系统补齐单元测试

Phase Details

Phase 1: 事件系统

Goal: 引擎能以 blockly 式低代码定义事件，并驱动简单场景的事件流程 Depends on: Nothing (first phase) Requirements: EVT-01, EVT-02, EVT-03 Success Criteria (what must be TRUE):

1. 开发者能通过数据/序列化接口定义事件（blockly 式低代码可序列化为引擎事件数据，编辑器在外部项目）
2. 引擎能执行踩踏触发事件（角色踩上地板触发对应事件）
3. 引擎能执行踩踏触发事件驱动的事件执行链路（对话/开门依赖 A2 内建函数清单，延后到收尾工作）
4. 事件系统保持面向初学者的简单抽象，未引入复杂场景的通用表达能力

Plans: 13/13 plans executed Plans:

• 01-13-PLAN.md

• 01-04-PLAN.md

• 01-05-PLAN.md

• 01-06-PLAN.md

• 01-07-PLAN.md

• 01-08-PLAN.md — GameEventStore add/get/duplicate-warning regression; rawEvent and cycle baselines preserved

• 01-09-PLAN.md — GameMap point-event-only save aggregation; production registration deferred

• 01-10-PLAN.md

• 01-11-PLAN.md — CoreState legacy map initialization selects eventLayer; existing source-aware movement path remains reachable

• 01-12-PLAN.md — Close phase-owned type diagnostics and CRLF/Prettier quality-gate gaps without behavior changes

Wave 1

• 01-01-PLAN.md — L0/L1 事件数据契约落地 + 图块/点位事件视图 + 存读档迁移

Wave 2 (blocked on Wave 1 completion)

• 01-02-PLAN.md — 执行器接口用户确认（checkpoint）+ 执行器实现 + 删除旧 ITrigger（D-13）+ CoreState 装配

Wave 3 (blocked on Wave 2 completion)

• 01-03-PLAN.md — moverImpl 踩踏触发重写为事件执行 + 阶段验收

Wave 8 (blocked on completed event ingestion, dispatch, and persistence gap plans)

• 01-11-PLAN.md — CoreState legacy map initialization selects eventLayer; existing source-aware dispatch remains reachable

Wave 9 (blocked on Wave 8 completion)

• 01-12-PLAN.md — Phase-owned type and CRLF/Prettier gap closure

Phase 2: 寻路系统

Goal: 引擎支持自动寻路，移动端点击地图即可触发移动 Depends on: Phase 1 Requirements: PATH-01, PATH-02 Success Criteria (what must be TRUE):

1. 角色能在地图上自动寻路移动到指定格
2. 移动端点击地图上的可达格时，角色自动寻路移动到该格
3. 寻路正确避开不可通行格（碰撞/障碍/墙体）

Plans: 5/5 plans executed

Scope correction (2026-09-10): 用户审查确认本阶段不交付未授权的 HeroPathfinding L3 勇士封装；当前阶段保留 L2 寻路核心、共享通行性谓词与 DataCommon 方向映射依赖，勇士或渲染侧接线不作为本阶段实现内容。 UI hint: yes Plans:

• 02-01-PLAN.md — 接口草案 + mover.ts:651 缺陷调查 + 回归脚手架 + D-07 用户拍板关卡（checkpoint）

• 02-02-PLAN.md — L0 坐标回写缺陷修复 + L2 寻路核心（有向图 + 最小损失 + 仅取路径 + 回退策略槽位）

• 02-03-PLAN.md — L3 接线（逐步/瞬移/回退默认策略/D-08 双语义/打断接管）+ barrel/logger 装配 + 阶段门禁

• 02-04-PLAN.md — 恢复用户授权的 path/types.ts 契约并收口 moverImpl TS18047

• 02-05-PLAN.md — 稳定全量 Vitest 门禁并提供非 watch 测试命令

Wave 1

• 02-01-PLAN.md — 接口草案与拍板关卡（autonomous: false）

Wave 2 (blocked on Wave 1 用户拍板)

• 02-02-PLAN.md — L0 修复 + L2 寻路核心

Wave 3 (blocked on Wave 2)

• 02-03-PLAN.md — L3 接线与阶段门禁

Wave 4 (gap closure; blocked on Wave 3 completion)

• 02-04-PLAN.md — 用户契约范围与阶段类型错误收口
• 02-05-PLAN.md — 全套件超时与跳过测试门禁收口

Phase 3: 数据端完成

Goal: 数据端 L0–L3 接口实现完成，数据层各系统可用并可在 Node 环境独立运行回放验证 Depends on: Phase 2 Requirements: DATA-01 Success Criteria (what must be TRUE):

1. 用户设计的 L0–L3 数据层接口全部落地，地图/角色/敌人/flag/战斗/触发器/存档/回放各系统可用
2. 数据端可在 Node 环境独立运行回放验证，无 DOM 依赖
3. 数据端与渲染端保持双端分离，渲染相关代码经 r()/rf() 门控或走 hook，渲染端不向数据端推送更新
4. 接口设计由用户主导，AI 仅负责实现

Plans: 19/19 plans executed Plans:

• 03-17-PLAN.md

• 03-18-PLAN.md

• 03-19-PLAN.md

• 03-10-PLAN.md

• 03-11-PLAN.md

• 03-12-PLAN.md

• 03-13-PLAN.md

• 03-14-PLAN.md

• 03-15-PLAN.md

• 03-16-PLAN.md

• 03-07-PLAN.md

• 03-08-PLAN.md

• 03-09-PLAN.md

• 03-01-PLAN.md — Node-safe CoreState、内部 legacy 依赖边界与最小 replay tracer

• 03-02-PLAN.md — 八个事件内建函数契约 checkpoint 与最小注册实现

• 03-03-PLAN.md — 稳定 replay enum、异步 command 与 top-level 注册

• 03-04-PLAN.md — 固定 Node 回放 fixture、首分歧 thrown diagnostic 与最终快照

• 03-05-PLAN.md — DATA-01 focused closure 与四包 type/circular 最终门禁

• 03-06-PLAN.md — Tile events contract 与 legacy conversion 收口

Wave 1

• 03-01-PLAN.md — Node-safe CoreState、内部 legacy 依赖边界与最小 replay tracer

Wave 2 (blocked on Wave 1 completion)

• 03-02-PLAN.md — 八个事件内建函数契约 checkpoint 与最小注册实现
• 03-06-PLAN.md — Tile events contract 与 legacy conversion 收口

Wave 3 (blocked on Wave 2 completion)

• 03-03-PLAN.md — 稳定 replay enum、异步 command 与 top-level 注册

Wave 4 (blocked on Wave 3 completion)

• 03-04-PLAN.md — 固定 Node 回放 fixture、首分歧 thrown diagnostic 与最终快照

Wave 5 (blocked on Wave 4 completion)

• 03-05-PLAN.md — DATA-01 focused closure 与四包 type/circular 最终门禁

Phase 4: 渲染适配与双布局

Goal: 渲染端通过新数据层接口驱动，并同时支持移动端与桌面端布局 Depends on: Phase 3 Requirements: REND-01, REND-02 Success Criteria (what must be TRUE):

1. 用新数据层接口加载一张地图后，已重构的渲染端能正确渲染该地图场景
2. 桌面端布局下，地图、角色、界面元素正常显示并可操作
3. 移动端（窄屏）布局下，同一场景正常显示且可操作
4. 数据端与渲染端保持双端分离——数据端无 DOM，仍可在 Node 环境跑回放验证

Plans: TBD UI hint: yes

Phase 5: Legacy 移植

Goal: 删除被新接口覆盖的 legacy 系统，迁移仍需要的内容 Depends on: Phases 1-4 Requirements: LEGACY-01, LEGACY-02 Success Criteria (what must be TRUE):

1. 被新接口覆盖的 legacy 系统已删除，代码中无残留引用
2. 仍需要的 legacy 内容已迁移到新接口
3. 仅当无新接口覆盖时才新增接口，且接口设计经用户 review
4. 移植后引擎仍能完整跑通一部魔塔，无功能回归

Plans: TBD

Phase 6: 单元测试

Goal: 为核心系统（数据层等）补齐单元测试 Depends on: Phases 1-5 Requirements: TEST-01 Success Criteria (what must be TRUE):

1. 核心数据层系统有单元测试覆盖
2. 测试覆盖关键行为（战斗伤害、触发器、寻路、事件等）
3. 测试在本地可运行且全部通过
4. 测试由 AI 编写并运行，通过验证后可提交

Plans: 9/9 原计划 executed replanned (D-28；旧 06-01/06-02 执行结果标记 superseded，按同号重跑；数据端切片，非数据 render/legacy 覆盖延后) + gap-fill 06-10..06-15 (D-46；人工评审缺口补测，只补测试不改生产代码；15/15 executed)

Plans:

• 06-01-PLAN.md — Combat L2 (data-system/src/combat) + EnemyContext aura pipeline / effect combos / full interface & code coverage (D-21..D-27)
• 06-02-PLAN.md — enemy top-level BASIC functionality only (data-state/src/enemy；单分支，无组合，无 save/load)
• 06-03-PLAN.md — Enemy data model full public surface except legacy (data-base/src/enemy；无 save/load)
• 06-04-PLAN.md — Replay focus ReplayArray ops + encode/decode + system/sandbox/decorators (data-common/src/replay；无 save/load，完整播放→06-07)
• 06-05-PLAN.md — Hero ALL files incl. rendering + async mover (data-base/src/hero；无 save/load)
• 06-06-PLAN.md — Map ALL interfaces, emphasis static/dynamic tiles + static arrays (data-base/src/map；无 save/load)
• 06-07-PLAN.md — Top-level integration: damage combos + map+replay play + second-play re-record equality; error 2001–2008 (user confirmed replay recording wired)
• 06-08-PLAN.md — Flag full surface + common (utils/indexer/faceManager+face/mover) (无 save/load)
• 06-09-PLAN.md — Save/load independent system: every saveState/loadState class + CoreState top-level (BLOCKED: pre-execution user confirmation)

Wave 1 (independent test-writing plans; no shared production edits)

• 06-01-PLAN.md
• 06-02-PLAN.md
• 06-03-PLAN.md
• 06-04-PLAN.md
• 06-05-PLAN.md
• 06-06-PLAN.md
• 06-08-PLAN.md

Wave 2 (blocked on Wave 1 + user confirmation)

• 06-07-PLAN.md — depends on 06-02/06-04/06-06; replay recording wired by user (17d7c8f), SUMMARY complete
• 06-09-PLAN.md — depends on 06-03/06-05/06-06/06-08; requires user to adjust CoreState saveables + add public save/load entry

Wave 3 (gap-fill batch, D-46; extends existing *.test.ts, no production edits)

• 06-10-PLAN.md — combat/enemy combination gaps: G-06-01-A/B/C + G-06-07-A
• 06-11-PLAN.md — hero/map gaps: G-06-05-A + G-06-06-A/B/C
• 06-12-PLAN.md — replay/enemy gaps: G-06-04-B (runnable) + G-06-04-A/G-06-03-A (correct-expectation skip)
• 06-13-PLAN.md — save/load gaps: G-06-09-A/B (only plan testing saveState/loadState, D-32)

Wave 4 (G-06-04-C follow-up gap-fill, D-46; serialized after 06-12 because it shares array.test.ts)

• 06-14-PLAN.md — replay read-stream gaps: G-06-04-C/A (stream-only complex route + middle start index) + G-06-04-C/B (per-param typed assertions, index progression, expired-after-mutation); blocked #06-04-3/#06-04-4 as correct-expectation it.skip

Wave 5 (G-06-01-D interface-coverage gap-fill, D-46; serialized after 06-14)

• 06-15-PLAN.md — combat interface gap: G-06-01-D (EnemyContext.deleteAura normal case — addAura applies atk 2→5 → deleteAura same instance → buildup expects 2); blocked #06-15-1 (same root cause as #06-01-4) as correct-expectation it.skip, pending user decision

Phase 7: 数据端缺陷修复

Goal: 修复 Phase 6 单元测试暴露的数据端疑似缺陷，使正确预期用例转绿，且仅限数据端、不涉及渲染端 Depends on: Phase 6 Requirements: FIX-01 Success Criteria (what must be TRUE):

1. 06-TEST-FINDINGS.md 登记的数据端疑似缺陷全部处置完毕（修复或经用户裁定改契约/不修复）：#06-01-1..4、#06-03-1、#06-04-1..4、#06-05-1..3、#06-06-1、#06-07-1、#06-08-1、#06-09-1/2/3/5，以及同根因的 #06-15-1（#06-09-4 已作废）
2. 对应的正确预期 it.skip 用例在修复后取消 skip 并通过；无法修复的缺陷经用户确认后同步修正接口文档/契约
3. pnpm test:ci 全绿且不新增跳过用例，数据范围 check:type / check:circular 门禁通过
4. 改动仅限数据端（packages 与 packages-user/data-），不改动渲染端 @user/client- 与 legacy 渲染接线，双端分离约束保持

Plans: TBD

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7

Phase	Plans Complete	Status	Completed
1. 事件系统	13/13	In Progress
2. 寻路系统	5/5	In Progress
3. 数据端完成	19/19	Complete	2026-09-12
4. 渲染适配与双布局	0/TBD	Not started	-
5. Legacy 移植	0/TBD	Not started	-
6. 单元测试	15/15	In Progress
7. 数据端缺陷修复	0/TBD	Not started	-