Configuration Reference

Complete reference for every configurable option in the CarverJS multiplayer system. All options have sensible defaults — you only need to override what you want to change.

import { useMultiplayer, useRoom } from "@carverjs/multiplayer";

useMultiplayer Options #

Pass these options to useMultiplayer() to control synchronization behaviour.

const multiplayer = useMultiplayer({
  mode: "prediction",
  tickRate: 60,
  broadcastRate: 20,
  keyframeInterval: 60,
  quantize: { position: 0.01 },
  prediction: { errorDecay: 0.85 },
  interpolation: { delay: 100 },
});

Top-Level Options #

QuantizeOptions #

Quantization rounds values to a fixed step size, reducing the number of bits needed on the wire.

quantize: {
  position: 0.01,   // ~1cm accuracy
  rotation: 0.001,  // ~0.06° accuracy
  velocity: 0.05,
}

DeltaThresholds #

Only include a field in the delta if it changed by more than the threshold since the last broadcast.

deltaThresholds: {
  position: 0.001,
  rotation: 0.001,
  velocity: 0.01,
}

PredictionSyncOptions #

Controls full-world prediction and rollback. Only relevant when mode is 'prediction'.

prediction: {
  maxRewindTicks: 15,
  snapThreshold: 150,
  errorDecay: 0.85,
  maxErrorPerFrame: 0,
  neutralInput: {},
  inputHistorySize: 120,
  driftTargetTicks: 4,
}

InterpolationOptions #

Controls how remote (non-local) entities are smoothed between network updates.

interpolation: {
  delay: 100,
  maxExtrapolation: 200,
  method: "hermite",
}

InterestManagementOptions #

Area-of-interest filtering. Only entities within range of the player are synchronized, dramatically reducing bandwidth in large worlds.

interestManagement: {
  enabled: true,
  cellSize: 50,
  viewDistance: 200,
  hysteresis: 20,
}

DebugOptions #

Developer tools for visualizing and simulating network conditions.

debug: {
  overlay: true,
  simulatedLatencyMs: 80,
  simulatedPacketLoss: 0.02,
  logLevel: "info",
}

useRoom Options #

Pass these options as the second argument to useRoom(roomId?, options?) — the first argument is the room to auto-join, or undefined to join later with room.join(id).

const room = useRoom("room-123", {
  displayName: "Player1",
  password: "secret",
  hostMigration: true,
  reconnectAttempts: 5,
  privacy: "relay",
});

Signaling Strategy Options #

Pass a strategy config to <MultiplayerProvider strategy={...}> to choose how peers discover each other. Defaults to { type: 'mqtt' } — free public brokers, zero configuration. The Firebase RTDB strategy takes the options below.

FirebaseStrategyConfig #

<MultiplayerProvider
  appId="my-game"
  strategy={{
    type: "firebase",
    databaseURL: "https://my-project.firebaseio.com",
    apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
    authTokenProvider: () => fetchCustomTokenFromYourBackend(),
    onAuthError: (error) => showReconnectPrompt(error),
  }}
>

Signaling paths are written under ${appId}/__carver__/.... An appId containing a slash simply nests deeper, which is how you scope security rules per namespace.

Networked Config Prop Reference #

The config prop on <Networked> controls per-entity sync behaviour.

<Networked id="player-1" config={{ sync: "transform", owner: peerId, interpolate: true }}>
  <Actor type="primitive" shape="box" />
</Networked>

Debug Tools #

DebugOverlay #

Enable the on-screen overlay to see live network statistics:

const multiplayer = useMultiplayer({
  debug: { overlay: true },
});

The overlay displays:

• RTT — round-trip time to each peer (ms)

• Bandwidth — inbound/outbound bytes per second

• Tick — current simulation tick and drift

• Entities — total synced entity count

• Packet loss — detected packet loss percentage

Toggle the overlay at runtime by pressing F3.

Network Simulator #

Inject artificial latency and packet loss for testing poor network conditions:

debug: {
  simulatedLatencyMs: 150,   // 150ms one-way delay
  simulatedPacketLoss: 0.05, // 5% random packet drop
}

Error Codes #

Errors delivered to useRoom's onError use CarverError with a code field from the CarverErrorCode enum. Firebase signaling authentication takes a separate path — see the uncoded row in the table and Authentication Errors below.

const room = useRoom("room-123", {
  onError: (error) => {
    switch (error.code) {
      case "ROOM_FULL":
        showToast("Room is full. Try again later.");
        break;
      case "INVALID_PASSWORD":
        promptPassword();
        break;
      default:
        console.error(`[Carver] ${error.code}: ${error.message}`);
    }
  },
});

Authentication Errors #

Firebase signaling auth failures are reported through the strategy's own onAuthError callback, not as a CarverErrorCode. There is no auth code to switch on in useRoom's onError:

<MultiplayerProvider
  appId="my-game"
  strategy={{
    type: "firebase",
    databaseURL: "https://my-project.firebaseio.com",
    apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
    authTokenProvider: () => fetchCustomTokenFromYourBackend(),
    onAuthError: (error) => {
      console.error(error.message); // context + the RTDB error, kept as `cause`
      rejoinRoom();
    },
  }}
>

onAuthError receives a plain Error — not a CarverMultiplayerError — naming the operation that failed and carrying the underlying RTDB error as cause. It fires in three situations:

Type Definitions #

See Types for all type definitions including UseMultiplayerOptions, UseRoomOptions, NetworkedConfig, QuantizeOptions, PredictionSyncOptions, PlayerInput, PhysicsStepCallback, InterpolationOptions, InterestManagementOptions, DebugOptions, CarverError, and CarverErrorCode.