react-three-game

react-three-game

React Three Game mounts serializable prefab documents as native React Three Fiber scenes. Components define the vocabulary; prefab JSON composes that vocabulary into entities.

Core model

Scope	Meaning	API
Scene	The outer R3F scene shared by composed prefabs	useScene() → { root, mode }
Prefab	One serializable document with local node ids and shared materials	usePrefab() → PrefabApi
Node	One entity in the active prefab	useNode(), useNodeObject(), useNodeHandle()
Component	A registered renderer/editor capability selected by type	registerComponent(component)

Child prefabs inherit the parent scene and receive their own prefab document scope.

Package entrypoints

Import	Contents
react-three-game	GameCanvas, PrefabRoot, scene/prefab/node hooks, component registration, events, types, loaders
react-three-game/editor	PrefabEditor, editor ref/context, fields, prefab-store hooks, import/export tools
react-three-game/plugins/crashcat	Crashcat runtime, authored physics component, ragdoll helpers

Prefab syntax

interface Prefab {
  id?: string;
  name?: string;
  materials?: Record<string, PrefabMaterial>;
  root: GameObject;
}

interface GameObject {
  id: string;
  name?: string;
  disabled?: boolean;
  hidden?: boolean;
  locked?: boolean;
  components?: Record<string, ComponentData | undefined>;
  children?: GameObject[];
}

interface ComponentData<P extends object = Record<string, unknown>> {
  type: string;
  properties: P;
}

Use stable ids, local transforms, radians, and asset paths resolved from basePath.

{
  "id": "starter",
  "name": "Starter Scene",
  "materials": {
    "crate": {
      "name": "Crate",
      "materialType": "standard",
      "color": "#d97706",
      "roughness": 0.7,
      "metalness": 0.1
    }
  },
  "root": {
    "id": "root",
    "children": [
      {
        "id": "camera",
        "components": {
          "transform": {
            "type": "Transform",
            "properties": {
              "position": [0, 3, 8],
              "rotation": [-0.25, 0, 0],
              "scale": [1, 1, 1]
            }
          },
          "camera": {
            "type": "Camera",
            "properties": { "projection": "perspective", "fov": 50 }
          }
        }
      },
      {
        "id": "crate",
        "components": {
          "transform": {
            "type": "Transform",
            "properties": {
              "position": [0, 0.5, 0],
              "rotation": [0, 0, 0],
              "scale": [1, 1, 1]
            }
          },
          "mesh": {
            "type": "Mesh",
            "properties": { "castShadow": true, "receiveShadow": true }
          },
          "geometry": {
            "type": "Geometry",
            "properties": { "geometryType": "box", "args": [1, 1, 1] }
          },
          "material": {
            "type": "Material",
            "properties": { "materialId": "crate" }
          }
        }
      }
    ]
  }
}

Component composition

Components on a node compose like R3F children:

<mesh>
  <boxGeometry attach="geometry" />
  <meshStandardMaterial attach="material" />
  {children}
</mesh>

Built-in role	Components	Composition
Transform	Transform	Applies the node's outer position, rotation, and scale
Object	Mesh, Model, Sprite, Text, lights, Camera	Owns the node's Three.js object slot
Attachment	Geometry, BufferGeometry, Material	Attaches to the enclosing object
Wrapper	Sound, Data, PrefabRef, custom behavior	Wraps the composed object and children

Materials live in Prefab.materials. A Material component selects one with materialId; every reference in that prefab shares the same Three.js material object. attach supports R3F attachment paths such as material.

Mounting

Runtime:

import { GameCanvas, PrefabRoot, type Prefab } from 'react-three-game';
import sceneJson from './scene.json';

const prefab = sceneJson as Prefab;

export function Game() {
  return (
    <GameCanvas>
      <PrefabRoot data={prefab} basePath="/game" />
    </GameCanvas>
  );
}

Editor:

import { PrefabEditor } from 'react-three-game/editor';

export function Authoring() {
  return <PrefabEditor prefab={prefab} basePath="/game" />;
}

PrefabRoot.data and PrefabEditor.prefab are document inputs. A new object value loads the new document. Editor mutations update the current document and ref.save() returns it. PrefabEditor.mode defaults to PrefabEditorMode.Edit and responds to new prop values.

Runtime scopes

import { useFrame } from '@react-three/fiber';
import {
  PrefabEditorMode,
  usePrefab,
  useScene,
} from 'react-three-game';

function SceneRuntime() {
  const scene = useScene();
  const prefab = usePrefab();

  useFrame((_, delta) => {
    if (scene.mode !== PrefabEditorMode.Play) return;
    const crate = prefab.getObject('crate');
    if (crate) crate.rotation.y += delta;
  });

  return null;
}

Hook	Useful members
useScene()	root, mode
usePrefab()	root, basePath, node/material CRUD, live objects, handles, loaded assets
useNode()	nodeId, editMode, isSelected, interaction handlers, current-node getters
useNodeObject<T>()	Live ref for the current node's Object3D
useNodeHandle<T>(kind)	Live ref for a current-node runtime handle
useAssetRuntime()	Shared model, texture, and sound cache

Core PrefabApi syntax:

prefab.get(id);
prefab.getObject(id);
prefab.getHandle(id, kind);
prefab.getModel(path);
prefab.getMaterial(materialId);

prefab.add(node, parentId);
prefab.update(id, node => nextNode);
prefab.setMaterial(materialId, material);
prefab.replaceNode(id, node);
prefab.remove(id);
prefab.duplicate(id);
prefab.move(id, targetId, 'inside');
prefab.replace(nextPrefab);

Authored changes use prefab mutations. Frame-by-frame motion uses live Three.js objects.

Custom components

Component fields infer their property names and value types from FieldDefinition<P>.

import { useFrame } from '@react-three/fiber';
import {
  registerComponent,
  useNode,
  useNodeObject,
  type Component,
  type ComponentViewProps,
} from 'react-three-game';
import {
  FieldRenderer,
  type ComponentEditorProps,
  type FieldDefinition,
} from 'react-three-game/editor';

type RotatorProperties = {
  speed?: number;
  axis?: 'x' | 'y' | 'z';
};

const fields = [
  { name: 'speed', type: 'number', label: 'Speed', step: 0.1 },
  {
    name: 'axis',
    type: 'select',
    label: 'Axis',
    options: [
      { value: 'x', label: 'X' },
      { value: 'y', label: 'Y' },
      { value: 'z', label: 'Z' },
    ],
  },
] satisfies FieldDefinition<RotatorProperties>[];

function RotatorEditor({ properties, update }: ComponentEditorProps<RotatorProperties>) {
  return <FieldRenderer fields={fields} values={properties} onChange={update} />;
}

function RotatorView({ properties, children }: ComponentViewProps<RotatorProperties>) {
  const { editMode } = useNode();
  const objectRef = useNodeObject();

  useFrame((_, delta) => {
    const object = objectRef.current;
    if (editMode || !object) return;
    object.rotation[properties.axis ?? 'y'] += delta * (properties.speed ?? 1);
  });

  return <>{children}</>;
}

const Rotator: Component<RotatorProperties> = {
  name: 'Rotator',
  Editor: RotatorEditor,
  View: RotatorView,
  defaultProperties: { speed: 1, axis: 'y' },
};

registerComponent(Rotator);

JSON usage:

{
  "rotator": {
    "type": "Rotator",
    "properties": { "speed": 1.5, "axis": "y" }
  }
}

Handles and events

import { useEffect, useRef } from 'react';
import {
  useNode,
  usePrefab,
  type ComponentViewProps,
} from 'react-three-game';

function DoorView({ children }: ComponentViewProps) {
  const { nodeId } = useNode();
  const prefab = usePrefab();
  const open = useRef(false);

  useEffect(() => {
    const handle = { open: () => { open.current = true; } };
    prefab.registerHandle(nodeId, 'door', handle);
    return () => prefab.registerHandle(nodeId, 'door', null);
  }, [nodeId, prefab]);

  return <>{children}</>;
}

Communication	Syntax
Broadcast	gameEvents.emit(name, payload) / useGameEvent(name, handler, deps)
Cross-node handle	prefab.getHandle<T>(nodeId, kind)
Current-node handle	useNodeHandle<T>(kind).current
Node pointer stream	onPointerEvent={(type, event, node) => ...}
Named click	Mesh.properties.emitClickEvent + clickEventName

Nested prefabs and cameras

{
  "id": "room-instance",
  "components": {
    "prefab": {
      "type": "PrefabRef",
      "properties": { "url": "/prefabs/room.json" }
    }
  }
}

Each nested prefab keeps local node ids and materials while sharing the outer scene mode. Camera nodes become the default camera in Play mode and render as wireframes in Edit mode.

Built-ins

Category	Components
Core	Transform, Mesh, Geometry, BufferGeometry, Material
Assets	Model, Sprite, Text, Sound, PrefabRef
Scene	Camera, Environment, AmbientLight, DirectionalLight, PointLight, SpotLight
Data	Data

Focused references

Task	Reference
Runtime managers, handles, events	rules/RUNTIME_INTEGRATIONS.md
Crashcat physics	rules/ADVANCED_PHYSICS.md
Authored lighting and shadows	rules/LIGHTING.md
Frame loops, instancing, streaming	rules/PERFORMANCE.md

Validate consuming projects with a production build and exercise component behavior in Edit and Play modes.