Multiplayer Quickstart

This is the shortest AuraJS multiplayer path right now.

TL;DR

auramaxx create my-room-game --template multiplayer
cd my-room-game
npm run dev

# second terminal
npm run join -- AURA2P

That is the default room-code multiplayer loop:

npm run dev hosts
npm run join -- CODE joins
the host stays authoritative for shared state
the starter can render clients from additive interpolated state helpers for smoother motion, and supported games can later opt into rollback-aware reads
local room lookup happens first
if the room is internet-backed, join("CODE") can fall back to coordinator lookup

Fastest Working Example

If you want the smallest copyable example before scaffolding your own game, use examples/multiplayer-party.

Local-first:

cd packages/aurascript/examples/multiplayer-party
auramaxx run .

# second terminal
auramaxx run . PARTY4

That example keeps host and join in one project and also shows:

room code
connection mode
transport path
transport status
ping
buffered snapshot metadata
rollback correction, replay, and continuity diagnostics
room chat

Make The Same Flow Internet-Backed

Keep the same host/join commands and add a relay host in aura.config.json:

{
  "multiplayer": {
    "relay": "relay.aurajs.gg"
  }
}

Or keep the project untouched and launch with:

AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg npm run dev
AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg npm run join -- AURA2P

When a relay host or explicit relay URLs are present, the room uses internet auto mode:

local room lookup first
coordinator lookup if no local room exists
direct UDP first when possible
relay fallback if direct UDP fails

If you also want one shareable web join page, add the launcher base URL:

{
  "multiplayer": {
    "relay": "relay.aurajs.gg",
    "launcherBaseUrl": "https://auralauncher.gg"
  }
}

Then the multiplayer starter HUD can surface a link like:

https://auralauncher.gg/join/AURA2P

If you want relay-only behavior, set:

{
  "multiplayer": {
    "mode": "relay",
    "relay": "relay.aurajs.gg"
  }
}

Add Multiplayer To An Existing Game

The minimum host-authoritative loop is:

aura.multiplayer.configure({ maxPlayers: 2, tickRate: 20 });

function startHost() {
  return aura.multiplayer.host({
    roomCode: "AURA2P",
    maxPlayers: 2,
    internetMode: "local",
  });
}

function hostTick(localInput) {
  aura.multiplayer.setState("player_0", stepPlayer(aura.multiplayer.getState("player_0"), localInput));
  const inputs = aura.multiplayer.getAllPlayerInputs() || {};
  for (const [playerId, input] of Object.entries(inputs)) {
    const key = `player_${playerId}`;
    aura.multiplayer.setState(key, stepPlayer(aura.multiplayer.getState(key), input));
  }
}

function clientTick(input) {
  if (aura.multiplayer.isConnected()) {
    aura.multiplayer.sendInput(input);
  }
}

Mental model:

host reads player inputs with getAllPlayerInputs()
host writes authoritative shared state with setState(...)
host logic reads raw getState() / getAllState()
clients that care about visual smoothness should prefer getInterpolatedState() / getInterpolatedAllState() for draw
clients join by room code with npm run join -- CODE or aura.multiplayer.join("CODE")

Stage 174 Recovery And Rollback Lane

AuraJS now also ships an advanced Stage 174 lane for explicit public-network recovery and supported rollback gameplay reads.

const localKey = `player_${aura.multiplayer.getLocalId()}`;

aura.multiplayer.configureRollbackLane({
  key: localKey,
  speed: 220,
  historyLimit: 16,
  bounds: { minX: 32, maxX: 608, minY: 96, maxY: 352 },
});

function draw() {
  const players = aura.multiplayer.isHost()
    ? (aura.multiplayer.getAllState() || {})
    : (aura.multiplayer.getRollbackAllState()
        || aura.multiplayer.getInterpolatedAllState()
        || aura.multiplayer.getAllState()
        || {});
  const rollback = aura.multiplayer.getRollbackDiagnostics(localKey);
  const network = aura.multiplayer.getNetworkDiagnostics();
}

Use that lane when your local gameplay state fits the runtime-supported rollback model:

configureRollbackLane(...) currently supports the built-in axis2d lane
getRollbackState() / getRollbackAllState() are rollback-aware gameplay reads for that supported lane
getRoomInfo() and getNetworkDiagnostics() surface reason-coded recovery states such as resume_pending and resumed
configureNetworkImpairment(...) / clearNetworkImpairment() exist for deterministic latency, jitter, loss, and short-outage testing

Truthful limit:

raw replicated state remains the authority path
the public starter/example path keeps remote players on interpolated reads and overlays the joined local player through the supported rollback lane
Stage 174 recovery is explicit client continuity for transient coordinator/control disruption, not invisible or universal internet rescue
Stage 174 rollback is opt-in and limited to supported gameplay-state lanes; it is not arbitrary authored-game rollback
the current boundary is frozen in ../../multiplayer-internet-hardening-and-rollback-grade-feel-contract-v1.md

Project Config TL;DR

Use aura.config.json -> multiplayer for project-level defaults:

{
  "multiplayer": {
    "roomCode": "AURA2P",
    "roomName": "My Room",
    "mode": "local",
    "relay": null,
    "coordinatorUrl": null,
    "relayUrl": null,
    "launcherBaseUrl": null,
    "showDiagnostics": true,
    "chatEnabled": true,
    "chatHistoryLimit": 6
  }
}

Use that block for:

room code
room name
internet relay defaults
optional launcher join page base URL
connection diagnostics
starter chat defaults

Use config/gameplay/local-multiplayer.config.js for local gameplay tuning:

port
player movement bounds
host fallback timing
tick rate

AURA

JSGG