tedwards/realms-in-ruin-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6aab068876b0680a980df2f6115ed70d8382f436
realms-in-ruin-dev/Documentation/Phase2/04-Phase2A-DecisionRegister.md
T
tedwardsandCursor 6aab068876 Document Phase 2A2b owner approval of shared gameplay contracts. 
Record Approved and Approved-with-Conditions decisions, reject bidirectional sync and client-overlap pickup RPC, and keep runtime validation as non-blocking obligations.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-17 08:20:29 -07:00

333 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Phase 2A — Decision Register
| Field | Value |
|---|---|
| Status | Complete |
| Date | 2026-07-17 |
| Phase | 2A2b — Owner decisions applied |
| Starting Git commit | `c2fa15db` |
| Owner decision date | 2026-07-17 |
| Rule | Every C-001–C-015 entry has an owner state: Approved, Approved with Conditions, Deferred (sub-choice), or Rejected (alternative). |
Companion: [`03-SharedGameplayContracts.md`](03-SharedGameplayContracts.md). Open decisions / validation obligations: [`02-Phase2A-OpenDecisions.md`](02-Phase2A-OpenDecisions.md).
---
## Summary table
| Decision | Owner state | Recommendation (locked) | Confidence | Validation obligation | Approval required |
|---|---|---|---|---|---|
| C-001 | Approved | ASC sole SoT for H/M/S currents and maxes | High | Combat/death cutover PIE (RE-2A1-022) | Resolved |
| C-002 | Approved with Conditions | Character-specific default GE; six attrs; fail visible; no duplicate init | Medium | Spawn/respawn per-class ASC; duplicate-init guard | Resolved |
| C-003 | Approved | Shared server ASC resource boundary; atomic costs | High | Cost mutation path (RE-2A1-015) | Resolved |
| C-004 | Approved (transitional) | ASC→legacy one-way named shadow; end state no shadow | High | Shadow inventory; no reverse write | Resolved |
| C-005 | Approved | Server damage boundary → ASC Health; ApplyDamage adapter only | Medium | Damage/death PIE (RE-2A1-022) | Resolved |
| C-006 | Approved | Server restore via boundary; clamp Max*; no over-resource default | Medium | Pickup/heal apply (RE-2A1-018) | Resolved |
| C-007 | Approved | Death from ASC Health ≤ 0; idempotent; anim presentation | Medium | Death path (RE-2A1-022) | Resolved |
| C-008 | Approved with Conditions | GameMode orchestrates; PC handoff; pawn reports only | Medium | Respawn/HUD (RE-2A1-022) | Resolved |
| C-009 | Approved | Client intent; server validate; multicast presentation-only | Medium | Ability + 2P (RE-2A1-015, 023) | Resolved |
| C-010 | Approved with Conditions | Animation presentation; timing signal into lifecycle; no sole notify authority | Medium | Interrupt/notify (RE-2A1-019–020) | Resolved |
| C-011 | Approved | Shared lifecycle; guaranteed cleanup; not sole AN_AttackComplete | Medium | Interrupt/death mid-ability (RE-2A1-020–022) | Resolved |
| C-012 | Approved | Player ASC on PlayerState; pawn Avatar; enemy self-ASC + corrected accessor | High | Respawn Owner/Avatar; enemy accessor (RE-2A1-028) | Resolved |
| C-013 | Approved | Overlay-only HUD; retire UpdatePlayerHUD; defer stamina UI | High | Overlay idempotence after respawn | Resolved |
| C-014 | Approved | Server pickup ownership; client-overlap RPC rejected as default | Medium | Overlap + 2P (RE-2A1-018, 023) | Resolved |
| C-015 | Approved | Minimum observability list; no permanent debug UI required | Medium | Harness/logs deliver listed fields | Resolved |
---
## Explicit rejected and deferred marks
| Item | Status | Notes |
|---|---|---|
| Bidirectional legacy synchronization | **Rejected** | C-004 |
| Client-overlap RPC as default pickup model | **Rejected** | C-014 |
| GameplayEffectExecutionCalculation choice | **Deferred** | C-005 — not selected |
| Exact default-GE mapping mechanism | **Deferred** | C-002 |
| Exact authoritative animation-timing mechanism | **Deferred** | C-010 |
| Exact temporary observability implementation | **Deferred** | C-015 |
| Whether any real consumer requires a temporary legacy shadow | **Deferred** | C-004 |
---
## C-001 — Canonical player resource source of truth
| Field | Content |
|---|---|
| Decision ID | C-001 |
| Title | Canonical player resource source of truth |
| State | Approved |
| Owner decision | ASC attributes sole authoritative source for Health, MaxHealth, Mana, MaxMana, Stamina, MaxStamina; DEPRECATED vars not authoritative |
| Approval conditions | None |
| Recommended option | ASC AttributeSet sole SoT |
| Alternatives | Legacy-only SoT — Rejected as end state; dual-SoT — Rejected |
| Static evidence | `05`, `06` §8, `01` P0 |
| Runtime evidence | RE-2A1-001, 004, 005, 012, 013; RT-001, RT-002 |
| Benefits | One truth for UI, combat, potions, death |
| Risks | Unconverted legacy readers break without shadow/cutover |
| Migration impact | Abilities, Amazonian death, Cleric heal, HUD, stamina |
| Blocking unknowns | N/A for architecture approval |
| Validation obligation | Post-init ASC; potion+combat mutate ASC; death from ASC (RE-2A1-022) |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-002 — Character default attribute initialization
| Field | Content |
|---|---|
| Decision ID | C-002 |
| Title | Character default attribute initialization |
| State | Approved with Conditions |
| Owner decision | Character-specific default Gameplay Effects with listed constraints |
| Approval conditions | Server-only; after ASC actor info + avatar valid; deterministic spawn/respawn; all six attrs; no native stamina fallback; no Blueprint CDO reliance; visible failure if missing; prevent duplicate init |
| Recommended option | Option A — character-specific default GE |
| Alternatives | B SetByCaller; C native service — historical alternatives; exact mapping **Deferred** |
| Static evidence | `06` §§2–4 |
| Runtime evidence | RE-2A1-001, 002, 011, 012 |
| Benefits | Per-class balance; deterministic init |
| Risks | Orphan GEs lack Max*; duplicate apply |
| Migration impact | PlayerState, GEs, Gunslinger, spawn/respawn |
| Validation obligation | Per-class ASC spawn/respawn; missing config visible; no duplicate GE |
| Approval question | Resolved — approved with conditions 2026-07-17 |
---
## C-003 — Resource-access boundary
| Field | Content |
|---|---|
| Decision ID | C-003 |
| Title | Resource-access boundary |
| State | Approved |
| Owner decision | Shared server-authoritative ASC boundary for all new reads, affordability, costs, restoration, max queries, gates; atomic cost commit |
| Approval conditions | None |
| Alternatives | Per-system ad-hoc ASC — Rejected |
| Static evidence | `05`, `07` S9, `06` |
| Runtime evidence | RE-2A1-014, 015 |
| Validation obligation | Cost reduces ASC once; failed affordability no mutation |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-004 — Legacy compatibility policy
| Field | Content |
|---|---|
| Decision ID | C-004 |
| Title | Legacy compatibility policy |
| State | Approved (transitional only) |
| Owner decision | ASC→legacy one-way shadow only for named read-only consumers with removal condition; ASC authoritative; no legacy write-through; bidirectional Rejected; end state no shadow; Option D preferred when migratable |
| Approval conditions | Named consumer + removal condition required per shadow |
| Alternatives | A Bidirectional — **Rejected**; B Legacy→ASC primary — Rejected; D no-sync preferred when migratable |
| Static evidence | `06` sync Missing |
| Runtime evidence | RE-2A1-004, 005, 013 |
| Validation obligation | Shadow matches ASC; inventory whether any shadow consumer needed (**Deferred** choice) |
| Approval question | Resolved — approved transitional 2026-07-17 |
---
## C-005 — Damage contract
| Field | Content |
|---|---|
| Decision ID | C-005 |
| Title | Damage contract |
| State | Approved |
| Owner decision | One server damage boundary: validate source/target; preserve instigator/causer; magnitude; mitigation at one boundary; mutate ASC Health; dedupe; death eval; observable damage event; ApplyDamage adapter only |
| Approval conditions | None for boundary; ExecCalc not approved |
| Alternatives | Final GE ExecutionCalculation — **Deferred**; legacy ApplyDamage+DEPRECATED health end state — Rejected |
| Static evidence | `05`, `09`, `06` |
| Runtime evidence | RE-2A1-022, 027, 030 |
| Validation obligation | Single ASC Health reduction; no double hit; death trigger |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-006 — Healing and resource restoration contract
| Field | Content |
|---|---|
| Decision ID | C-006 |
| Title | Healing and resource restoration contract |
| State | Approved |
| Owner decision | Authoritative restore via shared boundary; clamp to max; attribute source; update ASC; HUD via delegates; no over-resource by default |
| Approval conditions | None |
| Alternatives | Overheal via tagged GEs — not approved now |
| Static evidence | `05`, `06`, `12` |
| Runtime evidence | RE-2A1-018 |
| Validation obligation | Clamp at max; potion once; Overlay update |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-007 — Death contract
| Field | Content |
|---|---|
| Decision ID | C-007 |
| Title | Death contract |
| State | Approved |
| Owner decision | Death from ASC Health ≤ 0; authoritative; idempotent; one replicated dead state; cancel abilities; disable movement/interaction; anim presentation; shared death definition for player/enemy |
| Approval conditions | None |
| Alternatives | Legacy≤0 SoT — Rejected as end state |
| Static evidence | `05`, `09`, `10` |
| Runtime evidence | RE-2A1-004, 006, 013, 022 |
| Validation obligation | One transition; no re-entry; ABP follows replicated state |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-008 — Respawn contract
| Field | Content |
|---|---|
| Decision ID | C-008 |
| Title | Respawn contract |
| State | Approved with Conditions |
| Owner decision | GameMode owns orchestration; PlayerController owns handoff (request/state/possess/input/HUD); dying pawn reports only — must not create/possess replacement |
| Approval conditions | Must cover duplicate-request prevention, timing, destroy, spawn, PlayerState persistence, ASC avatar teardown/re-init, default reapply, possession, input restore, HUD idempotence |
| Alternatives | Pawn-owned sole respawn — Rejected |
| Static evidence | `07` S8, `11` |
| Runtime evidence | RE-2A1-010, 022 |
| Validation obligation | One respawn; Owner/Avatar correct; one Overlay |
| Approval question | Resolved — approved with clarification 2026-07-17 |
---
## C-009 — Authority contract
| Field | Content |
|---|---|
| Decision ID | C-009 |
| Title | Authority contract |
| State | Approved |
| Owner decision | Client intent; server validates life, ability, target, range, resources, cost, cooldown, result; authoritative owners write replicated state; multicast presentation-only |
| Approval conditions | None |
| Alternatives | Notify-as-sole-authority end state — Rejected |
| Static evidence | `05`, `10` |
| Runtime evidence | RE-2A1-015, 019, 021, 023–026 |
| Validation obligation | Listen-server damage once; montage both |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-010 — Animation responsibility contract
| Field | Content |
|---|---|
| Decision ID | C-010 |
| Title | Animation responsibility contract |
| State | Approved with Conditions |
| Owner decision | Animation owns presentation; may emit timing signal evaluated on authority; cannot be sole gameplay authority; signals enter ability lifecycle; cleanup not blocked by missing notify |
| Approval conditions | Exact timing mechanism not prescribed this pass — **Deferred** |
| Alternatives | Notify-authoritative hits as end state — Rejected |
| Static evidence | `10` |
| Runtime evidence | RE-2A1-019–021 |
| Validation obligation | Interrupt cleanup without AN_AttackComplete |
| Approval question | Resolved — approved with timing clarification 2026-07-17 |
---
## C-011 — Ability lifecycle and cleanup contract
| Field | Content |
|---|---|
| Decision ID | C-011 |
| Title | Ability lifecycle and cleanup contract |
| State | Approved |
| Owner decision | Shared lifecycle states; guaranteed cleanup for listed paths; AN_AttackComplete cannot be only cleanup path |
| Approval conditions | None |
| Alternatives | Montage-notify-only cleanup — Rejected |
| Static evidence | `05`, `07` S3/S12, `10` |
| Runtime evidence | RE-2A1-020 |
| Validation obligation | Complete + interrupted clear locks; death mid-ability |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-012 — PlayerState and pawn ownership contract
| Field | Content |
|---|---|
| Decision ID | C-012 |
| Title | PlayerState and pawn ownership contract |
| State | Approved |
| Owner decision | PlayerState owns ASC/AttributeSet/cross-pawn state; pawn owns avatar/movement/anim/equipment/transient/targeting presentation; re-InitAbilityActorInfo on possess/replace; enemy self-ASC valid with corrected accessor |
| Approval conditions | None |
| Alternatives | Move ASC to pawn — Rejected unless redesign |
| Static evidence | `06`, `09` |
| Runtime evidence | RE-2A1-007, 027, 028 |
| Validation obligation | Post-respawn Owner/Avatar; enemy ASC via corrected accessor |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-013 — HUD data-flow contract
| Field | Content |
|---|---|
| Decision ID | C-013 |
| Title | HUD data-flow contract |
| State | Approved |
| Owner decision | Overlay/widget-controller only; retire UpdatePlayerHUD; no UI SoT; idempotent HUD; no duplicate overlays; ASC-driven; stamina UI after canonical stamina init; UI cannot mutate gameplay |
| Approval conditions | None |
| Alternatives | UpdatePlayerHUD as second path — Rejected |
| Static evidence | `11`, `07` S10 |
| Runtime evidence | RE-2A1-008, 009 |
| Validation obligation | One Overlay spawn+respawn; bars track ASC |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-014 — Pickup authority and replication contract
| Field | Content |
|---|---|
| Decision ID | C-014 |
| Title | Pickup authority and replication contract |
| State | Approved |
| Owner decision | Server owns validate/apply-once/destroy-or-deactivate/replicate existence/dedupe/attribute; client-overlap RPC **Rejected** as default; client cosmetics after authoritative collection |
| Approval conditions | None |
| Alternatives | Client-overlap RPC default — **Rejected**; SP non-rep as MP model — Rejected |
| Static evidence | `12` |
| Runtime evidence | RE-2A1-016, 017, 018 |
| Validation obligation | One apply; ASC change; destroyed on all clients |
| Approval question | Resolved — approved 2026-07-17 |
---
## C-015 — Runtime observability contract
| Field | Content |
|---|---|
| Decision ID | C-015 |
| Title | Runtime observability contract |
| State | Approved |
| Owner decision | Observable: identity, net role, Owner/Avatar, attrs, active GEs, granted abilities, lifecycle, resource commitments, damage/death/respawn events, pickup apply count; via logs/debugger/ASC inspect/bounded harness; no permanent debug UI required |
| Approval conditions | None |
| Alternatives | Exact harness packaging — **Deferred**; permanent debug UI — not required |
| Static evidence | `13`, `15` |
| Runtime evidence | RE-2A1-015, 023, 028, 031 |
| Validation obligation | Each listed field obtainable in controlled session |
| Approval question | Resolved — approved 2026-07-17 |
---
## Approved architecture boundary summary
Canonical ASC attributes → shared server resource boundary → authoritative damage/healing → idempotent death → GameMode-owned respawn → ASC-driven HUD → authoritative ability lifecycle → character migration → enemy reconstruction → server-owned replicated pickups.
- PlayerState owns persistent player ASC state.
- Pawn is the player avatar.
- Enemy ASC is self-owned and requires a corrected accessor.
- Multicast animation is presentation-only.
- Legacy shadow values are temporary, one-way, named, and removable.
- No per-character reconstruction may begin before the shared contracts are planned and the initial Phase 2A implementation sequence is approved.
## Register integrity
- Every C-001–C-015 has an owner state.
- Status: Complete.
- Runtime validation obligations are recorded but do not reopen architecture approval.
- No Unreal implementation authorized by this register alone.
Reference in New Issue View Git Blame Copy Permalink