VRyHungry1/docs/superpowers/specs/2026-07-28-high-level-replication-design.md

High-level replication rebuild

Rebuild VRyHungry's multiplayer on Godot's stock MultiplayerSpawner and MultiplayerSynchronizer, so that adding a new object to the game requires no networking code at all. Replaces the bespoke spawn payloads, per-scene replication configs, and grab-authority handshake in place today.

Baseline being replaced: logs/mptest_report.txt, 146/146 checks passing as of 2026-07-28 19:47. That is the bar the rebuild has to clear.

The constraint that shapes everything

MultiplayerSpawner replicates node creation, name, and deletion — nothing more. All state comes from MultiplayerSynchronizer plus a SceneReplicationConfig. There is no engine switch for "sync everything regardless of what it is".

The way to get there anyway: a SceneReplicationConfig is a plain Resource, so it can be built in code from a convention and attached at runtime. One helper then covers every object in the game, and nothing has to be authored per scene.

Verified engine behaviour

Established by test/spike/, run against Godot 4.7.stable. These are load bearing — the design below is only correct because these hold.

#	Question	Result
Q1	Does default auto-spawn carry the spawn properties of a synchronizer attached at runtime, not baked into the .tscn?	Yes. A peer joining 4s after the spawn received pos=(5,6,7) health=42 label=hello.
Q2	Do ON_CHANGE properties reach a late joiner, and do later changes propagate?	Yes, both.
Q3	Can set_visibility_for(peer, false) suppress one peer's updates without despawning the node there?	No. The node is despawned and respawned on every visibility flip. Unusable — it would make a held object vanish from the holder's hand.
Q4	Can handing one of two synchronizers to a client let it drive the transform locally while server-owned state keeps arriving?	Yes. Client showed its own (1,1,1) and ignored the server's competing (-9,-9,-9); the server saw (1,1,1); server-owned health=123 still arrived.

Two traps worth recording. set_visibility_for is only an override on top of public_visibility, which defaults to true — calling it alone does nothing. And the spike's first version chained relative timers, which drifted enough that the client's observations straddled the server's actions; it now runs both peers on one absolute clock.

Design

Layer 1 — Net/net_replication.gd

The convention-based config builder. NetReplication.attach(node) gives a node two generated synchronizers:

• NetSync — script state. Always server-owned; gameplay outcomes are the server's to decide. ON_CHANGE.
• NetXform — position + quaternion. Server-owned while the object is loose, handed to a peer for the duration of a hold. ALWAYS.

What gets replicated, by convention:

• a Node3D replicates position and quaternion (never scale — nothing in this game animates scale as gameplay state)
• every script variable, on the node and any scripted descendant, whose name does not start with _ and whose declared type is serialisable

Underscore-prefixed vars are the opt-out, and they already mark exactly the state that must not cross the wire: @onready references, cached lookups, per-frame bookkeeping.

ON_CHANGE for state is a deliberate correctness choice, not just bandwidth. Under ALWAYS the synchronizer assigns every property every tick on receiving peers, so every replicated setter becomes a per-frame hot path — which is how this project previously ended up rebuilding every plate's visuals 60 times a second and rewriting four physics properties per item per tick.

Layer 2 — Net/net_world.gd

• Spawnable scenes registered by sorted directory scan of Items/, Containers/, Stations/, Prefabs/. Auto-spawn transmits an index into that array, so the order must be identical on every peer or clients build the wrong scene.
• spawn() = instantiate → set transform/name → add_child under the content root. No spawn_function, no payload dictionary.
• despawn() = queue_free() on the server. The _despawn_static_item RPC disappears: with nothing baked into the world scene, the spawner covers every case.
• NetReplication.attach runs from the content root's child_entered_tree on both peers. That is early enough for the synchronizers to enter the tree inside the spawner's own add_child, which is what lets them pick up the spawn payload (Q1).
• Client gating becomes one generic rule applied at the same hook: disable _process, disable every XRToolsSnapZone, freeze RigidBody3D. This replaces _gate_station + gate_existing_stations and applies to anything, not just things that happen to be stations.

Layer 3 — Net/net_grab.gd and Net/net_stations.gd

Two RPCs for the entire game: request_grab(item) and request_release(item, xform, lin, ang).

A client's hand picks the item up locally the instant the player grabs — no round trip — and asks the server to confirm. The server grants by moving NetXform authority to that peer (Q4), which is precisely what makes the local copy stop applying inbound transform updates. On release, authority returns to the server, which decides where the item actually ends up: server-authoritative snapping into stations lives in net_stations.gd, generic over the station group rather than per-station.

Deleted outright: Net/net_pickable.gd (209 lines), net_held_by and its held-state juggling, _set_item_authority, the grant/reject/force-release negotiation, and _gate_station.

Layer 4 — tests

test/mp_test_driver.gd (1458 lines) splits into orchestration, steps, asserts, snapshot, and report modules. The scenario list and the sync audit carry over unchanged — that audit compares what is actually rendered on both peers, which is what caught the plate-visuals desync that targeted assertions missed. Assertions written against old internals (net_held_by, "the client is the item's authority after grabbing") are rewritten against the new model.

Risks

• Replacing a green suite. Mitigated by running the headless suite after each layer rather than only at the end.
• The harness changes alongside the code it checks. Mitigated by keeping scenario list and audit logic byte-identical wherever possible, so it remains an independent check rather than one shaped to fit the new code.
• Blanket state replication picks up more vars than the old hand-authored configs. ON_CHANGE makes this cheap, but any setter reached this way still has to be idempotent and null-guarded — a spawn = true property fires its setter before the node is in the tree, so @onready refs are null there.
• Client→client transform relies on SceneMultiplayer.server_relay (on by default) to forward a holder's updates to the other clients. Fine for a listen-server, worth remembering if the topology ever changes.