TH1/.codex/skills/th1-network-sync/SKILL.md

name, description

name

description

th1-network-sync

TH1 project-specific network synchronization guide for Unity C# multiplayer, Steam P2P, GameNetSender/GameNetReceiver, SteamLobbyManager, SimpleP2P, MapData/NetData recovery, action sync, host start/resume, ForceUpdate, heartbeat, ordered delivery, large message chunking, send-failure handling, and lobby UI rollback. Use whenever Codex works on TH1 networking, multiplayer saves, deterministic sync, P2P queueing, MapData broadcasts, ActionConfirm/ActionExecute, reconnect, Timer-driven network callbacks, or any bug that may affect multiplayer reliability or ordering.

TH1 Network Sync

Core Rule

Treat multiplayer changes as state-machine changes, not only message sends. Before editing, trace the full path:

GameNetSender -> SteamLobbyManager -> SimpleP2P -> GameNetReceiver -> Main/ActionLogic/MapData.

Do not let one peer advance local game state unless the matching network send/receive contract succeeded.

First Files To Read

• Unity/Assets/Scripts/TH1_Logic/Steam/SimpleP2P.cs
• Unity/Assets/Scripts/TH1_Logic/Steam/SteamLobbyManager.cs
• Unity/Assets/Scripts/TH1_Logic/Steam/GameNetSender.cs
• Unity/Assets/Scripts/TH1_Logic/Steam/GameNetReceiver.cs
• Unity/Assets/Scripts/TH1_Data/NetData.cs
• Unity/Assets/Scripts/TH1_Data/MapData.cs
• Unity/Assets/Scripts/TH1_Logic/Core/Main.cs
• Unity/Assets/Scripts/TH1_Logic/Action/ActionLogic.cs
• Unity/Assets/Scripts/TH1_Instance/Timer.cs
• Unity/Assets/Scripts/TH1_Logic/Editor/NetworkStressEditorWindow.cs when changing or interpreting network stress tests

For the current network contract summary, read references/network-contract.md. For the one-click Steam P2P stress tool, report fields, and current healthy baseline, read references/network-stress.md.

Workflow

1. Classify the message.

   • Critical: GameStart, ForceUpdate, ActionConfirm, ActionExecute, full MapData, reconnect/restore messages.
   • Health/status: heartbeat, map confirm, lobby state, chat.
   • Critical messages must return bool or otherwise expose failure to the caller before local state advances.

2. Preserve ordering.

   • Keep game messages on SimpleP2P per-peer outgoing queues.
   • Do not bypass ordered envelopes for normal game messages.
   • Do not send direct raw Steam messages for gameplay sync unless you also preserve FIFO and failure semantics.

3. Preserve all-or-nothing broadcast for critical messages.

   • Broadcast through SteamLobbyManager.BroadcastMessage.
   • Preflight all lobby targets before enqueueing any target.
   • If any target cannot queue, return failure and avoid local progression.
   • Never accept "some peers got the critical message" as a valid state.

4. Gate local state on send success.

   • Host GameStart must succeed before SaveMapData, RefreshTurn, room UI close, or final success return.
   • Owner ActionExecute broadcast must succeed before owner local execute.
   • Client ActionConfirm must succeed before client local execute; TurnEnd may send and then stop local execution.
   • Heartbeat send timestamps should only update after the send was accepted.

5. Validate MapData before sending or applying.

   • Reject null maps, DeserializedMissingCriticalData, wrong NetMode, and missing core maps.
   • Call Net.RefreshPlayerNet(mapData) and respect its bool result.
   • Ensure every current lobby member maps to a valid PlayerId.
   • Do not repair missing critical data silently during deserialization.

6. Roll back failed start/resume.

   • Snapshot MapData, InputLogic, MapInteractionLogic, and MapGeneratorLogic before host start/resume mutation.
   • On failure or exception, restore the snapshot, dispose/reinitialize render state as appropriate, cancel pending start timers, and keep lobby UI open.
   • UI code must only invoke room-close/start callbacks after the start method returns true.

7. Keep receiver failure atomic.

   • Deserialize and dispatch inside try/catch.
   • If incoming GameStart or ForceUpdate validation fails, do not hide room UI and do not leave the game in ForceUpdating.
   • Restore previous game state if NetResumeMatch fails.

8. Preserve the stress-test path.

   • NetworkStressMessage is a diagnostics message and must not mutate gameplay state.
   • GameNetReceiver should ignore P2PMsgType.NetworkStress; the editor tool listens through SimpleP2P.OnMessageReceivedEvent.
   • Stress probes must still use Lobby.BroadcastMessage / SendMessageToPeer so they cover the real ordered queue and large-message chunking path.
   • Keep per-run RunId isolation so stale packets or ACKs from a previous test cannot pollute a new report.
   • The host should export after collecting client reports or after the configured report wait timeout; clients should retry report sends briefly after test completion.

Checks Before Finishing

Run:

dotnet build Unity/Assembly-CSharp.csproj --no-restore

If editor tooling changed, also run:

dotnet build Unity/Assembly-CSharp-Editor.csproj --no-restore

For network-heavy changes, inspect these risks explicitly:

• Could a critical broadcast partially enqueue?
• Could a caller ignore a failed send and still mutate game state?
• Could MapData deserialize with missing core fields and still be used?
• Could a timer callback fire after the target UI/object state is gone?
• Could a retry loop or ordered gap wait forever?
• If stress tooling or queue throughput changed, does the one-click two-machine report meet the baseline in references/network-stress.md?

What Not To Do

• Do not add a new direct send path around SimpleP2P queues for gameplay sync.
• Do not silently swallow SendMessageToPeer or BroadcastMessage failure.
• Do not call GameNetReceiver from a partial large-message chunk.
• Do not close the multiplayer room UI before host start returns success.
• Do not call GC.Collect() in match entry paths as a networking fix.