Merc-FJU 3.0 MUD AREA 重建工作流筆記

這個分支目前在做什麼

這個分支把舊 MUD 的區域開發整理成比較明確的 spec-first 流程：

1. 先用 area/world_map.md 決定世界拓樸、母城位置與交通主骨架。

2. 再用 plans/area/*.md 與 area/rebuild_plan.md 管單區 queue、 delivery_gate 與下一步。

3. 單區設計落在 area/<area>/map.md ，其中的 mapmd-json 是 machine-readable canonical graph。

4. 接著用 generator 投影 .roo ，再補 index / mob / obj / res / shp / directory.lst。

5. 最後用 build、startup smoke、 log/*、 debug/* 與 world checker 證明 area 真的可載入。

以 2026-03-26 這次檢視為例，tracker 的狀態大致如下：

也就是說，這個分支不是零散地補房間，而是持續沿著 world graph 把單區 spec、runtime 邊界與驗證證據一起補齊。

Source of Truth 順序

這個 repo 對 area rebuild 的事實來源有明確順位，讀檔順序大致如下：

有一條很重要的判讀原則：

• 如果 map.md 的 prose 和 mapmd-json 不一致，先以 mapmd-json 為準，再回頭修 prose。

七層開發流程

整條 AREA rebuild pipeline 可以拆成七層：

1. World Graph

   • 入口是 area/world_map.md

   • 用來決定城市、驛站、關隘、野外與地下鏈在世界骨架上的相對位置

2. Area Queue

   • 入口是 area/rebuild_plan.md

   • 決定現在該做哪一區，而不是想到哪就補哪

3. Area Plan

   • 入口是 plans/area/NNNN-*.md

   • 固定 level_range、 reserved_room_block、 external_links、 theme_basis

4. Area Spec

   • 入口是 area/<area>/map.md

   • 把 narrative spec 與 mapmd-json 寫在同一份檔案裡

5. Projection + Implementation

   • 用 generator 產出 .roo

   • 再補 index / mob / obj / res / shp / directory.lst

6. Runtime Validation

   • 跑 spec validate、world checker、build、startup smoke、log/debug 檢查

7. Commit / Merge Gate

   • 依 delivery_gate 決定是繼續修、先 commit，還是可以進下一區

新 AREA 的最小操作流程

如果要照這個分支的方式新增或重建一個 area，最小流程可以抓成下面這樣：

1. 先讀 AGENTS.md、 area/rebuild_plan.md 、對應 plans/area/NNNN-*.md。

2. 確認 area slug、 level_range、 reserved_room_block、 planned_vnum_range、 external_links。

3. 撰寫 area/<area>/map.md ，把 narrative spec 與 mapmd-json 一次補齊。

4. 先驗證 spec，再決定要不要輸出 .roo。

5. .roo 穩定後，再補 index / mob / obj / res / shp。

6. 把 area 掛進 area/directory.lst ，並同步 boundary room。

7. 跑 build、startup smoke、 log/*、 debug/* 、world checker。

8. 更新 tracker、單區 plan、必要的 current-game registry，最後再看 delivery_gate 能不能前進。

常用命令大致會長這樣：

reload 指令不要誤會

這點很重要，因為它會直接影響你怎麼設計開發節奏：

• 單區修改完成後，不是只靠遊戲內重載指令就算驗證完畢。

• 真正可信的證據是 loader 可讀、邊界相通、build 成功、startup 有成功訊號，而且 debug/* 沒冒出新的 area 相關錯誤。

city_hongnong 為什麼值得拿來當樣板

如果要找一個目前最適合拿來參考的 area，我會優先看 city_hongnong ，原因是它把整條鏈串得很完整：

• 有單區計畫： plans/area/0102-city-hongnong.md

• 有完整 spec： area/city_hongnong/map.md

• 有 mapmd-json

• 有 generator 輸出的 roo/18701-18711

• 有 index / mob / obj / res / shp

• 有 fort_hulao/14101 <-> city_hongnong/18701 的 runtime boundary

• 有 tracker 記錄 validation 結果，最後停在 implementation_ready_for_commit

如果想看不同 family 的對照樣板，也可以一起讀：

• road_north_border

  • 看道路型 area 怎麼接城市邊界

• fort_northern_watch

  • 看關隘 / watch 類型的 runtime milestone 怎麼收斂成可提交狀態

目前 queue 的節奏

這個 workflow 不是單純照世界圖一路往西抄，而是刻意維持 queue variety。 2026-03-26 檢視時：

• Todo 是空的

• In Progress 只有 city_hongnong

• Current Recommended Next Step 是先 commit city_hongnong

• commit 後，下一個 west-line actionable area 才是 wild_hongnong_farmland

這代表固定 prompt 繼續實作下一個待建 area 的真正意思是：

• 先續做目前可執行的 area

• 只有當 delivery_gate 允許，才切到下一區

• 不能因為想先做新題材，就跳過還沒收乾淨的 in_progress

參考入口

• AGENTS.md

• plans/0001-world-map-area-rebuild.md

• area/rebuild_plan.md

• area/world_map.md

• docs/area-development-handbook.md

• docs/codex-area-workflow.md

• area/city_hongnong/map.md