react-three-game 0.0.82 → 0.0.84

package/README.md

@@ -110,6 +110,16 @@ That means a saved scene is just a prefab, and the same prefab can be:
 * rendered directly with `PrefabRoot`
 * loaded inside another scene as reusable content
 
+`PrefabRoot` keeps the rendering model narrow and compositional:
+
+* `Transform` is the renderer-owned outer transform
+* `Geometry` + `Material` become the primary mesh content
+* non-instanced `Model` becomes the node's primary content
+* `Physics` is a renderer-owned outer wrapper
+* every other component `View` wraps the current subtree
+
+Custom component `View`s use normal React Three Fiber composition with `children`.
+
 ## Prefab Format
 
 ```ts
@@ -131,7 +141,7 @@ interface GameObject {
 
 ## Runtime Mutation
 
-When you need to change the live world, use the `Scene` API from `PrefabEditorRef`.
+Use the `Scene` API from `PrefabEditorRef` for authored state changes that should stay in prefab data.
 
 ```tsx
 import { useEffect, useRef } from "react";
@@ -153,21 +163,59 @@ function RaiseBall() {
 }
 ```
 
+Batch related entity changes so they flush as one store revision:
+
+```tsx
+scene.batch(() => {
+  scene.find("orb1")?.getComponent("Transform")?.set("position", [1, 0, 0]);
+  scene.find("orb2")?.getComponent("Transform")?.set("position", [-1, 0, 0]);
+});
+```
+
+Define a component runtime factory with `create(ctx)` for hot runtime behavior that mutates the live Three.js object directly:
+
+```tsx
+import type { Component } from "react-three-game";
+
+const Rotator: Component = {
+  name: "Rotator",
+  Editor: () => null,
+  defaultProperties: { speed: 1 },
+  create(ctx) {
+    return {
+      update(dt) {
+        const speed = ctx.component.get<number>("speed") ?? 1;
+        ctx.object.rotation.y += dt * speed;
+      },
+    };
+  },
+};
+```
+
+`View` handles composition and rendering. `create(ctx)` handles imperative runtime behavior.
+
 ## Useful Exports
 
 * `GameCanvas`
 * `PrefabRoot`
 * `PrefabEditor`
+* `PrefabEditorMode`
 * `Prefab`
 * `GameObject`
 * `Scene`
 * `Entity`
 * `EntityComponent`
 * `registerComponent`
+* `createPrefabStore`
+* `usePrefabStoreApi`
+* `useAssetRuntime()` / `useEntityRuntime()`
+* `useEntityObjectRef()` / `useEntityRigidBodyRef()`
 * `ground(...)`
 * `loadJson()` / `saveJson()`
 * `loadModel()` / `loadTexture()`
-* `exportGLB()` / `exportGLBData()`
+* `loadSound()` / `loadFiles()`
+* `exportGLB()`
+* `computeParentWorldMatrix()`
 
 ## Development
 

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export { default as GameCanvas } from './shared/GameCanvas';
 export type { GameCanvasProps } from './shared/GameCanvas';
-export { useBeforePhysicsStep, useAfterPhysicsStep, useRapier } from '@react-three/rapier';
 export { ground } from './helpers';
 export type { GroundOptions, Vec3 } from './helpers';
 export { sound as soundManager } from './helpers/SoundManager';
@@ -21,12 +20,16 @@ export { createModelNode, createImageNode, } from './tools/prefabeditor/prefab';
 export type { PrefabEditorProps, PrefabEditorRef, } from './tools/prefabeditor/PrefabEditor';
 export type { SpawnOptions, Scene, Entity, EntityComponent, EntityData, EntityUpdate, PropertyPath, SceneUpdates, } from './tools/prefabeditor/scene';
 export type { PrefabRootProps } from './tools/prefabeditor/PrefabRoot';
-export type { AssetRuntime, EntityRuntime, LiveObjectRef, LiveRigidBodyRef } from './tools/prefabeditor/runtimeContext';
-export { useAssetRuntime, useEntityRuntime, useEntityObjectRef, useEntityRigidBodyRef } from './tools/prefabeditor/runtimeContext';
+export type { AssetRuntime, EntityRuntime, LiveObjectRef, LiveRigidBodyRef } from './tools/prefabeditor/runtime';
+export { useAssetRuntime, useEntityRuntime, useEntityObjectRef, useEntityRigidBodyRef } from './tools/prefabeditor/runtime';
+export type { ComponentInstance, ComponentRuntimeContext } from './tools/prefabeditor/runtime';
 export type { Component, ComponentViewProps } from './tools/prefabeditor/components/ComponentRegistry';
 export type { FieldDefinition, FieldType } from './tools/prefabeditor/components/Input';
+export { MaterialOverridesProvider, useMaterialOverrides } from './tools/prefabeditor/components/MaterialComponent';
+export type { MaterialOverrides } from './tools/prefabeditor/components/MaterialComponent';
 export type { Prefab, GameObject, ComponentData } from './tools/prefabeditor/types';
 export { findComponent, findComponentEntry, hasComponent } from './tools/prefabeditor/types';
+export { float, positionLocal, sin, time, uniform, vec3, } from 'three/tsl';
 export { gameEvents, useGameEvent, usePhysicsEvent, useClickEvent, getEntityIdFromRigidBody } from './tools/prefabeditor/GameEvents';
 export type { GameEventType, GameEventMap, GameEventPayload, PhysicsEventType, InteractionEventType, PhysicsEventPayload, ClickEventPayload } from './tools/prefabeditor/GameEvents';
 export { loadFiles } from './tools/dragdrop/DragDropLoader';

package/dist/index.js

@@ -1,6 +1,5 @@
 // Core
 export { default as GameCanvas } from './shared/GameCanvas';
-export { useBeforePhysicsStep, useAfterPhysicsStep, useRapier } from '@react-three/rapier';
 // Helpers
 export { ground } from './helpers';
 export { sound as soundManager } from './helpers/SoundManager';
@@ -20,8 +19,10 @@ export { FieldRenderer, FieldGroup, ListEditor, Label, Vector3Input, Vector3Fiel
 // Prefab Editor - Utils
 export { loadJson, saveJson, exportGLB, exportGLBData, regenerateIds, computeParentWorldMatrix, } from './tools/prefabeditor/utils';
 export { createModelNode, createImageNode, } from './tools/prefabeditor/prefab';
-export { useAssetRuntime, useEntityRuntime, useEntityObjectRef, useEntityRigidBodyRef } from './tools/prefabeditor/runtimeContext';
+export { useAssetRuntime, useEntityRuntime, useEntityObjectRef, useEntityRigidBodyRef } from './tools/prefabeditor/runtime';
+export { MaterialOverridesProvider, useMaterialOverrides } from './tools/prefabeditor/components/MaterialComponent';
 export { findComponent, findComponentEntry, hasComponent } from './tools/prefabeditor/types';
+export { float, positionLocal, sin, time, uniform, vec3, } from 'three/tsl';
 // Game Events (physics + custom events)
 export { gameEvents, useGameEvent, usePhysicsEvent, useClickEvent, getEntityIdFromRigidBody } from './tools/prefabeditor/GameEvents';
 // Asset Loading

package/dist/tools/prefabeditor/PrefabRoot.js

@@ -13,6 +13,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useHelper } from "@react-three/drei";
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { BoxHelper, Euler, Matrix4, } from "three";
+import { useFrame } from "@react-three/fiber";
 import { useStore } from "zustand";
 import { useClickValid } from "./useClickValid";
 import { findComponent } from "./types";
@@ -22,9 +23,8 @@ import { loadModel, loadSound, loadTexture } from "../dragdrop";
 import { GameInstance, GameInstanceProvider, getRepeatAxesFromModelProperties, useInstanceCheck } from "./InstanceProvider";
 import { composeTransform, decompose } from "./utils";
 import { isPhysicsProps } from "./components/PhysicsComponent";
-import { denormalizePrefab } from "./prefab";
 import { createPrefabStore, PrefabStoreProvider, useOptionalPrefabStoreApi, usePrefabChildIds, usePrefabNode, usePrefabRootId } from "./prefabStore";
-import { AssetRuntimeContext, EntityRuntimeScope } from "./runtimeContext";
+import { AssetRuntimeContext, EntityRuntimeScope, createRuntimeEngine } from "./runtime";
 import { sound as soundManager } from "../../helpers/SoundManager";
 builtinComponents.forEach(registerComponent);
 const IDENTITY = new Matrix4();
@@ -61,7 +61,13 @@ export const PrefabRoot = forwardRef(({ editMode, data, store, selectedId, onSel
     const rigidBodyRefs = useRef(new Map());
     const rootRef = useRef(null);
     const parentStore = useOptionalPrefabStoreApi();
-    const [ownedStore] = useState(() => { var _a, _b; return createPrefabStore(data !== null && data !== void 0 ? data : denormalizePrefab((_b = (_a = store === null || store === void 0 ? void 0 : store.getState()) !== null && _a !== void 0 ? _a : parentStore === null || parentStore === void 0 ? void 0 : parentStore.getState()) !== null && _b !== void 0 ? _b : missingStoreState())); });
+    const [ownedStore] = useState(() => {
+        if (data)
+            return createPrefabStore(data);
+        if (store || parentStore)
+            return null;
+        throw new Error("PrefabRoot requires either a `data` or `store` prop");
+    });
     const resolvedStore = (_a = store !== null && store !== void 0 ? store : parentStore) !== null && _a !== void 0 ? _a : ownedStore;
     const usesOwnedStore = resolvedStore === ownedStore;
     const shouldProvideStoreContext = !parentStore || parentStore !== resolvedStore;
@@ -73,6 +79,10 @@ export const PrefabRoot = forwardRef(({ editMode, data, store, selectedId, onSel
         var _a;
         return (_a = objectRefs.current[id]) !== null && _a !== void 0 ? _a : null;
     }, []);
+    const getRigidBody = useCallback((id) => {
+        var _a;
+        return (_a = rigidBodyRefs.current.get(id)) !== null && _a !== void 0 ? _a : null;
+    }, []);
     useImperativeHandle(ref, () => ({
         root: rootRef.current,
         getObject,
@@ -84,17 +94,29 @@ export const PrefabRoot = forwardRef(({ editMode, data, store, selectedId, onSel
             setInjectedSounds(prev => (Object.assign(Object.assign({}, prev), { [path]: sound })));
         },
     }), [getObject]);
+    const runtimeEngine = useMemo(() => createRuntimeEngine({
+        store: resolvedStore,
+        getObject,
+        getRigidBody,
+    }), [resolvedStore, getObject, getRigidBody]);
     const registerRef = useCallback((id, obj) => {
         objectRefs.current[id] = obj;
+        runtimeEngine.invalidate();
         onObjectRefChange === null || onObjectRefChange === void 0 ? void 0 : onObjectRefChange(id, obj);
-    }, [onObjectRefChange]);
+    }, [onObjectRefChange, runtimeEngine]);
     const registerRigidBodyRef = useCallback((id, rb) => {
         rigidBodyRefs.current.set(id, rb);
-    }, []);
-    const getRigidBody = useCallback((id) => {
-        var _a;
-        return (_a = rigidBodyRefs.current.get(id)) !== null && _a !== void 0 ? _a : null;
-    }, []);
+        runtimeEngine.invalidate();
+    }, [runtimeEngine]);
+    useEffect(() => {
+        runtimeEngine.setActive(!editMode);
+    }, [editMode, runtimeEngine]);
+    useEffect(() => {
+        return () => runtimeEngine.dispose();
+    }, [runtimeEngine]);
+    useFrame((_, dt) => {
+        runtimeEngine.tick(dt);
+    });
     useEffect(() => {
         if (usesOwnedStore && data) {
             resolvedStore.getState().replacePrefab(data);
@@ -157,26 +179,15 @@ export const PrefabRoot = forwardRef(({ editMode, data, store, selectedId, onSel
         };
         syncAssets();
     }, [resolvedStore, assetManifestKey, basePath, injectedModels, injectedSounds, injectedTextures, models, sounds, textures]);
-    // Keep refs current so context getters are always fresh without changing context identity
-    const availableModelsRef = useRef(availableModels);
-    availableModelsRef.current = availableModels;
-    const availableTexturesRef = useRef(availableTextures);
-    availableTexturesRef.current = availableTextures;
-    const availableSoundsRef = useRef(availableSounds);
-    availableSoundsRef.current = availableSounds;
     const assetRuntime = useMemo(() => ({
         getObject,
         getRigidBody,
         registerRigidBodyRef,
-        getModel: (path) => { var _a; return (_a = availableModelsRef.current[path]) !== null && _a !== void 0 ? _a : null; },
-        getTexture: (path) => { var _a; return (_a = availableTexturesRef.current[path]) !== null && _a !== void 0 ? _a : null; },
-        getSound: (path) => { var _a; return (_a = availableSoundsRef.current[path]) !== null && _a !== void 0 ? _a : null; },
-        getAssetRevision: () => {
-            const modelKeys = Object.keys(availableModelsRef.current).sort().join('|');
-            const textureKeys = Object.keys(availableTexturesRef.current).sort().join('|');
-            return `${textureKeys}::${modelKeys}`;
-        },
-    }), [getObject, getRigidBody, registerRigidBodyRef]);
+        getModel: (path) => { var _a; return (_a = availableModels[path]) !== null && _a !== void 0 ? _a : null; },
+        getTexture: (path) => { var _a; return (_a = availableTextures[path]) !== null && _a !== void 0 ? _a : null; },
+        getSound: (path) => { var _a; return (_a = availableSounds[path]) !== null && _a !== void 0 ? _a : null; },
+        getAssetRevision: () => `${Object.keys(availableTextures).sort().join('|')}::${Object.keys(availableModels).sort().join('|')}`,
+    }), [getObject, getRigidBody, registerRigidBodyRef, availableModels, availableTextures, availableSounds]);
     const content = (_jsx("group", { ref: rootRef, children: _jsx(GameInstanceProvider, { models: availableModels, selectedId: selectedId, editMode: editMode, onSelect: editMode ? onSelect : undefined, registerRef: registerRef, children: _jsx(StoreRootNode, { selectedId: selectedId, onSelect: editMode ? onSelect : undefined, onClick: onClick, registerRef: registerRef, loadedModels: availableModels, editMode: editMode, parentMatrix: IDENTITY }) }) }));
     if (!shouldProvideStoreContext) {
         return _jsx(AssetRuntimeContext.Provider, { value: assetRuntime, children: content });
@@ -197,6 +208,7 @@ export function GameObjectRenderer(props) {
         if (prevInstancedRef.current !== undefined && prevInstancedRef.current !== isInstanced) {
             setIsTransitioning(true);
             const timer = setTimeout(() => setIsTransitioning(false), 100);
+            prevInstancedRef.current = isInstanced;
             return () => clearTimeout(timer);
         }
         prevInstancedRef.current = isInstanced;
@@ -225,18 +237,18 @@ function InstancedNode({ nodeId, parentMatrix = IDENTITY, editMode, registerRef,
     const modelUrl = (_c = (_b = findComponent(gameObject, "Model")) === null || _b === void 0 ? void 0 : _b.properties) === null || _c === void 0 ? void 0 : _c.filename;
     const instances = useMemo(() => buildRepeatedInstances(gameObject, parentMatrix, modelUrl, physicsProps), [gameObject, modelUrl, parentMatrix, physicsProps]);
     const groupRef = useRef(null);
+    const handleGroupRef = useCallback((object) => {
+        groupRef.current = object;
+        if (editMode) {
+            registerRef(nodeId, object);
+        }
+    }, [editMode, nodeId, registerRef]);
     const editClickHandlers = useClickValid(!!editMode && !isLocked, (e) => {
         onSelect === null || onSelect === void 0 ? void 0 : onSelect(nodeId);
         onClick === null || onClick === void 0 ? void 0 : onClick(e, gameObject);
     });
-    useEffect(() => {
-        if (editMode) {
-            registerRef(nodeId, groupRef.current);
-            return () => registerRef(nodeId, null);
-        }
-    }, [nodeId, registerRef, editMode]);
     if (editMode) {
-        return (_jsxs(_Fragment, { children: [_jsx("group", Object.assign({ ref: groupRef, position: localTransform.position, rotation: localTransform.rotation, scale: localTransform.scale }, editClickHandlers, { children: _jsx("mesh", { visible: false, children: _jsx("boxGeometry", { args: [0.01, 0.01, 0.01] }) }) })), instances.map(instance => (_jsx(GameInstance, { id: instance.id, sourceId: gameObject.id, clickable: clickable, clickEventName: clickEventName, modelUrl: instance.modelUrl, position: instance.position, rotation: instance.rotation, scale: instance.scale, locked: isLocked, physics: instance.physics }, instance.id)))] }));
+        return (_jsxs(_Fragment, { children: [_jsx("group", Object.assign({ ref: handleGroupRef, position: localTransform.position, rotation: localTransform.rotation, scale: localTransform.scale }, editClickHandlers, { children: _jsx("mesh", { visible: false, children: _jsx("boxGeometry", { args: [0.01, 0.01, 0.01] }) }) })), instances.map(instance => (_jsx(GameInstance, { id: instance.id, sourceId: gameObject.id, clickable: clickable, clickEventName: clickEventName, modelUrl: instance.modelUrl, position: instance.position, rotation: instance.rotation, scale: instance.scale, locked: isLocked, physics: instance.physics }, instance.id)))] }));
     }
     return (_jsx(_Fragment, { children: instances.map(instance => (_jsx(GameInstance, { id: instance.id, sourceId: gameObject.id, clickable: clickable, clickEventName: clickEventName, modelUrl: instance.modelUrl, position: instance.position, rotation: instance.rotation, scale: instance.scale, locked: isLocked, physics: instance.physics }, instance.id))) }));
 }
@@ -245,21 +257,25 @@ function StandardNode({ nodeId, selectedId, onSelect, onClick, registerRef, load
     const gameObject = usePrefabNode(nodeId);
     const childIds = usePrefabChildIds(nodeId);
     const isSelected = selectedId === nodeId;
-    if (!gameObject)
-        return null;
+    const isLocked = Boolean(gameObject === null || gameObject === void 0 ? void 0 : gameObject.locked);
+    const stillInstanced = useInstanceCheck(nodeId);
     const groupRef = useRef(null);
     const helperRef = useRef(null);
-    const isLocked = Boolean(gameObject.locked);
-    const stillInstanced = useInstanceCheck(nodeId);
+    const handleGroupRef = useCallback((object) => {
+        groupRef.current = object;
+        registerRef(nodeId, object);
+    }, [nodeId, registerRef]);
+    const handleHelperRef = useCallback((object) => {
+        helperRef.current = object;
+    }, []);
     const clickHandlers = useClickValid(!!editMode && !isLocked, (e) => {
         onSelect === null || onSelect === void 0 ? void 0 : onSelect(nodeId);
-        onClick === null || onClick === void 0 ? void 0 : onClick(e, gameObject);
+        if (gameObject)
+            onClick === null || onClick === void 0 ? void 0 : onClick(e, gameObject);
     });
     useHelper(editMode && isSelected ? helperRef : null, BoxHelper, "cyan");
-    useEffect(() => {
-        registerRef(nodeId, groupRef.current);
-        return () => registerRef(nodeId, null);
-    }, [nodeId, registerRef]);
+    if (!gameObject)
+        return null;
     const world = parentMatrix.clone().multiply(compose(gameObject));
     const physics = findComponent(gameObject, "Physics");
     const ready = isNodeReady(gameObject, loadedModels);
@@ -272,7 +288,7 @@ function StandardNode({ nodeId, selectedId, onSelect, onClick, registerRef, load
     const childNodes = _jsx(ChildNodes, { childIds: childIds, parentMatrix: world, selectedId: selectedId, onSelect: onSelect, onClick: onClick, registerRef: registerRef, loadedModels: loadedModels, editMode: editMode });
     const inner = (_jsx("group", Object.assign({}, clickHandlers, { children: renderCompositionNode(gameObject, renderCtx, childNodes) })));
     const physicsInner = editMode ? _jsx("group", { visible: false, children: inner }) : inner;
-    return (_jsx(EntityRuntimeScope, { nodeId: nodeId, editMode: editMode, isSelected: isSelected, children: editMode ? (_jsxs(_Fragment, { children: [_jsx("group", { ref: groupRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: _jsx("mesh", { visible: false, children: _jsx("boxGeometry", { args: [0.01, 0.01, 0.01] }) }) }), _jsx("group", { ref: helperRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: inner }), hasPhysics && (physicsDef === null || physicsDef === void 0 ? void 0 : physicsDef.View) ? (_jsx(physicsDef.View, { properties: physics.properties, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: physicsInner }, physicsKey)) : null] })) : hasPhysics && (physicsDef === null || physicsDef === void 0 ? void 0 : physicsDef.View) ? (_jsx(physicsDef.View, { properties: physics.properties, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: inner }, physicsKey)) : (_jsx("group", { ref: groupRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: inner })) }));
+    return (_jsx(EntityRuntimeScope, { nodeId: nodeId, editMode: editMode, isSelected: isSelected, children: editMode ? (_jsxs(_Fragment, { children: [_jsx("group", { ref: handleGroupRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: _jsx("mesh", { visible: false, children: _jsx("boxGeometry", { args: [0.01, 0.01, 0.01] }) }) }), _jsx("group", { ref: handleHelperRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: inner }), hasPhysics && (physicsDef === null || physicsDef === void 0 ? void 0 : physicsDef.View) ? (_jsx(physicsDef.View, { properties: physics.properties, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: physicsInner }, physicsKey)) : null] })) : hasPhysics && (physicsDef === null || physicsDef === void 0 ? void 0 : physicsDef.View) ? (_jsx(physicsDef.View, { properties: physics.properties, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: inner }, physicsKey)) : (_jsx("group", { ref: handleGroupRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, children: inner })) }));
 }
 function isRendererHandledComponent(componentType) {
     return componentType === "Transform"
@@ -284,7 +300,6 @@ function isRendererHandledComponent(componentType) {
 function getCompositionComponents(gameObject) {
     var _a;
     return Object.entries((_a = gameObject.components) !== null && _a !== void 0 ? _a : {}).reduce((result, [key, comp]) => {
-        var _a;
         if (!(comp === null || comp === void 0 ? void 0 : comp.type) || isRendererHandledComponent(comp.type))
             return result;
         const def = getComponentDef(comp.type);
@@ -294,7 +309,6 @@ function getCompositionComponents(gameObject) {
             key,
             View: def.View,
             properties: comp.properties,
-            composition: (_a = def.composition) !== null && _a !== void 0 ? _a : "wrap",
         });
         return result;
     }, []);
@@ -394,11 +408,6 @@ function renderNodePrimaryContent(gameObject, ctx) {
 }
 function applyNodeComposition(gameObject, subtree) {
     const components = getCompositionComponents(gameObject);
-    return components.reduce((acc, { key, View, properties, composition }) => composition === "sibling"
-        ? (_jsxs(_Fragment, { children: [_jsx(View, { properties: properties }, key), acc] }))
-        : (_jsx(View, { properties: properties, children: acc }, key)), subtree);
+    return components.reduce((acc, { key, View, properties }) => (_jsx(View, { properties: properties, children: acc }, key)), subtree);
 }
 export default PrefabRoot;
-function missingStoreState() {
-    throw new Error("PrefabRoot requires either data or store");
-}

package/dist/tools/prefabeditor/components/CameraComponent.js

@@ -3,7 +3,7 @@ import { OrthographicCamera, PerspectiveCamera, useHelper } from '@react-three/d
 import { useRef } from 'react';
 import { CameraHelper } from 'three';
 import { useFrame, useThree } from '@react-three/fiber';
-import { useEntityRuntime } from '../runtimeContext';
+import { useEntityRuntime } from '../runtime';
 import { FieldGroup, NumberField, SelectField } from './Input';
 const CAMERA_PROJECTION_OPTIONS = [
     { value: 'perspective', label: 'Perspective' },
@@ -66,7 +66,6 @@ const CameraComponent = {
     name: 'Camera',
     Editor: CameraComponentEditor,
     View: CameraComponentView,
-    composition: 'wrap',
     defaultProperties: cameraDefaults,
 };
 export default CameraComponent;

package/dist/tools/prefabeditor/components/ClickComponent.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useRef } from 'react';
 import { gameEvents } from '../GameEvents';
-import { useEntityRuntime } from '../runtimeContext';
+import { useEntityRuntime } from '../runtime';
 import { EventField, FieldGroup } from './Input';
 function ClickComponentEditor({ component, onUpdate }) {
     return (_jsxs(FieldGroup, { children: [_jsx("div", { style: { fontSize: 12, opacity: 0.8 }, children: "Emits a game event in play mode when this entity is clicked." }), _jsx(EventField, { name: "eventName", label: "Emit Event", values: component.properties, onChange: onUpdate, placeholder: "click" })] }));

package/dist/tools/prefabeditor/components/ComponentRegistry.d.ts

@@ -1,5 +1,6 @@
 import { FC } from "react";
 import { ComponentData, GameObject } from "../types";
+import type { ComponentInstance, ComponentRuntimeContext } from "../runtime";
 export type AssetRef = {
     type: "model" | "texture" | "sound";
     path: string;
@@ -27,11 +28,8 @@ export interface Component {
     }>;
     defaultProperties: any;
     View?: FC<ComponentViewProps>;
-    /**
-     * How this component participates in the implicit node composition pipeline.
-        * Defaults to `wrap`; `sibling` renders next to the current subtree.
-     */
-    composition?: "wrap" | "sibling";
+    /** Optional runtime factory for the non-React game loop. */
+    create?: (ctx: ComponentRuntimeContext) => ComponentInstance | void;
     /** Declare which asset paths this component references (for asset loading). */
     getAssetRefs?: (properties: Record<string, any>) => AssetRef[];
 }

package/dist/tools/prefabeditor/components/DirectionalLightComponent.js

@@ -2,8 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useHelper } from "@react-three/drei";
 import { useRef, useEffect, useState } from "react";
 import { useFrame } from "@react-three/fiber";
-import { CameraHelper, Vector3 } from "three";
-import { useEntityRuntime } from "../runtimeContext";
+import { CameraHelper } from "three";
+import { useEntityRuntime } from "../runtime";
 import { BooleanField, ColorField, NumberField, NumberInput, Vector3Input } from "./Input";
 import { LightSection, ShadowBiasField, mergeWithDefaults } from "./lightUtils";
 import { colors } from "../styles";
@@ -161,13 +161,7 @@ function DirectionalLightView({ properties, children }) {
             shadowCamera.updateMatrixWorld();
         }
     });
-    return (_jsxs(_Fragment, { children: [_jsx("directionalLight", { ref: directionalLightRef, color: color, intensity: intensity, castShadow: castShadow, "shadow-mapSize-width": shadowMapSize, "shadow-mapSize-height": shadowMapSize, "shadow-camera-near": shadowCameraNear, "shadow-camera-far": shadowCameraFar, "shadow-camera-top": shadowCameraTop, "shadow-camera-bottom": shadowCameraBottom, "shadow-camera-left": shadowCameraLeft, "shadow-camera-right": shadowCameraRight, "shadow-bias": shadowBias, "shadow-normalBias": shadowNormalBias, "shadow-autoUpdate": shadowAutoUpdate }), _jsx("object3D", { ref: targetRef, position: targetOffset }), editMode && isSelected && (_jsxs(_Fragment, { children: [_jsxs("mesh", { children: [_jsx("sphereGeometry", { args: [0.3, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true })] }), _jsxs("mesh", { position: targetOffset, children: [_jsx("sphereGeometry", { args: [0.2, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true, opacity: 0.5, transparent: true })] }), _jsxs("line", { children: [_jsx("bufferGeometry", { onUpdate: (geo) => {
-                                    const points = [
-                                        new Vector3(0, 0, 0),
-                                        new Vector3(targetOffset[0], targetOffset[1], targetOffset[2])
-                                    ];
-                                    geo.setFromPoints(points);
-                                } }), _jsx("lineBasicMaterial", { color: color, opacity: 0.6, transparent: true })] })] })), children] }));
+    return (_jsxs(_Fragment, { children: [_jsx("directionalLight", { ref: directionalLightRef, color: color, intensity: intensity, castShadow: castShadow, "shadow-mapSize-width": shadowMapSize, "shadow-mapSize-height": shadowMapSize, "shadow-camera-near": shadowCameraNear, "shadow-camera-far": shadowCameraFar, "shadow-camera-top": shadowCameraTop, "shadow-camera-bottom": shadowCameraBottom, "shadow-camera-left": shadowCameraLeft, "shadow-camera-right": shadowCameraRight, "shadow-bias": shadowBias, "shadow-normalBias": shadowNormalBias, "shadow-autoUpdate": shadowAutoUpdate }), _jsx("object3D", { ref: targetRef, position: targetOffset }), editMode && isSelected && (_jsxs(_Fragment, { children: [_jsxs("mesh", { children: [_jsx("sphereGeometry", { args: [0.3, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true })] }), _jsxs("mesh", { position: targetOffset, children: [_jsx("sphereGeometry", { args: [0.2, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true, opacity: 0.5, transparent: true })] }), _jsxs("line", { children: [_jsx("bufferGeometry", { children: _jsx("bufferAttribute", { attach: "attributes-position", args: [new Float32Array([0, 0, 0, targetOffset[0], targetOffset[1], targetOffset[2]]), 3] }) }), _jsx("lineBasicMaterial", { color: color, opacity: 0.6, transparent: true })] })] })), children] }));
 }
 const DirectionalLightComponent = {
     name: 'DirectionalLight',

package/dist/tools/prefabeditor/components/EnvironmentComponent.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Environment } from '@react-three/drei';
 import { FieldGroup, NumberField } from './Input';
-import { useAssetRuntime } from '../runtimeContext';
+import { useAssetRuntime } from '../runtime';
 function EnvironmentView({ properties, children, }) {
     const { getAssetRevision } = useAssetRuntime();
     const { intensity = 1, resolution = 256 } = properties;

package/dist/tools/prefabeditor/components/MaterialComponent.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from 'react';
 import type { ThreeElement } from '@react-three/fiber';
 import { Component } from './ComponentRegistry';
 import { MeshBasicNodeMaterial, MeshStandardNodeMaterial } from 'three/webgpu';
@@ -22,5 +23,11 @@ export interface MaterialProps extends Omit<MeshStandardMaterialProperties & Mes
     normalMapTexture?: string;
     normalScale?: [number, number];
 }
+export type MaterialOverrides = Record<string, unknown>;
+export declare function useMaterialOverrides(): MaterialOverrides;
+export declare function MaterialOverridesProvider({ overrides, children, }: {
+    overrides: MaterialOverrides;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
 declare const MaterialComponent: Component;
 export default MaterialComponent;

package/dist/tools/prefabeditor/components/MaterialComponent.js

@@ -10,13 +10,23 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
 import { extend } from '@react-three/fiber';
 import { FieldRenderer, Label, NumberInput } from './Input';
-import { useAssetRuntime } from '../runtimeContext';
-import { useMemo } from 'react';
+import { useAssetRuntime } from '../runtime';
 import { MeshBasicNodeMaterial, MeshStandardNodeMaterial } from 'three/webgpu';
 import { TexturePicker } from '../../assetviewer/page';
-import { RepeatWrapping, ClampToEdgeWrapping, SRGBColorSpace, LinearSRGBColorSpace, Vector2, NearestFilter, LinearFilter, NearestMipmapNearestFilter, NearestMipmapLinearFilter, LinearMipmapNearestFilter, LinearMipmapLinearFilter, FrontSide, BackSide, DoubleSide, } from 'three';
+import { RepeatWrapping, ClampToEdgeWrapping, SRGBColorSpace, LinearSRGBColorSpace, NearestFilter, LinearFilter, NearestMipmapNearestFilter, NearestMipmapLinearFilter, LinearMipmapNearestFilter, LinearMipmapLinearFilter, FrontSide, BackSide, DoubleSide, } from 'three';
+const EMPTY_MATERIAL_OVERRIDES = Object.freeze({});
+const MaterialOverridesContext = createContext(EMPTY_MATERIAL_OVERRIDES);
+export function useMaterialOverrides() {
+    return useContext(MaterialOverridesContext);
+}
+export function MaterialOverridesProvider({ overrides, children, }) {
+    const parent = useContext(MaterialOverridesContext);
+    const merged = useMemo(() => (Object.assign(Object.assign({}, parent), overrides)), [parent, overrides]);
+    return _jsx(MaterialOverridesContext.Provider, { value: merged, children: children });
+}
 extend({
     MeshBasicNodeMaterial,
     MeshStandardNodeMaterial,
@@ -121,7 +131,7 @@ function MaterialComponentEditor({ component, onUpdate, basePath = "" }) {
 }
 // View for Material component
 function MaterialComponentView({ properties: rawProps }) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f;
     const { getTexture } = useAssetRuntime();
     const properties = rawProps;
     const materialType = (_a = properties === null || properties === void 0 ? void 0 : properties.materialType) !== null && _a !== void 0 ? _a : 'standard';
@@ -181,21 +191,15 @@ function MaterialComponentView({ properties: rawProps }) {
         t.needsUpdate = true;
         return t;
     }, [normalMapTexture]);
-    const normalScaleVec = useMemo(() => {
-        var _a, _b;
-        if (!finalNormalMap)
-            return undefined;
-        return new Vector2((_a = normalScaleProp === null || normalScaleProp === void 0 ? void 0 : normalScaleProp[0]) !== null && _a !== void 0 ? _a : 1, (_b = normalScaleProp === null || normalScaleProp === void 0 ? void 0 : normalScaleProp[1]) !== null && _b !== void 0 ? _b : 1);
-    }, [finalNormalMap, normalScaleProp === null || normalScaleProp === void 0 ? void 0 : normalScaleProp[0], normalScaleProp === null || normalScaleProp === void 0 ? void 0 : normalScaleProp[1]]);
     if (!properties) {
         return _jsx("meshStandardNodeMaterial", { color: "red", wireframe: true });
     }
-    const materialKey = `${(_e = finalTexture === null || finalTexture === void 0 ? void 0 : finalTexture.uuid) !== null && _e !== void 0 ? _e : 'no-texture'}:${materialProps.transparent ? 'transparent' : 'opaque'}`;
-    const sharedProps = Object.assign({ map: finalTexture, side: resolvedSide }, materialProps);
+    const overrides = useMaterialOverrides();
+    const sharedProps = Object.assign(Object.assign({ map: finalTexture, side: resolvedSide }, materialProps), overrides);
     if (materialType === 'basic') {
-        return _jsx("meshBasicNodeMaterial", Object.assign({}, sharedProps), materialKey);
+        return _jsx("meshBasicNodeMaterial", Object.assign({}, sharedProps));
     }
-    return (_jsx("meshStandardNodeMaterial", Object.assign({}, sharedProps, { normalMap: finalNormalMap, normalScale: normalScaleVec }), materialKey));
+    return (_jsx("meshStandardNodeMaterial", Object.assign({}, sharedProps, { normalMap: finalNormalMap, normalScale: finalNormalMap ? [(_e = normalScaleProp === null || normalScaleProp === void 0 ? void 0 : normalScaleProp[0]) !== null && _e !== void 0 ? _e : 1, (_f = normalScaleProp === null || normalScaleProp === void 0 ? void 0 : normalScaleProp[1]) !== null && _f !== void 0 ? _f : 1] : undefined })));
 }
 const MaterialComponent = {
     name: 'Material',

package/dist/tools/prefabeditor/components/ModelComponent.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ModelPicker } from '../../assetviewer/page';
 import { useContext, useMemo } from 'react';
 import { BooleanField, FieldGroup, Label, ListEditor, NumberInput, SelectInput } from './Input';
-import { useAssetRuntime } from '../runtimeContext';
+import { useAssetRuntime } from '../runtime';
 import { EditorContext } from '../PrefabEditor';
 import { getRepeatAxesFromModelProperties, normalizeRepeatAxes } from '../InstanceProvider';
 import { colors } from '../styles';

package/dist/tools/prefabeditor/components/PhysicsComponent.js

@@ -12,7 +12,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { CapsuleCollider, RigidBody, useRapier } from "@react-three/rapier";
 import { useRef, useEffect, useCallback } from 'react';
-import { useAssetRuntime, useEntityRuntime } from "../runtimeContext";
+import { useAssetRuntime, useEntityRuntime } from "../runtime";
 import { BooleanField, EventInput, FieldGroup, ListEditor, NumberField, SelectField, SelectInput, Vector3Field } from "./Input";
 import { gameEvents, getEntityIdFromRigidBody } from "../GameEvents";
 import { colors } from "../styles";

package/dist/tools/prefabeditor/components/PointLightComponent.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useRef } from 'react';
 import { useHelper } from '@react-three/drei';
 import { PointLightHelper } from 'three';
-import { useEntityRuntime } from '../runtimeContext';
+import { useEntityRuntime } from '../runtime';
 import { BooleanField, ColorField, NumberField } from './Input';
 import { LightSection, ShadowBiasField, mergeWithDefaults } from './lightUtils';
 const pointLightDefaults = {

package/dist/tools/prefabeditor/components/SoundComponent.js

@@ -4,7 +4,7 @@ import { useThree } from '@react-three/fiber';
 import { SoundPicker } from '../../assetviewer/page';
 import { sound as soundManager } from '../../../helpers/SoundManager';
 import { gameEvents } from '../GameEvents';
-import { useAssetRuntime, useEntityRuntime } from '../runtimeContext';
+import { useAssetRuntime, useEntityRuntime } from '../runtime';
 import { BooleanField, EventField, FieldGroup, FieldRenderer, ListEditor, NumberField, SelectField } from './Input';
 import { colors } from '../styles';
 import { AudioListener } from 'three';
@@ -212,7 +212,6 @@ const SoundComponent = {
     name: 'Sound',
     Editor: SoundComponentEditor,
     View: SoundComponentView,
-    composition: 'sibling',
     defaultProperties: {
         eventName: '',
         clips: [],

package/dist/tools/prefabeditor/components/SpotLightComponent.js

@@ -3,7 +3,7 @@ import { useHelper } from "@react-three/drei";
 import { useRef, useEffect } from "react";
 import { BooleanField, ColorField, Label, NumberField, Vector3Input } from "./Input";
 import { SpotLightHelper } from "three";
-import { useAssetRuntime, useEntityRuntime } from "../runtimeContext";
+import { useAssetRuntime, useEntityRuntime } from "../runtime";
 import { useFrame } from "@react-three/fiber";
 import { TexturePicker } from "../../assetviewer/page";
 import { LightSection, ShadowBiasField, mergeWithDefaults } from "./lightUtils";

package/dist/tools/prefabeditor/runtime.d.ts

@@ -0,0 +1,61 @@
+import { type ReactNode } from "react";
+import type { Object3D, Texture } from "three";
+import type { PrefabStoreApi } from "./prefabStore";
+import { type EntityComponent, type Scene } from "./scene";
+export interface AssetRuntime {
+    registerRigidBodyRef: (id: string, rb: any) => void;
+    getModel: (path: string) => Object3D | null;
+    getTexture: (path: string) => Texture | null;
+    getSound: (path: string) => AudioBuffer | null;
+    getAssetRevision: () => string;
+    getObject: (id: string) => Object3D | null;
+    getRigidBody: (id: string) => any;
+}
+export interface AssetRuntimeContextValue extends AssetRuntime {
+}
+export interface EntityRuntime {
+    nodeId: string;
+    editMode?: boolean;
+    isSelected?: boolean;
+    getObject: <T extends Object3D = Object3D>() => T | null;
+    getRigidBody: <T = any>() => T | null;
+}
+export interface LiveRef<T> {
+    readonly current: T | null;
+}
+export type LiveObjectRef<T extends Object3D = Object3D> = LiveRef<T>;
+export type LiveRigidBodyRef<T = any> = LiveRef<T>;
+export declare const AssetRuntimeContext: import("react").Context<AssetRuntimeContextValue | null>;
+export declare function useAssetRuntime(): AssetRuntime;
+export declare function useEntityRuntime(): EntityRuntime;
+export declare function useEntityObjectRef<T extends Object3D = Object3D>(): LiveRef<T>;
+export declare function useEntityRigidBodyRef<T = any>(): LiveRef<T>;
+export declare function EntityRuntimeScope({ nodeId, editMode, isSelected, children, }: {
+    nodeId: string;
+    editMode?: boolean;
+    isSelected?: boolean;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Runtime behaviour produced by `Component.create(ctx)`. All methods optional. */
+export interface ComponentInstance {
+    start?(): void;
+    update?(dt: number): void;
+    destroy?(): void;
+}
+export interface ComponentRuntimeContext<TProperties = Record<string, any>> {
+    scene: Scene;
+    component: EntityComponent<TProperties>;
+    object: Object3D;
+    rigidBody: any;
+}
+export interface RuntimeEngine {
+    tick: (dt: number) => void;
+    setActive: (active: boolean) => void;
+    invalidate: () => void;
+    dispose: () => void;
+}
+export declare function createRuntimeEngine({ store, getObject, getRigidBody, }: {
+    store: PrefabStoreApi;
+    getObject: (id: string) => Object3D | null;
+    getRigidBody: (id: string) => any;
+}): RuntimeEngine;

package/dist/tools/prefabeditor/runtime.js

@@ -0,0 +1,184 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { getComponentDef } from "./components/ComponentRegistry";
+import { createScene } from "./scene";
+export const AssetRuntimeContext = createContext(null);
+const EntityRuntimeContext = createContext(null);
+export function useAssetRuntime() {
+    const ctx = useContext(AssetRuntimeContext);
+    if (!ctx)
+        throw new Error("useAssetRuntime must be used inside <PrefabRoot>");
+    return ctx;
+}
+export function useEntityRuntime() {
+    const ctx = useContext(EntityRuntimeContext);
+    if (!ctx)
+        throw new Error("useEntityRuntime must be used inside a component View rendered by <PrefabRoot>");
+    return ctx;
+}
+export function useEntityObjectRef() {
+    const { getObject } = useEntityRuntime();
+    return useMemo(() => ({ get current() { return getObject(); } }), [getObject]);
+}
+export function useEntityRigidBodyRef() {
+    const { getRigidBody } = useEntityRuntime();
+    return useMemo(() => ({ get current() { return getRigidBody(); } }), [getRigidBody]);
+}
+export function EntityRuntimeScope({ nodeId, editMode, isSelected, children, }) {
+    const asset = useContext(AssetRuntimeContext);
+    if (!asset)
+        throw new Error("EntityRuntimeScope must be used inside <PrefabRoot>");
+    const value = useMemo(() => ({
+        nodeId,
+        editMode,
+        isSelected,
+        getObject: () => asset.getObject(nodeId),
+        getRigidBody: () => asset.getRigidBody(nodeId),
+    }), [asset, editMode, isSelected, nodeId]);
+    return _jsx(EntityRuntimeContext.Provider, { value: value, children: children });
+}
+export function createRuntimeEngine({ store, getObject, getRigidBody, }) {
+    const scene = createScene({
+        getRootId: () => store.getState().rootId,
+        getNode: (id) => { var _a; return (_a = store.getState().nodesById[id]) !== null && _a !== void 0 ? _a : null; },
+        getChildIds: (id) => { var _a; return (_a = store.getState().childIdsById[id]) !== null && _a !== void 0 ? _a : []; },
+        getParentId: (id) => { var _a; return (_a = store.getState().parentIdById[id]) !== null && _a !== void 0 ? _a : null; },
+        updateNode: (id, update) => store.getState().updateNode(id, update),
+        updateNodes: (updates) => {
+            store.getState().updateNodes(Object.entries(updates).map(([id, update]) => ({ id, update })));
+        },
+        addNode: (node, options) => {
+            var _a;
+            const parentId = (_a = options === null || options === void 0 ? void 0 : options.parentId) !== null && _a !== void 0 ? _a : store.getState().rootId;
+            store.getState().addChild(parentId, node);
+            return node.id;
+        },
+        removeNode: (id) => store.getState().deleteNode(id),
+        getObject,
+        getRigidBody,
+    });
+    // key = `${nodeId}:${componentKey}:${componentType}`
+    const instances = new Map();
+    let active = false;
+    let dirty = true;
+    let lastRevision = store.getState().revision;
+    const unsubscribe = store.subscribe((state) => {
+        if (state.revision === lastRevision)
+            return;
+        lastRevision = state.revision;
+        dirty = true;
+    });
+    function destroy(key) {
+        var _a, _b;
+        const record = instances.get(key);
+        if (!record)
+            return;
+        try {
+            (_b = (_a = record.instance).destroy) === null || _b === void 0 ? void 0 : _b.call(_a);
+        }
+        catch (error) {
+            console.error(`[runtime] destroy ${key}`, error);
+        }
+        instances.delete(key);
+    }
+    function sync() {
+        const state = store.getState();
+        const live = new Set();
+        let hasPendingMount = false;
+        const visit = (nodeId) => {
+            var _a, _b, _c;
+            const node = state.nodesById[nodeId];
+            if (!node)
+                return;
+            if (!node.disabled && node.components) {
+                for (const componentKey in node.components) {
+                    const data = node.components[componentKey];
+                    if (!(data === null || data === void 0 ? void 0 : data.type))
+                        continue;
+                    const def = getComponentDef(data.type);
+                    if (!(def === null || def === void 0 ? void 0 : def.create))
+                        continue;
+                    const key = `${nodeId}:${componentKey}:${data.type}`;
+                    live.add(key);
+                    const object = getObject(nodeId);
+                    if (!object) {
+                        hasPendingMount = true;
+                        continue;
+                    }
+                    const rigidBody = getRigidBody(nodeId);
+                    const existing = instances.get(key);
+                    if (existing && existing.object === object && existing.rigidBody === rigidBody) {
+                        continue;
+                    }
+                    if (existing) {
+                        destroy(key);
+                    }
+                    const entity = scene.find(nodeId);
+                    const component = entity === null || entity === void 0 ? void 0 : entity.getComponent(componentKey);
+                    if (!entity || !component)
+                        continue;
+                    let instance;
+                    try {
+                        instance = (_a = def.create({ scene, component, object, rigidBody })) !== null && _a !== void 0 ? _a : {};
+                    }
+                    catch (error) {
+                        console.error(`[runtime] create ${key}`, error);
+                        continue;
+                    }
+                    instances.set(key, { instance, object, rigidBody });
+                    try {
+                        (_b = instance.start) === null || _b === void 0 ? void 0 : _b.call(instance);
+                    }
+                    catch (error) {
+                        console.error(`[runtime] start ${key}`, error);
+                    }
+                }
+            }
+            for (const childId of (_c = state.childIdsById[nodeId]) !== null && _c !== void 0 ? _c : [])
+                visit(childId);
+        };
+        visit(state.rootId);
+        for (const key of Array.from(instances.keys())) {
+            if (!live.has(key))
+                destroy(key);
+        }
+        dirty = hasPendingMount;
+    }
+    return {
+        tick(dt) {
+            if (!active)
+                return;
+            if (dirty)
+                sync();
+            for (const [key, record] of instances) {
+                if (!record.instance.update)
+                    continue;
+                try {
+                    record.instance.update(dt);
+                }
+                catch (error) {
+                    console.error(`[runtime] update ${key}`, error);
+                }
+            }
+        },
+        setActive(nextActive) {
+            if (active === nextActive)
+                return;
+            active = nextActive;
+            dirty = true;
+            if (!active) {
+                for (const key of Array.from(instances.keys()))
+                    destroy(key);
+            }
+        },
+        invalidate() {
+            dirty = true;
+        },
+        dispose() {
+            active = false;
+            for (const key of Array.from(instances.keys()))
+                destroy(key);
+            unsubscribe();
+        },
+    };
+}

package/dist/tools/prefabeditor/scene.d.ts

@@ -45,6 +45,14 @@ export interface Scene {
     };
     add: (node: GameObject, options?: SpawnOptions) => Entity;
     remove: (id: string) => void;
+    /**
+     * Coalesce many entity / component updates into a single store revision.
+     * Entity `update`/`set`, `EntityComponent` `set`/`update`, `addComponent`,
+     * and `removeComponent` calls inside the callback are buffered and flushed
+     * as one batched write. `add`, `remove`, and `destroy` (structural tree ops)
+     * still commit immediately.
+     */
+    batch: (fn: () => void) => void;
 }
 interface SceneAdapter {
     getRootId: () => string;

package/dist/tools/prefabeditor/scene.js

@@ -57,6 +57,42 @@ function setValueAtPath(value, path, nextValue) {
     return cloneBranch(value, 0);
 }
 export function createScene(adapter) {
+    let batchBuffer = null;
+    function routeUpdate(id, update) {
+        if (batchBuffer) {
+            const prev = batchBuffer.get(id);
+            batchBuffer.set(id, prev ? (node) => update(prev(node)) : update);
+            return;
+        }
+        adapter.updateNode(id, update);
+    }
+    function routeUpdates(updates) {
+        if (batchBuffer) {
+            for (const id in updates)
+                routeUpdate(id, updates[id]);
+            return;
+        }
+        adapter.updateNodes(updates);
+    }
+    function batch(fn) {
+        if (batchBuffer) {
+            fn();
+            return;
+        }
+        batchBuffer = new Map();
+        try {
+            fn();
+            if (batchBuffer.size > 0) {
+                const updates = {};
+                for (const [id, update] of batchBuffer)
+                    updates[id] = update;
+                adapter.updateNodes(updates);
+            }
+        }
+        finally {
+            batchBuffer = null;
+        }
+    }
     const getNode = (id) => {
         if (!adapter.getNode(id))
             missingNode(id);
@@ -76,7 +112,7 @@ export function createScene(adapter) {
                 return getValueAtPath(component.properties, path);
             },
             set(path, value) {
-                adapter.updateNode(entityId, node => {
+                routeUpdate(entityId, node => {
                     var _a;
                     const component = (_a = node.components) === null || _a === void 0 ? void 0 : _a[componentKey];
                     if (!component) {
@@ -86,7 +122,7 @@ export function createScene(adapter) {
                 });
             },
             update(update) {
-                adapter.updateNode(entityId, node => {
+                routeUpdate(entityId, node => {
                     var _a;
                     const component = (_a = node.components) === null || _a === void 0 ? void 0 : _a[componentKey];
                     if (!component) {
@@ -128,10 +164,10 @@ export function createScene(adapter) {
                 return (_b = (_a = adapter.getRigidBody) === null || _a === void 0 ? void 0 : _a.call(adapter, id)) !== null && _b !== void 0 ? _b : null;
             },
             set(data) {
-                adapter.updateNode(id, () => data);
+                routeUpdate(id, () => data);
             },
             update(update) {
-                adapter.updateNode(id, update);
+                routeUpdate(id, update);
             },
             getComponent(name) {
                 const node = adapter.getNode(id);
@@ -145,11 +181,11 @@ export function createScene(adapter) {
             },
             addComponent(type, properties) {
                 const key = type.toLowerCase();
-                adapter.updateNode(id, node => (Object.assign(Object.assign({}, node), { components: Object.assign(Object.assign({}, node.components), { [key]: createComponentData(type, properties) }) })));
+                routeUpdate(id, node => (Object.assign(Object.assign({}, node), { components: Object.assign(Object.assign({}, node.components), { [key]: createComponentData(type, properties) }) })));
                 return createComponent(id, key, type);
             },
             removeComponent(name) {
-                adapter.updateNode(id, node => {
+                routeUpdate(id, node => {
                     var _a;
                     const entry = findComponentEntry(node, name);
                     if (!entry)
@@ -169,13 +205,13 @@ export function createScene(adapter) {
             if (!mutate) {
                 return;
             }
-            adapter.updateNode(idOrUpdates, mutate);
+            routeUpdate(idOrUpdates, mutate);
             return;
         }
         if (Object.keys(idOrUpdates).length === 0) {
             return;
         }
-        adapter.updateNodes(idOrUpdates);
+        routeUpdates(idOrUpdates);
     }
     return {
         get rootId() {
@@ -196,5 +232,6 @@ export function createScene(adapter) {
         remove(id) {
             adapter.removeNode(id);
         },
+        batch,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-three-game",
-  "version": "0.0.82",
+  "version": "0.0.84",
   "description": "high performance 3D game engine built in React",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -43,7 +43,7 @@
     "concurrently": "^9.2.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "three": "^0.182.0",
+    "three": "^0.184.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.1"
   },

package/dist/tools/prefabeditor/runtimeContext.d.ts

@@ -1,40 +0,0 @@
-import { type ReactNode } from "react";
-import { Object3D, Texture } from "three";
-type RuntimeScopeProps = {
-    nodeId: string;
-    editMode?: boolean;
-    isSelected?: boolean;
-    children: ReactNode;
-};
-export interface AssetRuntime {
-    registerRigidBodyRef: (id: string, rb: any) => void;
-    getModel: (path: string) => Object3D | null;
-    getTexture: (path: string) => Texture | null;
-    getSound: (path: string) => AudioBuffer | null;
-    getAssetRevision: () => string;
-    getObject: (id: string) => Object3D | null;
-    getRigidBody: (id: string) => any;
-}
-export interface AssetRuntimeContextValue extends AssetRuntime {
-}
-export interface EntityRuntime {
-    nodeId: string;
-    editMode?: boolean;
-    isSelected?: boolean;
-    getObject: <T extends Object3D = Object3D>() => T | null;
-    getRigidBody: <T = any>() => T | null;
-}
-export interface LiveObjectRef<T extends Object3D = Object3D> {
-    readonly current: T | null;
-}
-export interface LiveRigidBodyRef<T = any> {
-    readonly current: T | null;
-}
-export declare const AssetRuntimeContext: import("react").Context<AssetRuntimeContextValue | null>;
-export declare const EntityRuntimeContext: import("react").Context<EntityRuntime | null>;
-export declare function useAssetRuntime(): AssetRuntime;
-export declare function useEntityRuntime(): EntityRuntime;
-export declare function useEntityObjectRef<T extends Object3D = Object3D>(): LiveObjectRef<T>;
-export declare function useEntityRigidBodyRef<T = any>(): LiveRigidBodyRef<T>;
-export declare function EntityRuntimeScope({ nodeId, editMode, isSelected, children, }: RuntimeScopeProps): import("react/jsx-runtime").JSX.Element;
-export {};

package/dist/tools/prefabeditor/runtimeContext.js

@@ -1,45 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useMemo } from "react";
-function createLiveRef(getCurrent) {
-    return {
-        get current() {
-            return getCurrent();
-        },
-    };
-}
-export const AssetRuntimeContext = createContext(null);
-export const EntityRuntimeContext = createContext(null);
-export function useAssetRuntime() {
-    const ctx = useContext(AssetRuntimeContext);
-    if (!ctx)
-        throw new Error("useAssetRuntime must be used inside <PrefabRoot>");
-    return ctx;
-}
-export function useEntityRuntime() {
-    const ctx = useContext(EntityRuntimeContext);
-    if (!ctx)
-        throw new Error("useEntityRuntime must be used inside a component View rendered by <PrefabRoot>");
-    return ctx;
-}
-export function useEntityObjectRef() {
-    const { getObject } = useEntityRuntime();
-    return useMemo(() => createLiveRef(() => getObject()), [getObject]);
-}
-export function useEntityRigidBodyRef() {
-    const { getRigidBody } = useEntityRuntime();
-    return useMemo(() => createLiveRef(() => getRigidBody()), [getRigidBody]);
-}
-export function EntityRuntimeScope({ nodeId, editMode, isSelected, children, }) {
-    const assetRuntime = useContext(AssetRuntimeContext);
-    if (!assetRuntime)
-        throw new Error("EntityRuntimeScope must be used inside <PrefabRoot>");
-    const { getObject, getRigidBody } = assetRuntime;
-    const value = useMemo(() => ({
-        nodeId,
-        editMode,
-        isSelected,
-        getObject: () => getObject(nodeId),
-        getRigidBody: () => getRigidBody(nodeId),
-    }), [editMode, getObject, getRigidBody, isSelected, nodeId]);
-    return _jsx(EntityRuntimeContext.Provider, { value: value, children: children });
-}