调整嵌套类位置 + 制订阶段 5 task
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-27
|
||||
@@ -0,0 +1,70 @@
|
||||
## Context
|
||||
|
||||
The networking stack now has a stable shared foundation: `KcpTransport` is the only reliable transport, message dispatch is host-injected, and session lifecycle is modeled explicitly for single-session clients and multi-session servers. However, `MessageManager` still sends every business message through one `ITransport`, `MovementComponent` still predicts and reconciles against authoritative state that arrives on the same reliable ordered lane as login and heartbeat traffic, and `SessionManager` still owns the last server-tick sample that prediction code reads indirectly through heartbeat handling.
|
||||
|
||||
Stage 6 needs a cross-cutting design because the current bottleneck is no longer transport correctness, but policy coupling. `PlayerInput` and `PlayerState` are high-frequency streams where newer data is usually more valuable than guaranteed delivery of older data. Keeping them on the same reliable ordered KCP lane as control-plane messages creates head-of-line blocking under packet loss or jitter. At the same time, time synchronization now serves prediction and reconciliation more than lifecycle ownership, so it should stop living inside the heartbeat/session state machine.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Introduce a host-agnostic delivery-policy layer that separates reliable control traffic from high-frequency gameplay synchronization traffic.
|
||||
- Define latest-wins sequencing rules for `PlayerInput` and `PlayerState` so stale updates can be rejected deterministically.
|
||||
- Extract clock-synchronization state from `SessionManager` into a dedicated sync-policy component that prediction and reconciliation code can consume directly.
|
||||
- Preserve the existing client single-session composition and server multi-session composition while evolving shared networking behavior.
|
||||
- Keep the envelope/message-type contract stable across the shared networking stack.
|
||||
|
||||
**Non-Goals:**
|
||||
- Replace `KcpTransport` as the project's reliable control transport.
|
||||
- Redesign login, logout, authentication, or reconnect semantics introduced in earlier stages.
|
||||
- Deliver stage 7 metrics/logging work in the same change.
|
||||
- Rewrite gameplay authority rules or build a full deterministic rollback system beyond the networking-facing prediction buffer changes needed here.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Introduce delivery-policy routing above transport implementations
|
||||
The shared runtime will add a policy-selection layer that resolves a delivery profile from `MessageType` before a message is sent or accepted. Reliable control messages continue to use the existing `ITransport` and `MessageManager` path, while high-frequency sync messages use a dedicated sync lane abstraction chosen by the host. This keeps transport choice centralized and prevents gameplay code from hard-coding which transport instance to call.
|
||||
|
||||
Alternative considered: add QoS flags or transport parameters to every `SendMessage` call.
|
||||
Rejected because it spreads policy decisions across handlers and host code, making the routing contract harder to audit and easier to misuse.
|
||||
|
||||
### Model `PlayerInput` and `PlayerState` as sequenced latest-wins streams
|
||||
The new sync strategy will treat `PlayerInput` and `PlayerState` as streams that carry monotonic ordering data, using the existing tick fields and allowing an explicit sequence field if the implementation needs one later. Receivers accept only the newest update for a given player/entity stream and drop older arrivals. This removes the main user-visible problem of reliable ordered delivery for movement: outdated packets blocking fresher state.
|
||||
|
||||
Alternative considered: keep both message types on reliable KCP and reduce send frequency.
|
||||
Rejected because it preserves head-of-line blocking and only hides the symptom by lowering update density.
|
||||
|
||||
Alternative considered: send sync traffic unreliably without any ordering metadata.
|
||||
Rejected because the receiver would have no deterministic way to reject stale state or reconcile prediction buffers safely.
|
||||
|
||||
### Extract clock sync into a dedicated strategy component
|
||||
`SessionManager` should continue owning transport/login/liveness/timeout/reconnect semantics, but it should stop being the long-term owner of server-clock samples. A dedicated clock-sync component can consume server tick samples from heartbeat responses and authoritative gameplay updates, smooth them as needed, and expose the current estimate to prediction/reconciliation code without mutating lifecycle state. This matches the real ownership boundary: clock sync informs simulation alignment, not session health.
|
||||
|
||||
Alternative considered: keep `LastServerTick` inside `SessionManager` and let gameplay code keep reading it there.
|
||||
Rejected because it couples sync tuning to lifecycle policy and makes later sampling changes look like session-state changes.
|
||||
|
||||
### Preserve explicit client and server host composition
|
||||
The Unity client should keep composing a main-thread dispatcher, a single-session lifecycle path, and local prediction code, while the server host keeps explicit multi-session routing. The new sync abstractions should be shared, but host adapters remain responsible for how they drive ticking, buffering, and per-peer identity. This avoids forcing Unity frame-loop concerns or server peer-collection concerns into one universal runtime type.
|
||||
|
||||
Alternative considered: hide sync routing inside `KcpTransport` or `SessionManager`.
|
||||
Rejected because both types already have narrower ownership boundaries, and embedding sync policy there would recreate the coupling earlier stages removed.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Two delivery lanes increase routing complexity] -> Mitigation: keep one central message-type-to-policy map and cover it with explicit routing tests.
|
||||
- [Dropped input packets can momentarily reduce simulation fidelity] -> Mitigation: define latest-wins semantics around ticked input snapshots and allow the sender to keep publishing the newest state at a steady cadence.
|
||||
- [Prediction corrections can become more visible if clock smoothing is noisy] -> Mitigation: isolate clock-sync state behind a dedicated component with deterministic tests for sample acceptance and smoothing behavior.
|
||||
- [Client and server integration can drift if abstractions are too host-specific] -> Mitigation: keep the policy contracts in shared networking code and verify client single-session and server multi-session behavior in edit mode tests.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Introduce shared delivery-policy abstractions and a default policy map while leaving all traffic on the existing reliable path as a safe starting point.
|
||||
2. Add the sync strategy lane and move `PlayerInput` and `PlayerState` routing onto it, while login/logout/heartbeat and other control traffic remain on KCP.
|
||||
3. Move server-tick ownership out of `SessionManager` and into a dedicated clock-sync state object consumed by prediction/reconciliation code.
|
||||
4. Update client reconciliation and server acceptance rules to use stale-drop/latest-wins semantics keyed by authoritative tick or sequence.
|
||||
5. Add regression tests for routing, stale packet rejection, reconciliation buffer pruning, and clock-sync sampling. If rollback is needed, the policy map can route all message types back to the reliable KCP path without undoing earlier lifecycle work.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should the first implementation of the sync lane use a dedicated `UdpClient`-backed transport, or should it start behind an abstract lane that can be backed by KCP tuning or raw UDP later?
|
||||
- Do remote-player `PlayerState` updates need an explicit sync sequence separate from simulation tick for interpolation-heavy actors?
|
||||
- Should the client send only the latest input snapshot each interval, or opportunistically bundle the newest few inputs to soften brief loss bursts without restoring head-of-line blocking?
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
The shared networking stack now has stable transport, dispatch, and session-lifecycle boundaries, but all gameplay traffic still rides the same reliable ordered KCP path. Stage 6 is needed now because high-frequency `PlayerInput` and `PlayerState` traffic can still suffer from head-of-line blocking, and clock synchronization is still coupled to heartbeat/session bookkeeping instead of being treated as a tunable sync policy.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add a shared high-frequency sync strategy layer that lets hosts assign delivery policies to gameplay synchronization messages instead of forcing `PlayerInput` and `PlayerState` through the same reliable ordered path as login and control traffic.
|
||||
- Define latest-wins sequencing rules for high-frequency client input and authoritative player-state updates so stale packets can be discarded instead of blocking fresher movement data.
|
||||
- Extract clock-synchronization sampling from `SessionManager` ownership into an explicit sync-policy component that can consume heartbeat or gameplay timing samples without changing lifecycle state semantics.
|
||||
- Update client prediction and reconciliation flow so authoritative state correction is aligned with the new sync-message sequencing rules.
|
||||
- Keep KCP as the only reliable transport for control-plane traffic such as login, logout, heartbeat/liveness, and other messages that still require guaranteed ordered delivery.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `network-sync-strategy`: Shared delivery-policy, sequencing, and reconciliation rules for high-frequency gameplay synchronization and independent clock-sync sampling.
|
||||
|
||||
### Modified Capabilities
|
||||
- `kcp-transport`: Reliable KCP delivery remains the default control-plane path, but high-frequency `PlayerInput` and `PlayerState` are no longer required to stay on the same reliable ordered lane.
|
||||
- `network-session-lifecycle`: Session lifecycle keeps heartbeat-focused liveness and timeout ownership, while clock-sync sampling moves to a separate sync strategy instead of living inside `SessionManager`.
|
||||
- `shared-network-foundation`: The shared client/server runtime composes message routing with delivery-policy selection for reliable control traffic and high-frequency sync traffic without introducing Unity-specific dependencies.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected code: `MessageManager`, `SharedNetworkRuntime`, `NetworkManager`, `ServerNetworkHost`, transport composition around `ITransport`/future sync lanes, movement prediction/reconciliation code, and new sync-policy/state types.
|
||||
- Affected behavior: login and other control traffic stay reliable, while `PlayerInput`/`PlayerState` follow latest-wins sequencing and stale-update dropping to reduce visible movement lag under packet loss or jitter.
|
||||
- Affected tests: edit mode networking tests need explicit coverage for delivery-policy routing, stale packet rejection, prediction/correction behavior, and independent clock-sync sampling alongside existing lifecycle regressions.
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: KCP is the sole reliable transport implementation
|
||||
The project SHALL expose `KcpTransport` as the only reliable `ITransport` implementation used by runtime networking paths. Reliable control-plane business messages, including login, logout, heartbeat, and other ordered session-management traffic, MUST continue to flow through KCP-backed sessions, while high-frequency `PlayerInput` and `PlayerState` synchronization MAY use a separate sync lane defined by the sync-strategy capability.
|
||||
|
||||
#### Scenario: Runtime networking uses KCP for reliable control delivery
|
||||
- **WHEN** the application constructs the reliable transport used for login and session control traffic
|
||||
- **THEN** that transport instance is `KcpTransport`
|
||||
- **THEN** reliable control payloads are sent and received through KCP session state
|
||||
|
||||
#### Scenario: High-frequency sync is allowed to bypass reliable ordered delivery
|
||||
- **WHEN** the runtime routes `PlayerInput` or `PlayerState` according to the high-frequency sync strategy
|
||||
- **THEN** those messages are not forced to use the reliable ordered KCP lane
|
||||
- **THEN** reliable KCP delivery remains available for control-plane traffic
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Heartbeat is limited to liveness, RTT, and time sync
|
||||
The shared session lifecycle SHALL treat heartbeat traffic as infrastructure input for liveness detection and round-trip-time measurement only. Clock-synchronization samples MUST be forwarded to a separate sync-strategy component rather than being owned by `SessionManager`, and heartbeat processing MUST NOT itself own login success, login failure, or reconnect policy decisions.
|
||||
|
||||
#### Scenario: Heartbeat updates liveness and RTT while forwarding clock samples
|
||||
- **WHEN** a heartbeat response is received for an active session
|
||||
- **THEN** the session manager updates last-seen or timeout bookkeeping and RTT data
|
||||
- **THEN** any server-tick sample is forwarded to the clock-sync strategy without making heartbeat the owner of login state
|
||||
|
||||
#### Scenario: Missing heartbeat triggers timeout state
|
||||
- **WHEN** the configured heartbeat timeout elapses without a required heartbeat or other liveness signal
|
||||
- **THEN** the session lifecycle transitions the session into a timed-out state
|
||||
- **THEN** reconnect handling is delegated to the lifecycle reconnect policy rather than hidden inside the heartbeat handler itself
|
||||
@@ -0,0 +1,53 @@
|
||||
# network-sync-strategy Specification
|
||||
|
||||
## Purpose
|
||||
Define how client and server route high-frequency gameplay synchronization traffic, reject stale updates, reconcile authoritative state, and process clock-sync samples independently of session lifecycle.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Hosts assign delivery policies to synchronization message types
|
||||
The shared networking core SHALL allow hosts to map business message types to delivery policies. `PlayerInput` and `PlayerState` MUST be assignable to a high-frequency sync policy that is independent from the reliable ordered control policy used by login and lifecycle traffic.
|
||||
|
||||
#### Scenario: High-frequency sync messages use a dedicated policy
|
||||
- **WHEN** the client or server sends `PlayerInput` or `PlayerState`
|
||||
- **THEN** the runtime resolves a high-frequency sync delivery policy for that message type
|
||||
- **THEN** the message is sent through the sync lane configured for that policy instead of defaulting to reliable ordered delivery
|
||||
|
||||
#### Scenario: Control traffic keeps reliable delivery
|
||||
- **WHEN** the runtime sends login, logout, heartbeat, or other session-management messages
|
||||
- **THEN** the runtime resolves the reliable ordered control policy
|
||||
- **THEN** those messages continue to use the reliable transport path
|
||||
|
||||
### Requirement: Sequenced sync receivers discard stale gameplay updates
|
||||
The high-frequency sync strategy SHALL tag gameplay synchronization messages with monotonic sequencing information and MUST discard stale `PlayerInput` or `PlayerState` updates that arrive older than the last accepted update for the same peer or entity stream.
|
||||
|
||||
#### Scenario: Older player input is ignored
|
||||
- **WHEN** the server receives a `PlayerInput` update with a tick or sequence older than the latest accepted input for that player
|
||||
- **THEN** the server drops that stale input update
|
||||
- **THEN** the newer accepted input remains authoritative for simulation
|
||||
|
||||
#### Scenario: Older player state does not rewind a client
|
||||
- **WHEN** the client receives a `PlayerState` update with a tick or sequence older than the latest applied authoritative state for that player
|
||||
- **THEN** the client ignores the stale state update
|
||||
- **THEN** visible movement continues from the newer authoritative state without rewinding to older data
|
||||
|
||||
### Requirement: Authoritative correction prunes acknowledged prediction history
|
||||
The client sync strategy SHALL reconcile local prediction against authoritative player-state updates by pruning acknowledged inputs at or before the authoritative tick and only reapplying newer pending inputs.
|
||||
|
||||
#### Scenario: Reconciliation removes already acknowledged inputs
|
||||
- **WHEN** the client accepts an authoritative `PlayerState` update for tick `N`
|
||||
- **THEN** locally buffered predicted inputs with tick less than or equal to `N` are removed from the replay buffer
|
||||
- **THEN** only inputs newer than `N` remain eligible for re-simulation
|
||||
|
||||
### Requirement: Clock synchronization is a separate sync-policy concern
|
||||
The shared networking core SHALL process server-tick or clock-synchronization samples through a dedicated sync-policy component rather than storing clock-sync ownership inside `SessionManager`.
|
||||
|
||||
#### Scenario: Heartbeat response contributes a clock sample without mutating lifecycle
|
||||
- **WHEN** a heartbeat or gameplay sync message carries a server-tick sample
|
||||
- **THEN** the runtime forwards that sample to the clock-sync strategy
|
||||
- **THEN** session lifecycle state remains unchanged except for liveness or RTT bookkeeping
|
||||
|
||||
#### Scenario: Hosts can consume smoothed clock data for prediction
|
||||
- **WHEN** prediction or reconciliation code needs the current server-time estimate
|
||||
- **THEN** it reads that estimate from the clock-sync strategy or state object
|
||||
- **THEN** it does not query `SessionManager` for authoritative clock ownership
|
||||
@@ -0,0 +1,14 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Shared core preserves current transport and message contracts
|
||||
The shared client/server foundation SHALL preserve the envelope-based business-message contract across client and server hosts while allowing delivery-policy selection behind the shared message-routing layer. Reliable control traffic MUST continue to use the existing `ITransport` contract, and high-frequency sync traffic MUST be composable through a host-agnostic sync strategy without introducing Unity-specific runtime types into the shared networking core.
|
||||
|
||||
#### Scenario: Shared hosts exchange the same envelope format across delivery lanes
|
||||
- **WHEN** a client host sends a business message through either the reliable control path or the high-frequency sync path
|
||||
- **THEN** the payload is encoded with the same shared envelope and message-type contract
|
||||
- **THEN** the server host decodes and routes it through shared networking logic without a host-specific protocol fork
|
||||
|
||||
#### Scenario: Hosts compose delivery-policy selection without Unity dependencies
|
||||
- **WHEN** a non-Unity server host constructs the runtime networking stack with reliable control traffic and a high-frequency sync lane
|
||||
- **THEN** it uses shared delivery-policy abstractions without depending on Unity frame-loop types
|
||||
- **THEN** the Unity client can use the same abstractions while still supplying its own host-specific dispatch behavior
|
||||
@@ -0,0 +1,23 @@
|
||||
## 1. Delivery Policy Infrastructure
|
||||
|
||||
- [ ] 1.1 Introduce shared delivery-policy abstractions and a default message-type map for reliable control traffic versus high-frequency sync traffic.
|
||||
- [ ] 1.2 Extend `SharedNetworkRuntime`, `MessageManager`, and host composition points to route messages through the resolved policy without breaking the shared envelope contract.
|
||||
- [ ] 1.3 Add the first sync-lane backend and any supporting transport adapter types needed to keep client single-session and server multi-session composition explicit.
|
||||
|
||||
## 2. High-Frequency Sync Routing
|
||||
|
||||
- [ ] 2.1 Route `PlayerInput` and `PlayerState` through the high-frequency sync policy while keeping login, logout, heartbeat, and other control messages on reliable KCP.
|
||||
- [ ] 2.2 Implement monotonic ordering tracking for sync streams and reject stale `PlayerInput` / `PlayerState` updates on the receiving side.
|
||||
- [ ] 2.3 Update server-side sync handling so each remote peer maintains independent latest-wins state instead of relying on reliable ordered delivery.
|
||||
|
||||
## 3. Clock Sync And Reconciliation
|
||||
|
||||
- [ ] 3.1 Introduce a dedicated clock-sync strategy/state object and move authoritative server-tick ownership out of `SessionManager`.
|
||||
- [ ] 3.2 Refactor heartbeat and authoritative-state handlers so liveness/RTT updates stay in session lifecycle while clock samples flow through the sync strategy.
|
||||
- [ ] 3.3 Update client prediction and reconciliation code to prune acknowledged inputs, ignore stale authoritative state, and replay only newer pending inputs.
|
||||
|
||||
## 4. Verification And Documentation
|
||||
|
||||
- [ ] 4.1 Add edit mode tests for delivery-policy routing, stale packet rejection, and clock-sync forwarding behavior.
|
||||
- [ ] 4.2 Add regression tests covering client prediction buffer pruning and server multi-session sync isolation under delayed or out-of-order updates.
|
||||
- [ ] 4.3 Update `CodeX-TODO.md` and related networking docs to reflect the phase 6 architecture and completion criteria.
|
||||
Reference in New Issue
Block a user