process TODO.md step4

2026-03-28 15:50:44 +08:00
parent 4a152e765b
commit f0064e2ae5
22 changed files with 850 additions and 62 deletions
@@ -0,0 +1,39 @@
+# client-authoritative-player-state Specification
+
+## Purpose
+Define how the Unity client owns, applies, and exposes authoritative `PlayerState` snapshots for local and remote players.
+
+## Requirements
+### Requirement: Client keeps one owned authoritative player-state snapshot per player
+The client SHALL keep one explicit owned authoritative `PlayerState` snapshot for each known player instead of spreading authoritative field ownership across unrelated presentation components. The owned snapshot MUST be the source of truth for authoritative `position`, `rotation`, `hp`, and optional `velocity` on the client.
+
+#### Scenario: Incoming authoritative state replaces the owned snapshot
+- **WHEN** the client accepts a newer `PlayerState` for a player
+- **THEN** the latest accepted packet becomes that player's owned authoritative snapshot on the client
+- **THEN** presentation and diagnostics read authoritative `position`, `rotation`, `hp`, and optional `velocity` from that owned snapshot
+
+### Requirement: Local player reconciliation applies the full authoritative state by tick
+The controlled client SHALL continue reconciling local prediction from authoritative `PlayerState.Tick`, and that reconciliation MUST apply the accepted authoritative `position` and `rotation` while keeping authoritative HP and optional velocity synchronized with the owned player-state snapshot.
+
+#### Scenario: Local authoritative state corrects predicted presentation
+- **WHEN** the controlled player accepts an authoritative `PlayerState` for tick `N`
+- **THEN** local reconciliation prunes or replays predicted movement using tick `N` according to the sync strategy
+- **THEN** the local player's visible transform is corrected toward authoritative `position` and `rotation`
+- **THEN** the local player's authoritative HP on the client matches the accepted `PlayerState`
+
+### Requirement: Remote players apply authoritative state without inventing gameplay truth
+Remote player presentation SHALL consume the accepted authoritative player-state snapshot owned by the client and MUST NOT invent HP or final gameplay state locally. Remote movement presentation MUST smooth authoritative position and rotation through a small buffered snapshot interpolation path instead of applying only the latest snapshot directly. Stale remote `PlayerState` packets that are older than the latest accepted authoritative tick for that player MUST NOT overwrite the owned snapshot or enter the interpolation buffer.
+
+#### Scenario: Remote authoritative state updates interpolation input and rejects stale packets
+- **WHEN** a remote player receives a newer authoritative `PlayerState`
+- **THEN** the client's owned snapshot for that remote player updates to the newer authoritative state
+- **THEN** remote presentation adds that accepted authoritative sample to the interpolation buffer for position and rotation smoothing
+- **THEN** an older later-arriving `PlayerState` for that remote player does not overwrite the newer authoritative snapshot or affect interpolation
+
+### Requirement: Authoritative HP and state changes are observable during MVP development
+The client SHALL expose authoritative HP or comparable authoritative state information through lightweight UI or diagnostics so developers can observe server-truth changes during MVP playtests.
+
+#### Scenario: Development UI reflects authoritative HP
+- **WHEN** the client accepts a `PlayerState` whose authoritative HP differs from the previously accepted snapshot
+- **THEN** the relevant UI or diagnostics update to show the new authoritative HP value
+- **THEN** the displayed value comes from authoritative `PlayerState` data rather than speculative local gameplay logic
@@ -0,0 +1,29 @@
+# client-remote-snapshot-interpolation Specification
+
+## Purpose
+Define how the Unity client buffers and interpolates authoritative remote `PlayerState` snapshots for presentation-only movement smoothing.
+
+## Requirements
+### Requirement: Remote players interpolate between buffered authoritative snapshots
+The client SHALL smooth remote-player presentation by buffering a small ordered set of accepted authoritative `PlayerState` snapshots and interpolating between buffered samples instead of lerping directly toward the latest snapshot.
+
+#### Scenario: Remote presentation uses buffered samples
+- **WHEN** the client has at least two buffered authoritative snapshots for a remote player
+- **THEN** remote position and rotation are calculated from interpolation between buffered snapshots
+- **THEN** the client does not smooth that remote player by directly lerping from the current transform to only the newest snapshot
+
+### Requirement: Remote snapshot interpolation uses a documented fixed delay
+The client SHALL render remote players at a small fixed interpolation delay behind the newest received authoritative snapshot timeline, and that delay/sample strategy MUST be documented in code comments or adjacent docs when the implementation is not otherwise obvious.
+
+#### Scenario: Interpolation delay is explicit to maintainers
+- **WHEN** a maintainer reads the remote snapshot interpolation path
+- **THEN** the code or nearby documentation states the interpolation delay and how buffered samples are selected
+- **THEN** the remote smoothing behavior can be tuned without reverse-engineering timing assumptions
+
+### Requirement: Remote interpolation remains presentation-only
+The client SHALL keep remote players non-predicted while using buffered snapshot interpolation. If interpolation cannot bracket two authoritative samples, the client MUST clamp to the latest accepted authoritative snapshot rather than extrapolating remote gameplay state.
+
+#### Scenario: Missing future sample does not trigger remote prediction
+- **WHEN** a remote player has fewer than two usable buffered snapshots for the current render time
+- **THEN** the client presents the latest accepted authoritative snapshot for that remote player
+- **THEN** the client does not extrapolate or simulate additional remote gameplay truth locally