@ericrisco/rsc 0.1.34 → 0.1.36

package/skills/gamedev-multiplayer/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: gamedev-multiplayer
+description: "Use when adding multiplayer, netcode, or replication to a game — syncing players/state across a network, online co-op or PvP, client-server vs peer-to-peer, server-authoritative design, client-side prediction + server reconciliation, snapshot interpolation, lag compensation, tick/netrate, and per-engine wiring: Godot 4.x MultiplayerSpawner/MultiplayerSynchronizer/@rpc/ENetMultiplayerPeer/set_multiplayer_authority, Unity Netcode for GameObjects (NetworkObject/NetworkBehaviour/NetworkVariable/[Rpc]/ServerRpc/ClientRpc), Unreal Actor replication (Replicated/ReplicatedUsing, Server/Client/NetMulticast RPCs, relevancy). Triggers: 'how do I sync players', 'client and server desync', 'players rubber-band or teleport', 'who has authority', 'laggy movement', 'cheater set their own health'. NOT single-player gameplay, AI, or input (route to engine skill godot/unity/unreal), and NOT matchmaking, dedicated-server hosting, or backend infra (route to deployment)."
+tags: [multiplayer, netcode, replication, networking, prediction, authority]
+recommends: [godot, unity, unreal, gamedev-physics]
+profiles: [full]
+origin: risco
+---
+
+# Game multiplayer & netcode
+
+Design and wire the network layer of a game across Godot 4.x, Unity, and Unreal: choose a
+topology, put authority in the right place, replicate the right state, and hide latency without
+opening the door to cheaters. This skill owns the *networking* decisions; the engine skills own
+the local gameplay those decisions sit on top of.
+
+## Version contract — read first
+
+Target the current APIs. **Never emit these deprecated / removed APIs:**
+
+| Engine | Target | Banned (removed/legacy) | Emit instead |
+|---|---|---|---|
+| **Godot** | 4.x | `master`/`puppet`/`remote`/`sync` keywords, `rpc_config()` as a func, `rset`, `NetworkedMultiplayerENet` | `@rpc(...)` annotation, `set_multiplayer_authority()`, `ENetMultiplayerPeer`, `MultiplayerSynchronizer` |
+| **Unity** | Netcode for GameObjects (NGO) 1.x/2.x | UNet / HLAPI: `NetworkIdentity`, `[Command]`, `[SyncVar]`, `NetworkServer`, `UnityEngine.Networking` | NGO `NetworkObject`, `NetworkBehaviour`, `NetworkVariable<T>`, `[Rpc(SendTo.X)]` |
+| **Unreal** | 5.x | replicating by polling in `Tick`, skipping `WithValidation` on gameplay RPCs | `UPROPERTY(Replicated / ReplicatedUsing=...)` + `GetLifetimeReplicatedProps`, `Server`/`Client`/`NetMulticast` `UFUNCTION`s |
+
+UNet is **removed** from modern Unity — do not scaffold it. If a repo genuinely uses Mirror (a
+community UNet-like fork), say so; this skill targets first-party NGO. In NGO 2.x the unified
+`[Rpc(SendTo.Server)]` / `[Rpc(SendTo.ClientsAndHost)]` attribute is preferred; the older
+`[ServerRpc]` / `[ClientRpc]` still compile (and enforce `…ServerRpc` / `…ClientRpc` method-name
+suffixes) — cover them but prefer the unified form on new code.
+
+## Fires on / When NOT
+
+**Fires on:** "how do I sync players", replication, netcode, RPCs, authority, online co-op or PvP,
+"client and server disagree", rubber-banding / teleporting players, prediction & reconciliation,
+lag compensation, tick rate / send rate, spawning networked objects, "the client can cheat".
+
+**When NOT (route away):**
+
+- Single-player movement, AI, input, animation, save files → the engine skill: `godot`, `unity`, `unreal`.
+- Physics determinism, collision, character controllers → `gamedev-physics` (netcode *consumes* it).
+- Matchmaking service, lobby backend, dedicated-server hosting/orchestration, relays, DB → `deployment`.
+- Web realtime (chat, presence, generic WebSocket app) that is not a game world → `webhooks` / a backend skill.
+
+## Topologies & authority
+
+Pick the topology first; everything else follows from it.
+
+- **Client-server, dedicated server** — a headless authoritative process no player controls. The gold
+  standard for competitive/persistent games: one source of truth, hardest to cheat, costs money to run.
+- **Client-server, listen server** — one player's machine is also the server (host). Cheap, zero infra,
+  but the host has a latency advantage and can tamper; fine for co-op and casual PvP. **Design so the
+  same code runs on both** (a listen server is a dedicated server that also has a local client).
+- **Peer-to-peer** — no central authority; peers exchange state directly. Low infra cost and low latency
+  between peers, but NAT traversal is painful, it is the easiest to cheat, and it needs lockstep or a
+  rollback model to stay consistent. Reasonable for small trusted lobbies or deterministic fighting games.
+
+**Server-authoritative is the default.** The server owns the truth; clients send *intent* (inputs,
+requests), never results. **Never trust the client:** the client cannot set its own health, position,
+score, currency, or hit results — it *asks*, the server *decides*, everyone else *observes*. A client
+that says "I moved to X / I did 40 damage / I have 999 gold" is either lagging or cheating; treat both
+the same. The one thing a client legitimately owns is its own input and, by convention, cosmetic-only
+state. See references/prediction-and-latency.md for how to keep this responsive.
+
+## State replication vs RPCs
+
+Two complementary tools — use the right one:
+
+- **State replication** = *continuous* synchronized values (health, position, ammo, team). The framework
+  watches a variable and pushes changes to relevant peers; late-joiners get the current value automatically.
+  Use for anything a client needs the *latest* of. It is idempotent and self-healing on packet loss.
+- **RPCs (remote procedure calls)** = *one-shot events* ("fire weapon", "play explosion at P", "open door").
+  Fire-and-forget; a dropped unreliable RPC is simply lost. Use for events, **never** for state you need to
+  stay consistent — a missed "you died" RPC leaves a client desynced forever; a replicated `isDead` bool
+  self-corrects.
+
+**Rule of thumb:** replicate *nouns* (state), RPC *verbs* (events). What to replicate: only what other
+peers must see, at the coarsest rate that still looks right — position/rotation of visible actors,
+gameplay stats, animation state flags. Do **not** replicate values a peer can derive locally, purely
+cosmetic particles, or high-frequency data no one observes.
+
+**Ownership / authority** decides *who may write*. Every networked object has an owner (a peer id) and an
+authority (usually the server). Writes to replicated state must come from the authority; ownership lets a
+client drive *its own* pawn's input while the server still validates the outcome. Getting ownership wrong
+is the #1 cause of "it works for the host but not the client" bugs.
+
+## The hard problems
+
+Latency (round-trip time, RTT) is the enemy; jitter and packet loss make it worse. Four techniques,
+covered in depth in **references/prediction-and-latency.md**:
+
+1. **Client-side prediction** — the owning client applies its own input *immediately* instead of waiting a
+   full RTT for the server, so local movement feels instant.
+2. **Server reconciliation** — the server is still authoritative; the client tags each input with a sequence
+   number, and when the authoritative state arrives it *replays* any inputs the server hadn't processed yet.
+   Mismatch → a correction (the visible "rubber-band"); minimize it, don't hide it.
+3. **Snapshot interpolation** — *remote* entities are rendered ~100 ms in the past, interpolating between the
+   last two received snapshots, so other players move smoothly instead of teleporting between updates.
+4. **Lag compensation** — for hitscan/instant hits, the server rewinds other entities to where the shooter
+   *saw* them (at the shooter's render time) before testing the hit. Fairer for the shooter; occasionally
+   "shot behind a wall" for the victim. A deliberate tradeoff, not a bug.
+
+**Tick rate / netrate:** the server simulates at a fixed tick (e.g. 20–64 Hz) and sends state at a *send
+rate* that may be lower than its sim rate and decoupled from client render FPS. Never tie gameplay to frame
+rate on a networked game — simulate on a fixed timestep, interpolate for rendering.
+
+## Per-engine mapping
+
+Short form here; full patterns in the references. All snippets are current-API.
+
+### Godot 4.x — high-level multiplayer
+
+`ENetMultiplayerPeer` for transport, `@rpc` for events, `MultiplayerSynchronizer` for state, and
+`MultiplayerSpawner` to replicate object spawns. Authority via `set_multiplayer_authority(peer_id)`.
+
+```gdscript
+# Host / join
+func host(port := 9999) -> void:
+    var peer := ENetMultiplayerPeer.new()
+    peer.create_server(port, 8)
+    multiplayer.multiplayer_peer = peer
+
+func join(ip: String, port := 9999) -> void:
+    var peer := ENetMultiplayerPeer.new()
+    peer.create_client(ip, port)
+    multiplayer.multiplayer_peer = peer
+
+# RPC: params are optional and order-free. any_peer lets clients call it;
+# authority (default) means only the multiplayer authority may call it.
+@rpc("any_peer", "call_local", "reliable")
+func request_fire(target: Vector3) -> void:
+    if not multiplayer.is_server(): return          # server validates
+    var shooter := multiplayer.get_remote_sender_id()
+    _resolve_shot(shooter, target)                  # server decides the result
+```
+
+- `set_multiplayer_authority(id)` on a node; check with `is_multiplayer_authority()`. A player scene
+  usually gives its input node authority to the owning peer while the server keeps authority over health.
+- `MultiplayerSynchronizer` streams a chosen property list (position, etc.) from the authority to peers;
+  set its replication interval and visibility (`set_visibility_for(peer, bool)`) to scope bandwidth.
+- `MultiplayerSpawner` replicates instancing of scenes under a path so late peers get existing objects.
+- Details, prediction wiring, and the full player-scene pattern: **references/godot-high-level-multiplayer.md**.
+
+### Unity — Netcode for GameObjects
+
+`NetworkObject` (the identity, spawned via `Spawn()`), `NetworkBehaviour` (networked scripts),
+`NetworkVariable<T>` (replicated state), and RPCs. `NetworkManager.Singleton.StartHost/StartServer/StartClient`.
+
+```csharp
+public class Player : NetworkBehaviour {
+    // Default perms: everyone reads, only the SERVER writes → authoritative health.
+    public NetworkVariable<int> Health = new(100);
+
+    [Rpc(SendTo.Server)]                       // client → server: an intent
+    void FireRpc(Vector3 target) {
+        // runs on the server; validate, then apply and let NetworkVariables replicate the result
+        ResolveShot(OwnerClientId, target);
+    }
+
+    [Rpc(SendTo.ClientsAndHost)]               // server → everyone: an event
+    void PlayMuzzleFxRpc(Vector3 at) { /* cosmetic only */ }
+}
+```
+
+- Ownership/role: `IsOwner`, `IsServer`, `IsClient`, `IsHost`, `OwnerClientId`. Only owners should send
+  owner-intent RPCs; the server validates regardless.
+- `NetworkVariable<T>(value, readPerm, writePerm)` — `NetworkVariableWritePermission.Server` (default) vs
+  `.Owner`; subscribe via `OnValueChanged`. Use `NetworkTransform` for pos/rot sync.
+- Prefer the unified `[Rpc(SendTo.X)]`; legacy `[ServerRpc]`/`[ClientRpc]` still work but need the
+  method-name suffixes. Full patterns: **references/unity-and-unreal-netcode.md**.
+
+### Unreal — Actor replication
+
+Set `AActor::bReplicates = true` (or `SetReplicates(true)`). Replicate properties with `UPROPERTY` and
+register them in `GetLifetimeReplicatedProps`; use RPC `UFUNCTION` specifiers for events.
+
+```cpp
+UPROPERTY(ReplicatedUsing = OnRep_Health)   // RepNotify fires on clients when it changes
+float Health = 100.f;
+
+UFUNCTION(Server, Reliable, WithValidation)  // client → server intent (+ validation)
+void ServerFire(FVector Target);
+
+UFUNCTION(NetMulticast, Unreliable)          // server → all: cosmetic event
+void MulticastMuzzleFx(FVector At);
+
+void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
+    Super::GetLifetimeReplicatedProps(Out);
+    DOREPLIFETIME(AMyPawn, Health);          // or DOREPLIFETIME_CONDITION for push/owner-only
+}
+```
+
+- Authority check: `HasAuthority()` (server or standalone); roles `ROLE_Authority`, `ROLE_AutonomousProxy`
+  (the owning client), `ROLE_SimulatedProxy` (observed elsewhere).
+- **Relevancy** keeps bandwidth sane: `NetCullDistanceSquared`, `bAlwaysRelevant`, `IsNetRelevantFor`, and
+  dormancy (`SetNetDormancy`) stop replicating actors a client can't perceive. Movement replicates via
+  `CharacterMovementComponent`, which already does prediction+reconciliation for you.
+- RepNotify vs Multicast, GAS/Network Prediction notes: **references/unity-and-unreal-netcode.md**.
+
+## Security / anti-cheat basics
+
+- **Validate every client input on the server** — bounds-check movement deltas, cooldowns, line-of-sight,
+  and resource costs. Reject the impossible; never assume a well-behaved client.
+- **Send a client only what it may know.** Don't replicate enemy positions through walls (wallhack fuel),
+  full inventories of others, or hidden RNG seeds — scope with relevancy/visibility.
+- Rate-limit and sanity-check RPCs; a client spamming `ServerFire` faster than the weapon allows is caught
+  by server-side cooldowns, not client-side ones.
+- Encryption/DTLS stops packet tampering on the wire but does **not** stop a modified client — only server
+  authority does. Treat anti-cheat as defense in depth, not a product this skill ships.
+
+## Testing multiplayer locally
+
+- **Godot:** enable *Debug → Run Multiple Instances* (2–4 windows) to host+join on one machine.
+- **Unity:** *Multiplayer Play Mode* (or ParrelSync) runs several virtual players from one project;
+  Network Simulator injects latency/loss.
+- **Unreal:** PIE *Number of Players* + *Net Mode* (Play As Listen Server / Client), and *Net PktLag* /
+  packet-emulation console vars to fake latency.
+- Always test **with simulated latency and packet loss**, not just on localhost — localhost hides every
+  prediction/reconciliation bug. Test the client path, not only the host's.
+
+## Guardrails / gotchas
+
+- Localhost is a liar: 0 ms RTT masks the exact desync/rubber-band bugs your players will hit. Inject lag.
+- Don't RPC state you need to stay consistent — replicate it (an unreliable event drop is permanent).
+- Don't tie simulation to render FPS; fixed timestep on the sim, interpolate on the render.
+- The listen-server host is a client too — guard authority-only logic behind an `is_server`/`HasAuthority`
+  check or it double-executes on the host.
+- Wrong ownership = "works for host, breaks for client." Set authority/ownership explicitly on spawn.
+- Replicating everything, every tick, to everyone melts bandwidth — scope by relevancy/visibility and rate.
+
+## Related skills
+
+- **`godot` / `unity` / `unreal`** — the engine your game runs in; owns local gameplay, input, scenes, build.
+- **`gamedev-physics`** — determinism, collision, character controllers; netcode replicates its results and
+  needs its determinism for prediction/rollback.
+- **`deployment`** — dedicated-server hosting, matchmaking/lobby backend, relays, and CI for game servers.
+- **`secure-coding`** — general threat modeling; this skill keeps only the game-specific anti-cheat controls.
+
+## Checklist
+
+- [ ] Topology chosen (dedicated / listen / P2P) and the *same code* runs on server and listen host.
+- [ ] Server-authoritative: clients send intent only; server validates and owns all gameplay state.
+- [ ] Each networked value is either replicated (state/nouns) or an RPC (events/verbs) — not the wrong one.
+- [ ] Ownership/authority set explicitly per object; authority-only logic guarded on the host.
+- [ ] Owning-client movement predicted + reconciled; remote entities snapshot-interpolated.
+- [ ] Hitscan uses server-side lag compensation; simulation on a fixed tick, decoupled from render FPS.
+- [ ] Only need-to-know state replicated per client (relevancy/visibility scoped); RPCs rate-limited.
+- [ ] Tested with simulated latency + packet loss across multiple instances, exercising the client path.
+- [ ] No banned APIs (UNet/HLAPI, Godot 3.x `master`/`puppet`/`rset`, `Tick`-polled Unreal replication).

package/skills/gamedev-multiplayer/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `gamedev-multiplayer` skill
+
+`cases.yaml` is a human/CI-readable trigger-and-capability spec, not an automated runner. Load the full
+skill-catalog descriptions into a routing agent and, for each `should_trigger` prompt, confirm this skill
+fires (including the near-miss phrasings that never say "netcode"); for each `should_not_trigger` prompt,
+confirm it stays silent and that whatever does fire matches the stated `route_to` sibling (godot, deployment,
+gamedev-physics, webhooks, secure-coding). Because LLM routing is non-deterministic, run several trials and
+take the majority. For the `capability` scenario, run it once with the skill body unavailable and once with
+`SKILL.md` + references loaded, then check each output against `must_include` — the with-skill answer must
+use current APIs (ENetMultiplayerPeer, `@rpc("any_peer", …)`, `is_server()` authority gate, no Godot 3.x
+`master`/`puppet`/`rset`) and clearly beat the baseline. Keep `cases.yaml` in sync with SKILL.md's
+"Fires on / When NOT" whenever scope changes.

package/skills/gamedev-multiplayer/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: gamedev-multiplayer
+
+should_trigger:
+  - prompt: "I have a single-player platformer in Godot 4 and I want to add online co-op. How do I sync the two players' positions and let one host the game?"
+    why: "Adding multiplayer/sync to a game is the core trigger; should produce ENetMultiplayerPeer host/join + MultiplayerSynchronizer/authority guidance."
+  - prompt: "In my Unity shooter the client sets its own health with a NetworkVariable and players can cheat. How should authority actually work?"
+    why: "Server-authoritative / never-trust-the-client + NetworkVariable write permissions; center of gravity of this skill."
+  - prompt: "Players rubber-band and teleport around when there's lag in my online game. What's the right way to fix the jitter?"
+    why: "Symptom text for prediction/reconciliation + snapshot interpolation; routes here without the word 'netcode'."
+  - prompt: "Should I use a dedicated server or peer-to-peer for my PvP game, and how do I stop clients from cheating?"
+    why: "Topology + authority decision, the second core section; not an infra/hosting question about how to run the server."
+  - prompt: "In Unreal, how do I replicate a health value to all clients and run a RepNotify when it changes, and what's the difference between a Server RPC and a NetMulticast?"
+    why: "Unreal Actor replication mapping: ReplicatedUsing/DOREPLIFETIME + Server vs NetMulticast RPC semantics."
+  - prompt: "What tick rate should my authoritative server run at, and how do I test multiplayer locally with fake latency before I ship?"
+    why: "Tick/netrate + local multiplayer testing with simulated latency, both explicitly owned here."
+  - prompt: "Is ServerRpc/ClientRpc still the way to do RPCs in Unity Netcode for GameObjects, or is there a newer attribute?"
+    why: "Version-contract question the skill answers directly: unified [Rpc(SendTo.X)] preferred, legacy pair still supported, UNet removed."
+
+should_not_trigger:
+  - prompt: "How do I read gamepad input and make my character jump in Godot 4?"
+    route_to: "godot"
+    why: "Single-player input/gameplay is the engine skill's job; no network dimension."
+  - prompt: "Set up a matchmaking backend and auto-scale dedicated game servers on a cloud provider with a lobby database."
+    route_to: "deployment"
+    why: "Server hosting/matchmaking/orchestration infra is delegated to deployment; this skill designs the in-game net layer, not the fleet."
+  - prompt: "My character controller clips through walls at high speed and collisions feel inconsistent — how do I fix the physics?"
+    route_to: "gamedev-physics"
+    why: "Collision/character-controller/determinism is physics; netcode consumes determinism but doesn't own the physics fix."
+  - prompt: "Build a realtime chat app with presence indicators over WebSockets for my website."
+    route_to: "webhooks"
+    why: "Generic web realtime that is not a game world/simulation is not this skill's domain."
+  - prompt: "Do a general threat model and authz review of my app's permission boundaries."
+    route_to: "secure-coding"
+    why: "Language/domain-agnostic threat modeling is secure-coding; this skill keeps only game-specific anti-cheat controls."
+
+capability:
+  - scenario: "In Godot 4.x, wire a server-authoritative 'fire weapon' from a client so the server validates and applies the shot, with the same code working on a listen-server host. Show the RPC and the authority handling."
+    must_include:
+      - "Uses ENetMultiplayerPeer (create_server / create_client) assigned to multiplayer.multiplayer_peer — NOT the removed NetworkedMultiplayerENet"
+      - "Declares the intent RPC with @rpc(\"any_peer\", ...) so a client may call it, and the client sends it with rpc_id(1, ...) to the server"
+      - "Gates the body with multiplayer.is_server() (or is_multiplayer_authority) so authoritative logic runs once, correctly on a listen host"
+      - "Identifies the sender with multiplayer.get_remote_sender_id() and validates before applying (server decides the result, client sends intent only)"
+      - "Uses no Godot 3.x APIs (no master/puppet/remote keywords, no rset, no rpc_config as a legacy call)"
+      - "Distinguishes replicating authoritative state (e.g. via MultiplayerSynchronizer / a replicated var) from firing the one-shot RPC event"

package/skills/gamedev-multiplayer/references/godot-high-level-multiplayer.md

@@ -0,0 +1,133 @@
+# Godot 4.x high-level multiplayer
+
+The high-level API sits on top of `MultiplayerPeer` and gives you three moving parts: **transport**
+(`ENetMultiplayerPeer`), **events** (`@rpc`), and **state** (`MultiplayerSynchronizer` +
+`MultiplayerSpawner`). Authority is per-node, set with `set_multiplayer_authority()`.
+
+Everything here is Godot 4.x. Godot 3.x used `master`/`puppet`/`remote`/`remotesync` keywords, `rset`,
+and `NetworkedMultiplayerENet` — **all gone**; never emit them.
+
+## Transport & connection
+
+```gdscript
+const PORT := 9999
+const MAX_PLAYERS := 8
+
+func host() -> void:
+    var peer := ENetMultiplayerPeer.new()
+    var err := peer.create_server(PORT, MAX_PLAYERS)
+    if err != OK: push_error("host failed: %s" % err); return
+    multiplayer.multiplayer_peer = peer
+
+func join(ip := "127.0.0.1") -> void:
+    var peer := ENetMultiplayerPeer.new()
+    peer.create_client(ip, PORT)
+    multiplayer.multiplayer_peer = peer
+
+func _ready() -> void:
+    multiplayer.peer_connected.connect(_on_peer_connected)     # server-side: a client joined
+    multiplayer.peer_disconnected.connect(_on_peer_disconnected)
+    multiplayer.connected_to_server.connect(_on_connected)     # client-side
+    multiplayer.server_disconnected.connect(_on_server_gone)
+```
+
+Useful `multiplayer` (SceneMultiplayer) members: `is_server()`, `get_unique_id()` (1 == server),
+`get_remote_sender_id()` (valid only inside an RPC body), `multiplayer_peer`.
+
+## RPCs — the `@rpc` annotation
+
+Params are optional and **order-free**. Signature: mode, sync, transfer mode, channel.
+
+- **mode**: `"authority"` (default — only the node's multiplayer authority may invoke it on remotes) or
+  `"any_peer"` (any client may invoke it — use this for client→server intent, then validate).
+- **sync**: `"call_remote"` (default) or `"call_local"` (also run on the caller).
+- **transfer**: `"unreliable"` (default), `"unreliable_ordered"`, or `"reliable"`.
+- **channel**: an int, and it must be the **last** argument.
+
+```gdscript
+# Client asks the server to fire. any_peer + call_local so the host's own call runs too.
+@rpc("any_peer", "call_local", "reliable")
+func request_fire(target: Vector3) -> void:
+    if not multiplayer.is_server(): return          # authority gate
+    var shooter := multiplayer.get_remote_sender_id()
+    if not _can_fire(shooter): return               # server-side cooldown / validation
+    _apply_shot(shooter, target)                    # server mutates authoritative state
+
+# Server → everyone, cosmetic only. Unreliable is fine for FX.
+@rpc("authority", "call_local", "unreliable")
+func play_muzzle_fx(at: Vector3) -> void:
+    _spawn_fx(at)
+
+# Invoking: rpc() = all peers; rpc_id(peer, ...) = one peer; rpc_id(1, ...) = the server.
+func _on_fire_pressed(target: Vector3) -> void:
+    rpc_id(1, "request_fire", target)               # client sends intent to server
+```
+
+Both sides must declare the **same** `@rpc` annotation on a function with the same name/path, or the call
+is rejected. A missing/mismatched annotation is the usual "my RPC does nothing" cause.
+
+## Authority
+
+```gdscript
+# On spawn, give the owning peer authority over its input node; server keeps authority over stats.
+func setup(owner_peer_id: int) -> void:
+    $Input.set_multiplayer_authority(owner_peer_id)      # recursive=true by default
+    # $Stats stays under server authority (peer id 1)
+
+func _physics_process(delta: float) -> void:
+    if $Input.is_multiplayer_authority():                # only the owner reads local input
+        var dir := Input.get_vector("left","right","up","down")
+        rpc_id(1, "submit_input", dir)                   # send intent to server
+```
+
+`set_multiplayer_authority(id, recursive := true)` sets it on the node (and children). Check with
+`is_multiplayer_authority()`; read with `get_multiplayer_authority()`. Authority drives who a
+`MultiplayerSynchronizer` streams *from* and who may call `"authority"`-mode RPCs.
+
+## State — MultiplayerSynchronizer
+
+Add a `MultiplayerSynchronizer` node, assign it a **replication config** (`SceneReplicationConfig`, edited
+in the inspector: list the properties to sync, e.g. `position`, `rotation`, and per-property spawn vs sync).
+It streams those properties **from the node's authority to the other peers** every replication interval.
+
+- `replication_interval` — how often synced properties are sent (throttle to save bandwidth).
+- `delta_interval` — for delta-synced properties.
+- Visibility: `set_visibility_for(peer_id, visible)`, `public_visibility`, `update_visibility()` — scope
+  who receives a given synchronizer (relevancy / anti-wallhack).
+
+Because it is authority-driven, an owner-authoritative synchronizer trusts the client's position — fine for
+co-op, risky for competitive. For server-authoritative movement, keep authority on the server and have the
+client send input via RPC (see prediction-and-latency.md).
+
+## Spawning — MultiplayerSpawner
+
+`MultiplayerSpawner` replicates *instancing*. Point its `spawn_path` at the parent node, register spawnable
+scenes with `add_spawnable_scene("res://player.tscn")`, and when the authority instances a child under that
+path (or you call `spawn(data)`), the same instance appears on every peer — including late joiners, which is
+the big win over manually RPC-ing spawns.
+
+```gdscript
+@onready var spawner := $MultiplayerSpawner
+
+func _ready() -> void:
+    spawner.spawn_function = _spawn_player     # optional custom factory
+
+func _on_peer_connected(id: int) -> void:      # server only
+    if multiplayer.is_server():
+        spawner.spawn(id)                      # data passed to spawn_function on every peer
+
+func _spawn_player(peer_id: int) -> Node:
+    var p := preload("res://player.tscn").instantiate()
+    p.name = str(peer_id)
+    p.setup(peer_id)
+    return p
+```
+
+## Gotchas
+
+- Server (peer 1) is also a client on a listen host — always gate authority logic behind `is_server()`.
+- `get_remote_sender_id()` is only meaningful *inside* an RPC; it returns 0 outside one.
+- Node paths must match across peers for RPCs/synchronizers to resolve — spawn via `MultiplayerSpawner` so
+  names line up, and set `name` deterministically (e.g. the peer id).
+- Reliable RPCs are ordered per channel and cost more; keep FX/heartbeats unreliable, keep state changes
+  reliable or (better) replicated.

package/skills/gamedev-multiplayer/references/prediction-and-latency.md

@@ -0,0 +1,104 @@
+# Prediction, reconciliation & latency hiding
+
+The whole reason netcode is hard: the speed of light. A round trip (RTT) of 60–150 ms is normal, and if the
+owning client had to wait a full RTT to see its own movement, the game would feel broken. The techniques
+below keep it responsive **without** giving up server authority. This is engine-agnostic theory; the
+per-engine references show where the hooks live.
+
+## The authoritative loop (mental model)
+
+1. Client samples input each tick, tags it with a **sequence number**, sends it to the server, and **applies
+   it locally immediately** (prediction).
+2. Server receives inputs, simulates them on its fixed tick, and produces authoritative state. It stamps each
+   state snapshot with the last input sequence number it processed for that client.
+3. Client receives the authoritative snapshot, **reconciles**: snap to the server state, then re-apply every
+   input *after* the acknowledged sequence number (they haven't reached the server yet).
+4. Other (remote) entities are rendered from buffered snapshots, **interpolated** slightly in the past.
+
+Server is always the source of truth. The client only ever *guesses ahead* and gets corrected.
+
+## 1. Client-side prediction
+
+The owning client runs the same movement code the server will run, on the same fixed timestep, the instant it
+presses a key — no waiting. Requirements:
+
+- **Deterministic** movement/simulation for the predicted entity (same input + same state → same result).
+  This is why `gamedev-physics` determinism matters here.
+- A **ring buffer** of unacknowledged inputs (`{seq, dt, input}`), kept until the server acknowledges them.
+- Predict only what the client owns (its pawn). Never predict other players — interpolate them instead.
+
+## 2. Server reconciliation
+
+When an authoritative snapshot arrives tagged "processed up to input N":
+
+```
+clientState = serverState               # trust the server
+discard buffered inputs with seq <= N   # server already applied these
+for each remaining buffered input (seq > N):
+    clientState = simulate(clientState, input)   # replay the unacknowledged ones
+```
+
+If the replayed result matches what the client already had, the correction is invisible. If it diverges (the
+server disagreed — lag, a missed collision, a rejected move), the entity snaps: the visible **rubber-band**.
+Goal is to *minimize* divergence, not to suppress the correction — hiding a legitimate correction is how you
+get players walking through walls on their screen.
+
+- **Smoothing**: for small corrections, blend toward the corrected position over a few frames instead of
+  hard-snapping, so a 2 cm disagreement isn't a visible pop. Hard-snap large ones.
+
+## 3. Snapshot interpolation (remote entities)
+
+You receive remote entities' state only every send-tick (e.g. every 50 ms) — rendering the latest packet
+directly makes them teleport. Instead, keep a small buffer and render them ~1–2 snapshots **in the past**:
+
+- **Interpolation delay** ≈ 100 ms (2× send interval + jitter margin). Render remote entities at
+  `now − delay`, interpolating between the two snapshots that straddle that time.
+- Trade-off: everyone else is shown slightly in the past. That is fine and standard.
+- **Extrapolation** (dead reckoning) predicts a remote entity forward when a packet is late — cheaper on
+  bandwidth but wrong on direction changes; prefer interpolation and only extrapolate briefly to cover a gap.
+
+So on one client, three clocks coexist: **its own pawn** = present (predicted), **remote entities** = past
+(interpolated), **the server** = the arbiter reconciling the two.
+
+## 4. Lag compensation (server-side rewind)
+
+For instant/hitscan hits, the shooter aimed at where they *saw* the target — which is `interpolation delay +
+½ RTT` in the past. If the server tests the hit against the target's *present* position, the shooter misses
+despite a perfect aim. Fix: the server keeps a short **history** of every entity's recent positions and, when
+processing a shot, **rewinds** the world to the shooter's view time before testing the hit.
+
+- Store ~1 second of position history per entity (a ring of transforms per tick).
+- On a shot: reconstruct positions at `clientRenderTime`, run the trace, then restore.
+- Trade-off: the victim can be hit just after ducking behind cover ("shot behind the wall"). This is an
+  accepted fairness choice favoring the shooter; cap how far back you rewind to bound the unfairness.
+
+## 5. Tick rate, send rate, netrate
+
+- **Simulation tick** — fixed Hz the server steps the world (20 / 30 / 60+; higher = more precise + more CPU).
+- **Send rate / snapshot rate** — how often state goes on the wire; often lower than sim tick, and independent
+  of client render FPS. This is the "netrate/updaterate/cmdrate" family in shooters.
+- **Client render FPS** — decoupled from both; render via interpolation between fixed-step states.
+- Bandwidth ≈ replicated-bytes × send-rate × relevant-peers. Shrink it with relevancy/visibility scoping,
+  quantized/delta-compressed fields, and lower send rates for distant or unimportant actors.
+
+**Never run gameplay in a variable `_process`/`Update`/`Tick` on a networked game** — use a fixed timestep
+(`_physics_process`, `NetworkUpdate`/`FixedUpdate`, Unreal's fixed sim) so prediction and reconciliation
+replay identically on client and server.
+
+## Alternative model: deterministic lockstep / rollback
+
+For fighting games and some RTS: no per-frame state replication at all — every peer runs the identical
+deterministic simulation and only **inputs** are exchanged. **Lockstep** waits for all inputs before advancing
+(one slow peer stalls everyone). **Rollback** (GGPO-style) predicts absent inputs, then rolls back and
+re-simulates when the real inputs arrive — excellent feel, but demands *bit-perfect determinism* (watch
+floats, iteration order, RNG) and bounded state you can snapshot/restore cheaply. Choose it only when you can
+guarantee that determinism; otherwise the client-server model above is the safer default.
+
+## Checklist for a responsive authoritative game
+
+- [ ] Owning pawn predicted locally on a fixed timestep; inputs buffered with sequence numbers.
+- [ ] Server acks the last processed input seq in each snapshot; client replays unacknowledged inputs.
+- [ ] Small corrections smoothed, large ones snapped; corrections never fully suppressed.
+- [ ] Remote entities interpolated ~100 ms in the past from a snapshot buffer.
+- [ ] Hitscan uses server-side rewind bounded to ~1 s of history.
+- [ ] Sim tick / send rate / render FPS all decoupled; bandwidth scoped by relevancy.