From 49613cd4a17c9f2488bec8aafb9694a21d3a1667 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Mon, 7 Sep 2026 17:17:17 +0800 Subject: [PATCH] docs: create roadmap (6 phases) --- .planning/REQUIREMENTS.md | 31 +++++++----- .planning/ROADMAP.md | 103 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 79 +++++++++++++++++++++++++++++ 3 files changed, 200 insertions(+), 13 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index bb37710..39a2031 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -18,6 +18,10 @@ Requirements for the engine's completion. Each maps to roadmap phases. - [ ] **PATH-01**: 引擎支持自动寻路 - [ ] **PATH-02**: 移动端通过点击地图触发自动寻路移动 +### 数据端（Data） + +- [ ] **DATA-01**: 数据端（L0–L3）接口实现完成——用户设计的接口全部落地，数据层各系统（地图/角色/敌人/flag/战斗/触发器/存档/回放）可用，并可在 Node 环境独立运行回放验证 + ### 渲染适配与双布局（Render） - [ ] **REND-01**: 渲染端适配新数据层接口 @@ -48,21 +52,22 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| EVT-01 | — | Pending | -| EVT-02 | — | Pending | -| EVT-03 | — | Pending | -| PATH-01 | — | Pending | -| PATH-02 | — | Pending | -| REND-01 | — | Pending | -| REND-02 | — | Pending | -| LEGACY-01 | — | Pending | -| LEGACY-02 | — | Pending | -| TEST-01 | — | Pending | +| EVT-01 | Phase 1 | Pending | +| EVT-02 | Phase 1 | Pending | +| EVT-03 | Phase 1 | Pending | +| PATH-01 | Phase 2 | Pending | +| PATH-02 | Phase 2 | Pending | +| DATA-01 | Phase 3 | Pending | +| REND-01 | Phase 4 | Pending | +| REND-02 | Phase 4 | Pending | +| LEGACY-01 | Phase 5 | Pending | +| LEGACY-02 | Phase 5 | Pending | +| TEST-01 | Phase 6 | Pending | **Coverage:** -- v1 requirements: 10 total -- Mapped to phases: 0 -- Unmapped: 10 ⚠️ +- v1 requirements: 11 total +- Mapped to phases: 11 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-09-07* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..587180e --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,103 @@ +# Roadmap: 魔塔游戏引擎（mota-ts） + +## Overview + +引擎从旧 mota-js 运行时逐步重构，渲染端已重构完成，数据端接口设计中。本路线图沿「事件系统 → 寻路 → 数据端完成 → 渲染适配 → legacy 移植 → 单元测试」的依赖顺序推进：先补齐剧情事件、自动寻路两大玩法系统，再完成数据端 L0–L3 接口落地，随后把新数据层与已重构渲染端打通并支持双布局，接着清理被新接口覆盖的 legacy，最后以单元测试兜底，使引擎能完整跑通一部魔塔。接口/架构设计由用户主导，AI 负责实现与测试，所有 git 提交须经用户 review。 + +## 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 环境独立跑回放验证 +- [ ] **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. 引擎能执行对话事件与开门事件，打通简单场景事件全链路 + 4. 事件系统保持面向初学者的简单抽象，未引入复杂场景的通用表达能力 +**Plans**: TBD + +### Phase 2: 寻路系统 +**Goal**: 引擎支持自动寻路，移动端点击地图即可触发移动 +**Depends on**: Phase 1 +**Requirements**: PATH-01, PATH-02 +**Success Criteria** (what must be TRUE): + 1. 角色能在地图上自动寻路移动到指定格 + 2. 移动端点击地图上的可达格时，角色自动寻路移动到该格 + 3. 寻路正确避开不可通行格（碰撞/障碍/墙体） +**Plans**: TBD +**UI hint**: yes + +### 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**: TBD + +### 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 编写，经用户 review 后提交 +**Plans**: TBD + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. 事件系统 | 0/TBD | Not started | - | +| 2. 寻路系统 | 0/TBD | Not started | - | +| 3. 数据端完成 | 0/TBD | Not started | - | +| 4. 渲染适配与双布局 | 0/TBD | Not started | - | +| 5. Legacy 移植 | 0/TBD | Not started | - | +| 6. 单元测试 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..23886b2 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,79 @@ +--- +gsd_state_version: '1.0' +status: planning +progress: + total_phases: 6 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 + percent: 0 +--- + +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-09-07) + +**Core value:** 引擎能完整跑通一部魔塔——开局到结局，存档、战斗、地图、事件、剧情全链路可玩。 +**Current focus:** Phase 1 — 事件系统 + +## Current Position + +Phase: 1 of 6 (事件系统) +Plan: 0 of TBD in current phase +Status: Ready to plan +Last activity: 2026-09-07 — Roadmap revised (6 phases, 11 requirements mapped) + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: N/A +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: N/A +- Trend: N/A + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- 接口/架构设计由用户主导；AI 仅做实现与测试 +- 渲染层先于数据层完成重构（既有顺序延续） +- 阶段顺序调整为玩法优先：事件 + 寻路 → 数据端完成 → 渲染适配 → legacy 移植 → 单元测试 +- Git 提交必须经用户 review，AI 不擅自提交 + +### Pending Todos + +None yet. + +### Blockers/Concerns + +- 数据层 L0–L3 接口设计仍在进行中（由用户主导），DATA-01（Phase 3）依赖接口设计落地 + +## Deferred Items + +| Category | Item | Status | Deferred At | Milestone | +|----------|------|--------|-------------|-----------| +| *(none)* | | | | | + +## Session Continuity + +Last session: 2026-09-07 +Stopped at: Roadmap 修订完成（6 阶段，重排为玩法优先），等待规划 Phase 1 +Resume file: None