# CarverJS Documentation

> React game engine built on Three.js with P2P multiplayer

## Installation

pnpm add @carverjs/core

## Docs

### Components

- [Game](https://docs.carverjs.dev/components/game.html): Game is the entry point for every CarverJS application. It wraps React Three Fiber's <Canvas />, sets up the WebGL renderer, lighting, environment, input system
- [World](https://docs.carverjs.dev/components/world.html): World is a level/scene container inside a Game./game.md. It groups Actors./actor.md, sets up a default camera, and optionally enables physics. Toggle worlds on/
- [Actor](https://docs.carverjs.dev/components/actor.html): An Actor is any renderable entity you place in a scene. Every actor shares a common set of transform and event props, but the type field determines what gets re
- [Camera](https://docs.carverjs.dev/components/camera.html): Camera gives you full control over the camera in a World scene. Drop it as a child of World to replace the default camera and controls with your own configurati
- [AudioListener](https://docs.carverjs.dev/components/audio-listener.html): AudioListener overrides the default audio listener position. By default, the Web Audio listener follows the active R3F camera. Mount this component to follow a 
- [SceneManager](https://docs.carverjs.dev/components/scene-manager.html): SceneManager organizes your game into discrete scenes menus, levels, HUDs with lifecycle management, stack-based navigation, and visual transitions. Place it in
- [Scene](https://docs.carverjs.dev/components/scene.html): Scene declaratively registers a scene configuration with the SceneManager./scene-manager.md. It does not render scene content — the SceneManager handles renderi
- [AssetLoader](https://docs.carverjs.dev/components/asset-loader.html): AssetLoader is a declarative preloader that loads all assets in a manifest before rendering its children. It shows a fallback typically a LoadingScreen./loading
- [LoadingScreen](https://docs.carverjs.dev/components/loading-screen.html): LoadingScreen is a pre-built, customizable loading screen component designed to work with AssetLoader./asset-loader.md. It renders as HTML content within the As
- [ParticleEmitter](https://docs.carverjs.dev/components/particle-emitter.html): ParticleEmitter is a declarative component for creating particle effects. Drop it into a scene or as a child of an Actor./actor.md to add fire, smoke, explosion

### Hooks

- [useAnimation](https://docs.carverjs.dev/hooks/use-animation.html): Manages animation playback for GLTF/GLB models. Wraps drei's useAnimations with play/pause, speed control, looping, and crossfade support.
- [useCamera](https://docs.carverjs.dev/hooks/use-camera.html): Provides imperative camera controls — shake, smooth transitions, and look-at. Used internally by the Camera component, but available directly for advanced use c
- [useGameLoop](https://docs.carverjs.dev/hooks/use-game-loop.html): Registers a per-frame callback with control over update stage, timestep mode, and integration with the global game phase. Built on R3F's useFrame with priority-
- [useInput](https://docs.carverjs.dev/hooks/use-input.html): useInput provides keyboard and pointer input for game logic. It reads from the InputManager../systems/input-manager.md which is automatically set up by Game../c
- [useCollision](https://docs.carverjs.dev/hooks/use-collision.html): useCollision registers a lightweight collider on an Actor and fires callbacks when it overlaps with other colliders. No physics engine required — this is Carver
- [useGridCollision](https://docs.carverjs.dev/hooks/use-grid-collision.html): useGridCollision provides a tile-based collision grid with O1 lookups. Ideal for grid-based games like Snake, tile RPGs, puzzle games, or any game that uses dis
- [usePhysics](https://docs.carverjs.dev/hooks/use-physics.html): usePhysics provides an imperative API for controlling a Rapier rigid body. Use it inside children of a physics-enabled Actor../components/actor.md to apply impu
- [useAudio](https://docs.carverjs.dev/hooks/use-audio.html): useAudio provides sound effects, music, and volume control for game logic. It reads from the AudioManager../systems/audio-manager.md which is automatically set 
- [useScene](https://docs.carverjs.dev/hooks/use-scene.html): useScene provides scene navigation and status. It reads from the scene store managed by SceneManager../components/scene-manager.md.
- [useAssets](https://docs.carverjs.dev/hooks/use-assets.html): useAssets provides synchronous access to preloaded assets from the AssetManager../systems/asset-manager.md cache. Assets must be preloaded via AssetLoader../com
- [useAssetProgress](https://docs.carverjs.dev/hooks/use-asset-progress.html): useAssetProgress subscribes to the AssetManager../systems/asset-manager.md's loading progress. It does not suspend — it returns the current snapshot and re-rend
- [useTween](https://docs.carverjs.dev/hooks/use-tween.html): useTween provides property tweening, number interpolation, and timeline sequencing for game animations. It reads from the TweenManager../systems/tween-manager.m
- [useParticles](https://docs.carverjs.dev/hooks/use-particles.html): useParticles creates and controls a particle emitter for visual effects like fire, smoke, explosions, and more. It reads from the ParticleManager../systems/part

### Types

- [Types](https://docs.carverjs.dev/types/index.html): All types are importable from @carverjs/core/types.

### Multiplayer

- [Getting Started with Multiplayer](https://docs.carverjs.dev/multiplayer/getting-started.html): CarverJS Multiplayer adds peer-to-peer networking to any CarverJS game. One player acts as the host, relaying state to all connected clients. Add a provider, ma
- [Core Concepts](https://docs.carverjs.dev/multiplayer/core-concepts.html): This page covers the fundamental building blocks of CarverJS multiplayer: the host-client model, the networked prop, actor ownership, connection states, sync mo
- [Lobby & Room Management](https://docs.carverjs.dev/multiplayer/lobby-and-rooms.html): CarverJS multiplayer ships four hooks that cover the entire lobby-to-gameplay lifecycle: discovering rooms, joining one, reading player state, and managing the 
- [Sync Modes](https://docs.carverjs.dev/multiplayer/sync-modes.html): CarverJS multiplayer provides three sync layers that can be used independently or combined. Each layer targets a different update frequency and game type — pick
- [Configuration Reference](https://docs.carverjs.dev/multiplayer/configuration.html): Complete reference for every configurable option in the CarverJS multiplayer system. All options have sensible defaults — you only need to override what you wan
- [Advanced Topics](https://docs.carverjs.dev/multiplayer/advanced.html): Deep dives into custom transports, dynamic spawning, interest management, performance tuning, and other advanced multiplayer patterns.
- [MultiplayerBridge](https://docs.carverjs.dev/multiplayer/multiplayer-bridge.html): <MultiplayerBridge> bridges the multiplayer context from the parent React tree into the R3F Canvas. This is required when <MultiplayerProvider> is placed outsid

### Systems

- [InputManager](https://docs.carverjs.dev/systems/input-manager.html): InputManager is a singleton that captures keyboard, pointer, and touch events from the DOM and makes them available to game logic on a per-frame basis.
- [CollisionManager](https://docs.carverjs.dev/systems/collision-manager.html): CollisionManager is a singleton that runs AABB, sphere, and circle overlap detection each frame. It uses a spatial hash for broad-phase culling and supports lay
- [GridCollisionManager](https://docs.carverjs.dev/systems/grid-collision-manager.html): GridCollisionManager is a singleton that manages a 2D tile-based collision grid backed by an Int32Array. It provides O1 cell lookups, neighbor queries, and worl
- [PhysicsProvider](https://docs.carverjs.dev/systems/physics-provider.html): PhysicsProvider is an internal system that conditionally wraps scene content in Rapier physics. It consists of two components:
- [AudioManager](https://docs.carverjs.dev/systems/audio-manager.html): AudioManager is a singleton that manages all audio playback using the Web Audio API, with an automatic HTML5 Audio fallback for environments without Web Audio s
- [SceneManager (System)](https://docs.carverjs.dev/systems/scene-manager.html): The SceneManagerImpl singleton provides imperative scene navigation for use outside React components — in event handlers, network callbacks, or third-party libr
- [AssetManager](https://docs.carverjs.dev/systems/asset-manager.html): AssetManager is a singleton that handles loading, caching, and lifecycle management of game assets. It supports GLTF models, textures, audio, JSON, and binary d
- [TweenManager](https://docs.carverjs.dev/systems/tween-manager.html): TweenManager is a singleton that manages all property tweening, number interpolation, and timeline sequencing. It uses an object pool for zero-GC per-frame perf
- [ParticleManager](https://docs.carverjs.dev/systems/particle-manager.html): ParticleManager is a singleton that manages all particle emitters. It uses GPU-instanced rendering via InstancedMesh and Structure-of-Arrays SoA particle data f


## Full Documentation Content

---
### Components > Game
URL: https://docs.carverjs.dev/components/game.html

Game
Game is the entry point for every CarverJS application. It wraps React Three Fiber's <Canvas /, sets up the WebGL renderer, lighting, environment, input system, and game loop — so you can focus on building your scene.
A single Game can contain multiple World./world.md components levels/scenes. Only one World is active at a time.
---
 Quick Start
 Minimal 3D game
 Minimal 2D game
---
 What Game Sets Up
 Feature  3D Mode default  2D Mode 
-------------------------------------
 Canvas  Shadows enabled  Shadows disabled 
 Ambient Light  intensity 0.4  intensity 1 
 Directional Light  position 10,15,10, castShadow, 1024x1024 shadow map  Not rendered 
 Sky  sunPosition 100,20,100  Not rendered 
 Environment  preset "sunset", background  Not rendered 
 Game Loop  Active GameLoopTick at priority -5  Active 
 Audio System  Active AudioFlush at priority -48  Active 
 Collision System  Active CollisionFlush at priority -25  Active 
 Input System  Active InputFlush at priority -50  Active 
---
 Props Reference
Game extends all R3F CanvasPropshttps://r3f.docs.pmnd.rs/api/canvas except camera plus the following:
 Prop  Type  Default  Description 
----------------------------------
 mode  "2d" \ "3d"  "3d"  Controls lighting, shadows, and default features 
 ambientLightProps  AmbientLightProps  —  Overrides for the ambient light 
 directionalLightProps  DirectionalLightProps  —  Overrides for the directional light 3D only 
 skyProps  SkyProps  —  Overrides for <Sky / 3D only 
 environmentProps  EnvironmentProps  —  Overrides for <Environment / 3D only 
 children  ReactNode  —  One or more <World components and other scene content 
Any extra props e.g., style, dpr, gl are passed to the underlying <Canvas /.
---
 Customizing the Environment
 Override lighting
 Override sky and environment
 Pass Canvas props
---
 Game Loop & Input
Game automatically mounts four internal systems:
1. GameLoopTick priority -5 — increments the global game store's elapsed and frameCount each frame while phase is "playing".
2. CollisionFlush priority -25 — runs built-in CollisionManager../systems/collision-manager.md overlap detection each frame. Runs after fixedUpdate, before update.
3. AudioFlush priority -48 — initializes the AudioManager../systems/audio-manager.md, syncs the audio listener to the active camera, updates spatial sound positions, and auto-pauses audio with the game phase.
4. InputFlush priority -50 — attaches the InputManager../systems/input-manager.md to the canvas and flushes input state before all game logic stages.
Any component inside <Game can use useGameLoop../hooks/use-game-loop.md, useInput../hooks/use-input.md, useCollision../hooks/use-collision.md, and useAudio../hooks/use-audio.md without additional setup.
---
 Multiple Worlds
A Game can contain multiple World components. Use the active prop to control which one is rendered:
Since the Canvas is owned by Game, switching worlds doesn't destroy the WebGL context — transitions are fast.
---
 Architecture
---
 Type Definitions
See Types../types/index.md for WorldMode, SkyProps, EnvironmentProps, AmbientLightProps, and DirectionalLightProps.

---
### Components > World
URL: https://docs.carverjs.dev/components/world.html

World
World is a level/scene container inside a Game./game.md. It groups Actors./actor.md, sets up a default camera, and optionally enables physics. Toggle worlds on/off with the active prop.
A Game can have multiple Worlds — only the active one is visible and receives rendering.
---
 Quick Start
---
 Props Reference
 Prop  Type  Default  Description 
----------------------------------
 active  boolean  true  Whether this world is visible. Set to false to hide it. 
 physics  WorldPhysicsConfig  —  Enable Rapier physics. Requires @react-three/rapier. 
 cameraProps2D  CameraProps2D  —  Overrides for the default OrthographicCamera 2D mode 
 cameraProps3D  CameraProps3D  —  Overrides for the default PerspectiveCamera 3D mode 
 orbitControlsProps  OrbitControlsProps  —  Overrides for the default OrbitControls 3D mode 
 children  ReactNode  —  Scene content Actors, Camera, etc. 
---
 Physics
Pass a physics prop to enable Rapier-based physics for all Actors in the World.
 Install
@react-three/rapier is an optional peer dependency — Rapier is lazy-loaded at runtime. If it's not installed and you pass a physics prop, a console warning is logged and children render without physics.
 WorldPhysicsConfig
 Field  Type  Default  Description 
-----------------------------------
 gravity  number, number, number  0, -9.81, 0  Gravity vector 
 timestep  number \ "vary"  1/60  Physics timestep. "vary" uses variable timestep. 
 interpolation  boolean  true  Smooth rendering between physics steps 
 debug  boolean  false  Show wireframe collider outlines 
 Basic physics
 2D physics
In 2D mode, Z translation and X/Y rotation are auto-locked per Actor.
 Debug mode
:::tip
Physics is configured at the World level, but each Actor opts-in individually via its own physics prop. See Actor./actor.md for ActorPhysicsProps.
:::
---
 Default Camera
World provides a default camera based on the mode set on the parent Game:
 Property  3D Mode  2D Mode 
----------------------------
 Type  PerspectiveCamera  OrthographicCamera 
 Position  0, 5, 10  0, 0, 100 
 FOV / Zoom  75  50 
 Near / Far  0.1 / 1000  0.1 / 1000 
 Orbit Controls  Enabled  Disabled 
 Override defaults
---
 Custom Camera
Drop a <Camera./camera.md inside World to replace the default camera and controls:
When a <Camera is detected, the default camera and orbit controls are skipped.
---
 Multiple Worlds
Use the active prop to switch between worlds:
Inactive worlds are hidden via visible={false} on the underlying Three.js group. The Canvas and WebGL context are not destroyed during world switches.
---
 Type Definitions
See Types../types/index.md for WorldPhysicsConfig, CameraProps2D, CameraProps3D, and OrbitControlsProps.

---
### Components > Actor
URL: https://docs.carverjs.dev/components/actor.html

Actor
An Actor is any renderable entity you place in a scene. Every actor shares a common set of transform and event props, but the type field determines what gets rendered:
 Type  What it renders 
----------------------
 "model"  A 3D model loaded from a .glb / .gltf file 
 "sprite"  A flat 2D image static or animated spritesheet 
 "primitive"  A code-generated geometric shape box, sphere, etc. 
---
 Choosing an Actor Type
Not sure which type to use? Here's a guide.
 Model type: "model"
Loads a pre-made 3D model file .glb / .gltf created in tools like Blender, Maya, or downloaded from asset stores.
Use for: Complex, detailed 3D objects — characters, buildings, vehicles, weapons, furniture. Anything that has detailed geometry, textures, and potentially skeletal animations baked into the file.
- Full 3D with complex geometry and textures from the file
- Supports built-in skeletal animations walk, idle, attack cycles
- Requires an external .glb/.gltf asset file
- Heaviest option file download + GPU resources
 Sprite type: "sprite"
A flat 2D image .png, .jpg rendered in the 3D/2D world. Sprites come in three flavours:
- Static — a single image displayed as-is
- Grid-based animation — a spritesheet image where all frames are arranged in a grid no extra files needed
- Atlas-based animation — a spritesheet image paired with a JSON atlas that describes each frame's position and size
Use for: 2D games, UI elements in 3D space, particle-like effects, trees/foliage in retro-style games, health bars, damage numbers. Think classic 2D game characters or "billboard" elements that always face the camera.
- Flat 2D image, no 3D depth
- Optionally billboards always faces camera — great for 2D characters in 3D worlds
- Two animation methods: grid-based just an image or atlas-based image + JSON
- Lighter than models, requires image assets
 Primitive type: "primitive"
A basic geometric shape box, sphere, cylinder, etc. generated entirely by code — no external files needed.
Use for: Prototyping, debug visuals, simple game objects platforms, walls, collectible orbs, ground planes, placeholder art during development, or minimalist/abstract game styles.
- No asset files needed — pure code
- 9 shapes: box, sphere, cylinder, cone, torus, plane, circle, capsule, ring
- 5 material types with color, wireframe, and opacity control
- Lightest option, instant rendering
- No animation support geometry only
 At a Glance
   Model  Sprite  Primitive 
----------------------------
 Dimensions  Full 3D  2D flat  3D geometric 
 Assets needed  .glb/.gltf file  .png/.jpg image  None 
 Animation  Skeletal walk, idle...  Spritesheet frames grid or atlas  None 
 Complexity  High detailed meshes  Low flat image  Minimal basic shape 
 Best for  Characters, props, buildings  2D games, billboards, UI  Prototyping, platforms, debug 
---
 Quick Start
A few copy-paste examples to get you going.
 Primitive — a red box
 Model — a character with an animation
 Sprite — a billboard tree
 Sprite — grid-based animated spritesheet
If your spritesheet is a single image with frames arranged in a grid, just pass spriteAnimation with a numberOfFrames count. CarverJS automatically calculates the rows and columns from the image dimensions.
 Sprite — atlas-based animated spritesheet
If you have a JSON atlas file exported from tools like TexturePacker or Aseprite, pass it via atlasUrl alongside the spritesheet image.
---
 Props Reference
Actor is a discriminated union on the type field. All three variants share a common base of transform, visibility, and event props.
 Common Props
These apply to every actor regardless of type.
 Prop  Type  Default  Description 
----------------------------------
 type  "model" \ "sprite" \ "primitive"  —  Required. Determines the renderer used 
 name  string  —  Name assigned to the group 
 position  Vector3  —  World position x, y, z 
 rotation  Euler  —  Rotation x, y, z 
 scale  Vector3  —  Scale x, y, z or uniform number. Overrides size if both are set 
 size  number  —  Uniform scale factor — preserves aspect ratio. size={2} doubles the actor in all axes 
 visible  boolean  true  Toggle visibility 
 castShadow  boolean  false  Whether meshes cast shadows 
 receiveShadow  boolean  false  Whether meshes receive shadows 
 renderOrder  number  —  Render order override 
 physics  ActorPhysicsProps  —  Rapier physics body config. Only active when parent World has physics. 
 userData  Record<string, unknown  —  Arbitrary user data on the group 
 children  ReactNode  —  Additional children inside the group 
 Event Props
All R3F pointer, click, and wheel events are supported:
onClick, onDoubleClick, onContextMenu, onPointerUp, onPointerDown, onPointerOver, onPointerOut, onPointerEnter, onPointerLeave, onPointerMove, onPointerMissed, onWheel
---
 Model Props
Additional props when type is "model".
 Prop  Type  Default  Description 
----------------------------------
 src  string  —  Required. URL to a .glb/.gltf file 
 useDraco  boolean \ string  —  Enable Draco decompression pass true or a decoder path 
 useMeshopt  boolean  —  Enable Meshopt decompression 
 animationName  string  —  Name of the animation clip to play 
 animationPaused  boolean  false  Pause the active animation 
 animationSpeed  number  1  Playback speed multiplier 
 animationLoop  boolean  true  Whether the animation loops 
:::tip
Models with skeleton animations are automatically cloned via SkeletonUtils.clone, so multiple instances of the same model can animate independently.
:::
---
 Sprite Props
Additional props when type is "sprite".
 Prop  Type  Default  Description 
----------------------------------
 src  string  —  Required. URL to the texture image 
 atlasUrl  string  —  URL to a spritesheet JSON atlas for atlas-based animation 
 billboard  boolean  true  Auto-face the camera 
 billboardLockX  boolean  —  Lock billboard rotation on X axis 
 billboardLockY  boolean  —  Lock billboard rotation on Y axis 
 billboardLockZ  boolean  —  Lock billboard rotation on Z axis 
 spriteAnimation  object  —  Animation settings see below. When provided without atlasUrl, enables grid-based animation. When provided with atlasUrl, enables atlas-based animation 
 How Sprites Render
The combination of atlasUrl and spriteAnimation determines what gets rendered:
 atlasUrl  spriteAnimation  Result 
---------------------------------------
 —  —  Static sprite — a single image 
 —  Provided  Grid-based animation — frames are auto-detected from the image grid 
 Provided  Provided  Atlas-based animation — frames are read from the JSON atlas 
 spriteAnimation Fields
 Field  Type  Default  Grid  Atlas  Description 
----------------------:----::-----:-------------
 numberOfFrames  number  1  Required  Optional  Total number of frames in the spritesheet 
 fps  number  10  Yes  Yes  Frames per second 
 loop  boolean  true  Yes  Yes  Loop the animation 
 startFrame  number  0  Yes  Yes  First frame index 
 endFrame  number  last frame  Yes  Yes  Last frame index 
 autoPlay  boolean  true  Yes  Yes  Start playing immediately 
 flipX  boolean  false  Yes  Yes  Mirror horizontally 
 frameName  string  —  —  Yes  Named frame to display 
 play  boolean  —  —  Yes  Start playback 
 pause  boolean  —  —  Yes  Pause playback 
 alphaTest  number  —  —  Yes  Alpha threshold for transparency 
 playBackwards  boolean  —  —  Yes  Reverse playback direction 
 resetOnEnd  boolean  —  —  Yes  Reset to first frame when done 
 animationNames  string  —  —  Yes  Available animation names in the atlas 
 onStart  function  —  —  Yes  Callback when animation starts 
 onEnd  function  —  —  Yes  Callback when animation ends 
 onLoopEnd  function  —  —  Yes  Callback when a loop cycle ends 
 onFrame  function  —  —  Yes  Callback on each frame change 
:::tip Grid-based animation
Grid-based animation is the simplest way to animate a sprite — just provide a single spritesheet image and set numberOfFrames. CarverJS automatically calculates the grid layout rows and columns from the image dimensions. No JSON atlas file or external tools required.
:::
---
 Primitive Props
Additional props when type is "primitive".
 Prop  Type  Default  Description 
----------------------------------
 shape  PrimitiveShape  "box"  Geometry type 
 geometryArgs  number  per-shape defaults  Constructor arguments for the geometry 
 materialType  PrimitiveMaterialType  "standard"  Material type 
 color  ColorRepresentation  "6366f1"  Material color 
 materialProps  Partial<MeshStandardMaterial  —  Additional material properties 
 wireframe  boolean  —  Render as wireframe 
 Available Shapes
 Shape  Default geometryArgs 
-------------------------------
 box  1, 1, 1 
 sphere  0.5, 32, 32 
 cylinder  0.5, 0.5, 1, 32 
 cone  0.5, 1, 32 
 torus  0.5, 0.2, 16, 32 
 plane  1, 1 
 circle  0.5, 32 
 capsule  0.5, 1, 4, 16 
 ring  0.3, 0.5, 32 
 Available Material Types
 Type  Description 
-------------------
 "standard"  Physically-based material default — responds to lighting realistically 
 "basic"  Flat shading, not affected by lights — good for UI or unlit objects 
 "phong"  Shiny specular highlights — good for glossy surfaces 
 "lambert"  Soft diffuse shading — good for matte surfaces 
 "toon"  Cel-shaded / cartoon look — hard-edged lighting bands 
---
 Physics Props
When the parent World./world.md has a physics prop, you can add physics to individual Actors via the physics prop. The Actor is wrapped in a Rapier <RigidBody.
 Field  Type  Default  Description 
-----------------------------------
 bodyType  RigidBodyType  "dynamic"  "dynamic", "fixed", "kinematicPosition", or "kinematicVelocity" 
 collider  PhysicsColliderType  "auto"  "cuboid", "ball", "capsule", "trimesh", "convexHull", or "auto" 
 mass  number  1  Mass of the body 
 restitution  number  0  Bounciness 0-1 
 friction  number  0.5  Friction coefficient 
 sensor  boolean  false  Trigger volume detects overlap, no physics response 
 gravityScale  number  1  Per-body gravity multiplier. 0 = no gravity 
 linearDamping  number  0  Linear velocity damping 
 angularDamping  number  0  Angular velocity damping 
 ccd  boolean  false  Continuous collision detection for fast-moving objects 
 enabledTranslations  boolean, boolean, boolean  —  Lock/unlock translation per axis. In 2D, Z is auto-locked 
 enabledRotations  boolean, boolean, boolean  —  Lock/unlock rotation per axis. In 2D, X/Y are auto-locked 
 onCollisionEnter  CollisionCallback  —  Called when another body starts touching 
 onCollisionExit  CollisionCallback  —  Called when another body stops touching 
:::tip
Use usePhysics../hooks/use-physics.md inside children of a physics-enabled Actor to imperatively control the rigid body apply impulses, set velocity, teleport, etc..
:::
---
 Ref
Actor forwards a ref to its root <group, giving you direct access to the Three.js object for imperative control:
---
 Type Definitions
See Types../types/index.md for all type definitions including ActorProps, ModelActorProps, SpriteActorProps, PrimitiveActorProps, ActorTransformProps, ActorEventProps, ActorPhysicsProps, PrimitiveShape, and PrimitiveMaterialType.

---
### Components > Camera
URL: https://docs.carverjs.dev/components/camera.html

Camera
Camera gives you full control over the camera in a World scene. Drop it as a child of World to replace the default camera and controls with your own configuration.
When World detects a <Camera child, it automatically skips its built-in camera and orbit controls — no extra flags needed.
---
 Quick Start
 Perspective camera with orbit controls
 Orthographic camera 2D-style
 Follow a target
 Get the imperative API
---
 Props Reference
 Prop  Type  Default  Description 
----------------------------------
 type  "perspective" \ "orthographic"  "perspective"  Camera projection type 
 controls  "orbit" \ "map" \ "pointerlock" \ "none"  "none"  Controls mode 
 follow  CameraFollowConfig  —  Follow configuration. Omit for a static camera 
 perspectiveProps  PerspectiveCameraProps  —  Overrides for the PerspectiveCamera when type="perspective" 
 orthographicProps  OrthographicCameraProps  —  Overrides for the OrthographicCamera when type="orthographic" 
 orbitControlsProps  OrbitControlsProps  —  Overrides for OrbitControls when controls="orbit" 
 mapControlsProps  MapControlsProps  —  Overrides for MapControls when controls="map" 
 pointerLockControlsProps  PointerLockControlsProps  —  Overrides for PointerLockControls when controls="pointerlock" 
 onReady  api: UseCameraReturn = void  —  Callback receiving the imperative camera API 
---
 Built-in Defaults
 Property  Perspective  Orthographic 
-------------------------------------
 Position  0, 5, 10  0, 0, 100 
 FOV / Zoom  75  50 
 Near  0.1  0.1 
 Far  1000  1000 
---
 CameraFollowConfig
 Field  Type  Default  Description 
-----------------------------------
 target  RefObject<Object3D  —  Required. Ref to the Object3D to follow 
 offset  x, y, z  0, 5, 10  Position offset from the target 
 smoothing  number  0.1  Lerp factor 0–1. Lower = smoother, higher = snappier 
 lookAt  boolean  true  Whether the camera looks at the target 
 lookAtOffset  x, y, z  0, 0, 0  Offset for the look-at point 
---
 Controls
 Mode  Description 
-------------------
 "none"  No controls — camera is static or driven by follow / imperative API 
 "orbit"  Click-drag to orbit around a point, scroll to zoom 
 "map"  Pan and zoom controls suited for top-down views 
 "pointerlock"  First-person style — locks the cursor and rotates on mouse move 
---
 Ref
Camera forwards a ref to the underlying Three.js camera object:
---
 Type Definitions
See Types../types/index.md for CameraType, CameraControlsType, CameraFollowConfig, PerspectiveCameraProps, OrthographicCameraProps, MapControlsProps, PointerLockControlsProps, and UseCameraReturn.

---
### Components > AudioListener
URL: https://docs.carverjs.dev/components/audio-listener.html

AudioListener
AudioListener overrides the default audio listener position. By default, the Web Audio listener follows the active R3F camera. Mount this component to follow a different Object3D instead e.g., a player ref.
---
 Quick Start
---
 When to Use
- Split-screen: Listener should follow one player, not the camera
- 2D games: The camera is often far from the action plane e.g., at Z=100. Setting the listener to the player gives correct left/right stereo panning based on world positions
- Cutscenes: Listener stays on a character while the camera moves freely
When AudioListener is not mounted, the listener automatically follows the active R3F camera the default behavior set by AudioFlush inside Game.
---
 Props
 Prop  Type  Description 
-------------------------
 listenerRef  RefObject<Object3D  Ref to the Object3D the listener should follow 
The listener position is updated every frame at priority -49, just before AudioFlush at -48.
On unmount, the override is cleared and the listener falls back to the camera.
---
 Type Definitions
See Types../types/index.md for AudioListenerConfig.

---
### Components > SceneManager
URL: https://docs.carverjs.dev/components/scene-manager.html

SceneManager
SceneManager organizes your game into discrete scenes menus, levels, HUDs with lifecycle management, stack-based navigation, and visual transitions. Place it inside Game./game.md and register scenes with Scene./scene.md.
---
 Quick Start
---
 Props Reference
 Prop  Type  Default  Description 
----------------------------------
 initial  string  —  Required. Name of the scene to start on mount 
 loadingFallback  ReactNode  null  Fallback shown while lazy-loaded scenes are loading must be a Three.js element 
 persistent  ReactNode  —  Elements rendered above all scenes, surviving transitions e.g., global audio wrapper 
 children  ReactNode  —  <Scene components for registration 
---
 Navigation
Scene navigation is stack-based with four operations:
 Method  Behavior  Previous Scene 
---------------------------------
 goname  Clear the stack, navigate to scene  Destroyed or sleeping if persistent 
 pushname  Push scene on top of stack  Sleeping 
 pop  Remove top scene, return to previous  Destroyed popped scene 
 replacename  Swap top of stack  Destroyed or sleeping if persistent 
Use the useScene../hooks/use-scene.md hook or the imperative getSceneManager../systems/scene-manager.md API.
 Example: Pause menu with push/pop
---
 Transitions
Pass a TransitionConfig as the third argument to any navigation method:
 Type  Behavior 
----------------
 "none"  Instant swap default 
 "fade"  Fade to color at midpoint, swap scenes, fade from color 
 "custom"  User-provided GLSL fragment shader with uProgress uniform 0-1 
 Default transition per scene
Set a default transition on the <Scene config. It applies when navigating to that scene without an explicit transition:
 Custom shader transition
---
 Scene Lifecycle
 Status  Mounted  Visible  Updates  Description 
------------------------------------------------
 created  No  No  No  Registered, not started 
 preloading  Yes  No  No  Lazy loading via Suspense 
 running  Yes  Yes  Yes  Active scene 
 paused  Yes  Yes  No  Visible but updates disabled 
 sleeping  Yes  No  No  Hidden, preserves React tree + GPU resources 
 shuttingdown  Yes  Yes  No  Transitioning out 
 destroyed  No  No  No  Unmounted 
 Sleep vs Destroy
- Non-persistent scenes are unmounted destroyed when navigated away from
- Persistent scenes persistent={true} are hidden sleeping — their React tree, Three.js objects, and GPU resources are preserved for fast re-entry
---
 Shared Data
Pass data between scenes without prop drilling:
---
 Lazy Loading
Code-split scenes with the loader prop:
The scene's JavaScript bundle loads on-demand when navigated to. A loadingFallback renders during loading:
---
 Error Isolation
Each scene is wrapped in its own error boundary. If a scene crashes, other scenes and the transition system continue running. The crashed scene is marked as destroyed.
---
 Architecture
---
 Type Definitions
See Types../types/index.md for SceneManagerProps, SceneConfig, SceneStatus, TransitionConfig, TransitionType, SceneStoreState, SceneEntry, and TransitionState.

---
### Components > Scene
URL: https://docs.carverjs.dev/components/scene.html

Scene
Scene declaratively registers a scene configuration with the SceneManager./scene-manager.md. It does not render scene content — the SceneManager handles rendering based on navigation state.
---
 Quick Start
---
 Props Reference
 Prop  Type  Default  Description 
----------------------------------
 name  string  —  Required. Unique scene identifier used in navigation calls 
 component  ComponentType<{ data?: T }  —  React component to render as scene content 
 loader   = Promise<{ default: ComponentType }  —  Lazy loader for code-splitting overrides component 
 transition  TransitionConfig  —  Default transition when navigating to this scene 
 persistent  boolean  false  Keep scene mounted sleeping when navigated away 
---
 Scene Component Contract
Scene components receive an optional data prop containing whatever was passed during navigation:
---
 Lazy Loading
Use loader instead of component for code-split scenes:
The scene module must have a default export:
---
 Type Definitions
See Types../types/index.md for SceneConfig, TransitionConfig, and SceneProps.

---
### Components > AssetLoader
URL: https://docs.carverjs.dev/components/asset-loader.html

AssetLoader
AssetLoader is a declarative preloader that loads all assets in a manifest before rendering its children. It shows a fallback typically a LoadingScreen./loading-screen.md during loading and automatically transitions the game phase from "loading" to "playing" when complete.
Place it inside Game./game.md requires R3F context and wrap your World./world.md or SceneManager./scene-manager.md.
---
 Quick Start
 Minimal preload
 With LoadingScreen
---
 How It Works
1. On mount, AssetLoader parses the manifest and starts loading all non-lazy assets via the AssetManager../systems/asset-manager.md.
2. For GLTF and texture assets, it also calls drei's useGLTF.preload / useTexture.preload to warm drei's internal cache. The browser's HTTP cache prevents double downloads.
3. During loading, the fallback is rendered as an HTML overlay via drei's <Html fullscreen. The progress callback receives real-time LoadingProgress../types/index.md updates.
4. On completion, children are rendered inside a <Suspense boundary. The game phase transitions from "loading" to "playing".
5. Assets are cached in the AssetManager's memory cache with LRU eviction. Access them later via useAssets../hooks/use-assets.md.
---
 Props Reference
 Prop  Type  Default  Description 
----------------------------------
 manifest  AssetManifest \ AssetEntry \ string  —  Required. Assets to preload. Pass an array of entries, a full manifest object, or a URL to a JSON manifest file 
 fallback  ReactNode \ progress: LoadingProgress = ReactNode  —  UI shown while loading. Use the render-prop form for progress display 
 concurrency  number  6  Maximum assets loading in parallel 
 retries  number  3  Retry attempts per failed asset 
 retryDelay  number  1000  Base delay between retries ms. Uses exponential backoff with jitter 
 timeout  number  30000  Timeout per asset in ms 
 minLoadTime  number  0  Minimum time to show fallback ms. Prevents flash for fast loads 
 onComplete   = void  —  Called when all assets finish loading 
 onError  errors: AssetLoadError = void  —  Called when any asset fails after all retries 
 onProgress  progress: LoadingProgress = void  —  Called on each progress update 
 children  ReactNode  —  Required. Content to render once loading completes 
---
 Asset Entry
Each entry in the manifest describes a single asset:
 Field  Type  Default  Description 
-----------------------------------
 url  string  —  Required. URL to load relative or absolute 
 key  string  url  Unique key for referencing via useAssets 
 type  AssetType  Auto-detected  Asset type: "gltf", "texture", "audio", "json", "binary" 
 priority  "critical" \ "high" \ "normal" \ "low" \ "lazy" \ number  "normal"  Loading priority. Higher loads first. "lazy" assets are skipped 
 group  string  —  Group name for batch loading/unloading 
 sizeHint  number  —  Expected file size in bytes for progress estimation 
 loaderOptions  Record<string, unknown  —  Loader-specific options. GLTF: { draco: true }. Audio: { streaming: true } 
 Auto-Detected Types
 Extensions  Asset Type 
----------------------
 .gltf, .glb  "gltf" 
 .png, .jpg, .jpeg, .webp, .svg  "texture" 
 .mp3, .ogg, .wav, .m4a  "audio" 
 .json  "json" 
 .bin, .dat  "binary" 
---
 Manifest Object
For larger games, use the full manifest format with a base URL and groups:
 JSON Manifest URL
Host the manifest as a JSON file and pass the URL:
---
 Priority Ordering
Assets are sorted by priority before loading. Higher values load first:
 Priority  Value  Use Case 
---------------------------
 "critical"  100  Splash screen assets, essential models 
 "high"  75  Main gameplay assets 
 "normal"  50  Standard assets default 
 "low"  25  Background music, ambient textures 
 "lazy"  0  Not loaded by AssetLoader — loaded on-demand via useAssets 
---
 Nested AssetLoaders Level Streaming
Nest AssetLoader components for level-by-level asset loading:
The outer loader handles core assets UI, fonts. Each level's loader handles level-specific assets. When a level unmounts, its assets remain cached for fast revisits evicted only under memory pressure.
---
 GLTF Draco/Meshopt
Pass compression options via loaderOptions:
:::tip
Ensure the useDraco / useMeshopt props on your Actor components match the loaderOptions in the manifest. Both need to agree on the compression format.
:::
---
 Error Handling
Failed assets are retried with exponential backoff. After all retries, errors are reported:
---
 Game Phase Integration
AssetLoader automatically manages the game phase:
1. Game mounts → phase = "loading" default
2. AssetLoader loads assets → phase stays "loading"
3. Loading completes → AssetLoader sets phase = "playing"
This integrates with useGameLoop../hooks/use-game-loop.md, which only fires callbacks when phase === "playing".
---
 Type Definitions
See Types../types/index.md for AssetManifest, AssetEntry, AssetGroupConfig, AssetType, LoadingProgress, and AssetLoadError.

---
### Components > LoadingScreen
URL: https://docs.carverjs.dev/components/loading-screen.html

LoadingScreen
LoadingScreen is a pre-built, customizable loading screen component designed to work with AssetLoader./asset-loader.md. It renders as HTML content within the AssetLoader's fallback slot.
---
 Quick Start
---
 Themes
 Default
Minimal progress bar with percentage text.
 Gaming
Wider progress bar with asset names, loaded count, rotating tips, and error display.
 Minimal
Spinner animation with percentage.
 Custom
Full control via children render prop. No default UI is rendered.
---
 Props Reference
 Prop  Type  Default  Description 
----------------------------------
 progress  LoadingProgress  —  Required. Loading progress data from AssetLoader's render prop 
 theme  "default" \ "gaming" \ "minimal" \ "custom"  "default"  Visual theme preset 
 background  string  "000000"  CSS background color or value 
 accentColor  string  "6366f1"  Progress bar accent color 
 logo  string \ ReactNode  —  Logo URL or React element displayed above the bar 
 tips  string  —  Loading tips to cycle gaming theme 
 tipInterval  number  5000  Tip rotation interval in ms 
 showCurrentAsset  boolean  true  Show the name of the asset being loaded 
 showCount  boolean  true  Show loaded/total count e.g., "12/20" 
 children  progress: LoadingProgress = ReactNode  —  Custom render function custom theme 
---
 Customization Examples
 Branded loading screen
 Fully custom layout
:::tip
You don't have to use LoadingScreen at all. The fallback render prop on AssetLoader accepts any React element. Use LoadingScreen for quick setup, or write your own UI from scratch.
:::
---
 Type Definitions
See Types../types/index.md for LoadingProgress and AssetLoadError.

---
### Components > ParticleEmitter
URL: https://docs.carverjs.dev/components/particle-emitter.html

ParticleEmitter
ParticleEmitter is a declarative component for creating particle effects. Drop it into a scene or as a child of an Actor./actor.md to add fire, smoke, explosions, and other visual effects.
For imperative control burst on demand, start/stop programmatically, use the useParticles../hooks/use-particles.md hook instead.
---
 Quick Start
---
 Props
ParticleEmitter accepts all ParticleEmitterConfig fields plus:
 Prop  Type  Default  Description 
----------------------------------
 preset  ParticlePreset  —  Base preset. Props override preset values 
 position  Vector3  0, 0, 0  Emitter position in parent space 
 rotation  Euler  —  Emitter rotation 
 enabled  boolean  true  Toggle emission on/off 
All ParticleEmitterConfig options are also accepted as props. See useParticles../hooks/use-particles.md for the full list.
---
 Presets
 Preset  Description 
---------------------
 "fire"  Ascending glow, orange to transparent, additive blend 
 "smoke"  Slow rising grey particles, expanding over lifetime 
 "explosion"  Radial burst with quick fade 
 "sparks"  Fast bright particles with gravity 
 "rain"  Vertical downpour 
 "snow"  Gentle falling white particles 
 "magic"  Colorful orbiting particles, additive blend 
 "confetti"  Tumbling colored particles with gravity 
---
 Custom Configuration
Override any preset value or build from scratch:
---
 Ref Forwarding
ParticleEmitter supports forwardRef for accessing the underlying <group:
---
 World vs Local Space
---
 Type Definitions
See Types../types/index.md for ParticleEmitterProps, ParticleEmitterConfig, ParticlePreset, and EmitterShapeConfig.

---
### Hooks > useAnimation
URL: https://docs.carverjs.dev/hooks/use-animation.html

useAnimation
Manages animation playback for GLTF/GLB models. Wraps drei's useAnimations with play/pause, speed control, looping, and crossfade support.
:::note
You typically don't need this hook directly — the Actor component with type="model" handles animations via its props. Use this hook when you need programmatic control e.g. crossfading between animations on user input.
:::
 Import
 Signature
 Parameters
 Parameter  Type  Description 
------------------------------
 clips  AnimationClip  Animation clips from a loaded GLTF gltf.animations 
 options  UseAnimationOptions  Playback configuration optional 
 UseAnimationOptions
 Field  Type  Default  Description 
-----------------------------------
 clipName  string  —  Name of the clip to play. Changing this switches animations with a 0.2s crossfade 
 paused  boolean  false  Pause/resume the active animation 
 speed  number  1  Playback speed multiplier applied to the mixer's timeScale 
 loop  boolean  true  true = LoopRepeat infinite, false = LoopOnce clamps when finished 
 Return Value UseAnimationReturn
 Field  Type  Description 
--------------------------
 ref  RefObject<Object3D  Attach to the animated object passed to <primitive ref={ref} 
 clipNames  string  List of available animation clip names 
 activeAction  AnimationAction \ null  Currently playing action 
 mixer  AnimationMixer  The underlying Three.js mixer 
 actions  Record<string, AnimationAction \ null  All actions keyed by clip name 
 playname  name: string = void  Play a clip by name crossfades from current 
 stopAll   = void  Stop all running animations 
 crossFadeToname, duration?  name: string, duration?: number = void  Smoothly transition to another clip. Default duration: 0.3s 
 Usage
 Declarative via options
 Programmatic control
 Type Definitions
See Types../types/index.md for UseAnimationOptions and UseAnimationReturn definitions.

---
### Hooks > useCamera
URL: https://docs.carverjs.dev/hooks/use-camera.html

useCamera
Provides imperative camera controls — shake, smooth transitions, and look-at. Used internally by the Camera component, but available directly for advanced use cases.
:::note
You typically don't need this hook directly — the Camera component exposes the same API via its onReady callback. Use this hook when you need camera control outside of a Camera component.
:::
 Import
 Signature
 Parameters
 Parameter  Type  Description 
------------------------------
 options  UseCameraOptions  Optional configuration 
 UseCameraOptions
 Field  Type  Description 
--------------------------
 follow  CameraFollowConfig  Follow a target object. See Camera — CameraFollowConfig../components/camera.mdcamerafollowconfig 
 Return Value UseCameraReturn
 Method  Signature  Description 
--------------------------------
 shake  intensity?: number, duration?: number = void  Trigger a camera shake. Default: intensity 0.3, duration 0.3s 
 moveTo  position: x, y, z, duration?: number = void  Smoothly transition to a position. Default duration: 1s. Uses smooth-step easing 
 lookAt  target: x, y, z = void  Immediately point the camera at a world position 
 Usage
 Shake on hit
 Cinematic pan
 Follow a player
 Type Definitions
See Types../types/index.md for UseCameraOptions, UseCameraReturn, and CameraFollowConfig.

---
### Hooks > useGameLoop
URL: https://docs.carverjs.dev/hooks/use-game-loop.html

useGameLoop
Registers a per-frame callback with control over update stage, timestep mode, and integration with the global game phase. Built on R3F's useFrame with priority-based ordering, a max-delta cap, and optional fixed-timestep accumulator.
:::note
useGameLoop must be called inside a component within a <World, since it relies on the R3F canvas context and the CarverJS game store.
:::
 Import
 Signature
 Parameters
 callback
Called every frame or every fixed tick while the game phase is "playing".
 Argument  Type  Description 
-----------------------------
 delta  number  Seconds since last frame or fixedDelta in fixed-timestep mode 
 elapsed  number  Total seconds elapsed while in the "playing" phase 
 options UseGameLoopOptions
 Option  Type  Default  Description 
------------------------------------
 stage  GameLoopStage  "update"  Which update stage this callback runs in 
 fixedTimestep  boolean  false  Use fixed-timestep accumulator only meaningful on "fixedUpdate" stage 
 fixedDelta  number  1/60  Seconds per fixed tick ~16.67ms 
 maxDelta  number  0.1  Maximum raw delta cap — prevents spiral-of-death after tab switches 
 enabled  boolean  true  Per-instance toggle, independent of global game phase 
 Return Value UseGameLoopReturn
 Field  Type  Description 
--------------------------
 phase  GamePhase  Current game phase from the store 
 isPaused  boolean  true when phase is "paused" or "gameover" 
 elapsed  number  Total elapsed seconds since the game started playing 
 Update Stages
Stages run in this order every frame:
 Stage  Priority  Intended Use 
-------------------------------
 earlyUpdate  -10  Input gathering, flag resets at frame start 
 fixedUpdate  -20  Deterministic physics and movement 
 update  -30  General game logic default 
 lateUpdate  -40  Camera follow, trailing effects, UI sync 
After all stages, R3F auto-renders the scene at priority 0.
 Game Phase
The loop integrates with the global game store. Callbacks only fire when phase === "playing". Control the phase via useGameStore:
The store initializes with phase: "loading". You must call setPhase"playing" to start the game loop.
 Usage
 Basic per-frame update
 Fixed timestep deterministic physics
 Pause and resume
 Staged updates input → logic
 Conditional enable
 Type Definitions
See Types../types/index.md for GameLoopStage, GamePhase, UseGameLoopOptions, UseGameLoopReturn, and GameLoopCallback.

---
### Hooks > useInput
URL: https://docs.carverjs.dev/hooks/use-input.html

useInput
useInput provides keyboard and pointer input for game logic. It reads from the InputManager../systems/input-manager.md which is automatically set up by Game../components/game.md.
---
 Quick Start
---
 Return Value
 Property  Type  Description 
-----------------------------
 isPressedcode  string = boolean  true while the key is held 
 isJustPressedcode  string = boolean  true only on the frame the key was first pressed 
 isJustReleasedcode  string = boolean  true only on the frame the key was released 
 isActionname  string = boolean  true if any key bound to the action is held 
 isActionJustPressedname  string = boolean  true if any key bound to the action was just pressed 
 getAxisneg, pos  string, string = number  Returns -1, 0, or 1 
 pointer  PointerState  Live pointer state position, isDown, justDown, justUp 
---
 Options
 Option  Type  Default  Description 
------------------------------------
 actions  Record<string, string  {}  Maps logical action names to key codes 
 keys  string  —  Subscribe to specific keys only 
 enabled  boolean  true  Toggle this hook on/off 
---
 Action Mapping
Instead of checking raw key codes, define actions:
---
 Axis Input
getAxis returns a value for two-key directional input:
---
 Pointer State
The pointer property is a live reference — always current when read inside useGameLoop:
 Field  Type  Description 
--------------------------
 position  { x: number, y: number }  Screen-space coordinates in pixels 
 isDown  boolean  Primary button is held 
 justDown  boolean  Button was pressed this frame 
 justUp  boolean  Button was released this frame 
---
 Key Codes
Key codes follow the KeyboardEvent.codehttps://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code standard:
 Key  Code 
-----------
 W  "KeyW" 
 A  "KeyA" 
 S  "KeyS" 
 D  "KeyD" 
 Space  "Space" 
 Shift  "ShiftLeft" 
 Arrow Up  "ArrowUp" 
 Enter  "Enter" 
 Escape  "Escape" 
---
 Type Definitions
See Types../types/index.md for UseInputOptions, UseInputReturn, ActionMap, KeyState, and PointerState.

---
### Hooks > useCollision
URL: https://docs.carverjs.dev/hooks/use-collision.html

useCollision
useCollision registers a lightweight collider on an Actor and fires callbacks when it overlaps with other colliders. No physics engine required — this is CarverJS's built-in collision system powered by the CollisionManager../systems/collision-manager.md.
---
 Quick Start
---
 Options
 Option  Type  Default  Description 
------------------------------------
 ref  RefObject<Object3D  —  Required. Ref to the Actor's group 
 collider  ColliderDef  —  Required. Collider shape definition 
 name  string  ""  Name for identification in collision events 
 userData  Record<string, unknown  {}  Arbitrary data passed through to events 
 layer  number  0xFFFFFFFF  Collision layer bitmask 
 mask  number  0xFFFFFFFF  Layers this collider checks against 
 sensor  boolean  false  Trigger mode detects overlap, no response 
 onCollisionEnter  CollisionCallback  —  First frame of overlap 
 onCollisionExit  CollisionCallback  —  Last frame of overlap 
 onCollisionStay  CollisionCallback  —  Every frame while overlapping 
 enabled  boolean  true  Toggle this collider on/off 
---
 Return Value
 Property  Type  Description 
-----------------------------
 isOverlappingname  string = boolean  Check if currently overlapping with a named collider 
 getOverlaps   = string  Get all current overlap names 
---
 Collider Shapes
 AABB Axis-Aligned Bounding Box
 Sphere 3D
 Circle 2D
---
 Collision Event
All callbacks receive a CollisionEvent:
 Field  Type  Description 
--------------------------
 otherName  string  Name of the other collider 
 otherUserData  Record<string, unknown  The other collider's userData 
 otherRef  RefObject<Object3D  The other collider's Object3D ref 
 isSensor  boolean  Whether the other collider is a sensor 
---
 Layer Filtering
Use bitmask layers to control which colliders interact:
---
 Sensor Mode
Sensors detect overlap but don't imply any physics response. Useful for triggers, collectibles, and zones:
---
 Type Definitions
See Types../types/index.md for UseCollisionOptions, UseCollisionReturn, ColliderDef, ColliderShape, CollisionEvent, and CollisionCallback.

---
### Hooks > useGridCollision
URL: https://docs.carverjs.dev/hooks/use-grid-collision.html

useGridCollision
useGridCollision provides a tile-based collision grid with O1 lookups. Ideal for grid-based games like Snake, tile RPGs, puzzle games, or any game that uses discrete cell movement.
---
 Quick Start
---
 Options
 Option  Type  Description 
---------------------------
 config  GridCollisionConfig  Required. Grid configuration 
 GridCollisionConfig
 Field  Type  Default  Description 
-----------------------------------
 width  number  —  Required. Number of cells along X 
 height  number  —  Required. Number of cells along Y 
 cellSize  number  1  World-space size of each cell 
 origin  number, number  0, 0  World-space origin offset 
---
 Return Value
 Method  Type  Description 
---------------------------
 setCellx, y, value  number, number, number = void  Set a cell value. 0 = empty, positive = occupied. 
 getCellx, y  number, number = number  Get cell value. Returns 0 if empty or out of bounds. 
 clearCellx, y  number, number = void  Clear a cell set to 0 
 isCellOccupiedx, y  number, number = boolean  Check if a cell is non-zero 
 worldToGridwx, wy  number, number = number, number  Convert world coordinates to grid coordinates 
 gridToWorldgx, gy  number, number = number, number  Convert grid coordinates to world coordinates cell center 
 getNeighbors4x, y  number, number = number, number, number, number  Get 4 cardinal neighbor values up, right, down, left 
 getNeighbors8x, y  number, number = number  Get 8 neighbor values cardinal + diagonal 
 clearAll   = void  Clear the entire grid 
---
 Snake Game Example
---
 Coordinate Conversion
Convert between world-space and grid-space:
---
 Type Definitions
See Types../types/index.md for UseGridCollisionOptions, UseGridCollisionReturn, GridCollisionConfig, and GridCellCallback.

---
### Hooks > usePhysics
URL: https://docs.carverjs.dev/hooks/use-physics.html

usePhysics
usePhysics provides an imperative API for controlling a Rapier rigid body. Use it inside children of a physics-enabled Actor../components/actor.md to apply impulses, set velocities, teleport, and more.
---
 Prerequisites
1. Install @react-three/rapier:
   
2. Enable physics on the World../components/world.md:
   
3. Add a physics prop to the Actor../components/actor.md:
   
4. Call usePhysics inside <PlayerController /.
---
 Quick Start
---
 Return Value
Returns UsePhysicsReturn  null. Returns null when no physics context exists or the component is not inside a physics-enabled Actor.
 Method  Type  Description 
---------------------------
 applyImpulseimpulse  number, number, number = void  Apply an instantaneous force 
 applyForceforce  number, number, number = void  Apply a continuous force resets each physics step 
 setLinearVelocityvel  number, number, number = void  Set linear velocity directly 
 getLinearVelocity   = number, number, number  Get current linear velocity 
 setAngularVelocityvel  number, number, number = void  Set angular velocity 
 setTranslationpos  number, number, number = void  Teleport the body to a position 
 getTranslation   = number, number, number  Get current position 
 setRotationquat  number, number, number, number = void  Set rotation as quaternion x, y, z, w 
 setEnabledenabled  boolean = void  Enable or disable the rigid body 
---
 Full Example
---
 Type Definitions
See Types../types/index.md for UsePhysicsReturn, ActorPhysicsProps, RigidBodyType, PhysicsColliderType, and WorldPhysicsConfig.

---
### Hooks > useAudio
URL: https://docs.carverjs.dev/hooks/use-audio.html

useAudio
useAudio provides sound effects, music, and volume control for game logic. It reads from the AudioManager../systems/audio-manager.md which is automatically set up by Game../components/game.md.
---
 Quick Start
---
 Return Value
 Property  Type  Description 
-----------------------------
 playname, options?  string, PlaySoundOptions? = SoundHandle \ null  Play a registered sound. Returns a handle to control the instance 
 stopname  string = void  Stop all instances of a named sound 
 pausename  string = void  Pause all instances of a named sound 
 resumename  string = void  Resume paused instances of a named sound 
 isPlayingname  string = boolean  Check if any instance is playing 
 playMusicsrc, options?  string \ string, MusicOptions? = void  Play a music track with crossfade 
 stopMusicfadeOut?  number? = void  Stop music with optional fade-out seconds 
 pauseMusic   = void  Pause the music 
 resumeMusic   = void  Resume the music 
 isMusicPlaying   = boolean  Check if music is playing 
 setVolumechannel, vol  AudioChannel, number = void  Set channel volume 0–1 
 getVolumechannel  AudioChannel = number  Get channel volume 
 setMutechannel, muted  AudioChannel, boolean = void  Mute/unmute a channel 
 isMutedchannel  AudioChannel = boolean  Check if a channel is muted 
 setMasterMutemuted  boolean = void  Mute/unmute all audio 
 preloadname  string = Promise<void  Preload a registered sound 
 preloadAllnames  string = Promise<void  Preload multiple sounds 
 isUnlocked  boolean  Whether the AudioContext has been unlocked user has interacted 
 isReady  boolean  Whether the audio system is fully ready 
---
 Options
 Option  Type  Default  Description 
------------------------------------
 sounds  SoundMap  {}  Map of sound names to definitions. Registered on mount, unregistered on unmount 
 enabled  boolean  true  Toggle all audio from this hook on/off 
---
 Sound Definition
Each sound in the sounds map is a SoundDefinition:
 Field  Type  Default  Description 
-----------------------------------
 src  string \ string  —  Required. URLs of the audio file. Array enables format negotiation 
 channel  AudioChannel  "sfx"  Volume channel: "sfx", "music", "ui", "ambient", "voice" 
 volume  number  1  Base volume 0–1 
 rate  number  1  Playback rate 0.5 = half speed, 2 = double 
 loop  boolean  false  Loop playback 
 maxInstances  number  5  Maximum simultaneous instances. Oldest is stolen when exceeded 
 preload  boolean  true  Preload the audio buffer on registration 
 sprites  AudioSpriteMap  —  Audio sprite regions see Audio Spritesaudio-sprites 
 cooldown  number  —  Minimum seconds between play calls. Rapid calls within cooldown are dropped 
 Format Negotiation
Provide multiple formats to maximize browser compatibility:
The system picks the first format the browser supports.
---
 Playing Sounds
 Basic
 With Options
 Sound Handle
play returns a SoundHandle for controlling the instance:
---
 Spatial Audio 3D
Attach a sound to a Three.js object for positional audio:
The sound's position updates every frame from the Object3D ref. The listener follows the active camera by default — override with AudioListener/docs/components/audio-listener.
 Option  Type  Default  Description 
------------------------------------
 ref  RefObject<Object3D  —  Required. The emitter's Object3D 
 panningModel  "HRTF" \ "equalpower"  "HRTF"  Panning algorithm 
 distanceModel  "linear" \ "inverse" \ "exponential"  "inverse"  Volume rolloff model 
 refDistance  number  1  Distance at which volume starts decreasing 
 maxDistance  number  100  Maximum audible distance 
 rolloffFactor  number  1  Rolloff speed 
 coneInnerAngle  number  360  Full-volume cone angle degrees 
 coneOuterAngle  number  360  Outer cone angle degrees 
 coneOuterGain  number  0  Volume outside outer cone 0–1 
 trackPosition  boolean  true  Update position every frame 
:::tip
For 2D games, use panningModel: "equalpower" cheaper and override the listener with AudioListener/docs/components/audio-listener pointing at the player ref. This gives correct left/right stereo panning.
:::
---
 Music
 Play Music
 Crossfade Between Tracks
When playMusic is called while music is already playing, the old track fades out and the new one fades in:
 Option  Type  Default  Description 
------------------------------------
 volume  number  1  Music volume 0–1 
 loop  boolean  true  Loop the track 
 crossfade.duration  number  2  Crossfade duration in seconds 
 Stop / Pause / Resume
---
 Audio Sprites
Pack multiple sounds into a single file to reduce HTTP requests:
 Field  Type  Default  Description 
-----------------------------------
 start  number  —  Start offset in seconds 
 duration  number  —  Duration in seconds 
 loop  boolean  false  Loop this sprite region 
---
 Volume Channels
Six independent volume channels, all routed through master:
 Channel  Purpose 
------------------
 "master"  Global output — affects everything 
 "sfx"  Sound effects default 
 "music"  Background music 
 "ui"  UI sounds clicks, hovers 
 "ambient"  Environmental audio wind, rain 
 "voice"  Character dialogue 
 Settings Menu Example
---
 AudioContext Unlock
Browsers require a user gesture before audio can play. The system handles this automatically:
1. On first click/tap/keypress, the AudioContext is unlocked
2. isUnlocked becomes true triggers React re-render
3. Queued music and looping sounds begin playing
4. One-shot SFX requested before unlock are silently dropped stale sounds are worse than none
---
 Game Phase Integration
Audio automatically pauses when the game phase is "paused" or "gameover", and resumes when "playing". No manual handling needed.
---
 Type Definitions
See Types../types/index.md for UseAudioOptions, UseAudioReturn, SoundDefinition, SoundMap, PlaySoundOptions, SoundHandle, SoundState, AudioChannel, AudioFormat, SpatialAudioOptions, PanningModel, DistanceModel, CrossfadeOptions, MusicOptions, AudioSpriteRegion, AudioSpriteMap, and AudioListenerConfig.

---
### Hooks > useScene
URL: https://docs.carverjs.dev/hooks/use-scene.html

useScene
useScene provides scene navigation and status. It reads from the scene store managed by SceneManager../components/scene-manager.md.
---
 Quick Start
---
 Return Value UseSceneReturn
 Property  Type  Description 
-----------------------------
 goname, data?, transition?  string, unknown?, TransitionConfig? = void  Navigate to a scene, clearing the stack 
 pushname, data?, transition?  string, unknown?, TransitionConfig? = void  Push a scene onto the stack current scene sleeps 
 poptransition?  TransitionConfig? = void  Pop the top scene, return to previous 
 replacename, data?, transition?  string, unknown?, TransitionConfig? = void  Replace the current scene 
 current  string \ null  Name of the current active scene 
 stack  readonly string  Full navigation stack last = current 
 isTransitioning  boolean  Whether a transition is in progress 
---
 Navigation Patterns
 Go clear stack
Destroys all scenes in the stack unless persistent, navigates to the target.
 Push overlay
Current scene sleeps, new scene pushes on top. Use for pause menus, inventories, dialogs.
 Pop return
Destroys the top scene, wakes the previous one.
 Replace swap
Replaces the current scene without changing stack depth. Use for level progression.
---
 Transition Config
All navigation methods accept an optional TransitionConfig:
 Field  Type  Default  Description 
-----------------------------------
 type  "none" \ "fade" \ "custom"  "none"  Transition type 
 duration  number  0.5  Duration in seconds 
 color  string  "000000"  Fade color for "fade" type 
 fragmentShader  string  —  Custom GLSL fragment shader for "custom" type 
 vertexShader  string  —  Custom vertex shader for "custom" type 
 uniforms  Record<string, { value: unknown }  —  Additional shader uniforms for "custom" type 
---
 useSceneData
Access the data passed to the current scene and cross-scene shared data.
 Return Value UseSceneDataReturn<T
 Property  Type  Description 
-----------------------------
 data  T \ undefined  Data passed to the current scene via navigation 
 setSharedkey, value  string, unknown = void  Set cross-scene shared data 
 getShared<Vkey  string = V \ undefined  Get cross-scene shared data 
 Usage
---
 useSceneTransition
Read-only access to the current transition state. Use for UI effects like dimming during transitions.
 Return Value UseSceneTransitionReturn
 Property  Type  Description 
-----------------------------
 active  boolean  Whether a transition is in progress 
 progress  number  Transition progress 0-1 
 from  string \ null  Source scene name 
 to  string \ null  Target scene name 
---
 useSceneLifecycle
Register lifecycle callbacks for a specific scene. Uses the callback-ref pattern so the latest closures are always called.
 Signature
 Callbacks
 Callback  When 
----------------
 onEnter  Scene transitions to "running" for the first time. Return a cleanup function. 
 onExit  Scene leaves "running" sleep, pause, or destroy 
 onSleep  Scene transitions to "sleeping" 
 onWake  Scene transitions from "sleeping" to "running" 
 onPause  Scene transitions to "paused" 
 onResume  Scene transitions from "paused" to "running" 
 Usage
---
 Type Definitions
See Types../types/index.md for UseSceneReturn, UseSceneDataReturn, UseSceneTransitionReturn, SceneLifecycleCallbacks, TransitionConfig, TransitionType, and SceneStatus.

---
### Hooks > useAssets
URL: https://docs.carverjs.dev/hooks/use-assets.html

useAssets
useAssets provides synchronous access to preloaded assets from the AssetManager../systems/asset-manager.md cache. Assets must be preloaded via AssetLoader../components/asset-loader.md before accessing them.
---
 Quick Start
:::note
For GLTF models and textures, you typically don't need useAssets — the Actor../components/actor.md component loads those via drei's useGLTF / useTexture internally. Use useAssets for non-visual assets like JSON config, audio buffers, and binary data.
:::
---
 Single Asset
Returns the cached asset data. Throws if the asset is not found in the cache.
---
 Multiple Assets
Returns an array of cached assets in the same order as the keys. Throws if any asset is missing.
---
 Reference Counting
useAssets automatically retains assets on mount and releases them on unmount. While a component is mounted and using an asset, that asset is protected from LRU cache eviction — even under memory pressure.
---
 Usage with AssetLoader
The typical pattern is to preload assets via AssetLoader../components/asset-loader.md and access them via useAssets:
---
 Type Definitions
See Types../types/index.md for AssetType, AssetEntry, and LoadingProgress.

---
### Hooks > useAssetProgress
URL: https://docs.carverjs.dev/hooks/use-asset-progress.html

useAssetProgress
useAssetProgress subscribes to the AssetManager../systems/asset-manager.md's loading progress. It does not suspend — it returns the current snapshot and re-renders when progress changes.
---
 Quick Start
---
 Return Value
Returns a Readonly<LoadingProgress object:
 Field  Type  Description 
--------------------------
 phase  "idle" \ "loading" \ "complete" \ "error"  Current loading phase 
 loaded  number  Number of assets finished loading 
 total  number  Total number of assets to load 
 progress  number  Fraction complete 0 to 1 
 currentAsset  string \ null  Key of the asset currently loading 
 currentGroup  string \ null  Group currently being loaded 
 errors  AssetLoadError  Errors encountered during loading 
---
 When to Use
Use useAssetProgress when you need progress data outside the AssetLoader../components/asset-loader.md fallback — for example, in a persistent HUD or debug overlay that lives above the Canvas.
For progress inside the AssetLoader's fallback, use the render-prop form instead:
---
 Type Definitions
See Types../types/index.md for LoadingProgress and AssetLoadError.

---
### Hooks > useTween
URL: https://docs.carverjs.dev/hooks/use-tween.html

useTween
useTween provides property tweening, number interpolation, and timeline sequencing for game animations. It reads from the TweenManager../systems/tween-manager.md which is automatically set up by Game../components/game.md.
---
 Quick Start
---
 Return Value
 Property  Type  Description 
-----------------------------
 tweenconfig  <T extends objectTweenConfig<T = TweenControls  Create and start a property tween 
 tweenNumberconfig  NumberTweenConfig = TweenControls  Create a target-less number tween 
 timelineconfig?  TimelineConfig? = TimelineControls  Create a timeline for sequenced animations 
 killAll   = void  Kill all tweens created by this hook instance 
 pauseAll   = void  Pause all active tweens 
 resumeAll   = void  Resume all paused tweens 
---
 Property Tweening
Animate any numeric property on any object. Supports dot-notation for nested properties like position.x.
 Basic
 With Explicit Start Values
 Callbacks
---
 TweenConfig
 Field  Type  Default  Description 
-----------------------------------
 target  T extends object  —  Required. Object whose properties to animate 
 to  Record<string, number  —  Required. End values supports dot-notation keys 
 from  Record<string, number  —  Start values. If omitted, current values are captured 
 duration  number  0.3  Duration in seconds 
 ease  EasingInput  "quad.out"  Easing function or preset name 
 delay  number  0  Delay before starting seconds 
 repeat  number  0  Additional repeats. -1 for infinite 
 repeatDelay  number  0  Delay between repeats seconds 
 yoyo  boolean  false  Reverse direction on each repeat 
 speed  number  1  Playback speed multiplier 
 group  string  ""  Named group for batch control 
 persist  boolean  false  Keep alive after completion not auto-released to pool 
 ignorePause  boolean  false  Continue updating when game is paused 
 onStart   = void  —  Fired when the tween starts playing 
 onUpdate  progress: number = void  —  Fired every frame with eased progress 0–1 
 onComplete   = void  —  Fired when all repeats finish 
 onRepeat  count: number = void  —  Fired after each repeat 
 onYoyo  direction: TweenDirection = void  —  Fired when direction reverses 
 onKill   = void  —  Fired when the tween is killed 
---
 TweenControls
Every tween call returns a TweenControls handle for imperative control:
 Property  Type  Description 
-----------------------------
 id  number  Unique tween ID 
 state  TweenState  Current state: "playing", "completed", "killed", etc. 
 progress  number  Current eased progress 0–1 
 pause   = TweenControls  Pause the tween 
 resume   = TweenControls  Resume a paused tween 
 kill   = TweenControls  Stop and release to pool 
 restart   = TweenControls  Restart from the beginning 
 seekprogress  number = TweenControls  Seek to a progress value 0–1 
 setSpeedmultiplier  number = TweenControls  Set playback speed 
 chainconfig  TweenConfig = TweenControls  Chain a tween to play after completion 
 finished  Promise<void  Resolves when the tween completes or is killed 
All control methods return the same TweenControls for chaining:
---
 Number Tweening
Interpolate a single number without needing a target object. Useful for scores, timers, opacity, and any custom value.
 Field  Type  Default  Description 
-----------------------------------
 from  number  —  Required. Start value 
 to  number  —  Required. End value 
 duration  number  0.3  Duration in seconds 
 ease  EasingInput  "quad.out"  Easing function 
 onUpdate  value: number, progress: number = void  —  Called every frame with the current interpolated value 
All other fields are the same as TweenConfig delay, repeat, yoyo, speed, etc..
---
 Timelines
Sequence multiple tweens with precise timing control. Inspired by GSAP's timeline API.
 Basic Sequence
By default, each tween starts after the previous one finishes.
 Overlapping Tweens
 Parallel Tweens
 Labels
 Callbacks
 Position Syntax
 Syntax  Meaning 
-----------------
 omitted  After previous entry ends 
 0.5  At absolute time 0.5s 
 "+=0.5"  0.5s after the previous entry ends 
 "-=0.3"  0.3s before the previous entry ends overlap 
 "<"  At the same time the previous entry starts 
 "<+=0.5"  0.5s after the previous entry starts 
 "label"  At the time of a named label 
 "label+=0.3"  0.3s after a named label 
 TimelineControls
 Property  Type  Description 
-----------------------------
 id  number  Unique timeline ID 
 state  TweenState  Current state 
 progress  number  Overall progress 0–1 
 duration  number  Total timeline duration in seconds 
 addconfig, position?  Adds a tween at a position  Returns self for chaining 
 addCallbackfn, position?  Adds a callback at a position  Returns self for chaining 
 addLabelname, position?  Adds a named label  Returns self for chaining 
 play  Start playing  Returns self 
 pause  Pause  Returns self 
 resume  Resume  Returns self 
 kill  Stop and clean up  Returns self 
 restart  Restart from beginning  Returns self 
 seektimeOrLabel  Seek to a time seconds or label name  Returns self 
 setSpeedmultiplier  Set playback speed  Returns self 
 finished  Promise<void  Resolves on completion 
---
 Easing Functions
33 Robert Penner easing presets plus spring. Pass as a string to the ease option.
 Presets
 Preset  Typical Use 
---------------------
 "linear"  Constant speed timers, progress bars 
 "quad.out"  Default. Smooth deceleration UI slide-in 
 "quad.in"  Accelerating start projectile launch 
 "cubic.inOut"  Smooth start/stop camera pan 
 "quart.out"  Snappy deceleration menu open 
 "sine.inOut"  Gentle oscillation breathing effect 
 "expo.out"  Sharp snap to end impact response 
 "elastic.out"  Spring overshoot UI popup 
 "back.out"  Overshoot and settle button press 
 "back.in"  Pull-back before action jump windup 
 "bounce.out"  Bouncing ball landing, drop 
 "spring"  Damped spring natural bounce 
Every equation comes in three variants: .in accelerating, .out decelerating, .inOut both.
 Custom Easing
---
 Repeat & Yoyo
---
 Chaining
Chain tweens to play in sequence:
---
 Promise-based Completion
The .finished property returns a Promise that resolves when the tween completes:
---
 Pause-Immune Tweens
Tweens pause automatically when the game phase is "paused" or "gameover". To keep a tween running during pause e.g., pause menu animations:
---
 Cleanup
All tweens created via useTween are automatically killed when the component unmounts. No manual cleanup needed for typical usage. For explicit control:
---
 Game Phase Integration
Tweens automatically respect the game phase:
 Phase  Behavior 
-----------------
 "loading"  All tweens frozen including ignorePause: true 
 "playing"  All tweens update normally 
 "paused"  Normal tweens freeze. ignorePause: true tweens continue 
 "gameover"  Same as paused 
---
 Type Definitions
See Types../types/index.md for EasingFn, EasingPreset, EasingInput, TweenState, TweenDirection, TweenConfig, NumberTweenConfig, TweenControls, TweenGroupControls, TimelineConfig, TimelineControls, TimelinePosition, and UseTweenReturn.

---
### Hooks > useParticles
URL: https://docs.carverjs.dev/hooks/use-particles.html

useParticles
useParticles creates and controls a particle emitter for visual effects like fire, smoke, explosions, and more. It reads from the ParticleManager../systems/particle-manager.md which is automatically set up by Game../components/game.md.
:::note
Particles use GPU-instanced rendering via InstancedMesh. Each emitter is a single draw call regardless of particle count.
:::
---
 Quick Start
---
 Return Value
 Property  Type  Description 
-----------------------------
 ref  RefObject<Object3D  Attach to a <group to position the emitter 
 burstcount?  number? = void  Emit a burst of particles default: 30 
 start   = void  Start continuous emission 
 stop   = void  Stop emission alive particles finish their lifetime 
 clear   = void  Stop emission and kill all particles immediately 
 setRaterate  number = void  Change emission rate stream mode 
 getActiveCount   = number  Current number of alive particles 
 isEmitting   = boolean  Whether the emitter is currently emitting 
 reset   = void  Reset to initial state 
---
 Options
useParticles accepts all ParticleEmitterConfig fields plus:
 Option  Type  Default  Description 
------------------------------------
 preset  ParticlePreset  —  Base preset: "fire", "smoke", "explosion", "sparks", "rain", "snow", "magic", "confetti". Individual props override preset values 
 enabled  boolean  true  Enable/disable the emitter 
---
 Emission Config
 Option  Type  Default  Description 
------------------------------------
 maxParticles  number  1000  Maximum alive particles at once 
 emission  "stream" \ "burst"  "stream"  Emission mode 
 rate  ValueRange  50  Particles per second stream mode 
 bursts  BurstConfig  —  Burst schedule burst mode 
 duration  number  Infinity  Emission duration. 0 = one-shot 
 loop  boolean  true  Loop after duration ends 
 startDelay  number  0  Delay before first emission seconds 
 autoPlay  boolean  true  Start emitting immediately 
---
 Emitter Shape
 Option  Type  Default  Description 
------------------------------------
 shape  EmitterShapeConfig  { shape: "point" }  Emission shape 
 Shapes
---
 Particle Properties
 Option  Type  Default  Description 
------------------------------------
 particle.speed  ValueRange  5  Initial speed 
 particle.lifetime  ValueRange  1  Lifetime in seconds 
 particle.size  ValueRange  1  Initial scale 
 particle.rotation  ValueRange  0  Initial rotation radians 
 particle.rotationSpeed  ValueRange  0  Rotation speed radians/sec 
 particle.color  ColorRange  "ffffff"  Initial color 
 particle.alpha  ValueRange  1  Initial opacity 
 particle.acceleration  x, y, z  0, 0, 0  Constant acceleration 
 particle.gravity  number  0  Downward gravity force 
 particle.drag  number  0  Linear drag 0 = none, 1 = full stop 
ValueRange can be a single number or min, max for randomization:
---
 Over-Lifetime Curves
Modify particle properties over their lifetime using keyframe curves. t is normalized 0 = birth, 1 = death.
---
 Rendering
 Option  Type  Default  Description 
------------------------------------
 blendMode  "normal" \ "additive" \ "multiply" \ "screen"  "normal"  Particle blend mode 
 texture  Texture \ string  —  Particle texture URL or Three.js Texture 
 spriteSheet  SpriteSheetConfig  —  Animated sprite sheet 
 billboard  boolean  true  Particles face the camera 
 space  "world" \ "local"  "world"  Coordinate space for simulation 
 sortByDistance  boolean  false  Sort back-to-front for transparency 
 Blend Modes
 Mode  Best For 
----------------
 "normal"  Smoke, confetti, solid particles 
 "additive"  Fire, sparks, magic, glow effects 
 "multiply"  Shadows, dark effects 
 "screen"  Bright overlays 
 Sprite Sheets
---
 Burst Mode
For one-shot effects like explosions:
 Burst Schedule
 Field  Type  Default  Description 
-----------------------------------
 time  number  0  Offset from emitter start seconds 
 count  ValueRange  —  Required. Particles to emit 
 cycles  number  1  Repeat count. 0 = infinite 
 interval  number  1  Delay between cycles seconds 
---
 Presets
8 built-in presets for common effects:
 Preset  Mode  Description 
---------------------------
 "fire"  stream  Ascending glow, orange to transparent, additive 
 "smoke"  stream  Slow rise, grey, expanding, normal blend 
 "explosion"  burst  Radial burst, quick fade, additive 
 "sparks"  burst  Fast bright particles with gravity 
 "rain"  stream  Vertical downpour, additive 
 "snow"  stream  Gentle falling, white, normal blend 
 "magic"  stream  Colorful sphere emission, additive 
 "confetti"  burst  Tumbling colored particles with gravity 
 Custom Presets
---
 World/Local Space
---
 Lifecycle Callbacks
---
 Full Example — Rocket Thruster
---
 Game Phase Integration
Particles automatically respect the game phase:
 Phase  Behavior 
-----------------
 "loading"  All emitters frozen 
 "playing"  Normal operation 
 "paused"  Emitters freeze — no emission, no updates 
 "gameover"  Same as paused 
---
 Cleanup
Emitters created via useParticles are automatically destroyed when the component unmounts. The GPU resources InstancedMesh, material, textures are disposed.
---
 Type Definitions
See Types../types/index.md for ParticleEmitterConfig, ParticlePreset, EmitterShapeConfig, ValueRange, ColorRange, LifetimeCurve, ColorGradient, BurstConfig, SpriteSheetConfig, ParticleBlendMode, OverLifetimeConfig, UseParticlesOptions, and UseParticlesReturn.

---
### Types > Types
URL: https://docs.carverjs.dev/types/index.html

Types
All types are importable from @carverjs/core/types.
 Game & World Types
 Type  Definition  Used by  Description 
---------------------------------------
 WorldMode  "2d" \ "3d"  Game  Scene mode 
 CameraProps2D  Partial<Omit<OrthographicCameraProps, "makeDefault"  World  Overrides for the 2D camera 
 CameraProps3D  Partial<Omit<PerspectiveCameraProps, "makeDefault"  World  Overrides for the 3D camera 
 SkyProps  Partial<drei.SkyProps  Game  Overrides for the Sky component 
 EnvironmentProps  Partial<drei.EnvironmentProps  Game  Overrides for the Environment component 
 OrbitControlsProps  Partial<drei.OrbitControlsProps  World  Overrides for OrbitControls 
 AmbientLightProps  Partial<ThreeElements"ambientLight"  Game  Overrides for ambient light 
 DirectionalLightProps  Partial<ThreeElements"directionalLight"  Game  Overrides for directional light 
 WorldPhysicsConfig  { gravity?, timestep?, interpolation?, debug? }  World  Physics configuration for a World 
 Actor Types
 ActorTransformProps
 Field  Type  Description 
--------------------------
 position  Vector3  World position — x, y, z or a Three.js Vector3 
 rotation  Euler  Rotation — x, y, z or a Three.js Euler 
 scale  Vector3  Scale — x, y, z, uniform number, or a Three.js Vector3. Overrides size 
 size  number  Uniform scale factor — scales all axes equally to preserve aspect ratio 
 ActorEventProps
All R3F pointer/interaction events on a <group:
onClick, onContextMenu, onDoubleClick, onPointerUp, onPointerDown, onPointerOver, onPointerOut, onPointerEnter, onPointerLeave, onPointerMove, onPointerMissed, onWheel
 PrimitiveShape
 PrimitiveMaterialType
 Camera Types
 Type  Definition  Description 
------------------------------
 CameraType  "perspective" \ "orthographic"  Camera projection type 
 CameraControlsType  "orbit" \ "map" \ "pointerlock" \ "none"  Controls mode 
 PerspectiveCameraProps  Partial<Omit<drei.PerspectiveCameraProps, "makeDefault"  Overrides for PerspectiveCamera 
 OrthographicCameraProps  Partial<Omit<drei.OrthographicCameraProps, "makeDefault"  Overrides for OrthographicCamera 
 MapControlsProps  Partial<drei.MapControlsProps  Overrides for MapControls 
 PointerLockControlsProps  Partial<drei.PointerLockControlsProps  Overrides for PointerLockControls 
 CameraFollowConfig
 Field  Type  Default  Description 
-----------------------------------
 target  RefObject<Object3D  —  Ref to the Object3D to follow 
 offset  number, number, number  0, 5, 10  Position offset from the target 
 smoothing  number  0.1  Lerp factor 0–1 
 lookAt  boolean  true  Whether the camera looks at the target 
 lookAtOffset  number, number, number  0, 0, 0  Offset for the look-at point 
 UseCameraOptions
 Field  Type  Description 
--------------------------
 follow  CameraFollowConfig  Follow configuration 
 UseCameraReturn
 Field  Type  Description 
--------------------------
 shake  intensity?: number, duration?: number = void  Trigger camera shake 
 moveTo  position: number, number, number, duration?: number = void  Smooth transition to a position 
 lookAt  target: number, number, number = void  Look at a world position 
 Game Loop Types
 Type  Definition  Description 
------------------------------
 GameLoopStage  "earlyUpdate" \ "fixedUpdate" \ "update" \ "lateUpdate"  Update stage for a game loop callback 
 GamePhase  "loading" \ "playing" \ "paused" \ "gameover"  Global game phase 
 GameLoopCallback  delta: number, elapsed: number = void  Per-frame callback signature 
 UseGameLoopOptions
 Field  Type  Default  Description 
-----------------------------------
 stage  GameLoopStage  "update"  Update stage 
 fixedTimestep  boolean  false  Fixed-timestep mode 
 fixedDelta  number  1/60  Seconds per fixed tick 
 maxDelta  number  0.1  Max raw delta cap 
 enabled  boolean  true  Whether this instance is active 
 UseGameLoopReturn
 Field  Type  Description 
--------------------------
 phase  GamePhase  Current game phase 
 isPaused  boolean  True when phase is paused or gameover 
 elapsed  number  Total elapsed seconds while playing 
 Input Types
 KeyState
 Field  Type  Description 
--------------------------
 pressed  boolean  Key is currently held down 
 justPressed  boolean  Key was first pressed this frame 
 justReleased  boolean  Key was released this frame 
 PointerState
 Field  Type  Description 
--------------------------
 position  { x: number, y: number }  Screen-space position in pixels 
 isDown  boolean  Primary pointer button is held 
 justDown  boolean  Button was pressed this frame 
 justUp  boolean  Button was released this frame 
 ActionMap
Maps logical action names to arrays of KeyboardEvent.code values.
 UseInputOptions
 Field  Type  Default  Description 
-----------------------------------
 keys  string  —  Subscribe to specific key codes only 
 actions  ActionMap  {}  Logical action map 
 enabled  boolean  true  Toggle this hook on/off 
 UseInputReturn
 Field  Type  Description 
--------------------------
 isPressed  code: string = boolean  Key is currently held 
 isJustPressed  code: string = boolean  Key was pressed this frame 
 isJustReleased  code: string = boolean  Key was released this frame 
 isAction  action: string = boolean  Any bound key for the action is held 
 isActionJustPressed  action: string = boolean  Any bound key for the action was just pressed 
 getAxis  neg: string, pos: string = number  Returns -1, 0, or 1 
 pointer  PointerState  Live pointer state 
 Collision Types Built-in
 ColliderShape
 ColliderDef
 AABBColliderDef
 Field  Type  Description 
--------------------------
 shape  "aabb"  Shape discriminator 
 halfExtents  number, number, number  Half-width, half-height, half-depth 
 offset  number, number, number  Offset from Actor position. Default: 0, 0, 0 
 SphereColliderDef
 Field  Type  Description 
--------------------------
 shape  "sphere"  Shape discriminator 
 radius  number  Sphere radius 
 offset  number, number, number  Offset from Actor position. Default: 0, 0, 0 
 CircleColliderDef
 Field  Type  Description 
--------------------------
 shape  "circle"  Shape discriminator 
 radius  number  Circle radius 
 offset  number, number, number  Offset from Actor position. Default: 0, 0, 0 
 CollisionEvent
 Field  Type  Description 
--------------------------
 otherName  string  Name of the other collider 
 otherUserData  Record<string, unknown  The other collider's userData 
 otherRef  RefObject<Object3D  The other collider's Object3D ref 
 isSensor  boolean  Whether the other collider is a sensor 
 CollisionCallback
 UseCollisionOptions
 Field  Type  Default  Description 
-----------------------------------
 ref  RefObject<Object3D  —  Required. Actor group ref 
 collider  ColliderDef  —  Required. Collider shape 
 name  string  ""  Identifier in collision events 
 userData  Record<string, unknown  {}  Passed through to events 
 layer  number  0xFFFFFFFF  Collision layer bitmask 
 mask  number  0xFFFFFFFF  Layers to check against 
 sensor  boolean  false  Trigger mode 
 onCollisionEnter  CollisionCallback  —  First frame of overlap 
 onCollisionExit  CollisionCallback  —  Last frame of overlap 
 onCollisionStay  CollisionCallback  —  Every frame while overlapping 
 enabled  boolean  true  Toggle on/off 
 UseCollisionReturn
 Field  Type  Description 
--------------------------
 isOverlapping  name: string = boolean  Check overlap with a named collider 
 getOverlaps   = string  Get all current overlap names 
 Grid Collision Types
 GridCollisionConfig
 Field  Type  Default  Description 
-----------------------------------
 width  number  —  Required. Cells along X 
 height  number  —  Required. Cells along Y 
 cellSize  number  1  World-space cell size 
 origin  number, number  0, 0  World-space origin offset 
 GridCellCallback
 UseGridCollisionOptions
 Field  Type  Description 
--------------------------
 config  GridCollisionConfig  Required. Grid configuration 
 UseGridCollisionReturn
 Field  Type  Description 
--------------------------
 setCell  x, y, value = void  Set cell value 0 = empty 
 getCell  x, y = number  Get cell value 
 clearCell  x, y = void  Clear a cell 
 isCellOccupied  x, y = boolean  Check if cell is non-zero 
 worldToGrid  wx, wy = number, number  World to grid coords 
 gridToWorld  gx, gy = number, number  Grid to world coords cell center 
 getNeighbors4  x, y = number, number, number, number  Cardinal neighbors up, right, down, left 
 getNeighbors8  x, y = number  8 neighbors cardinal + diagonal 
 clearAll   = void  Clear entire grid 
 Physics Types Rapier-backed
 RigidBodyType
 PhysicsColliderType
 WorldPhysicsConfig
 Field  Type  Default  Description 
-----------------------------------
 gravity  number, number, number  0, -9.81, 0  Gravity vector 
 timestep  number \ "vary"  1/60  Physics timestep 
 interpolation  boolean  true  Smooth rendering between steps 
 debug  boolean  false  Show wireframe colliders 
 ActorPhysicsProps
 Field  Type  Default  Description 
-----------------------------------
 bodyType  RigidBodyType  "dynamic"  Rigid body type 
 collider  PhysicsColliderType  "auto"  Collider shape 
 mass  number  1  Mass 
 restitution  number  0  Bounciness 0-1 
 friction  number  0.5  Friction coefficient 
 sensor  boolean  false  Trigger volume 
 gravityScale  number  1  Per-body gravity multiplier 
 linearDamping  number  0  Linear damping 
 angularDamping  number  0  Angular damping 
 ccd  boolean  false  Continuous collision detection 
 enabledTranslations  boolean, boolean, boolean  —  Lock/unlock per-axis translation 
 enabledRotations  boolean, boolean, boolean  —  Lock/unlock per-axis rotation 
 onCollisionEnter  CollisionCallback  —  Collision start callback 
 onCollisionExit  CollisionCallback  —  Collision end callback 
 UsePhysicsReturn
 Field  Type  Description 
--------------------------
 applyImpulse  number, number, number = void  Instantaneous force 
 applyForce  number, number, number = void  Continuous force 
 setLinearVelocity  number, number, number = void  Set linear velocity 
 getLinearVelocity   = number, number, number  Get linear velocity 
 setAngularVelocity  number, number, number = void  Set angular velocity 
 setTranslation  number, number, number = void  Teleport body 
 getTranslation   = number, number, number  Get position 
 setRotation  number, number, number, number = void  Set rotation quaternion 
 setEnabled  boolean = void  Enable/disable body 
 Audio Types
 AudioChannel
 AudioFormat
 SoundState
 AudioSpriteRegion
 Field  Type  Default  Description 
-----------------------------------
 start  number  —  Start offset in seconds 
 duration  number  —  Duration in seconds 
 loop  boolean  false  Loop this region 
 AudioSpriteMap
 SoundDefinition
 Field  Type  Default  Description 
-----------------------------------
 src  string \ string  —  Required. Audio URLs 
 channel  AudioChannel  "sfx"  Volume channel 
 volume  number  1  Base volume 0–1 
 rate  number  1  Playback rate 
 loop  boolean  false  Loop playback 
 maxInstances  number  5  Max simultaneous instances 
 preload  boolean  true  Preload on registration 
 sprites  AudioSpriteMap  —  Audio sprite regions 
 cooldown  number  —  Min seconds between plays 
 SpatialAudioOptions
 Field  Type  Default  Description 
-----------------------------------
 ref  RefObject<Object3D  —  Required. Emitter Object3D 
 panningModel  "HRTF" \ "equalpower"  "HRTF"  Panning algorithm 
 distanceModel  "linear" \ "inverse" \ "exponential"  "inverse"  Volume rolloff model 
 refDistance  number  1  Full-volume distance 
 maxDistance  number  100  Max audible distance 
 rolloffFactor  number  1  Rolloff speed 
 coneInnerAngle  number  360  Full-volume cone degrees 
 coneOuterAngle  number  360  Outer cone degrees 
 coneOuterGain  number  0  Volume outside outer cone 
 trackPosition  boolean  true  Auto-update position each frame 
 PlaySoundOptions
 Field  Type  Default  Description 
-----------------------------------
 volume  number  —  Override volume 
 rate  number  —  Override rate 
 loop  boolean  —  Override loop 
 sprite  string  —  Named sprite region 
 spatial  SpatialAudioOptions  —  3D spatial configuration 
 fadeIn  number  0  Fade-in duration seconds 
 delay  number  0  Delay before playback seconds 
 onEnd   = void  —  Called when playback finishes 
 onError  Error = void  —  Called on failure 
 SoundHandle
 Field  Type  Description 
--------------------------
 id  number  Unique instance ID 
 state  SoundState  Current state 
 stop   = void  Stop the instance 
 pause   = void  Pause the instance 
 resume   = void  Resume the instance 
 fade  from, to, duration = void  Fade volume 
 setVolume  number = void  Set volume 
 setRate  number = void  Set playback rate 
 CrossfadeOptions
 Field  Type  Default  Description 
-----------------------------------
 duration  number  2  Crossfade duration in seconds 
 MusicOptions
 Field  Type  Default  Description 
-----------------------------------
 volume  number  1  Music volume 0–1 
 loop  boolean  true  Loop the track 
 crossfade  CrossfadeOptions  —  Crossfade settings 
 UseAudioOptions
 Field  Type  Default  Description 
-----------------------------------
 sounds  SoundMap  {}  Sound definitions to register 
 enabled  boolean  true  Toggle audio on/off 
 UseAudioReturn
 Field  Type  Description 
--------------------------
 play  name, options? = SoundHandle \ null  Play a registered sound 
 stop  name = void  Stop all instances of a sound 
 pause  name = void  Pause instances 
 resume  name = void  Resume instances 
 isPlaying  name = boolean  Check if playing 
 playMusic  src, options? = void  Play music with crossfade 
 stopMusic  fadeOut? = void  Stop music 
 pauseMusic   = void  Pause music 
 resumeMusic   = void  Resume music 
 isMusicPlaying   = boolean  Check if music is playing 
 setVolume  channel, volume = void  Set channel volume 
 getVolume  channel = number  Get channel volume 
 setMute  channel, muted = void  Mute/unmute channel 
 isMuted  channel = boolean  Check mute state 
 setMasterMute  muted = void  Mute/unmute all 
 preload  name = Promise<void  Preload a sound 
 preloadAll  names = Promise<void  Preload multiple sounds 
 isUnlocked  boolean  AudioContext unlocked 
 isReady  boolean  Audio system ready 
 AudioListenerConfig
 Field  Type  Description 
--------------------------
 listenerRef  RefObject<Object3D  Custom listener source. Defaults to active camera 
 Asset Types
 AssetType
 AssetEntry
 Field  Type  Default  Description 
-----------------------------------
 url  string  —  Required. URL to load 
 key  string  url  Unique key for cache lookup 
 type  AssetType  Auto-detected  Asset type override 
 priority  "critical" \ "high" \ "normal" \ "low" \ "lazy" \ number  "normal"  Loading priority 
 group  string  —  Group name for batch operations 
 sizeHint  number  —  Expected file size in bytes 
 loaderOptions  Record<string, unknown  —  Loader-specific options 
 AssetManifest
 Field  Type  Default  Description 
-----------------------------------
 version  1  —  Schema version 
 baseUrl  string  ""  Base URL for relative asset paths 
 assets  AssetEntry  —  Required. Array of asset entries 
 groups  Record<string, AssetGroupConfig  —  Group configuration 
 AssetGroupConfig
 Field  Type  Default  Description 
-----------------------------------
 label  string  —  Human-readable label 
 preload  boolean  true  Preload this group upfront 
 exclusive  boolean  false  Auto-unload when another exclusive group loads 
 LoadingProgress
 Field  Type  Description 
--------------------------
 phase  "idle" \ "loading" \ "complete" \ "error"  Current loading phase 
 loaded  number  Assets finished loading 
 total  number  Total assets to load 
 progress  number  Fraction complete 0 to 1 
 currentAsset  string \ null  Asset currently loading 
 currentGroup  string \ null  Group currently loading 
 errors  AssetLoadError  Errors encountered 
 AssetLoadError
 Field  Type  Description 
--------------------------
 key  string  Asset key that failed 
 url  string  Asset URL that failed 
 message  string  Error message 
 retries  number  Retry attempts made 
 recoverable  boolean  Whether the error is recoverable 
 CacheEntry
 Field  Type  Description 
--------------------------
 data  T  The cached asset data 
 key  string  Cache key 
 type  AssetType  Asset type 
 sizeBytes  number  Estimated size in bytes 
 lastAccessedAt  number  Timestamp of last access 
 refCount  number  Active references prevents eviction 
 Tween Types
 EasingFn
Normalized easing function: takes t in 0, 1, returns eased value.
 EasingPreset
 EasingInput
Accepts a preset name, a custom function, or a cubic-bezier control point tuple.
 TweenState
 TweenDirection
 TweenConfig<T
 Field  Type  Default  Description 
-----------------------------------
 target  T extends object  —  Required. Object to animate 
 to  Record<string, number  —  Required. End values supports dot-notation 
 from  Record<string, number  —  Start values. If omitted, current values are captured 
 duration  number  0.3  Duration in seconds 
 ease  EasingInput  "quad.out"  Easing function or preset 
 delay  number  0  Delay before starting seconds 
 repeat  number  0  Additional repeats. -1 = infinite 
 repeatDelay  number  0  Delay between repeats seconds 
 yoyo  boolean  false  Reverse on each repeat 
 speed  number  1  Playback speed multiplier 
 group  string  ""  Named group for batch control 
 persist  boolean  false  Keep alive after completion 
 ignorePause  boolean  false  Continue when game is paused 
 onStart   = void  —  Start callback 
 onUpdate  progress: number = void  —  Per-frame callback with eased progress 
 onComplete   = void  —  Completion callback 
 onRepeat  count: number = void  —  Repeat callback 
 onYoyo  direction: TweenDirection = void  —  Direction reversal callback 
 onKill   = void  —  Kill callback 
 NumberTweenConfig
Same as TweenConfig except: no target/to/from fields. Instead has from: number and to: number. The onUpdate callback is value: number, progress: number = void.
 TweenControls
 Field  Type  Description 
--------------------------
 id  number  Unique tween ID 
 state  TweenState  Current state 
 progress  number  Eased progress 0–1 
 pause   = TweenControls  Pause the tween 
 resume   = TweenControls  Resume the tween 
 kill   = TweenControls  Stop and release 
 restart   = TweenControls  Restart from beginning 
 seekprogress  number = TweenControls  Seek to progress 0–1 
 setSpeedmultiplier  number = TweenControls  Set playback speed 
 chainconfig  TweenConfig = TweenControls  Chain a follow-up tween 
 finished  Promise<void  Resolves on completion 
 TweenGroupControls
 Field  Type  Description 
--------------------------
 pause   = void  Pause all tweens in the group 
 resume   = void  Resume all tweens in the group 
 kill   = void  Kill all tweens in the group 
 count  number  Active tween count in the group 
 TimelinePosition
A number is an absolute time in seconds. Strings support relative positioning: "+=0.5", "-=0.2", "<", "<+=0.5", "label", "label+=0.3".
 TimelineConfig
 Field  Type  Default  Description 
-----------------------------------
 repeat  number  0  Additional repeats. -1 = infinite 
 repeatDelay  number  0  Delay between repeats 
 yoyo  boolean  false  Reverse on each repeat 
 speed  number  1  Playback speed 
 paused  boolean  false  Start paused 
 ignorePause  boolean  false  Continue when game is paused 
 group  string  —  Named group 
 onStart   = void  —  Start callback 
 onUpdate  progress: number = void  —  Per-frame progress callback 
 onComplete   = void  —  Completion callback 
 onRepeat  count: number = void  —  Repeat callback 
 TimelineControls
 Field  Type  Description 
--------------------------
 id  number  Unique timeline ID 
 state  TweenState  Current state 
 progress  number  Overall progress 0–1 
 duration  number  Total duration in seconds 
 addconfig, position?  Adds a tween entry  Returns self 
 addCallbackfn, position?  Adds a callback entry  Returns self 
 addLabelname, position?  Adds a named label  Returns self 
 play  Start playing  Returns self 
 pause  Pause  Returns self 
 resume  Resume  Returns self 
 kill  Kill and clean up  Returns self 
 restart  Restart from beginning  Returns self 
 seektimeOrLabel  Seek to time or label  Returns self 
 setSpeedmultiplier  Set playback speed  Returns self 
 finished  Promise<void  Resolves on completion 
 UseTweenReturn
 Field  Type  Description 
--------------------------
 tween  <T extends objectTweenConfig<T = TweenControls  Create a property tween 
 tweenNumber  NumberTweenConfig = TweenControls  Create a number tween 
 timeline  TimelineConfig? = TimelineControls  Create a timeline 
 killAll   = void  Kill all hook-owned tweens 
 pauseAll   = void  Pause all active tweens 
 resumeAll   = void  Resume all paused tweens 
 Particle Types
 EmitterShape
 EmitterShapeConfig
 ValueRange
A single value or min, max range for per-particle randomization.
 ColorRange
A single color or startColor, endColor for random interpolation.
 CurveKeyframe
 Field  Type  Description 
--------------------------
 t  number  Normalized lifetime 0 = birth, 1 = death 
 value  number  Value at this point 
 LifetimeCurve
 ColorGradientStop
 Field  Type  Description 
--------------------------
 t  number  Normalized lifetime 0–1 
 color  ColorRepresentation  Color at this point 
 ColorGradient
 ParticleBlendMode
 ParticlePreset
 BurstConfig
 Field  Type  Default  Description 
-----------------------------------
 time  number  0  Time offset from emitter start seconds 
 count  ValueRange  —  Required. Particles to emit 
 cycles  number  1  Burst cycles. 0 = infinite 
 interval  number  1  Interval between cycles seconds 
 SpriteSheetConfig
 Field  Type  Default  Description 
-----------------------------------
 texture  Texture \ string  —  Required. Sprite sheet texture 
 columns  number  —  Required. Grid columns 
 rows  number  —  Required. Grid rows 
 totalFrames  number  columns  rows  Total frame count 
 fps  number  30  Animation speed 
 startFrame  number  0  Starting frame index 
 loop  boolean  true  Loop animation 
 randomStart  boolean  false  Randomize start frame per particle 
 ParticlePropertyConfig
 Field  Type  Default  Description 
-----------------------------------
 speed  ValueRange  5  Initial speed 
 lifetime  ValueRange  1  Lifetime in seconds 
 size  ValueRange  1  Initial scale 
 rotation  ValueRange  0  Initial rotation radians 
 rotationSpeed  ValueRange  0  Rotation speed radians/sec 
 color  ColorRange  "ffffff"  Initial color 
 alpha  ValueRange  1  Initial opacity 
 acceleration  number, number, number  0, 0, 0  Constant acceleration 
 gravity  number  0  Downward gravity force 
 drag  number  0  Linear drag 0–1 
 OverLifetimeConfig
 Field  Type  Description 
--------------------------
 size  LifetimeCurve  Size multiplier over lifetime 
 alpha  LifetimeCurve  Alpha multiplier over lifetime 
 color  ColorGradient  Color gradient over lifetime replaces initial color 
 rotationSpeed  LifetimeCurve  Rotation speed multiplier 
 speed  LifetimeCurve  Speed multiplier 
 ParticleEmitterConfig
 Field  Type  Default  Description 
-----------------------------------
 name  string  —  Unique name for lookups 
 maxParticles  number  1000  Max alive particles 
 emission  "stream" \ "burst"  "stream"  Emission mode 
 rate  ValueRange  50  Particles/sec stream mode 
 bursts  BurstConfig  —  Burst schedule 
 duration  number  Infinity  Emission duration 0 = one-shot 
 loop  boolean  true  Loop after duration 
 startDelay  number  0  Delay before first emission 
 shape  EmitterShapeConfig  { shape: "point" }  Emission shape 
 particle  ParticlePropertyConfig  —  Per-particle initial properties 
 overLifetime  OverLifetimeConfig  —  Over-lifetime modifiers 
 blendMode  ParticleBlendMode  "normal"  Blend mode 
 texture  Texture \ string  —  Particle texture 
 spriteSheet  SpriteSheetConfig  —  Sprite sheet config 
 billboard  boolean  true  Particles face camera 
 space  "world" \ "local"  "world"  Simulation space 
 sortByDistance  boolean  false  Sort for transparency 
 autoPlay  boolean  true  Auto-start 
 onParticleBorn  index: number = void  —  Birth callback 
 onParticleDeath  index: number = void  —  Death callback 
 onComplete   = void  —  All particles died after emission stopped 
 UseParticlesOptions
Extends ParticleEmitterConfig with:
 Field  Type  Default  Description 
-----------------------------------
 preset  ParticlePreset  —  Base preset to merge with 
 enabled  boolean  true  Enable/disable emitter 
 UseParticlesReturn
 Field  Type  Description 
--------------------------
 ref  RefObject<Object3D  Attach to a <group for positioning 
 burstcount?  number? = void  Emit a burst 
 start   = void  Start continuous emission 
 stop   = void  Stop emission 
 clear   = void  Stop and kill all particles 
 setRaterate  number = void  Change stream rate 
 getActiveCount   = number  Alive particle count 
 isEmitting   = boolean  Whether currently emitting 
 reset   = void  Reset to initial state 
 ParticleEmitterProps
Extends ParticleEmitterConfig with:
 Field  Type  Default  Description 
-----------------------------------
 preset  ParticlePreset  —  Base preset to merge with 
 position  Vector3  0, 0, 0  Emitter position 
 rotation  Euler  —  Emitter rotation 
 enabled  boolean  true  Enable/disable emitter 
 Hook Types
Importable from @carverjs/core/hooks:
 Type  Description 
-------------------
 UseAnimationOptions  Options for useAnimation — clipName, paused, speed, loop 
 UseAnimationReturn  Return value of useAnimation — ref, clipNames, activeAction, mixer, actions, play, stopAll, crossFadeTo 
 UseCameraOptions  Options for useCamera — follow 
 UseCameraReturn  Return value of useCamera — shake, moveTo, lookAt 
 UseGameLoopOptions  Options for useGameLoop — stage, fixedTimestep, fixedDelta, maxDelta, enabled 
 UseGameLoopReturn  Return value of useGameLoop — phase, isPaused, elapsed 
 GameLoopCallback  Callback type for useGameLoop 
 GameLoopStage  Stage enum: earlyUpdate, fixedUpdate, update, lateUpdate 
 GamePhase  Phase enum: loading, playing, paused, gameover 
 UseInputOptions  Options for useInput — keys, actions, enabled 
 UseInputReturn  Return value of useInput — isPressed, isJustPressed, isJustReleased, isAction, isActionJustPressed, getAxis, pointer 
 KeyState  Key state: pressed, justPressed, justReleased 
 PointerState  Pointer state: position, isDown, justDown, justUp 
 ActionMap  Maps action names to key code arrays 
 UseCollisionOptions  Options for useCollision — ref, collider, name, layer, mask, callbacks 
 UseCollisionReturn  Return value of useCollision — isOverlapping, getOverlaps 
 ColliderDef  Collider shape definition: AABBColliderDef \ SphereColliderDef \ CircleColliderDef 
 CollisionEvent  Collision event data: otherName, otherUserData, otherRef, isSensor 
 CollisionCallback  Callback type for collision events 
 UseGridCollisionOptions  Options for useGridCollision — config 
 UseGridCollisionReturn  Return value of useGridCollision — setCell, getCell, isCellOccupied, etc. 
 GridCollisionConfig  Grid configuration: width, height, cellSize, origin 
 UsePhysicsReturn  Return value of usePhysics — applyImpulse, setLinearVelocity, setTranslation, etc. 
 UseAudioOptions  Options for useAudio — sounds, enabled 
 UseAudioReturn  Return value of useAudio — play, stop, playMusic, setVolume, isUnlocked, etc. 
 SoundDefinition  Sound config: src, channel, volume, rate, loop, maxInstances, preload, sprites, cooldown 
 SoundMap  Maps sound names to SoundDefinition objects 
 PlaySoundOptions  Per-play overrides: volume, rate, loop, sprite, spatial, fadeIn, delay, onEnd 
 SoundHandle  Handle returned by play — id, state, stop, pause, resume, fade, setVolume, setRate 
 SoundState  Playback state: "playing", "paused", "stopped" 
 AudioChannel  Volume channels: "master", "sfx", "music", "ui", "ambient", "voice" 
 SpatialAudioOptions  3D audio config: ref, panningModel, distanceModel, refDistance, maxDistance 
 MusicOptions  Music config: volume, loop, crossfade 
 CrossfadeOptions  Crossfade config: duration 
 AudioSpriteRegion  Sprite region: start, duration, loop 
 AudioSpriteMap  Maps sprite names to AudioSpriteRegion objects 
 AudioListenerConfig  Listener override: listenerRef 
 AssetType  Asset categories: "gltf", "texture", "audio", "json", "binary" 
 AssetEntry  Single asset definition: url, key, type, priority, group, sizeHint, loaderOptions 
 AssetManifest  Complete manifest: version, baseUrl, assets, groups 
 AssetGroupConfig  Group config: label, preload, exclusive 
 LoadingProgress  Loading state: phase, loaded, total, progress, currentAsset, errors 
 AssetLoadError  Error info: key, url, message, retries, recoverable 
 EasingFn  Easing function signature: t: number = number 
 EasingPreset  Named easing presets: "linear", "quad.out", "bounce.in", "spring", etc. 
 EasingInput  Easing input: EasingPreset \ EasingFn \ number, number, number, number 
 TweenState  Tween lifecycle state: "idle", "pending", "delayed", "playing", "completed", "killed" 
 TweenDirection  Tween direction: "forward", "reverse" 
 TweenConfig  Tween config: target, to, from, duration, ease, delay, repeat, yoyo, speed, callbacks 
 NumberTweenConfig  Number tween config: from, to, duration, ease, onUpdatevalue, progress 
 TweenControls  Tween handle: id, state, progress, pause, resume, kill, restart, seek, chain, finished 
 TweenGroupControls  Group controls: pause, resume, kill, count 
 TimelineConfig  Timeline config: repeat, yoyo, speed, paused, ignorePause, callbacks 
 TimelineControls  Timeline handle: add, addCallback, addLabel, play, pause, kill, seek, finished 
 TimelinePosition  Position: number \ string supports "+=0.5", "-=0.2", "<", "label" 
 UseTweenReturn  Return value of useTween — tween, tweenNumber, timeline, killAll, pauseAll, resumeAll 
 UseParticlesOptions  Options for useParticles — extends ParticleEmitterConfig with preset, enabled 
 UseParticlesReturn  Return value of useParticles — ref, burst, start, stop, clear, setRate, getActiveCount, isEmitting, reset 
 ParticleEmitterConfig  Full emitter config: maxParticles, emission, rate, shape, particle, overLifetime, blendMode, texture, billboard, space, callbacks 
 ParticlePreset  Preset names: "fire", "smoke", "explosion", "sparks", "rain", "snow", "magic", "confetti" 
 EmitterShapeConfig  Shape config: PointShapeConfig \ ConeShapeConfig \ SphereShapeConfig \ RectangleShapeConfig \ EdgeShapeConfig \ RingShapeConfig 
 ValueRange  Randomizable value: number \ number, number 
 ColorRange  Randomizable color: ColorRepresentation \ ColorRepresentation, ColorRepresentation 
 LifetimeCurve  Over-lifetime keyframes: CurveKeyframe 
 ColorGradient  Over-lifetime color: ColorGradientStop 
 BurstConfig  Burst schedule entry: time, count, cycles, interval 
 SpriteSheetConfig  Sprite sheet config: texture, columns, rows, fps, loop, randomStart 
 ParticleBlendMode  Blend modes: "normal", "additive", "multiply", "screen" 
 OverLifetimeConfig  Over-lifetime curves: size, alpha, color, rotationSpeed, speed 
 ParticlePropertyConfig  Per-particle init: speed, lifetime, size, rotation, color, alpha, acceleration, gravity, drag 
 Component Prop Types
Importable from @carverjs/core/components:
 Type  Description 
-------------------
 GameProps  Props for the Game component 
 WorldProps  Props for the World component 
 ActorProps  Union type: ModelActorProps \ SpriteActorProps \ PrimitiveActorProps 
 ModelActorProps  Props for <Actor type="model" 
 SpriteActorProps  Props for <Actor type="sprite" 
 PrimitiveActorProps  Props for <Actor type="primitive" 
 CameraProps  Props for the Camera component 
 ActorPhysicsProps  Physics configuration for an Actor 
 WorldPhysicsConfig  Physics configuration for a World 
 AudioListenerConfig  Props for the AudioListener component 
 AssetLoaderProps  Props for the AssetLoader component 
 LoadingScreenProps  Props for the LoadingScreen component 
 ParticleEmitterProps  Props for the ParticleEmitter component — extends ParticleEmitterConfig with preset, position, rotation, enabled

---
### Multiplayer > Getting Started with Multiplayer
URL: https://docs.carverjs.dev/multiplayer/getting-started.html

Getting Started with Multiplayer
CarverJS Multiplayer adds peer-to-peer networking to any CarverJS game. One player acts as the host, relaying state to all connected clients. Add a provider, mark actors as networked, and you have a multiplayer game.
---
 Installation
:::note Peer Dependencies
@carverjs/multiplayer requires @carverjs/core and react as peer dependencies. If you already have a CarverJS game running, you're all set. For Firebase signaling, also install firebase.
:::
---
 Setup
Wrap your scene with <MultiplayerProvider inside your <Game. Pass a unique appId to namespace your rooms on the signaling network.
 Prop  Type  Default  Description 
----------------------------------
 appId  string  --  Required. Unique app identifier. Namespaces rooms across the signaling network. 
 strategy  StrategyConfig  { type: 'mqtt' }  Signaling strategy. MQTT free, zero config or Firebase RTDB. 
 iceServers  RTCIceServer  Google/Cloudflare STUN  Custom STUN/TURN servers for WebRTC. 
 children  ReactNode  --  Scene content Worlds, Actors, etc. 
 Signaling Strategies
CarverJS multiplayer is serverless -- peer discovery and WebRTC handshakes happen through existing networks, not a custom server. You bring your own infrastructure:
- MQTT default -- Free, zero config. Uses public MQTT brokers. Good for prototyping and small games.
- Firebase RTDB -- Bring your own Firebase project. More reliable for production. Set up a Firebase Realtime Databasehttps://console.firebase.google.com, enable test-mode rules, and pass the URL.
- TURN server optional -- Only needed when peers are behind restrictive NAT/firewalls. Cloudflare TURNhttps://developers.cloudflare.com/calls/turn/ or any TURN provider. For same-network testing, STUN alone is sufficient.
---
 Quick Start
Below is a minimal multiplayer game with a lobby screen and a networked scene. Players join a room, and once the host starts the game, everyone sees a shared world with networked actors.
---
 How It Works
 P2P Host-Client Model
CarverJS multiplayer uses a peer-to-peer architecture where one player is the host and all others are clients. The host runs the authoritative game state and relays it to clients. There is no dedicated server -- the host is the server.
Peer discovery happens through a signaling strategy MQTT brokers or Firebase RTDB. After peers find each other, all game data flows directly peer-to-peer over WebRTC data channels. The signaling network is only used for the initial handshake.
 Three Sync Modes
CarverJS provides three layers of synchronization, each suited to a different type of game:
 Mode  Layer  Best For 
-----------------------
 Events  1  Turn-based games, chat, infrequent updates 
 Snapshot  2  RPGs, casual games, moderate update frequency 
 Prediction  3  FPS, racing, competitive games requiring low-latency feel 
You choose the mode per actor via the networked prop. Different actors in the same game can use different modes.
 Host Election
Host assignment is deterministic and serverless: peers are sorted by their ID, and the lowest ID becomes host. If the host disconnects, the next peer automatically takes over. State is preserved through the migration -- clients experience a brief pause the "migrating" connection state and then resume under the new host.
---
 Migrating from Single-Player
Already have a working CarverJS game? You can add multiplayer in four steps.
 Step 1 -- Add MultiplayerProvider
Wrap your existing scene with <MultiplayerProvider. You can place it inside or outside <Game:
:::info Why MultiplayerBridge?
R3F's <Canvas used by <Game creates a separate React reconciler. React contexts from the parent tree are not automatically available inside it. <MultiplayerBridge re-provides the multiplayer context inside the Canvas. See MultiplayerBridge./multiplayer-bridge.md for details.
:::
 Step 2 -- Mark actors as networked
Add the networked prop to any <Actor whose state should be shared across players:
Actors without networked remain local -- they render on each client independently great for particles, UI elements, and static scenery.
 Step 3 -- Add useMultiplayer hook
Use useMultiplayer in a component to control the connection lifecycle:
 Step 4 -- Add a lobby UI
Add useLobby and useRoom to build a room browser so players can find each other:
:::tip
You can add multiplayer incrementally. Start by networking just one actor the player and expand from there. Actors without the networked prop are completely unaffected.
:::
---
 What's Next
- Core Concepts./core-concepts.md -- deep dive into host/client architecture, sync modes, actor ownership, and connection states.

---
### Multiplayer > Core Concepts
URL: https://docs.carverjs.dev/multiplayer/core-concepts.html

Core Concepts
This page covers the fundamental building blocks of CarverJS multiplayer: the host-client model, the networked prop, actor ownership, connection states, sync modes, and how multiplayer integrates with the game loop.
---
 Host vs Client
CarverJS multiplayer uses a peer-to-peer host-client model. There is no dedicated game server — one player acts as the host and all others connect as clients.
 Role  Responsibility 
---------------------
 Host  Runs authoritative game state, resolves conflicts, relays snapshots to clients 
 Client  Sends inputs/requests to host, receives and applies state updates 
The first player to create a room becomes the host. When other players join, they connect directly to the host via WebRTC data channels.
:::note
Game logic runs on every peer, but only the host's state is authoritative. Clients that detect a mismatch reconcile to the host's version. This keeps the architecture simple while preventing desync.
:::
---
 The networked Prop
The networked prop on Actor../components/actor.md controls whether and how an actor's state is synchronized across peers. There are three usage patterns.
 Simple — networked={true}
The most common pattern. Syncs the actor's transform position, rotation, scale using the default sync mode snapshot. The host owns the actor.
Use when: You have a shared object a platform, a ball, an NPC that the host controls and all clients should see.
 Configured — networked={{ sync, owner }}
Full control over sync mode and ownership. Use this for player-controlled actors or physics objects that need specific synchronization behavior.
 Field  Type  Default  Description 
-----------------------------------
 sync  "events" \ "snapshot" \ "prediction" \ false  "snapshot"  Synchronization mode 
 owner  string  host peer ID  Peer ID of the player who controls this actor 
 priority  number  1  Update priority — higher values sync more frequently when bandwidth is limited 
 interpolate  boolean  true  Smooth incoming state updates on non-owner clients 
Use when: A specific player owns the actor their character, their vehicle or you need a particular sync mode.
 Registered but not synced — networked={{ sync: false }}
The actor is registered with the network system it gets a stable network ID but no automatic state synchronization occurs. You handle all updates manually via events.
Use when: You want to trigger discrete actions on the actor open a chest, toggle a switch via events rather than continuous state sync. This keeps bandwidth minimal.
 At a Glance
 Pattern  Sync  Owner  Typical Use 
-----------------------------------
 networked={true}  Snapshot default  Host  Shared objects, NPCs, world elements 
 networked={{ sync: "prediction", owner: id }}  Prediction  Specific player  Player characters, vehicles 
 networked={{ sync: "events" }}  Events  Host  Turn-based tokens, chat bubbles 
 networked={{ sync: false }}  Manual  —  Chests, doors, switches 
---
 Actor Ownership
Every networked actor has an owner — the peer who has authority to update it. Other peers receive the owner's updates and apply them.
 Default: Host-Owned
When you use networked={true} or omit the owner field, the host owns the actor. Only the host can move it; clients see a synchronized copy.
 Player-Owned
Assign ownership to a specific player by passing their peer ID:
The owner has full authority to update the actor's transform, physics state, and custom properties. Non-owners see interpolated updates.
 Ownership Transfer
Ownership can be transferred at runtime. A common pattern is picking up an item — ownership moves from the host to the player who grabbed it:
:::tip
Keep ownership assignments simple. A good rule of thumb: each player owns their character and any items they're holding. The host owns everything else.
:::
---
 Connection States
The multiplayer system follows a state machine. Use connectionState from useMultiplayer to drive your UI.
 State  Meaning  Recommended UI 
--------------------------------
 "disconnected"  Not connected to any room  Show lobby / main menu 
 "connecting"  Establishing WebRTC connection to host  Show loading spinner with "Connecting..." 
 "connected"  Fully connected, syncing state  Show the game 
 "migrating"  Host left, electing new host  Show brief overlay "Host migrating..." 
 "error"  Connection failed or lost unexpectedly  Show error message with retry button 
 Handling States in Your UI
:::note
During host migration, clients retain their local state. Once the new host is elected typically 1-2 seconds, it broadcasts a full snapshot and clients reconcile. No game data is lost.
:::
---
 Sync Modes
CarverJS provides three synchronization modes, layered by complexity and latency tolerance. Choose the mode that fits your game's needs — different actors in the same game can use different modes.
 Events Layer 1
State changes are sent as discrete messages. No continuous sync — updates happen only when something fires an event.
Best for: Turn-based games, card games, chat messages, infrequent interactions.
 Snapshot Layer 2
The host periodically sends a full or delta snapshot of each networked actor's state. Clients apply the snapshot and interpolate between updates for smooth visuals.
Snapshots are sent at the tickRate configured on <MultiplayerProvider default 20 Hz. The system automatically computes deltas — only changed properties are transmitted.
Best for: RPGs, casual multiplayer, cooperative games, strategy games.
 Prediction Layer 3
The owner applies inputs immediately client-side prediction and sends them to the host. The host validates and broadcasts the authoritative result. Non-owner clients interpolate toward the latest confirmed state. If a mismatch is detected, the owner rolls back and replays.
Best for: Fast-paced games where input latency must feel instant — FPS, racing, fighting, platformers.
 Decision Table
 Mode  Latency Feel  Bandwidth  Best For  Complexity 
----------------------------------------------------
 Events  N/A discrete  Very low  Turn-based, chat, menus  Low 
 Snapshot  Smooth interpolated  Moderate  RPG, casual, co-op  Medium 
 Prediction  Instant predicted  Higher  FPS, racing, competitive  High 
:::tip
Start with snapshot mode. It handles the majority of multiplayer games well. Only switch to prediction if players report noticeable input lag, and only use events for inherently discrete interactions.
:::
---
 The Game Loop Integration
Multiplayer hooks into the CarverJS game loop via R3F's useFrame at priority -55. This places the network tick between the InputFlush priority -50 and the lateUpdate stage priority -40.
 Frame Execution Order
 Priority  System  Description 
-------------------------------
 -5  GameLoopTick  Advances elapsed time and frame count 
 -10  earlyUpdate  Input gathering, flag resets 
 -20  fixedUpdate  Deterministic physics 
 -25  CollisionFlush  Collision detection 
 -30  update  General game logic 
 -40  lateUpdate  Camera follow, trailing effects 
 -50  InputFlush  Input system flush 
 -55  MultiplayerTick  Network send/receive, state reconciliation 
 0  R3F Render  Scene render 
 What Happens Each Network Tick
1. Receive — Incoming messages from peers are dequeued and applied.
2. Reconcile — For prediction-mode actors, mismatch detection and rollback occur.
3. Send — Outgoing state updates snapshots, events, or input frames are batched and transmitted.
This ordering ensures that game logic has finished updating before the network system captures and sends the current frame's state, and that incoming remote state is applied before the next frame's logic runs.
---
 What's Next
- Getting Started./getting-started.md — installation, setup, and a quick-start example.

---
### Multiplayer > Lobby & Room Management
URL: https://docs.carverjs.dev/multiplayer/lobby-and-rooms.html

Lobby & Room Management
CarverJS multiplayer ships four hooks that cover the entire lobby-to-gameplay lifecycle: discovering rooms, joining one, reading player state, and managing the session as a host.
---
 useLobby
useLobby subscribes to room announcements on the signaling network and returns a live list of available rooms. Use it to build a lobby screen where players can browse, filter, and create rooms.
 Options
 Option  Type  Default  Description 
------------------------------------
 autoRefresh  boolean  true  Automatically poll for room list updates 
 filter  LobbyFilter  —  Filter the room list on the server side 
 filter
 Field  Type  Description 
--------------------------
 maxPlayers  number  Only show rooms with this max player count 
 gameMode  string  Only show rooms matching this game mode 
 hasPassword  boolean  Only show rooms that are password-protected or not 
 Return Value
 Property  Type  Description 
-----------------------------
 rooms  Room  Live list of available rooms matching the current filter 
 createRoom  config: RoomConfig = Promise<Room  Create a new room and return it. The caller automatically becomes the host 
 refresh   = void  Manually trigger a room list refresh 
 isLoading  boolean  true while a fetch or create is in progress 
:::tip
When autoRefresh is enabled, the room list updates on a regular interval. Call refresh manually after a player action e.g. creating a room for an immediate update.
:::
---
 useRoom
useRoom manages the connection lifecycle for a single room. It handles joining, leaving, reconnection, transport selection, and host migration.
 Options
 Option  Type  Default  Description 
------------------------------------
 transport  CarverTransport  --  Supply a custom CarverTransport instance to bypass the built-in WebRTCTransport 
 password  string  --  Room password for private rooms 
 displayName  string  --  Display name shown to other players 
 playerMetadata  Record<string, unknown  --  Arbitrary metadata attached to this player avatar, team, etc. 
 iceServers  RTCIceServer  Provider defaults  Custom STUN/TURN servers for this room 
 hostMigration  boolean  true  Automatically elect a new host if the current host disconnects 
 reconnectAttempts  number  3  Number of automatic reconnection attempts on disconnect 
 privacy  'all' \ 'relay'  'all'  Set to 'relay' to force TURN relay hides player IPs 
 onConnected   = void  --  Callback fired when the connection is established 
 onDisconnected  reason: string = void  --  Callback fired when the connection is lost 
 onHostMigration  newHostId: string = void  --  Callback fired when host migration occurs 
 onError  error: CarverMultiplayerError = void  --  Callback fired on connection or room errors 
 Return Value
 Property  Type  Description 
-----------------------------
 join   = Promise<void  Connect to the room. Called automatically on mount unless manually controlled 
 leave   = void  Disconnect from the room and clean up 
 connectionState  string  Current state: "disconnected", "connecting", "connected", "reconnecting" 
 room  Room \ null  The current room object, or null if not yet connected 
 error  Error \ null  The latest error, or null 
 isConnected  boolean  Shorthand for connectionState === "connected" 
 isHost  boolean  Whether the local player is the room host 
:::note
Setting hostMigration: false means the room is destroyed when the host disconnects. This is useful for games where the host runs authoritative game logic that cannot be transferred.
:::
---
 usePlayers
usePlayers provides a reactive view of every player in the room. It re-renders whenever a player joins, leaves, changes ready state, or updates metadata.
 Return Value
 Property  Type  Description 
-----------------------------
 players  Player  All players currently in the room including self 
 self  Player \ null  The local player, or null if not yet connected 
 host  Player \ null  The current room host, or null 
 getPlayer  peerId: string = Player \ undefined  Look up a player by their peer ID 
 allReady  boolean  true when every player in the room has isReady: true 
---
 useHost
useHost exposes host-only room management actions. Every function checks host status before executing — if called by a non-host client, it logs a warning and no-ops.
 Return Value
 Property  Type  Description 
-----------------------------
 kick  peerId: string = void  Remove a player from the room 
 transferHost  peerId: string = void  Transfer host privileges to another player 
 setRoomState  state: RoomState = void  Set the room state "waiting", "starting", "playing", "finished" 
 setMaxPlayers  max: number = void  Update the maximum player count 
 lockRoom   = void  Prevent new players from joining 
 unlockRoom   = void  Allow new players to join again 
 isHost  boolean  Whether the local player is the room host 
:::tip
All useHost functions are safe to call from any player. Non-host calls are silently ignored with a console warning, so you do not need to guard every call with an isHost check — but hiding host-only UI behind isHost provides a better user experience.
:::
---
 Complete Flow Example
The typical multiplayer journey: lobby screen browse and create rooms → room screen wait for players, ready up → game screen gameplay with synced state.
 Lobby Screen
 Room Screen
 Game Screen
---
 Type Definitions
 Player
 Field  Type  Description 
--------------------------
 peerId  string  Unique identifier assigned by the transport layer 
 displayName  string  Human-readable name set via useRoom options 
 isHost  boolean  Whether this player is the current room host 
 isSelf  boolean  Whether this player is the local client 
 isReady  boolean  Ready state toggled by the player 
 isConnected  boolean  true while the player has an active connection 
 metadata  Record<string, unknown  Arbitrary data set via playerMetadata in useRoom 
 latencyMs  number  Round-trip latency in milliseconds 
 joinedAt  number  Unix timestamp ms when the player joined the room 
 Room
 Field  Type  Description 
--------------------------
 id  string  Unique room identifier 
 name  string  Display name set at creation 
 hostId  string  Peer ID of the current host 
 playerCount  number  Current number of connected players 
 maxPlayers  number  Maximum allowed players 
 gameMode  string \ undefined  Optional game mode label 
 isPrivate  boolean  Whether the room requires a password 
 metadata  Record<string, unknown  Arbitrary room-level data 
 createdAt  number  Unix timestamp ms when the room was created 
 state  RoomState  "waiting", "starting", "playing", or "finished" 
---
 RoomState
 State  Description 
--------------------
 "waiting"  Room is open, players are joining and readying up 
 "starting"  Countdown or loading phase before gameplay begins 
 "playing"  Game is in progress 
 "finished"  Game has ended, room may be cleaned up or returned to waiting

---
### Multiplayer > Sync Modes
URL: https://docs.carverjs.dev/multiplayer/sync-modes.html

Sync Modes
CarverJS multiplayer provides three sync layers that can be used independently or combined. Each layer targets a different update frequency and game type — pick the one that matches your needs, or stack them for complex scenarios.
---
 Decision Guide
Not sure which sync mode to use? Start here.
 Game Type  Recommended Mode  Why 
---------------------------------
 Turn-based chess, cards  Events  Low frequency, discrete actions — no continuous state to sync 
 Chat / social  Events  Messages are one-off payloads, not continuous state 
 Casual / RPG  Snapshots  Moderate update rate, host-authoritative, simple to set up 
 Platformer / adventure  Snapshots  Smooth interpolation is enough at typical movement speeds 
 FPS / racing  Prediction  High update rate, client-side prediction hides latency 
 Competitive / esports  Prediction  Rollback correction keeps gameplay fair under bad network conditions 
:::tip
When in doubt, start with Snapshots. It covers most games well and is simpler than Prediction. You can switch later without changing your game logic — only the mode option changes.
:::
---
 Layer 1: Events useNetworkEvents
Events are fire-and-forget messages sent between peers. They are ideal for infrequent, discrete actions like chat messages, turn submissions, emotes, or game-over signals.
 When to Use
- Turn-based games where players take actions one at a time
- Chat systems and notification broadcasts
- Any action that happens occasionally rather than every frame
 API
 Return Value
 Property  Type  Description 
-----------------------------
 sendEvent  type: string, payload: unknown, target?: string = void  Send an event to a specific peer by peerId or the host if no target is given 
 broadcast  type: string, payload: unknown = void  Send an event to all connected peers 
 onEvent  type: string, callback: payload: unknown, senderId: string = void = void  Register a listener for a specific event type 
 Host Validation
For authoritative games, route events through the host for validation before broadcasting:
 Example: Chat + Turn-Based Game
---
 Layer 2: Snapshots useMultiplayer with mode='snapshot'
Snapshot sync is a host-authoritative model where the host reads actor state each tick, broadcasts it to all clients, and clients interpolate between received snapshots for smooth rendering.
 When to Use
- Casual multiplayer, RPGs, adventure games
- Games with moderate update frequency
- When simplicity matters more than minimal latency
 How It Works
1. Host samples Actor positions, rotations, and custom state at the broadcastRate
2. Host broadcasts a snapshot compressed state bundle to all clients
3. Clients receive snapshots and interpolate between the two most recent ones
4. Rendering always trails the latest snapshot by one tick interval, producing smooth motion
 Interpolation Modes
 Mode  Description  Best For 
-----------------------------
 Linear  Straight-line interpolation between two snapshots  Simple movement, UI elements 
 Hermite  Curve-fitting interpolation using velocity data  Characters, vehicles, anything with momentum 
Hermite interpolation uses the velocity at each snapshot to construct a smooth curve, eliminating the "jagged" look that linear interpolation can produce when entities change direction.
 Extrapolation
When a snapshot arrives late, clients can extrapolate — continue the last known trajectory until the next snapshot arrives. Extrapolation prevents entities from freezing but may cause visible corrections when the real snapshot finally arrives.
Configure extrapolation via the interpolation.extrapolateMs option:
 Options
 Option  Type  Default  Description 
------------------------------------
 mode  'snapshot'  —  Enable snapshot sync 
 tickRate  number  60  Simulation tick rate Hz 
 broadcastRate  number  20  Snapshots per second sent by the host 
 keyframeInterval  number  60  Ticks between full non-delta snapshots 
 interpolation.method  'linear' \ 'hermite'  'hermite'  Interpolation algorithm 
 interpolation.bufferSize  number  120  Number of snapshots to buffer 
 interpolation.extrapolateMs  number  250  Maximum extrapolation time in ms 0 to disable 
 Example: Casual Multiplayer Game
:::note
In snapshot mode, only the host sends state. Clients send their input to the host, and the host incorporates it into the next snapshot. This keeps the game authoritative and prevents cheating.
:::
---
 Layer 3: Prediction useMultiplayer with mode='prediction'
Prediction sync adds client-side prediction and server reconciliation on top of the snapshot model. The client immediately applies inputs locally, then corrects if the host disagrees.
 When to Use
- FPS, racing, fighting, and other competitive games
- Any game where input latency is noticeable and frustrating
- Scenarios with variable or high network latency
 How It Works
1. Client applies input locally and renders the predicted result immediately
2. Client sends the input with a tick number to the host
3. Host processes the input authoritatively and includes the result in the next snapshot
4. Client receives the snapshot and compares it to the predicted state
5. If they match — no correction needed. If they differ — the client rolls back to the authoritative state and replays all unacknowledged inputs
 onPhysicsStep Callback
For deterministic prediction, provide an onPhysicsStep callback. This function runs on both client for prediction and host for authority, ensuring identical simulation:
 Error Smoothing
When a rollback correction occurs, snapping the entity to the corrected position looks jarring. CarverJS applies error smoothing — the visual position blends toward the corrected position over several frames using an exponential decay factor:
A higher value e.g. 0.9 smooths more aggressively but takes longer to converge. A lower value e.g. 0.5 snaps faster but may be visible.
 Options
 Option  Type  Default  Description 
------------------------------------
 mode  'prediction'  —  Enable prediction sync 
 tickRate  number  60  Simulation ticks per second 
 onPhysicsStep  inputs: Map<string, unknown, tick: number, isRollback: boolean = void  —  Deterministic step function run on client and host 
 prediction.maxRewindTicks  number  15  Maximum ticks of unacknowledged inputs to buffer 
 prediction.errorSmoothingDecay  number  0.85  Exponential decay factor for visual correction 0-1 
 prediction.maxErrorPerFrame  number  5  Position error threshold to trigger rollback 
 prediction.snapThreshold  number  15  Error distance that triggers hard snap instead of smooth correction 
 prediction.lagCompensation  boolean  false  Enable host-side lag compensation for hit validation 
 Example: Competitive Game with Prediction
:::note
Prediction mode requires a deterministic onPhysicsStep. Avoid Math.random, Date.now, or any non-deterministic logic inside the step function. Use the tick number as a seed if you need randomness.
:::
---
 Combining Layers
Sync layers are designed to stack. A common pattern is Snapshots + Events: use snapshots for continuous state positions, health, scores and events for discrete actions chat messages, item pickups, ability triggers.
 Example: Snapshot Sync + Event Chat
---
 useMultiplayer Return Value
 Property  Type  Description 
-----------------------------
 isActive  boolean  true when the sync engine is running and connected 
 networkQuality  'good' \ 'degraded' \ 'poor'  Estimated network quality based on latency and packet loss 
 tick  number  Current local tick number 
 serverTick  number  Latest tick acknowledged by the host 
 drift  number  Ticks ahead of server positive = ahead, negative = behind 
 syncEngine  SyncMode  The active sync mode: 'events', 'snapshot', or 'prediction' 
---
 useNetworkEvents Return Value
 Property  Type  Description 
-----------------------------
 sendEvent  type: string, payload: unknown, target?: string = void  Send to a specific peer or the host 
 broadcast  type: string, payload: unknown = void  Send to all peers 
 onEvent  type: string, callback: payload: unknown, senderId: string = void = void  Listen for a specific event type 
---
 Performance Tips
:::tip
- Broadcast rate: Start at 20/s for snapshots. Increase only if motion looks choppy. Higher rates consume more bandwidth.
- Hermite interpolation: Almost always better than linear. The CPU cost is negligible compared to the visual improvement.
- Prediction mode: Only use when your game genuinely needs it. The added complexity of deterministic step functions and rollback logic is not worth it for casual games.
- Combine wisely: Use events for things that happen occasionally chat, abilities, turns. Use snapshots or prediction for things that change every frame positions, rotations, velocities. Sending per-frame data as events will flood the network.
:::

---
### Multiplayer > Configuration Reference
URL: https://docs.carverjs.dev/multiplayer/configuration.html

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.
---
 useMultiplayer Options
Pass these options to useMultiplayer to control synchronization behaviour.
 Top-Level Options
 Option  Type  Default  Description 
------------------------------------
 mode  'events' \ 'snapshot' \ 'prediction'  'snapshot'  Sync strategy. events sends only inputs; snapshot sends full state; prediction adds client-side prediction and reconciliation 
 tickRate  number  60  Fixed-timestep simulation rate in Hz. Higher = more precise physics but more CPU 
 broadcastRate  number  20  How often the host sends state updates per second. Independent of tickRate 
 keyframeInterval  number  60  Number of ticks between full keyframe snapshots. Between keyframes, only deltas are sent 
 quantize  QuantizeOptions  —  Reduce floating-point precision to save bandwidth 
 deltaThresholds  DeltaThresholds  —  Minimum change required before a field is included in a delta update 
 prediction  PredictionOptions  —  Client-side prediction and server reconciliation settings 
 interpolation  InterpolationOptions  —  How remote entities are smoothed between updates 
 interestManagement  InterestManagementOptions  —  Area-of-interest filtering for large worlds 
 debug  DebugOptions  —  Debug overlay and network simulation tools 
 onPhysicsStep  dt: number = void  —  Callback invoked each physics tick. Required for prediction mode to replay inputs 
---
 QuantizeOptions
Quantization rounds values to a fixed step size, reducing the number of bits needed on the wire.
 Field  Type  Default  Description 
-----------------------------------
 position  number  —  Step size for position axes. 0.01 = centimetre precision 
 rotation  number  —  Step size for rotation radians. 0.001 is typically sufficient 
 velocity  number  —  Step size for linear/angular velocity 
:::tip
Quantization is one of the cheapest ways to reduce bandwidth. A position quantized to 0.01 is visually indistinguishable from full float64 in most games.
:::
---
 DeltaThresholds
Only include a field in the delta if it changed by more than the threshold since the last broadcast.
 Field  Type  Default  Description 
-----------------------------------
 position  number  0.001  Minimum positional change world units 
 rotation  number  0.001  Minimum rotational change radians 
 velocity  number  0.01  Minimum velocity change 
---
 PredictionOptions
Controls client-side prediction and server reconciliation. Only relevant when mode is 'prediction'.
 Field  Type  Default  Description 
-----------------------------------
 enabled  boolean  true  Enable client-side prediction 
 maxRewindTicks  number  30  Maximum number of ticks the client will rewind and replay during reconciliation 
 correctionSmoothing  number  0.2  Blend factor for correction 0 = instant snap, 1 = no correction. 0.2 gives a smooth visual correction over ~5 frames 
 inputBufferSize  number  60  Number of past input frames stored for replay during reconciliation 
:::note
Prediction mode requires onPhysicsStep to be provided so the engine can replay inputs during reconciliation.
:::
---
 InterpolationOptions
Controls how remote non-local entities are smoothed between network updates.
 Field  Type  Default  Description 
-----------------------------------
 delay  number  100  Interpolation delay in milliseconds. Higher = smoother but more latency 
 maxExtrapolation  number  200  Maximum time ms to extrapolate beyond the last received state before freezing 
 method  'linear' \ 'hermite'  'linear'  Interpolation curve. Hermite produces smoother motion for accelerating objects 
---
 InterestManagementOptions
Area-of-interest filtering. Only entities within range of the player are synchronized, dramatically reducing bandwidth in large worlds.
 Field  Type  Default  Description 
-----------------------------------
 enabled  boolean  false  Enable spatial interest management 
 cellSize  number  50  Spatial hash cell size in world units 
 viewDistance  number  200  Maximum distance world units at which entities are synced to a client 
 hysteresis  number  20  Buffer zone to prevent entities flickering in/out at the boundary 
---
 DebugOptions
Developer tools for visualizing and simulating network conditions.
 Field  Type  Default  Description 
-----------------------------------
 overlay  boolean  false  Show the on-screen debug overlay with live stats 
 simulatedLatencyMs  number  0  Artificial one-way latency added to every message ms 
 simulatedPacketLoss  number  0  Fraction of packets to randomly drop 0–1. 0.05 = 5% loss 
 logLevel  'none' \ 'error' \ 'warn' \ 'info' \ 'debug'  'warn'  Console log verbosity 
---
 useRoom Options
Pass these options to useRoom to configure the connection and room behaviour.
 Option  Type  Default  Description 
------------------------------------
 transport  CarverTransport  --  Pass a custom CarverTransport instance to bypass the built-in WebRTCTransport 
 password  string  --  Room password. Joining peers must provide the same value 
 displayName  string  --  Human-readable name shown in the player list 
 playerMetadata  Record<string, unknown  --  Arbitrary metadata attached to this player avatar, team, skin, etc. 
 iceServers  RTCIceServer  Provider defaults  Custom STUN/TURN servers for this room overrides provider-level config 
 hostMigration  boolean  true  Automatically elect a new host when the current host disconnects 
 reconnectAttempts  number  3  Number of automatic reconnection attempts on disconnect 
 reconnectIntervalMs  number  2000  Delay between reconnection attempts ms 
 privacy  'all' \ 'relay'  'all'  Set to 'relay' to force all traffic through TURN servers hides player IP addresses 
 onConnected   = void  --  Callback when successfully connected to the room 
 onDisconnected  reason: string = void  --  Callback when disconnected from the room 
 onHostMigration  newHostId: string = void  --  Callback when the host changes 
 onError  error: CarverMultiplayerError = void  --  Callback for any multiplayer error 
---
 Networked Config Prop Reference
The config prop on <Networked controls per-entity sync behaviour.
 Field  Type  Default  Description 
-----------------------------------
 sync  'transform' \ 'rigid-body' \ 'custom'  'transform'  What data is synchronized. transform syncs position/rotation/scale; rigid-body adds velocity and angular velocity; custom sends only what you provide 
 owner  string  host peer ID  Peer ID that has authority over this entity. Only the owner can write state 
 custom  Record<string, unknown  —  Arbitrary key-value pairs synced alongside transform. Useful for health, score, animation state 
 interpolate  boolean  true  Whether remote copies of this entity use interpolation. Disable for instant-snap objects like UI cursors 
---
 Debug Tools
 DebugOverlay
Enable the on-screen overlay to see live network statistics:
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:
:::tip
Test with simulatedLatencyMs: 200 and simulatedPacketLoss: 0.1 to approximate a poor mobile connection. If your game still feels playable, it will work well on most real networks.
:::
---
 Error Codes
All multiplayer errors use CarverError with a code field from the CarverErrorCode enum.
 Code  Meaning  Common Cause  Recovery 
---------------------------------------
 ROOMNOTFOUND  The room ID does not exist  Typo in room ID, or room expired  Verify the room ID and retry 
 ROOMFULL  Room has reached max players  All player slots are taken  Show "room full" UI, retry later 
 ROOMLOCKED  Room is locked by the host  Host called room.lock  Inform the user, wait for unlock 
 INVALIDPASSWORD  Wrong room password  User entered incorrect password  Prompt for correct password 
 CONNECTIONFAILED  Could not establish a connection  Firewall, NAT, or network issue  Retry, or set privacy: 'relay' to force TURN 
 HOSTUNREACHABLE  Cannot reach the room host  Host went offline without migration  Wait for host migration, or rejoin 
 KICKED  Kicked from the room by the host  Host called room.kickpeerId  Show "kicked" message to the user 
 SIGNALINGERROR  Signaling strategy error  MQTT broker or Firebase unreachable  Check network, retry after a delay 
 TURNCREDENTIALERROR  TURN server credential failure  Expired or invalid TURN credentials  Refresh credentials and retry 
 TRANSPORTERROR  Low-level transport failure  WebRTC data channel closed unexpectedly  Automatic reconnection will attempt recovery 
 MIGRATIONFAILED  Host migration did not complete  All candidate hosts disconnected simultaneously  Rejoin or create a new room 
---
 Type Definitions
See Types../types/index.md for all type definitions including UseMultiplayerOptions, UseRoomOptions, NetworkedConfig, QuantizeOptions, PredictionOptions, InterpolationOptions, InterestManagementOptions, DebugOptions, CarverError, and CarverErrorCode.

---
### Multiplayer > Advanced Topics
URL: https://docs.carverjs.dev/multiplayer/advanced.html

Advanced Topics
Deep dives into custom transports, dynamic spawning, interest management, performance tuning, and other advanced multiplayer patterns.
---
 Custom Transport
The built-in WebRTC and WebSocket transports cover most use cases, but you can plug in your own backend by implementing the CarverTransport interface.
 Interface
 Example: Custom WebSocket Transport
Use it with useRoom:
:::note
Your custom transport must handle peer discovery, message routing, and host election. CarverJS calls createChannel for its internal sync channels — make sure your implementation supports multiple named channels.
:::
---
 Spawn & Despawn useNetworkState
useNetworkState provides host-authoritative dynamic entity management. Use it for objects that are created and destroyed at runtime — projectiles, loot drops, NPCs, etc.
 API
 Method  Caller  Description 
-----------------------------
 spawnid, state  Host only  Create a new networked entity with initial state 
 despawnid  Host only  Remove a networked entity 
 requestSpawnid, config  Any peer  Request the host to spawn an entity. Host validates and calls spawn 
 getStateid  Any peer  Read the current state of an entity 
 setStateid, partial  Owner only  Update fields on an entity merges with existing state 
 Example: Dynamic Projectile Spawning
:::tip
Always use requestSpawn from clients instead of calling spawn directly. This lets the host validate the request e.g., check cooldowns, ammo count before creating the entity.
:::
---
 Interest Management
In large worlds with hundreds of entities, sending every entity to every player wastes bandwidth. Interest management uses a spatial hash to filter entities by proximity — each client only receives entities within its view distance.
 Configuration
 How It Works
1. The world is divided into a grid of cells cellSize x cellSize.
2. Each entity is assigned to the cell containing its position.
3. For each client, the host only sends entities in cells within viewDistance of that client's position.
4. The hysteresis buffer prevents entities from flickering in and out when a player moves along a cell boundary.
 Performance Implications
 Scenario  Without Interest Mgmt  With Interest Mgmt 
---------------------------------------------------
 500 entities, 8 players  ~4000 entity updates/broadcast  ~200–400 per player 
 1000 entities, 16 players  ~16000 updates/broadcast  ~300–600 per player 
:::note
Interest management only affects what the host sends. The host still simulates all entities. For very large worlds 10,000+ entities, also consider reducing broadcastRate and increasing keyframeInterval.
:::
---
 Performance Tuning
Every multiplayer game has unique bandwidth and latency requirements. Here's how each setting affects performance.
 broadcastRate
Controls how many state updates per second the host sends.
 Value  Bandwidth  Smoothness  Best For 
----------------------------------------
 10  Low  Acceptable with interpolation  Turn-based, slow-paced games 
 20  Medium  Good  Most action games default 
 30–60  High  Very smooth  Competitive shooters, racing 
 tickRate
The simulation rate affects physics precision. Separate from broadcastRate.
- 30 Hz — adequate for platformers and casual games
- 60 Hz — good default for most games
- 120 Hz — competitive games requiring precise physics
 quantize
Reducing floating-point precision is the lowest-effort bandwidth optimization.
 deltaThresholds
Skip fields that haven't changed meaningfully. A stationary entity sends almost no data between keyframes.
 keyframeInterval
Full snapshots are reliable but expensive. Deltas are cheap but can accumulate errors.
 Value  Trade-off 
------------------
 30 0.5s at 60Hz  Very reliable, higher bandwidth 
 60 1s at 60Hz  Good balance default 
 120 2s at 60Hz  Lower bandwidth, slower error recovery 
:::tip
Start with the defaults. Profile with the debug overlay enabled debug: { overlay: true } and tune one setting at a time. Over-optimizing without measurement often makes things worse.
:::
---
 IP Privacy TURN-Only Mode
By default, WebRTC exposes player IP addresses via STUN. Setting privacy: 'relay' forces all traffic through TURN servers, hiding IPs from other peers at the cost of ~10-30ms added latency.
:::note
Only enable relay mode when IP privacy is a hard requirement e.g., public lobbies where players don't trust each other.
:::
---
 Host Migration
When the current host disconnects, CarverJS automatically elects a new host so the game continues without interruption.
 How It Works
1. Detection — peers detect host disconnection via heartbeat timeout.
2. Election — the peer with the lowest sorted peer ID is elected as the new host. This deterministic rule ensures all peers agree without coordination.
3. Grace period — a 500ms grace period allows the old host to reconnect before migration proceeds.
4. State transfer — the new host already has the latest state from prior snapshots. It immediately begins broadcasting.
 Configuration
State is preserved because all peers maintain the latest keyframe locally. The new host resumes from the last acknowledged tick, and clients re-interpolate from their buffers for a seamless visual transition.
:::tip
Test host migration by opening your game in multiple tabs and closing the host tab. The game should continue within ~500ms.
:::
---
 Network Quality
CarverJS continuously monitors connection quality and exposes a three-tier signal for adaptive gameplay.
 Quality Levels
 Level  RTT  Packet Loss  Typical Scenario 
-------------------------------------------
 good  < 100ms  < 2%  Wired or strong Wi-Fi 
 degraded  100–250ms  2–10%  Mobile data, congested Wi-Fi 
 poor   250ms   10%  Weak signal, international relay 
 Reading Network Quality
 Adaptive Quality Patterns
Adjust settings dynamically based on network conditions:
:::tip
Reducing broadcastRate on poor connections prevents packet queue buildup that causes cascading lag spikes -- especially valuable for mobile games.
:::
---
 Type Definitions
See Types../types/index.md for all type definitions including CarverTransport, CarverChannel, ChannelOptions, NetworkQuality, UseNetworkStateReturn, and InterestManagementOptions.

---
### Multiplayer > MultiplayerBridge
URL: https://docs.carverjs.dev/multiplayer/multiplayer-bridge.html

MultiplayerBridge
<MultiplayerBridge bridges the multiplayer context from the parent React tree into the R3F Canvas. This is required when <MultiplayerProvider is placed outside the <Game component.
---
 Why It's Needed
CarverJS <Game renders into an R3F <Canvas, which uses a separate React reconciler. React contexts from the parent tree — including the MultiplayerContext created by <MultiplayerProvider — are not automatically available inside the Canvas.
Without <MultiplayerBridge, hooks like useNetworkEvents, useMultiplayer, and useNetworkState will throw an error when called inside the Canvas because they cannot find the MultiplayerContext.
---
 When to Use
Use <MultiplayerBridge when your <MultiplayerProvider is outside the <Game component. This is the recommended pattern for games that have lobby/room screens HTML UI that need access to multiplayer hooks like useRoom, usePlayers, and useHost before the Canvas is rendered.
You do NOT need <MultiplayerBridge if your <MultiplayerProvider is placed inside <Game directly in the R3F tree. In that case, the context is already available.
---
 Usage
---
 Props
 Prop  Type  Description 
-------------------------
 children  ReactNode  Scene content to render inside the bridged context 
---
 How It Works
<MultiplayerBridge reads the MultiplayerContext value from the parent React tree using useContext, then re-provides that same value via a new <MultiplayerContext.Provider inside the R3F tree. This is a lightweight operation — no data is copied or transformed.
---
 Common Patterns
 Pattern 1: Lobby Outside, Game Inside Recommended
 Pattern 2: Everything Inside Canvas No Bridge Needed
:::tip
Pattern 1 is recommended for most games because it allows you to build rich HTML lobby/room UIs that use useRoom, usePlayers, and useHost without needing the Canvas to be active.
:::

---
### Systems > InputManager
URL: https://docs.carverjs.dev/systems/input-manager.html

InputManager
InputManager is a singleton that captures keyboard, pointer, and touch events from the DOM and makes them available to game logic on a per-frame basis.
It is mounted automatically by Game../components/game.md — you do not need to set it up manually.
---
 How It Works
1. DOM events keydown, keyup, pointerdown, pointerup, pointermove, touch events are captured asynchronously and queued.
2. Once per frame at priority -50, before all game logic, flush processes the queued events and updates key/pointer state.
3. Game logic reads the current state via getKey and getPointer.
This ensures consistent input state within a single frame — no matter when a DOM event fires, the state only changes at the start of the next frame.
---
 Frame-Based Input States
Each key tracks three states per frame:
 State  Meaning 
----------------
 pressed  Key is currently held down 
 justPressed  Key was first pressed this frame 
 justReleased  Key was released this frame 
The pointer tracks equivalent states:
 State  Meaning 
----------------
 isDown  Primary button is held 
 justDown  Button was pressed this frame 
 justUp  Button was released this frame 
 position  Screen-space { x, y } in pixels 
---
 API
 getInputManager
Returns the singleton InputManager instance. Creates one if it doesn't exist.
 destroyInputManager
Detaches all DOM listeners and destroys the singleton. Called automatically when Game unmounts.
 manager.getKeycode: string: KeyState
Returns the state of a key by its KeyboardEvent.codehttps://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code e.g., "KeyW", "Space", "ArrowUp".
 manager.getPointer: PointerState
Returns a live reference to the pointer state. Always up-to-date when read inside useGameLoop.
---
 Usage
Most game code should use the useInput../hooks/use-input.md hook instead of accessing InputManager directly. The hook provides a cleaner API with action mapping and axis helpers.
Direct access is useful for systems-level code:
---
 Type Definitions
See Types../types/index.md for KeyState and PointerState.

---
### Systems > CollisionManager
URL: https://docs.carverjs.dev/systems/collision-manager.html

CollisionManager
CollisionManager is a singleton that runs AABB, sphere, and circle overlap detection each frame. It uses a spatial hash for broad-phase culling and supports layer/mask filtering.
It is mounted automatically by Game../components/game.md via the internal CollisionFlush system priority -25. You do not need to set it up manually.
---
 How It Works
1. Each component calls useCollision../hooks/use-collision.md to register a collider with a shape, layer, and callbacks.
2. Every frame at priority -25 after fixedUpdate, before update, CollisionFlush calls tick.
3. tick runs:
   - Broad phase — inserts all colliders into a spatial hash grid and extracts candidate pairs.
   - Layer filtering — skips pairs where layerA & maskB === 0  layerB & maskA === 0.
   - Narrow phase — tests AABB-AABB, sphere-sphere, and AABB-sphere overlaps.
   - Event dispatch — fires onCollisionEnter, onCollisionStay, and onCollisionExit callbacks.
---
 Supported Shape Pairs
 Shape A  Shape B  Supported 
------------------:---------:
 AABB  AABB  Yes 
 Sphere  Sphere  Yes 
 Circle  Circle  Yes 
 AABB  Sphere/Circle  Yes 
 Sphere  Circle  Yes 
All tests are 2D-aware — in "2d" mode, the Z axis is ignored.
---
 API
 getCollisionManager
Returns the singleton instance. Creates one if it doesn't exist.
 destroyCollisionManager
Destroys the singleton. Called automatically when Game unmounts.
---
 Usage
Most game code should use useCollision../hooks/use-collision.md instead of accessing CollisionManager directly. Direct access is useful for systems-level code:
---
 Type Definitions
See Types../types/index.md for ColliderDef, ColliderShape, CollisionEvent, and CollisionCallback.

---
### Systems > GridCollisionManager
URL: https://docs.carverjs.dev/systems/grid-collision-manager.html

GridCollisionManager
GridCollisionManager is a singleton that manages a 2D tile-based collision grid backed by an Int32Array. It provides O1 cell lookups, neighbor queries, and world-to-grid coordinate conversion.
Unlike CollisionManager./collision-manager.md, GridCollisionManager is not auto-mounted by Game. You create and manage it via useGridCollision../hooks/use-grid-collision.md.
---
 How It Works
1. Call useGridCollision../hooks/use-grid-collision.md with a GridCollisionConfig to create the grid.
2. The hook initializes a flat Int32Array of width  height cells.
3. Use setCell / getCell / isCellOccupied to read/write cell values.
4. On unmount, the grid is destroyed.
Cell values: 0 = empty, positive integers = occupied by type you define the meaning.
---
 API
 getGridCollisionManager
Returns the singleton instance. Creates one if it doesn't exist.
 destroyGridCollisionManager
Destroys the singleton and frees the grid memory. Called automatically when the useGridCollision hook unmounts.
---
 Usage
Most game code should use useGridCollision../hooks/use-grid-collision.md instead of accessing the manager directly.
---
 Type Definitions
See Types../types/index.md for GridCollisionConfig and GridCellCallback.

---
### Systems > PhysicsProvider
URL: https://docs.carverjs.dev/systems/physics-provider.html

PhysicsProvider
PhysicsProvider is an internal system that conditionally wraps scene content in Rapier physics. It consists of two components:
- PhysicsGate — wraps World children in Rapier's <Physics when a physics config is provided.
- PhysicsBodyWrapper — wraps an Actor in Rapier's <RigidBody when the Actor has a physics prop.
You do not need to use these directly — they are used internally by World../components/world.md and Actor../components/actor.md.
---
 How It Works
 PhysicsGate used by World
1. When a World../components/world.md has a physics prop, PhysicsGate lazy-loads @react-three/rapier via dynamic import.
2. If the import succeeds, children are wrapped in <Physics with the configured gravity, timestep, interpolation, and debug settings.
3. If @react-three/rapier is not installed, a console warning is logged and children render without physics.
 PhysicsBodyWrapper used by Actor
1. When an Actor../components/actor.md has a physics prop and a PhysicsContext is available, the Actor's group is wrapped in <RigidBody.
2. In 2D mode, Z translation and X/Y rotation are auto-locked.
3. Collision callbacks onCollisionEnter, onCollisionExit are mapped to Rapier's event system.
4. A RigidBodyRefContext is provided so usePhysics../hooks/use-physics.md can access the body.
---
 Lazy Loading
Rapier is loaded dynamically at runtime:
- Not installed — warning logged, children render normally.
- Loading — children render without physics until the module resolves.
- Loaded — <Physics and <RigidBody wrappers activate.
This means @react-three/rapier is a true optional dependency — your bundle doesn't include it unless you install and use it.
---
 Install
---
 Context API
Two internal contexts are exposed for advanced use:
 usePhysicsContext
Returns PhysicsContextValue  null. Contains:
 Field  Type  Description 
--------------------------
 available  boolean  Whether Rapier is loaded and active 
 is2D  boolean  Whether the World is in 2D mode 
 config  WorldPhysicsConfig  The physics config from the World 
 modules  RapierModules  References to Physics and RigidBody components 
 useRigidBodyRef
Returns RefObject<RapierRigidBody  null. Used internally by usePhysics../hooks/use-physics.md to access the rigid body instance.
---
 Type Definitions
See Types../types/index.md for WorldPhysicsConfig, ActorPhysicsProps, RigidBodyType, and PhysicsColliderType.

---
### Systems > AudioManager
URL: https://docs.carverjs.dev/systems/audio-manager.html

AudioManager
AudioManager is a singleton that manages all audio playback using the Web Audio API, with an automatic HTML5 Audio fallback for environments without Web Audio support.
It is mounted automatically by Game../components/game.md — you do not need to set it up manually.
---
 How It Works
1. On Game mount, the AudioContext is created and unlock listeners are attached to the document.
2. On first user gesture click, tap, keypress, the AudioContext is resumed and a silent buffer is played to satisfy iOS Safari requirements. Queued music begins playing.
3. Each frame at priority -48, after input flush, flush runs:
   - Pauses/resumes the context based on game phase
   - Updates spatial sound positions from Object3D refs
   - Syncs the Web Audio listener to the active camera
4. On Game unmount, all sounds stop, the AudioContext closes, and all resources are freed.
---
 Audio Backend Detection
The system auto-detects the best available backend:
 Backend  When Used  Features 
------------------------------
 Web Audio API  AudioContext is available 98%+ of browsers  Full features: spatial audio, gain automation, AudioParam scheduling 
 HTML5 Audio  AudioContext unavailable  Basic playback, volume via audio.volume, no spatial audio 
The fallback is transparent — the public API is identical regardless of backend.
---
 Volume Routing Web Audio
Channel gains are created once and persist for the lifetime of the AudioContext. Mute is implemented by setting gain to 0 and restoring on unmute.
---
 API
 getAudioManager
Returns the singleton AudioManager instance. Creates one if it doesn't exist.
 destroyAudioManager
Stops all sounds, closes the AudioContext, and destroys the singleton. Called automatically when Game unmounts.
 Sound Registration
 Method  Description 
---------------------
 registerSoundname, def  Register a sound definition. Preloads by default 
 unregisterSoundname  Unregister and stop all instances 
 Playback
 Method  Description 
---------------------
 playname, options?  Play a registered sound. Returns SoundHandle 
 stopByNamename  Stop all instances of a sound 
 pauseByNamename  Pause all instances 
 resumeByNamename  Resume paused instances 
 isSoundPlayingname  Check if any instance is playing 
 Music
 Method  Description 
---------------------
 playMusicsrc, options?  Play a music track with crossfade 
 stopMusicfadeOut?  Stop music with optional fade-out 
 pauseMusic  Pause the music 
 resumeMusic  Resume the music 
 isMusicPlaying  Check if music is playing 
 Volume
 Method  Description 
---------------------
 setChannelVolumechannel, volume  Set channel volume 0–1 
 getChannelVolumechannel  Get channel volume 
 setChannelMutechannel, muted  Mute/unmute a channel 
 isChannelMutedchannel  Check mute state 
 setMasterMutemuted  Mute/unmute all audio 
 Preloading
 Method  Description 
---------------------
 preloadname  Preload a registered sound 
 preloadAllnames  Preload multiple sounds 
 unloadBuffername  Free a sound's buffer from memory 
 Listener
 Method  Description 
---------------------
 setListenerSourceobj  Set the default listener camera. Called by AudioFlush 
 setCustomListenerobj  Override the listener. Called by AudioListener component 
---
 Usage
Most game code should use the useAudio../hooks/use-audio.md hook. Direct manager access is useful for systems-level code:
---
 Type Definitions
See Types../types/index.md for AudioChannel, SoundDefinition, PlaySoundOptions, SoundHandle, MusicOptions, and SoundState.

---
### Systems > SceneManager (System)
URL: https://docs.carverjs.dev/systems/scene-manager.html

SceneManager System
The SceneManagerImpl singleton provides imperative scene navigation for use outside React components — in event handlers, network callbacks, or third-party libraries. It wraps the Zustand scene store, following the same pattern as InputManager./input-manager.md and AudioManager./audio-manager.md.
---
 How It Works
The singleton is a thin passthrough to the Zustand sceneStore. All state lives in the store — the singleton just provides a non-React API for accessing it.
The <SceneManager component must be mounted inside <Game for scene navigation to work. The imperative API is for code that runs outside the React tree.
---
 API
 getSceneManager
Returns the singleton instance. Creates it on first call.
 destroySceneManager
Resets the scene store and nulls the singleton. Called automatically when <SceneManager unmounts.
 Navigation
All navigation methods accept an optional TransitionConfig as the last argument:
 Query
 Shared Data
---
 Usage
Most game code should use the useScene../hooks/use-scene.md hook inside React components. The imperative API is for edge cases:
---
 Type Definitions
See Types../types/index.md for TransitionConfig and SceneStoreState.

---
### Systems > AssetManager
URL: https://docs.carverjs.dev/systems/asset-manager.html

AssetManager
AssetManager is a singleton that handles loading, caching, and lifecycle management of game assets. It supports GLTF models, textures, audio, JSON, and binary data with concurrency-limited loading, priority ordering, LRU cache eviction, and retry with exponential backoff.
Unlike other managers, AssetManager is not mounted automatically by Game../components/game.md. Use AssetLoader../components/asset-loader.md for declarative preloading, or access the manager directly for imperative control.
---
 How It Works
1. Manifest parsing: Asset entries are normalized — relative URLs are resolved against baseUrl, types are auto-detected from file extensions, and entries are sorted by priority.
2. Concurrency-limited loading: A worker pool pattern loads assets in parallel default: 6 concurrent. Each worker pulls the next task from a shared queue.
3. Retry with backoff: Failed loads retry up to 3 times with exponential backoff and jitter to avoid thundering herd.
4. Caching: Loaded assets are stored in an in-memory LRU cache 256 MB default. Reference counting prevents eviction of assets in active use.
5. Progress tracking: Real-time progress is available via useSyncExternalStore used by useAssetProgress../hooks/use-asset-progress.md.
6. Resource disposal: On eviction or explicit unload, Three.js resources textures, geometries, materials are properly disposed.
---
 API
 getAssetManager
Returns the singleton AssetManager instance. Creates one if it doesn't exist.
 destroyAssetManager
Clears all caches, disposes Three.js resources, and destroys the singleton.
 detectAssetTypeurl
Detect asset type from a URL's file extension. Returns AssetType  undefined.
---
 Loading
 Method  Description 
---------------------
 load<Turl, options?  Load a single asset. Returns cached result if available. Deduplicates concurrent requests 
 loadManifestmanifest, callbacks?  Load all non-lazy assets from a manifest with progress tracking 
 loadGroupname  Load all assets in a named group 
 preloadurls  Fire-and-forget preload for one or more URLs 
 load Options
 Option  Type  Description 
---------------------------
 type  AssetType  Override auto-detection 
 key  string  Cache key defaults to URL 
 loaderOptions  Record<string, unknown  Passed to the underlying loader 
 loadManifest Callbacks
 Callback  Description 
-----------------------
 onProgressprogress  Called on each progress update 
 onComplete  Called when all assets finish loading 
 onErrorerrors  Called when any asset fails after all retries 
---
 Cache Access
 Method  Description 
---------------------
 get<Tkey  Get a cached asset synchronously. Returns undefined if not cached 
 haskey  Check if an asset is cached 
 isLoadingkey  Check if an asset is currently loading 
---
 Cache Management
 Method  Description 
---------------------
 unloadkey  Unload a specific asset, disposing Three.js resources 
 unloadGroupgroup  Unload all assets in a group 
 clearAll  Clear all cached assets 
 getMemoryUsage  Get current cache size in bytes 
 retainkey  Increment reference count prevents LRU eviction 
 releasekey  Decrement reference count 
---
 Configuration
---
 Custom Loaders
Register custom loaders for new asset types or override built-in ones:
---
 Built-in Loaders
 Type  Loader  Output 
----------------------
 "gltf"  GLTFLoader three-stdlib, lazy-imported  GLTF scene object 
 "texture"  TextureLoader three, lazy-imported  THREE.Texture 
 "audio"  fetch → arrayBuffer  ArrayBuffer 
 "json"  fetch → json  Parsed object 
 "binary"  fetch → arrayBuffer  ArrayBuffer 
GLTF supports Draco and Meshopt decompression via loaderOptions:
---
 Usage
Most game code should use AssetLoader../components/asset-loader.md + useAssets../hooks/use-assets.md. Direct manager access is useful for imperative scenarios:
---
 Memory Management
The cache uses LRU Least Recently Used eviction with reference counting:
- LRU: When the cache exceeds maxCacheBytes, the least-recently-accessed asset with refCount === 0 is evicted.
- Reference counting: useAssets retains assets on mount and releases on unmount. Retained assets are never evicted.
- Disposal: Evicted Three.js resources textures, geometries, materials are properly disposed via .dispose.
---
 Type Definitions
See Types../types/index.md for AssetType, AssetEntry, AssetManifest, AssetGroupConfig, LoadingProgress, AssetLoadError, and CacheEntry.

---
### Systems > TweenManager
URL: https://docs.carverjs.dev/systems/tween-manager.html

TweenManager
TweenManager is a singleton that manages all property tweening, number interpolation, and timeline sequencing. It uses an object pool for zero-GC per-frame performance.
It is mounted automatically by Game../components/game.md — you do not need to set it up manually.
---
 How It Works
1. On Game mount, the TweenFlush internal component is created, which calls getTweenManager.tickdelta every frame at priority -15.
2. Each frame, tick runs:
   - Reads game phase via useGameStore.getState — all tweens freeze during "loading", normal tweens freeze during "paused" / "gameover"
   - Iterates the active tween list, advancing timing, applying easing, and writing interpolated values to target properties
   - Processes repeat/yoyo cycles, fires callbacks, handles chain completion
   - Updates active timelines
3. On Game unmount, all tweens are killed, the pool is drained, and the singleton is destroyed.
---
 Object Pool
The TweenManager pre-allocates 64 Tween instances at startup. When a tween completes, it is reset and returned to the pool. The pool grows on demand up to a maximum of 512 active tweens.
This design ensures zero garbage collection pressure during gameplay — no objects are created or destroyed per frame.
---
 Frame Priority
Tweens run after game logic update at -20 so that tweens created in useGameLoop take effect the same frame. They run before lateUpdate -10 so late-update code sees tween-applied values.
---
 API
 getTweenManager
Returns the singleton TweenManager instance. Creates one if it doesn't exist.
 destroyTweenManager
Kills all active tweens and timelines, drains the pool, and destroys the singleton. Called automatically when Game unmounts.
 Tween Creation
 Method  Description 
---------------------
 createconfig  Create and start a property tween. Returns TweenControls 
 createNumberconfig  Create a target-less number tween. Returns TweenControls 
 createTimelineconfig?  Create a timeline. Returns TimelineControls 
 Group Controls
 Method  Description 
---------------------
 getGroupname  Get group controls for a named group. Returns TweenGroupControls 
TweenGroupControls provides pause, resume, kill, and count for batch control over all tweens in a group.
 Global Controls
 Method  Description 
---------------------
 pauseAll  Pause all active tweens 
 resumeAll  Resume all paused tweens 
 killAll  Kill all active tweens and timelines 
 killByIdid  Kill a specific tween by its ID 
 Frame Update
 Method  Description 
---------------------
 tickdelta  Advance all active tweens by delta seconds. Called by TweenFlush 
---
 Usage
Most game code should use the useTween../hooks/use-tween.md hook, which provides auto-cleanup on unmount. Direct manager access is useful for systems-level code:
---
 Easing Utilities
The easing module is also exported from @carverjs/core/systems:
---
 Type Definitions
See Types../types/index.md for TweenConfig, NumberTweenConfig, TweenControls, TimelineConfig, TimelineControls, TweenGroupControls, EasingFn, EasingPreset, and EasingInput.

---
### Systems > ParticleManager
URL: https://docs.carverjs.dev/systems/particle-manager.html

ParticleManager
ParticleManager is a singleton that manages all particle emitters. It uses GPU-instanced rendering via InstancedMesh and Structure-of-Arrays SoA particle data for zero-GC per-frame performance.
It is mounted automatically by Game../components/game.md — you do not need to set it up manually.
---
 How It Works
1. On Game mount, the ParticleFlush internal component is created, which calls getParticleManager.tickdelta every frame at priority -12.
2. Each frame, tick runs for each registered emitter:
   - Reads game phase via useGameStore.getState — emitters freeze during "paused" / "gameover" / "loading"
   - Emission phase: accumulates fractional particles stream or checks burst schedules, spawns new particles from the free-list pool
   - Update phase: advances age, applies velocity/acceleration/drag/gravity, evaluates over-lifetime curves, kills expired particles returns to pool
   - Write phase: composes instance matrices, writes color/alpha/sprite-frame to GPU buffers, sets mesh.count to alive count
3. On Game unmount, all emitters are destroyed, GPU resources are disposed, and the singleton is reset.
---
 Zero-GC Architecture
- SoA Structure-of-Arrays: Particle data stored as 26 pre-allocated Float32Arrays position, velocity, age, color, etc. for cache-friendly iteration
- Free-list pool: Dead particle indices recycled via a stack — no object allocation in the hot path
- Pre-allocated temporaries: Reusable Matrix4, Vector3, Quaternion, Color objects for per-frame computation
- GPU instancing: One InstancedMesh per emitter — single draw call regardless of particle count
---
 Frame Priority
Particles run after tweens -15 so tween-animated emitter positions are up-to-date. They run before lateUpdate -10 so late-update code sees current particle state.
---
 API
 getParticleManager
Returns the singleton ParticleManager instance. Creates one if it doesn't exist.
 destroyParticleManager
Disposes all emitters, frees GPU resources, and destroys the singleton. Called automatically when Game unmounts.
 Emitter Lifecycle
 Method  Description 
---------------------
 createEmitterconfig  Create and register a new emitter. Returns a unique ID string 
 destroyEmitterid  Remove an emitter and dispose its GPU resources 
 getEmitterid  Get an EmitterInstance by ID for imperative control 
 Global Controls
 Method  Description 
---------------------
 setModemode  Set world mode "2d" or "3d". Called automatically by ParticleFlush 
 tickdelta  Advance all emitters by delta seconds. Called by ParticleFlush 
 dispose  Destroy all emitters and free resources 
 EmitterInstance Controls
Each EmitterInstance returned by getEmitter exposes:
 Method  Description 
---------------------
 start  Start continuous emission 
 stop  Stop emission alive particles finish their lifetime 
 clear  Stop and kill all particles immediately 
 reset  Reset to initial state 
 burstcount?  Emit a burst of particles 
 setRaterate  Change stream emission rate 
 getActiveCount  Number of alive particles 
 isEmitting  Whether currently emitting 
---
 Preset Registry
---
 Usage
Most game code should use the useParticles../hooks/use-particles.md hook or <ParticleEmitter../components/particle-emitter.md component, which provide auto-cleanup on unmount. Direct manager access is useful for systems-level code:
---
 Type Definitions
See Types../types/index.md for ParticleEmitterConfig, ParticlePreset, EmitterShapeConfig, ParticlePropertyConfig, OverLifetimeConfig, ValueRange, ColorRange, LifetimeCurve, ColorGradient, BurstConfig, SpriteSheetConfig, and ParticleBlendMode.