net
game/net provides cross-target multiplayer networking for NSGo games: a unified Transport across WebSocket (native + WebAssembly), native UDP, and simulated loopback; server-authoritative delta snapshot replication with client prediction and interpolation; and deterministic lockstep and rollback netcode.
import "github.com/nsgo-dev/game/packages/game/net"
Cross-target transports (Transport)
Every transport implements the same non-blocking Transport interface (Send, Recv, LocalID, Peers, Close) with ChannelReliableOrdered and ChannelUnreliable channels and PeerBroadcast (PeerID(0)):
| Transport | Constructor | Targets & use case |
|---|---|---|
WebSocketServer / WebSocketTransport |
ListenWebSocket, DialWebSocket |
Native + browser (js/wasm); works across NATs and web builds. |
UDPTransport |
ListenUDP + AddPeer |
Native targets (desktop/mobile) for low-latency datagrams. |
LoopbackHub / LoopbackTransport |
NewLoopbackHub + AddPeer |
In-memory deterministic tests with configurable Latency, Jitter, LossRate, and Seed. |
hub := net.NewLoopbackHub(net.LoopbackConfig{
Latency: 40 * time.Millisecond,
Jitter: 10 * time.Millisecond,
LossRate: 0.02,
Seed: 7,
})
serverTx := hub.AddPeer(1)
clientTx := hub.AddPeer(2)
_ = serverTx.Send(2, net.ChannelReliableOrdered, []byte("hello"))
hub.Advance(60 * time.Millisecond)
pkt, ok := clientTx.Recv()
_, _ = pkt, ok
Server-authoritative delta replication
Use ServerWorld and ClientWorld for action, co-op, or arena games where the server owns authoritative entity state. ServerWorld.Step(tick) tracks per-peer acknowledged snapshots and sends compact field-level deltas (falling back to full snapshots when needed):
// Server:
server := net.NewServerWorld(serverTx)
heroID := server.Spawn(net.EntityState{
ComponentState: net.ComponentState{Kind: 1, X: 100, Y: 50},
})
server.Update(heroID, updatedState)
_ = server.Step(tick)
// Client:
client := net.NewClientWorld(clientTx, serverID)
client.OnSpawn = func(e net.EntityState) { /* attach visuals */ }
client.OnDespawn = func(id net.EntityID) { /* remove visuals */ }
client.Poll()
client.Predict(heroID, localCmd, applyInput)
renderEntities := client.Interpolate(renderTick) // smooth remote entity motion
_ = renderEntities
Inspect bandwidth and reconciliation behavior with server.Stats(), client.PredictedState(id), client.Reconciliations(), and client.LastReconcileError().
Deterministic lockstep and rollback netcode
For fighting games, RTS titles, or tight arcade co-op, implement SimState (Step, Save, Load, Checksum) and drive it with LockstepSession or RollbackSession:
session := net.NewRollbackSession(net.RollbackConfig{
Transport: peerTx,
Sim: sim,
Peers: []net.PeerID{1, 2},
MaxRollback: 8,
InputDelay: 1,
ChecksumInterval: 30,
OnDesync: func(ev net.DesyncEvent) {
log.Printf("desync at tick %d: local=%x remote=%x", ev.Tick, ev.LocalChecksum, ev.RemoteChecksum)
},
})
// Each fixed step in game.Loop.Update:
if err := session.Poll(); err != nil {
return err
}
if err := session.Step(net.InputFrame{Tick: session.Tick(), Peer: peerTx.LocalID(), Bits: buttons}); err != nil {
return err
}
RollbackSessionpredicts missing remote inputs, saves snapshots per tick, and automatically rewinds and resimulates when a late remote input disagrees with prediction (returningErrRollbackWindowExceededif a peer falls beyondMaxRollback).LockstepSession(SubmitInput,Poll,Step) advances only when every peer's input for the current tick has arrived, ideal for RTS or turn-synchronized play.- Both sessions exchange periodic checksums (use
ChecksumByteshelper) to surface determinism bugs immediately viaOnDesyncandDesyncs().