Multiplayer Patterns for ZX

Multiplayer Patterns for Nethercore ZX

GGRS rollback netcode implementation. All gameplay code must be deterministic.

ZX Capabilities

How Rollback Works

1. Predict remote input (usually "same as last frame")
2. Advance game state with predictions
3. Correct when actual input arrives: restore snapshot, re-run with correct input
4. Result appears seamless to players

Desync = different game states = broken multiplayer.

Determinism Rules

Session FFI

Why? update() runs on ALL clients identically. render() is local-only.

fn is_local(player_id: u32) -> bool {
    (local_player_mask() & (1 << player_id)) != 0
}

State Design

Target: < 100 KB rollback state

Include:

• Player positions, velocities, health
• Entity states
• RNG state
• World state

Exclude (visual-only):

• Particles, screen shake
• Audio state
• Cached calculations

Viewport Layouts

fn render() {
    for (i, player_id) in local_players().enumerate() {
        set_viewport(i, local_count);
        render_player_view(player_id);
    }
    viewport_clear();
    draw_shared_ui();
}

See references/viewport-layouts.md for complete implementations.

Common Mistakes

WRONG - local_player_mask in update():

fn update() {
    let mask = local_player_mask();  // DESYNC!
    if (mask & 1) != 0 { /* breaks determinism */ }
}

CORRECT - process all players in update():

fn update() {
    for i in 0..player_count() {
        process_input(i);  // All players, deterministic
    }
}

Testing Progression

1. Local single-player
2. Local multiplayer (2-4 controllers)
3. Synthetic desync test (compare state hashes)
4. LAN test
5. Simulated latency (50-200ms)
6. Real online test

Desync Debugging

1. Hash game state each frame
2. Find first divergent frame
3. Compare state dumps
4. Check: random, floats, hash iteration, uninitialized memory

Performance

Each viewport = separate render pass. 4 viewports = ~4x render work.

Optimize: simpler effects in split-screen, LOD, reduced particles.

Related Skills

• physics-collision — Deterministic physics
• zx-dev:rollback-reviewer — Agent to detect non-deterministic code
• game-design:multiplayer-design — Conceptual multiplayer design