adventure-table

P4 — 實作規格

Phase：P4 — Quick Combat
本文件只定義 P4 各 Subphase 完成後什麼必須成立。具體 DB schema、API、module、MCP tool、transaction 與 persistence wiring 放在同目錄的 開發設計方針.md；自動／人工驗收與 closeout evidence 放在 測試指南.md。

最後更新：2026-09-13

1. P4 定位

P3 已把 active Session 做成可長時間運作的 Exploration table，具備 durable event stream、Chat / Action / Check、Server authoritative formal rolls、Current State mutation、Human / AI controller、DM proxy 與正式 MCP 入口；M04 又把真實 ChatGPT Web Plus 接入、OAuth、AI Join Kit 與 server-hosted guide 補齊。

P4 是第一個正式 Combat Phase，交付 Quick Combat：保留桌上跑團的敘事與 DM 裁定方式，不建立座標、距離或格線幾何，網站只接手真正值得由 Server 同步、計算、保存與驗證的 Combat State。

P4 關門後，Human DM、Human Player、AI DM、AI Player 必須能在同一場 Quick Combat 中：

P4 不是 Tactical Combat。Grid、token coordinates、movement budget、distance、range geometry、AoE cells、wall / door / terrain、automatic Opportunity Attack detection、battle-map editor 全留 P5。

P4 也不建立 P6 Adventure Runtime / EncounterTemplate，不把 Combat log 擴成 P7 完整 Timeline / Snapshot / Restore，不做 CRPG 式 Victory Screen / Auto Loot。

2. P4 固定 Subphase

P4 固定拆成六個可獨立實作、驗證與 commit 的 Subphases：

P4-A — Monster & Combatant Foundation
↓
P4-B — Combat Lifecycle, Initiative & Action Economy
↓
P4-C — Attack, Damage & Core Action Resolution
↓
P4-D — Spells, Conditions, Concentration & Reactions
↓
P4-E — Quick Combat UI, DM Adjudication & AI Tool Surface
↓
P4-F — Full P4 Integration & Closeout

三份 P4 文件必須使用完全一致的名稱與順序。

不得在 P4-A 順手做 Tactical token / grid；不得在 P4-D 為了支援所有特殊能力建立 generic effect DSL；不得在 P4-E 因 AI DM 需要 encounter context 就提前建立 P6 Adventure / Scene / NPC runtime；不得把 P4 event / combat history包裝成 P7 完整 Timeline。

3. P3 / M04 → P4 必須承接的既有真實邊界

P4 不重造以下既有能力：

P4 新 Combat action 必須沿用以上 authority 與 event substrate，不另建 Combat-only Human identity、AI roll engine、secret filter 或第二套 Character Current State updater。

3.1 Combat 可以跨 Session 延續

產品既有規格明定：End Session 不會結束 Combat、不會清 HP / Conditions / pending gameplay state。P4 因此必須把 active Combat 視為 Campaign gameplay state，而不是只存在某個 Session 的暫存 UI。

結果必須成立：

第一版同一 Campaign 同時只允許一場 active Combat；歷史 ended Combat可保留供未來 Timeline 使用。

4. P4 全 Phase 共用產品邊界

4.1 Quick Combat 沒有 geometry

Quick Combat 本質是：

Exploration UI + canonical Combat State

以下由 Server正式處理：

以下 不由 P4 自動推導：

Quick Combat 不建立假的 coordinates、Zone System 或 hidden distance number。Position Note完全 optional；真人 DM可全部口頭描述。

4.2 自動化深度

P4 的原則是：常見且可可靠結構化的核心戰鬥規則自動化；複雜、敘事型、罕見或需要世界判定的能力交給 DM。

必須自動化的核心：

允許部分結構化 + description + DM adjudication：

P4 不建立 generic rules DSL / scripting language 來追求 100% D&D 自動化。

4.3 正常命中後直接 resolve，不逐擊 DM Confirm

一般 Attack / Spell 若所有必要輸入都已確定：

Choose action / target
→ Server validate action economy + resources
→ formal roll(s)
→ resolve hit/save
→ damage/healing/effect
→ commit Current State + Combat State + event atomically

不要求每一擊都停給 DM按「Approve Damage」。

只有 Quick Combat 無法自行知道的空間／裁定資訊才需要 DM，例如：

Human DM 可在事後用既有 Direct Edit /合法 state edit修正小錯；第一版仍不做 Undo Transaction。

4.4 Turn 與 action economy 是硬規則，但不把 Freeform 鎖死

4.5 敵人資訊 visibility

DM 取得完整 Monster Instance / Combatant combat data。

Player / AI Player 預設不得取得：

Player可取得：

所有 secrecy 必須在 Server projection / DTO層完成，不可把精確資料送到 client後靠 CSS隱藏。

P4-A — Monster & Combatant Foundation

目標

建立 P4 / P5 共用的非空間 Combat data foundation，並把 P0 延後的 完整 SRD 5.1 Monster / Beast stat blocks 納入正式 content pipeline。

完成後必須為真

  1. Monster Template、Monster Instance、Combatant 是不同概念：Template是可重用規則資料；Instance是某個世界／戰鬥中的 live state；Combatant是 Combat Engine共用視圖／行為介面。
  2. SRD 5.1 的 Monster / Beast templates全數進入正式 runtime content data，不從 docs/ parse。P4-A 的 authoritative import source固定為既有 SRD provenance pin：5e-bits/5e-database@ce47a18dfeb3e41a1b2a2dfe00a25761c3c3a4f1 的 src/2014/en/5e-SRD-Monsters.json，該 pinned source共 334 筆 Monster records，其中 type=beast 共 87 筆；Beast是同一 Monster corpus的 subset，不另有第二份 Beast source。Checked-in content manifest必須保存 source commit / path / expected_records=334 / expected_beasts=87，runtime不直接依賴 upstream。 2a. P4-A 同步交付 zh-TW / en 的 user-visible Monster label coverage：至少 Monster name，以及 Trait / Action / Bonus Action / Reaction / Legendary Action 等命名欄位。完整英文 stat block description先作 canonical source；若 P4-A 尚未把 long-form description expose給 Human UI / MCP，可延後 description翻譯到首次 user-visible exposure的 Subphase，但 English fallback 不算 supported-locale completeness。任何 Subphase一旦正式顯示／搜尋某個 description欄位，就必須同 Subphase補齊 zh-TW。
  3. Template核心至少承載 Name、Size、Type、AC、HP formula / default、Speed、Ability Scores；SRD有資料時承載 Saves、Skills、Resistances、Immunities、Condition Immunities、Senses、Languages、CR。
  4. Combat能力可承載 Traits、Actions、Bonus Actions、Reactions、Multiattack、Save-based Actions、Recharge、Spellcasting與 lightweight Legendary Actions。
  5. 能可靠結構化的 attack/save/damage/recharge資料必須結構化；複雜特殊能力可保留 description + structured hints，由 DM adjudication。不得為了單一怪物建立通用 DSL。
  6. Monster Instance至少可保存 current HP、Temp HP若適用、conditions/effects、combat status、initiative、reaction availability、recharge/resources、visibility與 optional Position Note。
  7. Quick Enemy不需 Template即可建立；最低 Name、AC、HP、Speed就能成為 combatant，需要攻擊時再加 Name / Attack Bonus / Damage。
  8. Quick Enemy之後可以 Save as Monster Template；save只複製可重用規則資料，不把 current HP、initiative、已消耗 reaction等 instance state寫進 Template。
  9. NPC與Monster不合併：NPC突然進戰鬥可掛 Quick Stats / Choose Template；Monster日後變故事角色仍由未來 NPC workflow處理。
  10. Combatant projection從本 Subphase起就區分 DM full view 與 Player safe view，並有自動 secrecy tests。
  11. P4-A不建立 Combat round / turn lifecycle，不建立 Attack resolve UI，不建立 P5 geometry。
  12. Standalone不載入 Monster / Combat multiplayer schema或 route；Character Core不得反向 import Combat module。

P4-B — Combat Lifecycle, Initiative & Action Economy

目標

建立可 durable resume 的 Quick Combat lifecycle、initiative、round / turn與 action economy，讓一場 Combat可以跨 browser reload、server restart與 Session boundary繼續。

完成後必須為真

  1. current DM可從 active Session Start Quick Combat；Player不能自行建立／結束 Combat。
  2. Start Combat不要求 EncounterTemplate。Party active characters可快速加入；DM可加 Monster Template instance、Quick Enemy或之後新增 entrant。
  3. 同一 Campaign第一版最多一場 active Combat；重複 Start不得產生第二場平行 active Combat。
  4. Combat mode在建立時固定為 quick；P4沒有 Tactical mode建立入口，也不能中途切 mode。
  5. Initiative使用既有 RollGroup / RollRequest substrate，基本公式 d20 + DEX；支援 monster group initiative、tie resolution、surprise與 mid-combat entrant。
  6. Combat canonical state至少可恢復：status、round、current turn、ordered combatants、initiative、surprise、action / bonus / reaction availability、extra-attack bookkeeping、ready/reaction pending狀態。
  7. Turn advance由 Server authoritative validation控制；不能由 client只改 local index。
  8. 一般 Action / Bonus Action不能在別人的 Turn提交；Reaction走合法 reaction window；current DM proxy仍須消耗 subject combatant自己的 economy。
  9. Dash / Disengage在 Quick Combat只消耗 Action並記錄 intent / public effect，不建立 movement distance budget；是否真的避開 OA由 DM裁定。
  10. Dodge / Search / Ready / Freeform等基礎 action有最小正式 representation；無法自動 resolve的 fiction consequence仍由 DM。
  11. Session End不自動 End Combat。下一 Session若 Campaign仍有 active Combat，Resume可看到 round / current turn / combatants與 pending reaction。Combat entry以 Character / Monster Instance為持久 subject，不因下一 Session的 Seat/Party不同而刪除或重建：新 Session仍有 Seat控制同一 Character時，該 controller重新取得該 existing entry的合法操作權；某 Character本場未出席時，entry與 turn order仍保留，沒有 Player controller可操作它，current DM可明確 Skip Turn、標記 withdrawn/removed，或在需要時以 DM proxy處理該 Character；不得自動把 entry綁給別的 Seat。新 Session／Late Join出現的新 Character也不自動進 active Combat，只有 current DM以 mid-combat entrant加入後才建立 entry與 initiative。
  12. 只有 current DM可以 End Combat。沒有 hostile只可提示，不自動結束。
  13. End Combat清除：initiative、round、current turn、action / bonus / reaction、surprise、Ready、combat-only bookkeeping，以及產品規格指定的 death-save cleanup；保留 HP、Temp HP、slots/resources、persistent conditions、concentration、inventory與 Monster/NPC outcome。
  14. P4-B不實作完整 attack/damage/spell resolution；只交付 lifecycle與 economy substrate。

P4-C — Attack, Damage & Core Action Resolution

目標

把最常見的武器／怪物攻擊、傷害、治療、基本 combat action做成 Server authoritative transaction，Human與AI共用。

完成後必須為真

  1. Character與Monster可從合法 attack definition建立正式 Attack action；Player只能操作自己 Seat combatant，current DM可代理任意Player或控制敵人。
  2. Attack roll沿用 P3 formal roll substrate，支援 normal / advantage / disadvantage、Nat 20、Nat 1與可追蹤 modifier source。
  3. Nat 20依 5e 2014 double damage dice、不 double flat modifier；Nat 1 attack auto miss。
  4. 一般命中後由 Server直接 roll / compute damage並套用 target state；不逐擊等待 DM confirm。
  5. Damage先扣 Temp HP，再扣 Current HP；Healing不補 Temp HP；0 HP與過量傷害規則依本 Phase已實作範圍處理。active Combat中的一般受傷／治療（包含玩家自己在 UI 輸入「扣 7 HP」、AI DM resolve、Attack / Spell outcome）都必須走同一 semantic damage / healing boundary，而不是以 absolute current_hp patch反推發生了什麼；該 boundary負責 Temp HP順序、Concentration trigger與0 HP consequences。Human DM Direct Edit仍可用 absolute HP作修正，屬明確 correction path，不假裝成一次 damage event。
  6. Resistance / Immunity / Vulnerability若 Template / Character state已有可靠 machine-readable資料，damage pipeline必須套用；無法結構化的特殊例外交 DM裁定。
  7. Saving-throw action可建立一或多個正式 save RollRequest，依合法 DC / ability與 visibility resolve；secret資料仍 Server-filtered。
  8. Quick Combat沒有 range geometry。若 action需要空間判定，resolution必須明確進 dm_adjudication_required / 等價狀態，而不是猜距離。
  9. Grapple / Shove依 2014核心規則處理 opposed check、size/free-hand constraints與結果 state；拖行距離與 cliff / hazard等 geometry consequence由 DM。
  10. PC到 0 HP建立 Unconscious + Prone與 death-save state；Monster到 0 HP不自動標 Dead，交由 DM選 Dead / Unconscious / Surrendered / Other outcome。
  11. Death Save支援 10–19 success、2–9 failure、Nat20 → 1 HP、Nat1 → 2 failures、三成功 stable、三失敗 dead；Healing >0移除 Unconscious但 Prone保留。
  12. Combat action的 state mutation、roll result、resource/economy consumption與 event emission必須原子提交；retry不得重傷害、重扣資源或重擲。
  13. Human UI與MCP adapter不得各自計算命中／傷害；都呼叫同一 application/domain service。
  14. P4-C不處理完整 spell skeleton、concentration與 reaction chain，留 P4-D。

P4-D — Spells, Conditions, Concentration & Reactions

目標

在不建立 generic rules DSL 的前提下，把 Quick Combat最常見的 Spell、Condition、Concentration與 Reaction正式接進 Combat Engine。

完成後必須為真

  1. Spell Skeleton至少支援：Spell Attack、Saving Throw、Auto Effect、AoE target list、Damage / Healing、Concentration、Upcasting。
  2. Cast Spell只允許目前 Character rules / Current State合法的 spell access與資源；slot / Pact Magic /其他既有 SpellResourcePool不得被 Combat layer重新發明。
  3. Quick Combat的 AoE由 acting user提出 target list、必要時 current DM確認 affected targets；Server不建立假的 AoE geometry。
  4. Concentration由 Server canonical state追蹤：開始新 concentration會結束舊 concentration；受傷時可建立對應 CON save；Combat End不自動清 concentration。
  5. 2014 Conditions至少完整支援規格列出的：Blinded、Charmed、Deafened、Frightened、Grappled、Incapacitated、Invisible、Paralyzed、Petrified、Poisoned、Prone、Restrained、Stunned、Unconscious、Exhaustion levels。
  6. Conditions不是 icon-only；其可可靠結構化的機械效果要進 rules calculation。複雜例外可 partial structured + notes，不做 universal effect DSL。
  7. Temporary Effects可表達規格需要的 Advantage / Disadvantage、+N、AC、Speed、Attack、Save、Check、Damage修正；P4 Quick不使用 Speed effect計算 movement feet，但資料模型不得阻礙 P5使用。 7a. 需要跨 Combat／Session保留的 PC truth必須正式擴充 shared Character Current State，而不是藏在 combat_entries：至少包含 Concentration、Exhaustion level、Death Save state與可跨 Combat存在的 Temporary Effects；HP / Temp HP / persistent Conditions / resources沿用既有 Current State。combat_entries只保存 initiative、turn/economy、surprise、Ready / reaction window與 combat-only bookkeeping。這些 shared Character State欄位不得 reference Room / Session / Combat row，保持 Standalone可攜。 7b. Character JSON schema_version="1" 維持 backward-compatible import contract；Current State新增欄位採 additive/default-safe演進，不改既有欄位語意。新版必須持續 import既有 v1 / legacy unstable fixture，並以 Web ↔ Standalone export/import roundtrip證明新增 state不遺失；若未來需要破壞既有 v1語意才另開新 schema version。
  8. ReactionRequest是 durable pending state，可在 browser / AI reconnect後恢復；Reaction不需自己的 Turn，但必須驗 reaction availability與 controller authority。
  9. Quick Combat Opportunity Attack不自動偵測。只有 DM trigger / adjudication後才建立 ReactionRequest。
  10. Ready使用同一 Reaction substrate；自由文字 trigger由 DM判斷，不建立 scripting DSL。
  11. Lightweight Legendary Action可有最小 action-economy representation；特殊 timing / lair action等超出目前結構化能力者保留 description + DM adjudication，不為此膨脹引擎。
  12. Spell / condition / reaction resolve仍須與 roll、resource、state、event原子提交與 idempotent retry。

P4-E — Quick Combat UI, DM Adjudication & AI Tool Surface

目標

把 P4-A～D 的 Combat Engine變成真人與外部 AI都能實際跑的桌面體驗；UI保持桌上工具而不是 CRPG command console。

完成後必須為真

  1. Quick Combat沿用 Session table layout，不跳到另一套產品：Main Stage顯示 Combat Header、Initiative List、Combatants、Main Situation / Description與 Quick Action Bar；Chat / Dice / Log仍可用。
  2. Combat Header至少顯示 Round / Current Turn；Combatants顯示角色／敵人的公開名稱、公開 Conditions、action economy與 optional Position Note。
  3. DM視圖可看到完整敵人 AC / HP / resources / recharge等必要資訊；Player / AI Player DTO與UI遵守敵人 secrecy contract，不收到精確 hidden資料。
  4. Player選 Action，若需要 target再選 target；UI不得要求先建 Scene / EncounterTemplate / Map。
  5. 遇到 Quick Combat無法自動判斷的 range / cover / AoE targets / OA /特殊能力時，current DM收到清楚的 adjudication request，可選 in/out of range、adv/disadv、affected targets、trigger/no trigger或 freeform ruling後繼續 resolve。
  6. Position Note與 Main Situation完全 optional；空白時 Combat仍可正常跑。
  7. Human DM可直接調整 Monster Instance / combatant status與必要 combat bookkeeping，且走正式 server mutation / event；不做 Undo Transaction。
  8. MCP tool catalog加入 Combat read/write tools，DM與Player依 role取得合法集合；AI不直接送 raw HP patch來模擬 Attack。
  9. get_session_context / briefing在 active Combat時提供 compact Combat context與下一步指引，包含 Round、Current Turn、自身可見 combatants、pending roll / reaction / adjudication；不塞整份 Monster database。
  10. AI DM可 Start Combat、建立／加入敵人、roll initiative、處理敵人 turn、提出 DM adjudication、End Combat；AI Player可在自己 turn選合法 action、target、roll / resolve並回到 wait loop。
  11. AI與Human共用 Combat services，MCP只做 auth / DTO / tool adaptation；不能建立 ai_attack() 的另一套規則引擎。
  12. Combat event在 Chat / Log的呈現遵守既有分工：敘事／人物發言留 Chat；機械結果以 compact Log / system event呈現，避免每個 modifier都洗 Chat。
  13. 雙語 zh-TW / en UI、errors、tool descriptions與 guide更新同 Subphase交付。

P4-F — Full P4 Integration & Closeout

目標

以真正可玩的完整 Quick Combat journey驗證 P4，不以單元測試拼湊代替整合證據。

完成後必須為真

  1. Human browser journey可完成：Start Combat → add SRD enemy → initiative → 多回合 Player / DM turns → attack / save / damage → condition / concentration或 reaction → 0 HP / outcome → End Combat。
  2. 至少一條 journey證明 Quick Combat空間問題會交給 DM adjudication，而不是出現 fake geometry。
  3. reload、controller reconnect與 server restart後 active Combat可恢復 Round / Current Turn / combatants / pending roll / reaction / adjudication，且不重擲、不重傷害。
  4. Session End時 active Combat保持；下一 Session可 resume同一 Combat；Combat End後 cleanup / preserved state符合產品規格。
  5. Player / AI Player敵人 secrecy有 browser/API/MCP三層證據：精確 HP / AC / hidden resources不會出現在 payload。
  6. current DM proxy Player Combat action走同一 rules / action economy，audit保留 acting DM與subject Character。
  7. P4新增 migration在真 PostgreSQL fresh install + legacy upgrade驗證；Standalone schema / import boundary維持乾淨。
  8. P0～P3 / M02～M04直接受影響 regression全綠；既有 P3 event / roll / AI authority不因 Combat改壞。
  9. 真實 ChatGPT Web Plus透過現有 M04 connector完成至少一場 Combat journey。最低 gate：AI DM取得 context → Start Quick Combat → initiative → Human或AI Player action → attack/save/damage resolve → turn advance → End Combat；所有桌上可見輸出實際寫回 Adventure Table，不只回在 host chat。
  10. 真實 AI gate必須包含至少一次 wait_for_event / reconnect continuity，確認新增 Combat tools沒有破壞 M04固定 catalog / auth / role scope。
  11. Phase closeout前完成 static review、Non-E2E regression、Full-Stack E2E與具名 closeout evidence；P4-A～F全部關門後才合併回 main。

5. P4 明確不做

P4 明確不做：

這些缺少時，Quick Combat仍必須是一套完整可玩的戰鬥方式，而不是「等 P5 地圖做完才真正能打」。

This site is open source. Improve this page.