tedwards/realms-in-ruin-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Phase 2A2a shared gameplay contract proposals.

Browse Source 
Propose ASC resource, authority, damage/death/respawn, and related contracts for owner review without approving or implementing them.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
tedwards
2026-07-17 07:51:35 -07:00
co-authored by Cursor
parent 9919faab4a
commit c2fa15dbe3
3 changed files with 1659 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/Phase2/04-Phase2A-DecisionRegister.md
+342
View File
@@ -0,0 +1,342 @@
# Phase 2A — Decision Register
| Field | Value |
|---|---|
| Status | Draft |
| Date | 2026-07-17 |
| Phase | 2A2a |
| Starting Git commit | `9919faab` |
| Rule | All entries are **Proposed**, **Alternative**, **Deferred**, or **Blocked**. None are **Approved**. |
Companion: [`03-SharedGameplayContracts.md`](03-SharedGameplayContracts.md). Open-decision reconciliation: [`02-Phase2A-OpenDecisions.md`](02-Phase2A-OpenDecisions.md).
---
## Summary table
| Decision | Recommendation | Confidence | Blocking issue | Approval required |
|---|---|---|---|---|
| C-001 | ASC AttributeSet sole SoT for H/M/S currents and maxes | High | None for proposal; combat cutover needs death PIE later | Yes |
| C-002 | Option A — character-specific default GE after ASC actor info valid | Medium | Orphan GEs lack Max*; must fail visibly if missing | Yes |
| C-003 | Shared server ASC resource interface; atomic costs | High | Cost mutation path not runtime-proven | Yes |
| C-004 | ASC→legacy one-way shadow only; bidirectional rejected | High | Which consumers still need shadow until migrated | Yes |
| C-005 | Server damage boundary writing ASC; ApplyDamage as adapter; ExecCalc deferred | Medium | Damage/death path not exercised (RE-2A1-022) | Yes |
| C-006 | Server restore via same boundary; clamp to Max*; no over-resource by default | Medium | Pickup/heal overlap not observed (RE-2A1-018) | Yes |
| C-007 | Death from ASC Health ≤ 0; idempotent; anim presentation-only | Medium | Death path not observed; legacy health 0 at spawn risk | Yes |
| C-008 | GameMode + PC own respawn; ASC re-init; idempotent HUD | Medium | Respawn not observed (RE-2A1-022) | Yes |
| C-009 | Client intent; server validate; multicast presentation-only | Medium | Ability + 2P paths blocked (RE-2A1-015, 023) | Yes |
| C-010 | Animation cosmetic; server timing correlation; no notify authority | Medium | Notify chain not executed | Yes |
| C-011 | Shared lifecycle; guaranteed cleanup without sole AN_AttackComplete | Medium | Interrupt test blocked (RE-2A1-020) | Yes |
| C-012 | Player ASC on PlayerState; pawn Avatar; enemy self-ASC separate | High | Enemy inspector Tool Limitation (RE-2A1-028) | Yes |
| C-013 | Overlay-only HUD; retire UpdatePlayerHUD; defer stamina UI | High | Respawn Overlay duplication untested | Yes |
| C-014 | Server pickup validate/apply/destroy; replicate existence; ban naked non-rep MP pickups | Medium | Overlap apply + 2P blocked | Yes |
| C-015 | Minimum observability list; no permanent debug UI required yet | Medium | Harness not built; env limits remain | Yes |
---
## C-001 — Canonical player resource source of truth
| Field | Content |
|---|---|
| Decision ID | C-001 |
| Title | Canonical player resource source of truth |
| State | Proposed |
| Recommended option | ASC attributes are sole SoT for Health, MaxHealth, Mana, MaxMana, Stamina, MaxStamina; DEPRECATED vars non-authoritative |
| Alternatives | Keep legacy SoT during reconstruction only (rejected as primary); character-specific transitional dual-SoT (rejected — prolongs P0) |
| Static evidence | `05-LegacyAbilityArchitecture.md` resource inventory; `06-PartialGASArchitecture.md` §8 legacy/GAS boundary; `01-ExecutiveSummary.md` P0 dual resources |
| Runtime evidence | RE-2A1-001, 004, 005, 012, 013; RT-001, RT-002 |
| Benefits | One truth for UI, combat, potions, death; removes spawn divergence class of bugs |
| Risks | Breaking unconverted legacy readers if shadow/cutover incomplete |
| Migration impact | Abilities, Amazonian death, Cleric heal, HUD, future stamina |
| Blocking unknowns | Whether AnyDamage fires with legacy health already 0 |
| Runtime validation | Post-init ASC match; potion vs combat both mutate ASC; death from ASC |
| Approval question | Do you approve ASC AttributeSet as the sole canonical source of truth for Health, MaxHealth, Mana, MaxMana, Stamina, and MaxStamina, with DEPRECATED Blueprint resource variables treated as non-authoritative? |
---
## C-002 — Character default attribute initialization
| Field | Content |
|---|---|
| Decision ID | C-002 |
| Title | Character default attribute initialization |
| State | Proposed |
| Recommended option | A — Character-specific default Gameplay Effect selected by pawn/class; server apply after ASC actor info valid; explicit current+max H/M/S; visible fail on missing assignment |
| Alternatives | B — Shared init GE + SetByCaller; C — Native initialization service; hybrid Max* fill transitional |
| Static evidence | `06-PartialGASArchitecture.md` §§2–4 default GE matrix; native Init*; DefaultAttributesGameplayEffect=None |
| Runtime evidence | RE-2A1-001, 002, 011, 012 — identical ASC; no active GE; CDO legacy defaults |
| Benefits | Per-class balance; reuses existing GE assets/property; deterministic spawn/respawn |
| Risks | Existing orphan GEs omit Max*; incomplete GE applied → broken clamps |
| Migration impact | PlayerState, character GEs, Gunslinger missing GE, spawn/respawn |
| Blocking unknowns | Final per-class balance numbers (design); Gunslinger defaults |
| Runtime validation | Per-class ASC after spawn/respawn; missing assignment visible error |
| Approval question | Do you approve Option A (character-specific default Gameplay Effect applied server-side after ASC actor info is valid), with visible failure on missing assignment and mandatory explicit current+max Health/Mana/Stamina? |
---
## C-003 — Resource-access boundary
| Field | Content |
|---|---|
| Decision ID | C-003 |
| Title | Resource-access boundary |
| State | Proposed |
| Recommended option | Shared authoritative ASC interface; atomic server cost check+mutate; no new DEPRECATED direct access |
| Alternatives | Per-system ad-hoc ASC reads (rejected — recreates dual writers) |
| Static evidence | `05` FCanUseMana / DEPRECATED costs; `07` S9; `06` boundary |
| Runtime evidence | RE-2A1-014, 015 — cost path not proven; Ability004ManaCost CDO=0 |
| Benefits | Incremental migration without two SoTs; consistent affordability |
| Risks | Bypass of interface during hasty BP edits |
| Migration impact | All cost/heal/damage resource call sites |
| Blocking unknowns | Exact FCanUseMana body edge cases; cost timing vs montage |
| Runtime validation | Cost reduces ASC once; failed affordability no mutation |
| Approval question | Do you approve a shared server-authoritative ASC resource interface as the only allowed read/write path for new gameplay resource access, with atomic cost validation and mutation? |
---
## C-004 — Legacy compatibility policy
| Field | Content |
|---|---|
| Decision ID | C-004 |
| Title | Legacy compatibility policy |
| State | Proposed |
| Recommended option | C — ASC→legacy one-way shadow for temporary read-only consumers; prefer D cutover when possible |
| Alternatives | D — No sync / migrate first; A bidirectional **Rejected by Existing Evidence**; B legacy→ASC rejected as primary |
| Static evidence | `06` sync Missing; `01` P0 dual pools |
| Runtime evidence | RE-2A1-004, 005, 013 — divergent spawn; Overlay ASC vs combat legacy |
| Benefits | Avoids feedback loops; protects ASC from zeroed legacy writers |
| Risks | Shadow forgotten; legacy writer still active |
| Migration impact | AnyDamage, FCanUseMana readers, Server_UpdateHUD |
| Blocking unknowns | Full runtime inventory of legacy readers during death/ability |
| Runtime validation | Shadow matches after ASC change; legacy cannot overwrite ASC |
| Approval question | Do you approve ASC→legacy one-way shadow only for temporary read-only consumers, with bidirectional sync prohibited and legacy writers forbidden from silently overwriting ASC? |
---
## C-005 — Damage contract
| Field | Content |
|---|---|
| Decision ID | C-005 |
| Title | Damage contract |
| State | Proposed |
| Recommended option | Single server damage boundary writing ASC Health; legacy ApplyDamage as transitional adapter; ExecutionCalculation deferred |
| Alternatives | Pure GE ExecutionCalculation (Deferred/Alternative); keep ApplyDamage+legacy health (Rejected as end state) |
| Static evidence | `05` ApplyDamage paths; `09` enemy reception Missing; `06` no ExecCalc project subclasses |
| Runtime evidence | RE-2A1-022, 027, 030 — damage not observed; enemy components present |
| Benefits | One entry for players/enemies; dedupe; death hook |
| Risks | Adapter gap during migration; enemy consumer still Missing |
| Migration impact | All ApplyDamage sites; Amazonian AnyDamage; Phase 2D enemies |
| Blocking unknowns | Runtime authority of hit windows; block absorb design |
| Runtime validation | Single ASC Health reduction; no double hit; death trigger |
| Approval question | Do you approve a single server-authoritative damage entry that writes ASC Health, with legacy ApplyDamage limited to a transitional adapter, and ExecutionCalculation design deferred? |
---
## C-006 — Healing and resource restoration contract
| Field | Content |
|---|---|
| Decision ID | C-006 |
| Title | Healing and resource restoration contract |
| State | Proposed |
| Recommended option | Server restore via shared ASC boundary; clamp to Max*; consumables same path; no over-resource by default |
| Alternatives | Allow overheal via tagged GEs only (future design) |
| Static evidence | `05` Cleric recover; `06`/`12` potion GEs; no AttributeSet clamp |
| Runtime evidence | RE-2A1-018 — pickup apply not run |
| Benefits | Overlay and combat agree; potions/abilities consistent |
| Risks | Cleric transitional dual heal if not adapted |
| Migration impact | Cleric 002, EffectActors, DEPRECATED recover |
| Blocking unknowns | Intended overheal design (none evidenced) |
| Runtime validation | Clamp at max; potion +25 once; Overlay update |
| Approval question | Do you approve server-authoritative restoration through the shared ASC resource boundary, clamping to Max* by default, with consumables and ability heals using the same path? |
---
## C-007 — Death contract
| Field | Content |
|---|---|
| Decision ID | C-007 |
| Title | Death contract |
| State | Proposed |
| Recommended option | Authoritative idempotent death from ASC Health ≤ 0; shared replicated dead state; anim presentation-only |
| Alternatives | Tag-only State.Dead as primary (Deferred until tags wired); legacy≤0 SoT (Rejected as end state) |
| Static evidence | `05` Amazonian death; `09` enemy IsDead forced false; `10` ABP Death |
| Runtime evidence | RE-2A1-006, 004, 013, 022 — IsDead false; legacy health 0; death not observed |
| Benefits | Idempotent; aligns Overlay and death; fixes enemy ABP ownership of truth |
| Risks | Instant death if legacy path fires before ASC cutover |
| Migration impact | PlayerDeath, Amazonian AnyDamage, enemy death ABP, tags |
| Blocking unknowns | Whether AnyDamage runs at legacy 0; Paladin inbound damage path |
| Runtime validation | One death transition; no re-entry; ABP follows replicated state |
| Approval question | Do you approve authoritative, idempotent death evaluated from ASC Health ≤ 0, with animation as presentation-only and player/enemy differing only in post-death lifecycle? |
---
## C-008 — Respawn contract
| Field | Content |
|---|---|
| Decision ID | C-008 |
| Title | Respawn contract |
| State | Proposed |
| Recommended option | GameMode + PlayerController own server respawn lifecycle; pawn does not solely replace itself |
| Alternatives | Pawn-owned Server_RespawnPlayer as sole owner (Rejected as primary) |
| Static evidence | `07` S8; `11` PlayerRespawn / PlayerFirstSpawn |
| Runtime evidence | RE-2A1-010 — spawn warning; RE-2A1-022 — respawn untested |
| Benefits | Clear ownership; ASC/HUD rebind; duplicate-respawn guard |
| Risks | Existing pawn respawn graphs need rewiring; PlayerFirstSpawn warning |
| Migration impact | GM_Dungeoneer, PC_Character, base death/respawn, HUD |
| Blocking unknowns | Exact timer (~2s) intent; Overlay recreate vs rebind preference in practice |
| Runtime validation | One respawn; ASC Owner/Avatar correct; defaults reapplied; one Overlay |
| Approval question | Do you approve GameMode + PlayerController ownership of server respawn lifecycle (pawn must not solely replace itself), including ASC re-init, default reapplication, possession, input restore, and idempotent HUD bind? |
---
## C-009 — Authority contract
| Field | Content |
|---|---|
| Decision ID | C-009 |
| Title | Authority contract |
| State | Proposed |
| Recommended option | Client intent → server validate/commit → multicast presentation-only; notify not sole authority |
| Alternatives | Allow Authority-gated notify gameplay indefinitely (Rejected as end state); documented narrow exceptions (Deferred) |
| Static evidence | `05`/`10` Input→Server→Multicast→AN→UseAbility |
| Runtime evidence | RE-2A1-015, 019, 021, 023–026 — ability/2P not observed |
| Benefits | Predictable MP; removes interrupt/notify authority risk |
| Risks | Timing feel change during migration; temporary dual patterns |
| Migration impact | All ability network paths; Phase 2B |
| Blocking unknowns | Server vs client notify evaluation roles at runtime |
| Runtime validation | Listen-server damage once; montage both; no client Health write |
| Approval question | Do you approve client-intent / server-validation authority, with multicast limited to presentation, and AnimNotify forbidden as sole authority for damage, costs, or state transitions? |
---
## C-010 — Animation responsibility contract
| Field | Content |
|---|---|
| Decision ID | C-010 |
| Title | Animation responsibility contract |
| State | Proposed |
| Recommended option | Animation owns cosmetics; may correlate timing; must not solely own damage/cost/death/respawn/cleanup |
| Alternatives | Keep notify-authoritative hit windows (Rejected as end state) |
| Static evidence | `10-AnimationDependencies.md` shared architecture and Networking Risk |
| Runtime evidence | RE-2A1-019–021 — notify path not run |
| Benefits | Clear cosmetic vs authority split; preserves timing via server windows |
| Risks | VFX desync vs hits; migration cost for montages |
| Migration impact | AN_Ability_*, AN_AttackComplete, Multicast_PlayMontage |
| Blocking unknowns | Exact notify trigger times (Manual Editor) |
| Runtime validation | Interrupt cleanup without AN_AttackComplete; hits still server-valid |
| Approval question | Do you approve animation as cosmetic-only for authority purposes, with server-owned timing correlation allowed, and notify-driven authoritative gameplay prohibited as the end state? |
---
## C-011 — Ability lifecycle and cleanup contract
| Field | Content |
|---|---|
| Decision ID | C-011 |
| Title | Ability lifecycle and cleanup contract |
| State | Proposed |
| Recommended option | Shared lifecycle states; guaranteed cleanup on interrupt/death/destroy/timeout; no sole AN_AttackComplete dependence |
| Alternatives | Montage blend-out notify required (insufficient alone); cancel tags + EndAbility (compatible Alternative) |
| Static evidence | `05` empty Ends; `07` S3/S12; `10` unwired montage pins |
| Runtime evidence | RE-2A1-020 — interrupt blocked |
| Benefits | No stuck CurrentlyAttacking; safe death mid-ability |
| Risks | Under-specified per-ability cancel policy |
| Migration impact | All Begin/End/UseAbility; Phase 2B framework |
| Blocking unknowns | Which existing actions can interrupt without asset edits |
| Runtime validation | Complete and interrupted montages both clear locks |
| Approval question | Do you approve the shared ability lifecycle states and the rule that cleanup must be guaranteed without sole dependence on AN_AttackComplete? |
---
## C-012 — PlayerState and pawn ownership contract
| Field | Content |
|---|---|
| Decision ID | C-012 |
| Title | PlayerState and pawn ownership contract |
| State | Proposed |
| Recommended option | Keep player ASC/AttributeSet on PlayerState; pawn Avatar; enemy self-ASC separate contract |
| Alternatives | Move ASC to pawn (Rejected unless redesign approved); dual ownership unclear Avatar rules (Rejected) |
| Static evidence | `06` ownership; `09` enemy GetASC nullptr |
| Runtime evidence | RE-2A1-007, 027, 028 |
| Benefits | Survives respawn; matches existing native design |
| Risks | Enemy accessor defect continues until 2D/2E fix |
| Migration impact | InitAbilityActorInfo, EffectActor GetASC, enemies |
| Blocking unknowns | Whether enemy InitAbilityActorInfo fully exposes ASC to inspector |
| Runtime validation | Post-respawn Owner/Avatar; enemy ASC via corrected accessor |
| Approval question | Do you approve keeping player ASC/AttributeSet on PlayerState with pawn as Avatar only, and treating enemy self-ASC as a separate ownership/init contract? |
---
## C-013 — HUD data-flow contract
| Field | Content |
|---|---|
| Decision ID | C-013 |
| Title | HUD data-flow contract |
| State | Proposed |
| Recommended option | Overlay/widget-controller only; retire UpdatePlayerHUD; idempotent HUD; defer stamina UI |
| Alternatives | Implement UpdatePlayerHUD as second path (Rejected); recreate Overlay every possess without guard (Rejected) |
| Static evidence | `11` HUD matrix; `07` S10 unimplemented UpdatePlayerHUD |
| Runtime evidence | RE-2A1-008, 009 — Overlay present; no stamina widget |
| Benefits | Single UI SoT; avoids duplicate overlays |
| Risks | Respawn rebind bugs if InitOverlay not idempotent |
| Migration impact | RIRHUD, Overlay, Server_UpdateHUD callers |
| Blocking unknowns | Exact Overlay instance counts after respawn |
| Runtime validation | One Overlay spawn+respawn; bars track ASC |
| Approval question | Do you approve Overlay/widget-controller as the sole gameplay HUD data path, retirement of UpdatePlayerHUD, idempotent HUD creation, and deferred stamina UI until attribute contracts are approved? |
---
## C-014 — Pickup authority and replication contract
| Field | Content |
|---|---|
| Decision ID | C-014 |
| Title | Pickup authority and replication contract |
| State | Proposed |
| Recommended option | Server validate/apply/destroy; replicated existence; at-most-once; ban non-rep MP pickups without server visibility model |
| Alternatives | Server RPC from client overlap (Alternative); SP-only non-rep prototypes documented (transitional only) |
| Static evidence | `12-Pickups-And-Effects.md` Authority Risk |
| Runtime evidence | RE-2A1-016, 017, 018 |
| Benefits | Consistent MP; prevents double apply |
| Risks | Requires actor replication enablement; enemy null ASC destroy side effect |
| Migration impact | Four EffectActors; Phase 2E; GetASC fix interaction |
| Blocking unknowns | Duplicate apply under 2P; sphere overlap details |
| Runtime validation | One apply; ASC change; destroyed on all clients |
| Approval question | Do you approve server-owned pickup validation/apply/destroy with replicated existence, at-most-once collection, and a ban on non-replicated pickups for network gameplay without an explicit server visibility model? |
---
## C-015 — Runtime observability contract
| Field | Content |
|---|---|
| Decision ID | C-015 |
| Title | Runtime observability contract |
| State | Proposed |
| Recommended option | Minimum inspectable set via logs/debugger/ASC inspect/future harness; no permanent debug UI required yet |
| Alternatives | Permanent debug HUD (Deferred); do nothing (Rejected — blocks reconstruction trust) |
| Static evidence | `13-Unknowns-And-RuntimeQuestions.md` runtime groups; `15` handoff |
| Runtime evidence | RE-2A1-015, 023, 028, 031 — tool/environment limits |
| Benefits | Makes blocked areas closable; prevents false negatives from tools |
| Risks | Harness scope creep; env still blocks Enhanced Input / 2P |
| Migration impact | Logging; temporary harness; not gameplay SoT |
| Blocking unknowns | How to enable 2-client PIE without config save; Enhanced Input injection |
| Runtime validation | Each listed field obtainable in controlled session |
| Approval question | Do you approve the minimum observability list as a prerequisite for trusting reconstruction, without requiring permanent debug UI yet? |
---
## Register integrity
- No decision recorded as Approved.
- Recommendations are Proposed only.
- Bidirectional sync recorded as Rejected by Existing Evidence under C-004.
- ExecutionCalculation under C-005 is Deferred / Alternative, not selected.