mirror of
https://github.com/motajs/template.git
synced 2026-09-13 02:08:50 +08:00
docs(01-06): complete raw map event ingestion plan
This commit is contained in:
parent
974669b00a
commit
a35e1e116d
@ -9,9 +9,9 @@ Requirements for the engine's completion. Each maps to roadmap phases.
|
||||
|
||||
### 事件系统（Event）
|
||||
|
||||
- [ ] **EVT-01**: 引擎提供事件系统的数据/序列化接口，支持 blockly 式低代码定义（编辑器在外部项目）
|
||||
- [ ] **EVT-02**: 事件系统能驱动简单场景的事件流程（踩踏触发链路；对话、开门依赖 A2 内建函数清单，延后到收尾工作）
|
||||
- [ ] **EVT-03**: 事件系统定位为初学者抽象，仅覆盖简单场景，不为复杂场景追求通用表达
|
||||
- [x] **EVT-01**: 引擎提供事件系统的数据/序列化接口，支持 blockly 式低代码定义（编辑器在外部项目）
|
||||
- [x] **EVT-02**: 事件系统能驱动简单场景的事件流程（踩踏触发链路；对话、开门依赖 A2 内建函数清单，延后到收尾工作）
|
||||
- [x] **EVT-03**: 事件系统定位为初学者抽象，仅覆盖简单场景，不为复杂场景追求通用表达
|
||||
|
||||
### 寻路（Pathfinding）
|
||||
|
||||
@ -52,9 +52,9 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| EVT-01 | Phase 1 | Pending |
|
||||
| EVT-02 | Phase 1 | Pending |
|
||||
| EVT-03 | Phase 1 | Pending |
|
||||
| EVT-01 | Phase 1 | Complete |
|
||||
| EVT-02 | Phase 1 | Complete |
|
||||
| EVT-03 | Phase 1 | Complete |
|
||||
| PATH-01 | Phase 2 | Pending |
|
||||
| PATH-02 | Phase 2 | Pending |
|
||||
| DATA-01 | Phase 3 | Pending |
|
||||
@ -65,6 +65,7 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
| TEST-01 | Phase 6 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
|
||||
- v1 requirements: 11 total
|
||||
- Mapped to phases: 11
|
||||
- Unmapped: 0 ✓
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## Overview
|
||||
|
||||
引擎从旧 mota-js 运行时逐步重构，渲染端已重构完成，数据端接口设计中。本路线图沿「事件系统 → 寻路 → 数据端完成 → 渲染适配 → legacy 移植 → 单元测试」的依赖顺序推进：先补齐剧情事件、自动寻路两大玩法系统，再完成数据端 L0–L3 接口落地，随后把新数据层与已重构渲染端打通并支持双布局，接着清理被新接口覆盖的 legacy，最后以单元测试兜底，使引擎能完整跑通一部魔塔。接口/架构设计由用户主导，AI 负责实现与测试，所有 git 提交须经用户 review。
|
||||
引擎从旧 mota-js 运行时逐步重构，渲染端已重构完成，数据端接口设计中。本路线图沿「事件系统 → 寻路 → 数据端完成 → 渲染适配 → legacy 移植 → 单元测试」的依赖顺序推进：先补齐剧情事件、自动寻路两大玩法系统，再完成数据端 L0–L3 接口落地，随后把新数据层与已重构渲染端打通并支持双布局，接着清理被新接口覆盖的 legacy，最后以单元测试兜底，使引擎能完整跑通一部魔塔。接口/架构设计由用户主导，AI 负责实现与测试；验证通过后 AI 可自行创建 git commit。
|
||||
|
||||
## Phases
|
||||
|
||||
@ -34,19 +34,28 @@ Decimal phases appear between their surrounding integers in numeric order.
|
||||
3. 引擎能执行踩踏触发事件驱动的事件执行链路（对话/开门依赖 A2 内建函数清单，延后到收尾工作）
|
||||
4. 事件系统保持面向初学者的简单抽象，未引入复杂场景的通用表达能力
|
||||
|
||||
**Plans**: 3 plans
|
||||
**Plans**: 6/10 plans executed
|
||||
Plans:
|
||||
|
||||
- [x] 01-04-PLAN.md
|
||||
- [x] 01-05-PLAN.md
|
||||
- [x] 01-06-PLAN.md
|
||||
- [ ] 01-07-PLAN.md
|
||||
- [ ] 01-08-PLAN.md
|
||||
- [ ] 01-09-PLAN.md
|
||||
- [ ] 01-10-PLAN.md
|
||||
|
||||
**Wave 1**
|
||||
|
||||
- [ ] 01-01-PLAN.md — L0/L1 事件数据契约落地 + 图块/点位事件视图 + 存读档迁移
|
||||
- [x] 01-01-PLAN.md — L0/L1 事件数据契约落地 + 图块/点位事件视图 + 存读档迁移
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
|
||||
- [ ] 01-02-PLAN.md — 执行器接口用户确认（checkpoint）+ 执行器实现 + 删除旧 ITrigger（D-13）+ CoreState 装配
|
||||
- [x] 01-02-PLAN.md — 执行器接口用户确认（checkpoint）+ 执行器实现 + 删除旧 ITrigger（D-13）+ CoreState 装配
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
|
||||
- [ ] 01-03-PLAN.md — moverImpl 踩踏触发重写为事件执行 + 阶段验收
|
||||
- [x] 01-03-PLAN.md — moverImpl 踩踏触发重写为事件执行 + 阶段验收
|
||||
|
||||
### Phase 2: 寻路系统
|
||||
|
||||
@ -115,7 +124,7 @@ Plans:
|
||||
1. 核心数据层系统有单元测试覆盖
|
||||
2. 测试覆盖关键行为（战斗伤害、触发器、寻路、事件等）
|
||||
3. 测试在本地可运行且全部通过
|
||||
4. 测试由 AI 编写，经用户 review 后提交
|
||||
4. 测试由 AI 编写并运行，通过验证后可提交
|
||||
|
||||
**Plans**: TBD
|
||||
|
||||
@ -126,7 +135,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
|
||||
|
||||
| Phase | Plans Complete | Status | Completed |
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. 事件系统 | 0/TBD | Not started | - |
|
||||
| 1. 事件系统 | 6/10 | In Progress| |
|
||||
| 2. 寻路系统 | 0/TBD | Not started | - |
|
||||
| 3. 数据端完成 | 0/TBD | Not started | - |
|
||||
| 4. 渲染适配与双布局 | 0/TBD | Not started | - |
|
||||
|
||||
@ -1,19 +1,20 @@
|
||||
---
|
||||
gsd_state_version: "1.0"
|
||||
current_phase: 1
|
||||
current_phase_name: 事件系统
|
||||
milestone: v1.0
|
||||
current_phase: 01
|
||||
current_phase_name: event
|
||||
status: executing
|
||||
stopped_at: Phase 1 context gathered
|
||||
last_updated: "2026-09-07T14:06:31.386Z"
|
||||
last_activity: 2026-09-07
|
||||
last_activity_desc: Roadmap revised (6 phases, 11 requirements mapped)
|
||||
state_head: 6f06b686560de391f0c76bf0b0e72658a94e3e37
|
||||
stopped_at: Completed 01-06-PLAN.md
|
||||
last_updated: "2026-09-08T15:55:40.633Z"
|
||||
last_activity: 2026-09-08
|
||||
last_activity_desc: Phase 01 Plan 05 decision recording completed
|
||||
state_head: 974669b00a0e356f51b59a5d124f43a1d85a75d1
|
||||
progress:
|
||||
total_phases: 6
|
||||
completed_phases: 0
|
||||
total_plans: 3
|
||||
completed_plans: 0
|
||||
percent: 0
|
||||
total_plans: 10
|
||||
completed_plans: 6
|
||||
milestone_name: milestone
|
||||
---
|
||||
|
||||
# Project State
|
||||
@ -23,22 +24,22 @@ progress:
|
||||
See: .planning/PROJECT.md (updated 2026-09-07)
|
||||
|
||||
**Core value:** 引擎能完整跑通一部魔塔——开局到结局，存档、战斗、地图、事件、剧情全链路可玩。
|
||||
**Current focus:** Phase 1 — 事件系统
|
||||
**Current focus:** Phase 01 — event
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 1 (事件系统) — READY TO EXECUTE
|
||||
Plan: 0 of TBD in current phase
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-09-07 — Roadmap revised (6 phases, 11 requirements mapped)
|
||||
Phase: 01 (event) — EXECUTING
|
||||
Plan: 6 of 10
|
||||
Status: Ready to execute next plan
|
||||
Last activity: 2026-09-08 — Phase 01 execution started
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
Progress: [█████░░░░░] 50%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
|
||||
- Total plans completed: 0
|
||||
- Total plans completed: 5
|
||||
- Average duration: N/A
|
||||
- Total execution time: 0 hours
|
||||
|
||||
@ -54,6 +55,13 @@ Progress: [░░░░░░░░░░] 0%
|
||||
- Trend: N/A
|
||||
|
||||
*Updated after each plan completion*
|
||||
**Per-Plan Metrics:**
|
||||
|
||||
| Plan | Duration | Tasks | Files |
|
||||
|------|----------|-------|-------|
|
||||
| Phase 01 P04 | 7min | 3 tasks | 2 files |
|
||||
| Phase 01 P05 | 17min | 2 tasks | 4 files |
|
||||
| Phase 01 P06 | 20min | 2 tasks | 4 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@ -65,7 +73,13 @@ Recent decisions affecting current work:
|
||||
- 接口/架构设计由用户主导；AI 仅做实现与测试
|
||||
- 渲染层先于数据层完成重构（既有顺序延续）
|
||||
- 阶段顺序调整为玩法优先：事件 + 寻路 → 数据端完成 → 渲染适配 → legacy 移植 → 单元测试
|
||||
- Git 提交必须经用户 review，AI 不擅自提交
|
||||
- AI 可在验证通过后自行创建 git commit，无需用户逐次审批；验证未通过不得提交
|
||||
- [Phase 01]: Serialized event registration and map event-id binding remain deferred; CoreState retains only a TODO and no new public registration API is added.
|
||||
- [Phase 01]: Source-aware dispatch uses IGameEventInvocation { id: string; env: IBlockEventEnv } and one full-sequence execute call.
|
||||
- [Phase 01]: IMapLayerSave.pointEvents uses index -> priority -> eventId, independent from map-matrix dirty, with pure-baseline overlay loading and crop/clear resize semantics.
|
||||
- [Phase 01]: Phase 01 Plan 05 preserves rawEvent as public Statement[] with constructor/setRaw aliasing, generic Promise<R>, and current as Promise<R> adapters; no defensive-copy, unknown, or cache-safety changes.
|
||||
- [Phase 01]: Phase 01 Plan 05 defers eventStore circular dependencies, preserving current imports and behavior and recording the exact check:circular paths as the phase baseline.
|
||||
- [Phase 01]: Plan 01-06 validates raw map event containers before registration and binds coordinate events to the event layer.
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@ -74,6 +88,8 @@ None yet.
|
||||
### Blockers/Concerns
|
||||
|
||||
- 数据层 L0–L3 接口设计仍在进行中（由用户主导），DATA-01（Phase 3）依赖接口设计落地
|
||||
- 01-08 rawEvent cache-safety and no-as implementation assumptions conflict with the explicit 01-05 user-approved current contract; replan before execution.
|
||||
- eventStore circular paths are explicitly preserved as the Phase 01 baseline; revise any gate that requires those paths to disappear before execution.
|
||||
|
||||
## Deferred Items
|
||||
|
||||
@ -83,6 +99,6 @@ None yet.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-09-07T10:26:54.613Z
|
||||
Stopped at: Phase 1 context gathered
|
||||
Resume file: .planning/phases/01-event/01-CONTEXT.md
|
||||
Last session: 2026-09-08T15:55:40.597Z
|
||||
Stopped at: Completed 01-06-PLAN.md
|
||||
Resume file: None
|
||||
|
||||
141
.planning/phases/01-event/01-06-SUMMARY.md
Normal file
141
.planning/phases/01-event/01-06-SUMMARY.md
Normal file
@ -0,0 +1,141 @@
|
||||
---
|
||||
phase: 01-event
|
||||
plan: 06
|
||||
subsystem: event-map-ingestion
|
||||
tags: [typescript, vitest, map, events, validation]
|
||||
requires:
|
||||
- phase: 01-event/01-04
|
||||
provides: User-approved point-event ownership and event-layer contract
|
||||
provides:
|
||||
- Validated raw map event ingestion into coordinate point-event views
|
||||
- Event-layer selection by the `event` layer alias
|
||||
- Malformed raw-input rejection before map registration with logger codes 62/63/64
|
||||
affects: [01-07, 01-09, 01-10, phase-01-verification]
|
||||
actuals:
|
||||
tokens: 4648
|
||||
tasks: 2
|
||||
commits: 3
|
||||
plan_head_before: 6f6ed62b1b401a8e1d51207ba7b08c8e7935dfb2
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- Runtime validation completes before `createMap` so malformed input cannot leave partial registration
|
||||
- Serialized coordinate events are loaded into `ILayerEventView` and marked pure
|
||||
key-files:
|
||||
created:
|
||||
- packages-user/data-base/src/map/eventPath.test.ts
|
||||
modified:
|
||||
- packages-user/data-base/src/map/mapState.ts
|
||||
- packages-user/data-base/src/map/mapLayer.ts
|
||||
- packages/common/src/logger.json
|
||||
key-decisions:
|
||||
- "Raw point events remain coordinate-owned and are never written into a static tile event view."
|
||||
- "Malformed map/event containers, ranges, and leaf values are rejected before map registration; codes 62, 63, and 64 retain distinct meanings."
|
||||
patterns-established:
|
||||
- "Dynamic and point-event indexes use explicit Map lookup/insertion rather than unsupported runtime upsert methods."
|
||||
requirements-completed: [EVT-01, EVT-02, EVT-03]
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Valid serialized point events populate the event layer's coordinate view and leave tile events clean."
|
||||
requirement: EVT-01
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "packages-user/data-base/src/map/eventPath.test.ts#raw point events and event layer"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "Malformed raw map/event structures are rejected without registering a floor and use semantic logger codes."
|
||||
requirement: EVT-01
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "packages-user/data-base/src/map/eventPath.test.ts#MapState malformed raw event structures"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
duration: 20min
|
||||
completed: 2026-09-08
|
||||
status: complete
|
||||
commits: 3
|
||||
plan_head_before: 6f6ed62b1b401a8e1d51207ba7b08c8e7935dfb2
|
||||
---
|
||||
|
||||
# Phase 01 Plan 06: Raw Map Event Ingestion Summary
|
||||
|
||||
**Validated serialized map event ingestion with coordinate-bound point views, event-layer selection, and no-partial-registration guarantees**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 20 min
|
||||
- **Started:** 2026-09-08T15:39:21Z
|
||||
- **Completed:** 2026-09-08
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 4
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Connected `MapState.fromRaw` to the coordinate point-event view and selected the actual event layer by alias.
|
||||
- Added pre-registration runtime validation for raw map/event containers, numeric keys, positions, priorities, and string event ids.
|
||||
- Added focused Vitest coverage for valid ingestion, pure baselines, malformed input, semantic logger codes, and no half-registered floor.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: 贯通 raw map → point event view → eventLayer 的真实地图路径** - `564ef25` (fix)
|
||||
2. **Task 2: 在地图注册前拒绝 malformed raw event 结构** - `a730f33` (fix)
|
||||
3. **Task 2 blocking runtime fix: replace unsupported Map upsert calls** - `974669b` (fix)
|
||||
|
||||
**Plan metadata:** pending state/summary commit
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `packages-user/data-base/src/map/mapState.ts` - Validates raw structures before registration and binds point events to coordinate views.
|
||||
- `packages-user/data-base/src/map/eventPath.test.ts` - Covers valid point ingestion and malformed raw rejection.
|
||||
- `packages/common/src/logger.json` - Adds code 63 for invalid containers and code 64 for invalid leaf/range values.
|
||||
- `packages-user/data-base/src/map/mapLayer.ts` - Replaces unsupported Map upsert calls with explicit lookup/insertion required by the Node test path.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- Kept point-event ownership in the coordinate view and did not bind serialized point ids to static tile views.
|
||||
- Kept event registration and event-store population deferred; this plan only establishes the map-side event-layer path.
|
||||
- Used code 62 only for non-numeric keys, code 63 for missing/null/non-object containers, and code 64 for invalid leaf values or ranges.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Replaced unsupported Map upsert runtime calls**
|
||||
- **Found during:** Task 1 verification
|
||||
- **Issue:** The Node Vitest runtime did not provide the `Map.prototype.getOrInsertComputed`/`getOrInsert` methods used by the point and dynamic indexes, so valid raw ingestion crashed before assertions.
|
||||
- **Fix:** Replaced the affected `MapLayer` upsert calls with explicit get/create/set logic, including the dynamic save aggregation path in the same file.
|
||||
- **Files modified:** `packages-user/data-base/src/map/mapLayer.ts`
|
||||
- **Verification:** Focused Vitest and ESLint pass.
|
||||
- **Committed in:** `974669b`
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (Rule 3 - blocking)
|
||||
**Impact on plan:** The fix was limited to the directly blocking runtime behavior and introduced no public API change.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- Focused tests initially exposed the unsupported Map upsert runtime dependency; it was fixed inline before the plan verification was rerun.
|
||||
- Repository-wide type, circular-dependency, and unrelated lint debt remains outside this plan's scope and was not changed.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Plan 01-10 can build on the validated layer and point-event views for tile defaults and lifecycle persistence.
|
||||
- CoreState's legacy event-layer initialization and production serialized-event registration remain deferred to the user's later revised 01-09 decision.
|
||||
|
||||
---
|
||||
*Phase: 01-event*
|
||||
*Completed: 2026-09-08*
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- All planned implementation/test files and this summary exist.
|
||||
- Task commits `564ef25`, `a730f33`, and `974669b` are present in git history.
|
||||
- Focused Vitest and ESLint verification passed; unrelated working-tree changes remain unstaged.
|
||||
Loading…
Reference in New Issue
Block a user