adventure-table

M01 — 實作規格

Phase：M01 — Multi-Source Character Content Expansion
類型：M Phase（Modification / Maintenance Phase）
本文件定義目前已拍板 M01 Subphase 完成後什麼必須為真。A～N 是截至 2026-09-06 已完成的 baseline；M01 現為長期保持 open 的 Character Content Expansion / Maintenance track，M01-O 已拍板為 XGE / TCE Feat Expansion。具體資料格式、schema、模組、API、migration 與接線放在 開發設計方針.md；自動與人工驗收方式放在 測試指南.md。

最後更新：2026-09-13

1. M01 定位

P0 / P1 已完成 Character Core、SRD 5.1 Content Foundation、Character Builder、Level Up、immutable Build Versions 與 Current State。M01 不重做這些地基；M01 要解決的是：

  1. SRD 5.1 角色內容量不足。
  2. Content Registry / StableKey / Builder 仍有 srd5.1 單一來源假設。
  3. 使用者提供的 PHB / SCAG / GoS / VGM / VRGR / XGE / TCE / MTF 等私人規則資料，需要逐批正式轉成 runtime content。
  4. 新內容若帶來現有角色系統尚未正式表示的規則形狀，M01 只補該批資料真正需要的最小通用能力，不建立大而全的 future engine。
  5. PHB 相對 SRD 缺少的 Feats / Spells 已在 M01-K 補成正式 runtime catalog，而不是只停留在 reference Markdown。
  6. M01-L / M01-M 進一步補齊當時已拍板的 VGM / SCAG / MTF 種族範圍，並補上 Race/Subrace movement、negative racial modifier compatibility、Natural Armor、Tiefling replacement composition、conditional movement 與 live ancestry mode 等最小通用能力。
  7. M01-O 正式補入 XGE 15 個種族專長與 TCE 15 個通用專長，共 30 個 Feats。 這批內容必須沿用 M01-K 的 Feat acquisition / prerequisite / nested choice / provenance 地基，只新增這 30 個 Feats 真正需要的有限通用規則形狀。
  8. Magic Items 尚未正式納入目前已完成 baseline。 魔法物品_TCE.md 保留為 reference；未來若要做，必須另拆新的 M01 Subphase，不因 M01 長期 open 而自動視為 scope。

M01 的目標從來不是「一次做完整 D&D」；現在正式定案為長期內容／維護軌：把當下確定要加入的角色內容做成可靠的 Multi-Source Character Content，讓每個已拍板 Subphase各自完成、各自驗證，而不是等待一個永遠不會真正成立的「所有角色內容都補完」final closeout。

歷史執行順序曾為：

M01-A → M01-B → M01-C
→ 暫停 M01
→ M02 — Traditional Chinese / English Localization
→ 回到 M01-D → ... → M01-K → M01-L → M01-M → M01-N

M02 closeout 後從 M01-D 接續的歷史編號不變。A～N 現已各自 closeout；M01-O 為下一個已拍板、尚未實作的內容 Subphase。

自 2026-09-06 起，取消「Full M01 Integration & Closeout 才能進 P2」這個前置 gate。 M01 保持 open，正常產品 Roadmap 已可進入 P2；新的 M01 內容依序接續編號。M01 不改寫 P2～P8 的產品 Roadmap，也不因自己保持 open 而阻塞 P Roadmap。

2. M Phase 全專案規則

M Phase 使用：

M01
M02
M03
...

適用於：

M Phase 與 P Phase 相同：

M Phase 不得拿來偷跑未來產品系統。例如 M01 遇到 Combat feature時，可以保存 metadata，但不得因此提前建立 P4 Combat Engine。

3. M01 資料來源與正式資料原則

3.1 supplied reference documents

本 Phase 已提供／可能持續新增的 reference 放在：

docs/暫用規則資訊/

目前已使用過的範圍包含 PHB / SCAG / GoS / VGM / VRGR / XGE / TCE / MTF 的角色相關資料。這些檔案是：

human / maintainer reference

不是 runtime source。

Reference Markdown 內的規則描述文字可以在 authoring / materialization 階段直接搬進正式 runtime data / localization。 禁止的是 runtime 將 Markdown 本身當作規則資料源，不是禁止複製 reference text。

Reference 中的 mechanics / metadata 仍必須在 materialization 時依正式 source identity 正規化。不同來源新增的 access / option / reprint provenance不能因為整理在同一份 Markdown就混成同一 canonical source。

魔法物品_TCE.md 目前仍只是 future reference；未來若正式導入，必須另拆新的 M01 Subphase。

3.2 Runtime Source of Truth

某項內容正式導入後：

data/<pack>/...

才是程式 Source of Truth。

禁止 runtime：

Markdown 可以保留 provenance / reference，也可以作為 authoring-time規則文字來源，但不與正式 JSON形成雙主來源。正式 runtime data 與 reference若日後出現差異，runtime一律以 data/<pack>/... 與既有 localization SSOT為準。

3.3 Pack identities

目前 baseline 正式使用：

srd5.1
phb2014
scag
gos
vgm
vrgr
xge
tce
mtf

M01-O 沿用既有 xge / tce pack，不新增別名 pack。未來 M01-P+ 可按新 Subphase正式新增 pack。Stable identity 不因中文翻譯、UI顯示名稱或檔名變動。

3.4 Private project boundary

Repository 為私人朋友使用專案。M01 不建立 Marketplace、Publisher backend、公開 Content Pack distribution 或商業 license workflow；但來源／provenance仍要明確，因為它直接影響資料 identity與未來維護。

4. M01 共通硬原則

4.1 StableKey

正式格式：

<pack-id>:<kind>:<index>

同 kind:index 不同 pack可共存。Display Name永遠不是 foreign key。

4.2 content_sources

CharacterBuild.content_sources 的 canonical semantics：

該 Build 實際引用到的 Content Pack 集合。

由 server compiler依 candidate Build refs derive；不信任 client手填，也不得拿來當 Builder allowlist / permission gate。

4.3 Server authoritative

M01所有新規則仍走：

Builder Draft
→ server choices / compile / validation
→ Review
→ Confirm
→ immutable CharacterBuild

Frontend 不 hardcode D&D legality。

4.4 Build vs Current State

延續 P0/P1：永久角色選擇與來源屬 Build；目前 HP、resources、prepared、Inventory、active infusion、feature mode等 live state屬 Current State。新增 M01 不得破壞這條邊界。

4.5 不做 Universal Rules DSL

M01 可以增加當批資料真正需要的 finite primitive；但不做 arbitrary expression language、user-authored scripts、combat trigger DSL 或 generic effect interpreter。

4.6 Automation 等級

優先：identity/source → Builder legality → Build/State persistence → Sheet/Review presentation → 已有 substrate可安全支援的 automation。需要未來 Combat / Rest / Roll / day-clock的效果可 structured + manual；UI不得把 manual effect誤表示為已自動套用。

4.7 Localization 承接

M02 已建立的永久規則持續適用所有未來 M01 Subphase：新增或修改 user-visible UI / rules presentation，同一 Subphase同步提供 zh-TW / en；StableKey / mechanics identity不因翻譯改變；缺 required locale視為該 Subphase未完成。

4.8 M03 standalone compatibility

M03 已交付後，M01 也多了一條永久相容責任。未來 M01-O+ 若碰到：

Character Build / State / Version
StableKey / Content Registry
Builder provenance
Character JSON schema / import / export
shared Character APIs / DTOs

必須同步做 M03 standalone compatibility review。角色／內容核心不得反向依賴 Room / Campaign / Session / Seat / Party Roster等多人層；Web↔Standalone JSON exchange若受影響，要在同一 Subphase說明 schema與相容策略。

4.9 Downstream P compatibility

P2 之後，新的 M01 Subphase不再只需要保證 P0/P1。若改動會影響已完成的後續 P Phase consumer，該 M01 Subphase必須把那些直接受影響的 P Phase regression列入 closeout。這個相容集合會隨正常 Roadmap前進而擴大。

5. 已完成 baseline 與後續編號

截至 2026-09-06 已逐項 closeout：

M01-A — Multi-Source Content Pack Foundation
M01-B — PHB Character Origins & Background Expansion
M01-C — SCAG / GoS Background Expansion
M01-D — VGM Race Expansion
M01-E — SCAG Half-Elf Variant & Grant Replacement
M01-F — VRGR Lineage & Dhampir
M01-G — TCE Artificer Core
M01-H — TCE Artificer Advanced Features & Infusions
M01-I — TCE Optional Class Features & Fighting Styles
M01-J — 2014 Class Subclass Expansion
M01-K — PHB Feat & Spell Catalog Expansion
M01-L — VGM & SCAG Remaining Race Expansion / Generic Race Mechanics
M01-M — MTF Planar Race Expansion & Tiefling Bloodline / Variant System
M01-N — Character Sheet HTML Export

每個已完成 Subphase的完整實作與驗收證據由本目錄既有 M01-*_CLOSEOUT.md、git history與對應測試承擔。

已拍板、尚未實作：

M01-O — XGE & TCE Feat Expansion

下一個未使用字母是 M01-P。 不預留任何字母給 Full Closeout，也不要求先決定「M01最後一個內容 Subphase」。後續只有在使用者正式拍板下一批內容後，才把 P / Q / R… 的完整規格同步加入本文件、開發設計方針.md 與 測試指南.md。

6. M01 Long-Running Track Policy

6.1 沒有「全部內容完成」的 final gate

M01 不再宣告某一刻「D&D 2014角色內容全部完成」。A～N代表目前已正式交付的 baseline；M01-O 是目前已拍板的下一項內容。新的書籍內容、Magic Items、角色規則補強或 UI / rules presentation改進都可以日後再以新的 M01 Subphase加入。

因此：

M01 open
≠ P2 blocked
≠ M01-A～N 未完成

6.2 每個新增 Subphase 自己關門

未來 M01-O+ 每項都必須：

不建立一個無限延後的總體 closeout來替代每個 Subphase的責任。

6.3 Cumulative regression 是 reference，不是一次性的 final closeout

A～N累積出的完整 Character regression仍然有價值，但用途改為：

具體 cumulative matrix放在 測試指南.md。它不是 P2開始前必須再跑一次的 gate，也不代表未來每個小型 M01都必須跑完整矩陣。

6.4 Magic Items 等 deferred scope

目前未正式納入的 Magic Items / generic Attunement / item charges / magic-item modifier automation等仍是未拍板 future scope。它們只有在使用者明確決定後，才成為新的 M01-P+ Subphase；不能因 M01長期 open就被默認納入，也不能因尚未完成而阻塞 P2。

6.5 P2+ handoff

P2現在可以正式進入規格設計與實作。後續 M01與P Roadmap可以交錯進行，但共享 contract的修改必須遵守 §4.8 / §4.9 的 standalone與downstream compatibility規則。

7. M01-N — Character Sheet HTML Export

7.1 Scope

角色卡可以輸出成一份單向、只給人看的 HTML。使用者自選輸出範圍：

角色配置（Build only）
當前快照（Current copy）

產品層行為以 規格企劃.md 第十一章 Export 段為準，本節不複述，只定義完成後什麼必須為真。

本 Subphase 不含：Character JSON schema 變更、新 server endpoint、新 DTO 欄位、任何 Import 路徑、Version History 或多版本輸出。

7.2 完成後必須為真

  1. 角色卡上可以叫出 HTML 輸出，且輸出範圍由使用者選。 既有的 Character JSON 匯出入口行為不變。
  2. 輸出檔自足。 不含 script、不連外部樣式／字型／圖片、不打任何 API；在沒有本站、沒有網路的環境雙擊即可正確呈現。
  3. 輸出檔是完整角色卡。 目前角色卡的三個分頁內容全部攤平在同一份文件裡，不靠分頁互動。
  4. 角色配置不輸出 Current State。 具體為：目前 HP／臨時 HP、剩餘 Hit Dice、剩餘法術位、剩餘職業資源、狀態（conditions）、已準備標記與物品欄皆不出現；Max HP、Hit Dice 總量、法術位總格數、資源容量照常出現。
  5. 角色配置仍輸出完整法術存取清單（存取由 Build 決定），但不標記哪些已準備。
  6. 角色配置仍輸出 AC，並在文件內註明其計算基準包含目前裝備。 AC 由 Build 與 State 共同決定，這是刻意保留並揭露的例外。
  7. 當前快照輸出角色卡目前顯示的全部內容，包含上述所有 Current State。
  8. 兩份輸出一眼可分辨。 檔名與文件開頭都標明範圍與 Build Version；當前快照另外標明輸出時間。
  9. 輸出檔可列印。 以瀏覽器列印或另存 PDF 時不輸出深色底，卡片不被切在跨頁處。
  10. 語言凍結在輸出當下的 locale，且 zh-TW / en 皆可正確輸出。輸出檔本身不提供語言切換。
  11. 沒有任何 Import 路徑接受這個格式。 產品與程式層都不得把 HTML 當成可讀回的資料來源。
  12. 只輸出請求者本來就看得到的資料。 輸出內容取自角色卡已呈現的資料，不得為了輸出而取得額外資料。
  13. 單機版行為與網頁版一致。 standalone boundary 不因本功能改變。

7.3 不做

8. M01-O — XGE & TCE Feat Expansion

8.1 Scope / inventory

本 Subphase只處理 docs/暫用規則資訊/專長_TCE_XGE.md 已整理的 2014 規則內容：

XGE — 15 個 Racial Feats
TCE — 15 個 Feats
合計 — 30 個 Feats

來源 identity 分別維持既有 xge / tce pack；reference Markdown 只作 authoring 來源。正式 runtime 資料、雙語 presentation與 mechanics metadata 必須 materialize 進既有 content / localization SSOT，runtime 不得讀 Markdown。

本 Subphase 不含：TCE Magic Items、XGE / TCE 其他章節內容、2024 Feats、完整 Combat / Reaction / Rest / Spell Engine、Firearms 完整裝備 catalog、Poison crafting subsystem。

8.2 完成後必須為真

  1. Inventory 完整且來源正確。 XGE 15 / 15、TCE 15 / 15，全數可由 Registry 解析；StableKey 唯一、pack provenance 正確、沒有用 display name 去重，也沒有把 later-source Feat 偽裝成 phb2014 / srd5.1。
  2. 沿用同一套 Feat acquisition。 Variant Human、ASI → Feat、High-Level Create、Level Up、Build Edit 等既有取得路徑都使用同一 server-authoritative Feat pool / prerequisite / nested-choice resolver，不建立 XGE/TCE 專用 Builder。
  3. 新增 ancestry prerequisite 能力。 Server 可正確表示並驗證 race / subrace / lineage-compatible ancestry prerequisite，以及 Dwarf OR Small race 這類 compound predicate；不得靠中文／英文顯示名稱判定。至少覆蓋 Dragonborn、Drow、Dwarf、Elf / Half-Elf、Gnome、High Elf、Tiefling、Half-Orc、Human、Variant Human (phb2014:race:variant-human)、Half-Elf / Half-Orc、Halfling、Wood Elf 與 Small size predicate；Variant Human 雖是獨立 race StableKey，仍必須在 ancestry prerequisite 語意上被視為 Human。
  4. 既有 prerequisite atom 繼續共用。 Spellcasting or Pact Magic、martial-weapon proficiency與其他既有 ability / proficiency / compound prerequisite 必須由同一 resolver 判定；不因 Eldritch Adept / Metamagic Adept / Fighting Initiate另寫 hardcode。Spellcasting or Pact Magic atom 必須同時承認 subclass 授予的 Spellcasting feature（例如 Eldritch Knight、Arcane Trickster 於 subclass level 3 取得的 Spellcasting），不得只看 class 是否為施法職業；此擴充同時回饋給既有使用同一 atom 的 PHB Feat，不另建 M01-O 專用判定。
  5. Ability Score +1 是正式 structural choice。 Dragon Fear / Hide、Dwarven Fortitude、Elven Accuracy、Fade Away、Fey Teleportation、Flames of Phlegethos、Infernal Constitution、Orcish Fury、Second Chance、Squat Nimbleness，以及 TCE 的 Chef / Crusher / Fey Touched / Gunner / Piercer / Shadow Touched / Skill Expert / Slasher / Telekinetic / Telepathic 等，只能從各自合法能力集合選擇並受 20 上限與既有 ASI/feat compile 規則約束。
  6. 技能／工具／語言／Expertise choices 結構化。 Prodigy、Skill Expert、Squat Nimbleness、Chef、Poisoner、Artificer Initiate 等使用既有或最小泛化的 proficiency / language / expertise primitive；Artificer Initiate 必須提供「自選一種工匠工具熟練」，且同一被選工具還要保留「可作為施展任何以 INT 為施法關鍵屬性的法術之法器」的 typed relation，不得只存成一段 description。Expertise只能選已熟練且尚未受同類 double-proficiency效果覆蓋的技能。新取得的技能若規則允許，可以成為同一次 acquisition 的 Expertise候選。Fey Teleportation 的 Sylvan 語言也必須以正式 language grant 保存。
  7. 既有 option pool 可被 Feat 合法重用。 Fighting Initiate 使用 Fighter Fighting Style pool且排除角色已擁有的 style；Eldritch Adept 使用 canonical Eldritch Invocation pool並遵守「有 prerequisite 的 invocation 只有符合條件的 Warlock 才能選」；Metamagic Adept選兩個 distinct canonical Metamagic options。不得複製第二份 style / invocation / metamagic catalog。
  8. Feat-linked retraining 版本化。 Eldritch Adept 的 invocation 在每次 Level Up可替換；Fighting Initiate與 Metamagic Adept只在升到取得 ASI feature 的 class level時開放其規則允許的替換。替換產生新的 Build Version，舊版本保留原選擇。
  9. Feat-granted spell access 正確。 Drow High Magic、Fey Teleportation、Wood Elf Magic、Artificer Initiate、Fey Touched、Shadow Touched、Telekinetic、Telepathic等沿用 canonical Spell identity / source-aware access；固定法術不複製 spell definition，自選法術依規則限制 level / school / class list；施法關鍵屬性、free-cast recharge與可使用自身 spell slots的語意必須保存在 Build / feature metadata中，不得錯寫成一般 class Known / Prepared。
  10. 依選定能力值決定 spellcasting ability 的關聯要保留。 Fey Touched / Shadow Touched / Telekinetic / Telepathic所選 INT/WIS/CHA +1 同時決定該 Feat法術的施法屬性；不能在資料或 UI 中拆成互相矛盾的兩個獨立選擇。
  11. 現有 static / derived substrate 能做的效果要接上。 Dragon Hide 的未著甲 AC candidate沿用 Natural Armor substrate；Squat Nimbleness 的 walking speed +5沿用 movement contribution；Infernal Constitution的 resistance / poisoned-save advantage等可由既有 Character Rules / Sheet安全呈現的靜態事實必須結構化。Gunner 的 firearms proficiency 必須保存成 typed weapon-proficiency fact／category，而不是引用不存在的 firearm equipment entity；M01-O 不因此導入完整 DMG firearm catalog。 Telepathic 的 60 ft 單向心電感應也必須保存成 typed static communication fact，至少包含 range、需看見目標、使用已知且目標能理解的語言、以及不賦予對方心電回覆能力。若某項現有 DTO尚未正式呈現，至少保留 machine-readable mechanics與雙語說明，不為顯示而發明錯誤自動化。
  12. Metamagic Adept 的 2 Sorcery Points 不得失真。 必須保存「可與其他來源累加，但這 2 點只能用於 Metamagic」的來源／用途限制。若現有 resource aggregation不能同時保留限制，必須補最小通用的 source-scoped contribution / spend-tag能力，不能把這 2 點無條件變成可拿去做 Flexible Casting 的一般 Sorcery Points。
  13. runtime automation boundary 要逐 Feat 分類。 需要 Combat / Reaction / Roll / Rest / turn timing / target geometry才可執行的效果，例如 Bountiful Luck、Dragon Fear、Dwarven Fortitude、Elven Accuracy、Fade Away、Flames of Phlegethos、Orcish Fury、Second Chance、Crusher / Piercer / Slasher、Poisoner、Telekinetic push等，可以 structured + deferred/manual；但必須保存足夠 identity / trigger / usage / recharge / description metadata，UI不得聲稱已自動套用。
  14. Character presentation完整。 Review / Character Sheet能顯示 Feat名稱、來源、description與已選 nested options；zh-TW / en 同一 Subphase交齊。Combat-deferred效果仍要讓玩家看得懂自己擁有什麼，不因未自動執行而消失。
  15. Persistence / provenance穩定。 Create / Level Up / Build Edit / reload / server restart後，Feat acquisition identity、nested choices、spell/style/invocation/metamagic selections、content sources與Version History保持一致；不 in-place rewrite歷史 Build。
  16. Standalone保持可用。 xge / tce Feat content與新 generic rule shape必須留在 shared Character / Content core；Standalone Builder / Character JSON若攜帶這些 StableKey與選擇，不能因多人層 dependency而失效。
  17. Downstream P2/P3不得被破壞。 Room Character Workspace仍可建立／編輯含 M01-O Feat的角色；Campaign / Seat / Session對 Character identity與既有 Character payload的引用不因本次 content expansion改變。若實作最終改到 shared DTO/schema，closeout必須加上直接受影響的 P2/P3 regression。

8.3 明確不做

This site is open source. Improve this page.