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: { enabled: true },
  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,
}

PredictionOptions #

Controls client-side prediction and server reconciliation. Only relevant when mode is 'prediction'.

prediction: {
  enabled: true,
  maxRewindTicks: 30,
  correctionSmoothing: 0.2,
  inputBufferSize: 60,
}

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 to useRoom() to configure the connection and room behaviour.

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

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 #

All multiplayer errors use CarverError with a code field from the CarverErrorCode enum.

const room = useRoom({
  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}`);
    }
  },
});

Type Definitions #

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