clearup

2026-04-06 11:58:36 +08:00
parent b1b38b485e
commit aebc4011c7
84 changed files with 5796 additions and 238 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-05
@@ -0,0 +1,68 @@
+## Context
+
+P0 separated authoritative snapshot identity from movement-input acknowledgement, and P1 made server cadence explicit while introducing an initial bounded-correction path for controlled-player reconciliation. That leaves one remaining UX-focused gap: repeated small authoritative corrections can still look noisy because the client only decides "bounded correction or snap" at the moment a snapshot is accepted. The implementation does not yet define how bounded correction persists, gets replaced, or escalates when multiple authoritative snapshots arrive while the local player is still converging.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Define a stable controlled-player visual-correction policy that survives across multiple accepted authoritative snapshots.
+- Keep authoritative gameplay truth separate from temporary visual smoothing state so local presentation can converge without weakening server authority.
+- Specify when a new small correction replaces, merges with, or escalates an existing bounded correction.
+- Add regression requirements that prove repeated small corrections converge and large divergence still snaps immediately.
+
+**Non-Goals:**
+- Do not change server-authoritative movement cadence, tick semantics, or movement parameter ownership.
+- Do not modify remote-player interpolation rules.
+- Do not introduce extrapolation, rollback beyond existing local replay, or a second gameplay-truth state on the client.
+- Do not turn bounded correction into an unbounded smoothing layer that can hide persistent divergence.
+
+## Decisions
+
+### Decision: Represent local visual convergence as explicit correction state
+The controlled-player path will keep authoritative transform truth separate from a short-lived visual correction state that tracks the remaining offset being paid down after reconciliation.
+
+Why:
+- Repeated small authoritative updates need continuity; otherwise each accepted snapshot effectively restarts smoothing from scratch.
+- An explicit correction state makes the contract testable and prevents presentation code from quietly mixing visual offset with authoritative gameplay truth.
+
+Alternative considered:
+- Recompute a one-frame bounded correction on every accepted snapshot without storing correction state. Rejected because it does not define behavior across consecutive snapshots and tends to produce visible jitter under sustained updates.
+
+### Decision: New authoritative snapshots update or replace active correction by policy
+When the controlled player already has active bounded correction and another authoritative snapshot arrives, the client will either fold the new residual error into the active correction, replace it with a fresher target, or escalate to hard snap when the combined error breaches the snap threshold.
+
+Why:
+- The sample needs deterministic behavior when correction is still in flight and another snapshot arrives.
+- Replacement rules are necessary to keep the visual path responsive to newer authoritative truth without accumulating stale offsets forever.
+
+Alternative considered:
+- Queue multiple corrections independently. Rejected because it increases latency and can create laggy visual tails after authority has already advanced.
+
+### Decision: Bound correction by convergence budget, not by indefinite smoothing
+Bounded correction will have an explicit convergence budget derived from cadence-aware limits so the visual path either settles quickly or escalates to snap when authority keeps diverging.
+
+Why:
+- P2 is intended to reduce visible twitching, not to hide desync.
+- A bounded budget preserves the principle that authoritative truth must win quickly under sustained mismatch.
+
+Alternative considered:
+- Smooth indefinitely with a low-pass presentation filter. Rejected because it can mask real divergence and make the controlled player feel floaty.
+
+## Risks / Trade-offs
+
+- [Explicit correction state increases local presentation complexity] -> Keep the state narrow, owned by the controlled-player path only, and cover it with regression tests.
+- [Aggressive replacement rules can reintroduce visible twitching] -> Define deterministic merge/replace thresholds and verify them with multi-snapshot regressions.
+- [Overly permissive smoothing can hide divergence too long] -> Keep a hard snap threshold and convergence budget that force recovery to authoritative truth.
+- [Unity update timing can still expose frame-rate-specific artifacts] -> Express requirements in terms of convergence behavior and authoritative ownership rather than exact frame counts.
+
+## Migration Plan
+
+1. Extend the controlled-player reconciliation contract to expose explicit visual correction state and replacement rules.
+2. Update the local sync strategy requirements so consecutive authoritative snapshots interact predictably with bounded correction.
+3. Add regression coverage for repeated small corrections, correction replacement, and snap escalation.
+4. Implement and verify the new policy before archiving the change.
+
+## Open Questions
+
+- Whether the correction state should be fully encapsulated inside `MovementComponent` or extracted into a dedicated helper/state holder.
+- The exact convergence budget values that feel stable in the sample scene without making the controlled player feel detached from input.
@@ -0,0 +1,24 @@
+## Why
+
+P0 and P1 fixed the correctness side of controlled-player reconciliation: acknowledged movement tick is explicit, steady-state prediction uses server-confirmed movement parameters, and authoritative movement cadence is no longer accidental. The sample still has one remaining gap: the local controlled player can look busy or twitchy under repeated small corrections because the current bounded-correction path is only a first-pass clamp, not a fully specified visual convergence policy.
+
+## What Changes
+
+- Tighten the controlled-player reconciliation requirements so small authoritative corrections accumulate through an explicit visual-correction state instead of repeatedly restarting ad hoc per accepted snapshot.
+- Require the local presentation path to separate authoritative gameplay truth from short-lived visual correction state, preserving hard snap only for material divergence.
+- Extend the sync-strategy contract so bounded correction defines convergence behavior across consecutive snapshots instead of only classifying a single snapshot as small or large error.
+- Extend regression coverage to prove multi-snapshot convergence, correction replacement rules, and hard-snap fallback still hold.
+
+## Capabilities
+
+### New Capabilities
+<!-- None. -->
+
+### Modified Capabilities
+- `client-authoritative-player-state`: Tighten the controlled-player presentation contract so authoritative truth and temporary visual correction state remain distinct during local convergence.
+- `network-sync-strategy`: Tighten local reconciliation so bounded correction has explicit replacement, convergence, and snap-escalation rules across consecutive authoritative snapshots.
+- `gameplay-flow-regression-coverage`: Require edit-mode regressions that cover multi-snapshot convergence and repeated local correction behavior for the controlled player.
+
+## Impact
+
+Affected areas include controlled-player reconciliation and presentation code in `MovementComponent` plus any helper types that own local correction state, along with edit-mode regression tests for sync strategy and gameplay-flow round trips. No transport, session-lifecycle, or server authoritative movement protocol changes are expected in this phase.
@@ -0,0 +1,20 @@
+## MODIFIED Requirements
+
+### Requirement: Local player reconciliation applies the full authoritative state by tick
+The controlled client SHALL continue reconciling local prediction from authoritative `PlayerState` snapshots while keeping authoritative HP and optional velocity synchronized with the owned player-state snapshot. Reconciliation MUST use the acknowledged movement-input tick defined by the sync strategy, and the visible controlled-player transform MUST keep authoritative gameplay truth separate from short-lived visual correction state. Small divergence after replay MUST converge through explicit bounded correction state, while large divergence or failed convergence MUST still snap immediately to authoritative `position` and `rotation`.
+
+#### Scenario: Local authoritative state corrects predicted presentation
+- **WHEN** the controlled player accepts an authoritative `PlayerState` whose acknowledged movement-input tick is `N`
+- **THEN** local reconciliation prunes or replays predicted movement using tick `N` according to the sync strategy
+- **THEN** the controlled player's authoritative gameplay state updates immediately to the accepted `position`, `rotation`, HP, and optional velocity
+- **THEN** the local player's visible transform may temporarily differ only through bounded visual correction state that converges back to the authoritative baseline
+
+#### Scenario: Consecutive small corrections replace or fold into active visual correction
+- **WHEN** the controlled player accepts a newer authoritative `PlayerState` while a bounded visual correction is still active and the new residual error remains inside the configured bounded-correction limits
+- **THEN** the client updates the active visual correction state according to the sync strategy instead of preserving stale correction targets indefinitely
+- **THEN** the controlled player's authoritative gameplay state still reflects only the newest accepted `PlayerState`
+
+#### Scenario: Large local divergence bypasses bounded correction
+- **WHEN** the controlled player accepts an authoritative `PlayerState` and the remaining transform error exceeds the configured snap threshold or the active bounded correction can no longer converge within its budget
+- **THEN** the controlled player's visible transform snaps immediately to authoritative `position` and `rotation`
+- **THEN** any temporary visual correction state is cleared before later local prediction resumes from that authoritative baseline
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Gameplay-flow regressions cover controlled-player correction decisions
+The edit-mode regression suite SHALL cover the controlled-player reconciliation path after authoritative movement replay, including bounded correction for small cadence-aligned error, correction replacement under consecutive authoritative snapshots, and hard snap fallback for large or non-convergent divergence.
+
+#### Scenario: Controlled-player reconciliation uses bounded correction for small error
+- **WHEN** an edit-mode regression test applies an authoritative local `PlayerState` that leaves only small post-replay divergence
+- **THEN** the controlled-player path keeps authoritative ownership of the snapshot
+- **THEN** visible correction converges without an immediate hard snap on the acceptance frame
+
+#### Scenario: Controlled-player reconciliation updates active correction on repeated small snapshots
+- **WHEN** an edit-mode regression test feeds multiple authoritative local `PlayerState` updates whose residual divergence remains inside bounded-correction limits while a prior correction is still active
+- **THEN** the controlled-player path replaces or folds the active correction according to the sync strategy
+- **THEN** the test proves the client does not accumulate multiple stale correction tails
+
+#### Scenario: Controlled-player reconciliation snaps on large divergence
+- **WHEN** an edit-mode regression test applies an authoritative local `PlayerState` that leaves divergence beyond the configured snap threshold
+- **THEN** the controlled-player path immediately applies the authoritative transform state
+- **THEN** later prediction resumes from that authoritative baseline
+
+#### Scenario: Controlled-player reconciliation snaps after failed convergence
+- **WHEN** an edit-mode regression test feeds consecutive authoritative local `PlayerState` updates that keep bounded correction from converging within the configured budget
+- **THEN** the controlled-player path escalates to a hard snap
+- **THEN** the active correction state is cleared before later local prediction continues
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Authoritative correction prunes acknowledged prediction history
+The client sync strategy SHALL reconcile local prediction against authoritative player-state updates by pruning acknowledged movement inputs at or before the authoritative acknowledged movement tick and only reapplying newer pending `MoveInput` messages. For the controlled player, reconciliation MUST classify authoritative error after replay into a bounded-correction path for small cadence-aligned divergence and an immediate snap path for large divergence. When bounded correction is already active, later authoritative snapshots MUST deterministically replace, fold into, or escalate that correction based on the newest residual error instead of stacking unbounded visual offsets.
+
+#### Scenario: Reconciliation removes already acknowledged movement inputs
+- **WHEN** the client accepts an authoritative `PlayerState` update that acknowledges movement tick `N`
+- **THEN** locally buffered predicted `MoveInput` messages with tick less than or equal to `N` are removed from the replay buffer
+- **THEN** only `MoveInput` messages newer than `N` remain eligible for re-simulation
+
+#### Scenario: Small post-replay error uses bounded correction
+- **WHEN** the controlled client finishes replay after accepting an authoritative `PlayerState` and the remaining position or rotation error stays within the configured bounded-correction threshold
+- **THEN** the client keeps authoritative ownership of the accepted snapshot
+- **THEN** local presentation converges through bounded correction instead of an immediate hard snap on that frame
+
+#### Scenario: New small error updates active bounded correction
+- **WHEN** the controlled client accepts another authoritative `PlayerState` before the previous bounded correction has finished and the new residual error still stays within bounded-correction limits
+- **THEN** the sync strategy updates the active bounded correction state using the newest authoritative residual error
+- **THEN** the client does not queue multiple independent correction tails for the same controlled player
+
+#### Scenario: Failed bounded correction escalates to snap
+- **WHEN** the controlled client detects that the residual error from consecutive authoritative updates exceeds the snap threshold or remains non-convergent beyond the configured correction budget
+- **THEN** the client immediately applies the authoritative transform state
+- **THEN** any active bounded correction state is discarded before later prediction continues from the authoritative baseline
@@ -0,0 +1,15 @@
+## 1. Controlled Correction State
+
+- [x] 1.1 Introduce an explicit controlled-player visual correction state that stays separate from authoritative gameplay truth.
+- [x] 1.2 Route `MovementComponent` reconciliation so accepted authoritative snapshots update or clear the visual correction state instead of restarting ad hoc per-frame correction.
+
+## 2. Consecutive Snapshot Policy
+
+- [x] 2.1 Implement deterministic rules for folding, replacing, or snapping active bounded correction when newer authoritative snapshots arrive before convergence completes.
+- [x] 2.2 Add convergence-budget and snap-escalation handling so repeated non-convergent small corrections cannot accumulate indefinitely.
+
+## 3. Regression Coverage
+
+- [x] 3.1 Add sync-strategy unit tests that cover repeated small corrections updating the active correction state.
+- [x] 3.2 Add gameplay-flow regression coverage for multi-snapshot controlled-player convergence and snap escalation after failed convergence.
+- [x] 3.3 Run the edit-mode network regression suite, or document the blocking environment issue if the runtime remains unavailable.