react-three-game 0.0.93 → 0.0.94

package/README.md

@@ -152,7 +152,7 @@ interface GameObject {
 
 ## Runtime Mutation
 
-Use editor or root refs for scene-native object access, and use the editor mutation methods for authored data changes.
+Use the editor or root ref for scene-native object access, and the `Scene` mutation methods for authored data changes.
 
 ```tsx
 import { useEffect, useRef } from "react";
@@ -162,7 +162,7 @@ function RaiseBall() {
   const editorRef = useRef<PrefabEditorRef>(null);
 
   useEffect(() => {
-    editorRef.current?.updateNode("ball", (node) => ({
+    editorRef.current?.update("ball", (node) => ({
       ...node,
       components: {
         ...node.components,
@@ -184,29 +184,33 @@ function RaiseBall() {
 For live Three.js access, use mounted objects directly:
 
 ```tsx
-const ball = editorRef.current?.getNodeObject("ball");
+const ball = editorRef.current?.getObject("ball");
 ball?.rotateY(0.5);
 ```
 
-For runtime integrations that need edit-time re-sync, subscribe to authored scene changes:
+For runtime integrations that need to react to authored scene changes, subscribe through the prefab store:
 
 ```tsx
-const stop = editorRef.current?.onSceneChange((revision) => {
-  console.log("scene changed", revision);
-});
+import { usePrefabStoreApi } from "react-three-game";
 
-stop?.();
+const store = usePrefabStoreApi();
+const stop = store.subscribe(
+  (s) => s.nodesById,
+  (next, prev) => console.log("scene changed", next, prev),
+);
+
+stop();
 ```
 
-For runtime-owned imperative state, use node-local handles instead of reaching for ad hoc globals:
+For runtime-owned imperative state, register node-local handles instead of reaching for ad hoc globals:
 
 ```tsx
 import { useEffect } from "react";
-import { useAssetRuntime, useCurrentNode, useCurrentNodeHandle } from "react-three-game";
+import { useAssetRuntime, useNode, useNodeHandle } from "react-three-game";
 
 function SpinnerView({ children }: { children?: React.ReactNode }) {
-  const { nodeId } = useCurrentNode();
-  const { registerNodeHandle } = useAssetRuntime();
+  const { nodeId } = useNode();
+  const { registerHandle } = useAssetRuntime();
 
   useEffect(() => {
     const handle = {
@@ -215,15 +219,15 @@ function SpinnerView({ children }: { children?: React.ReactNode }) {
       },
     };
 
-    registerNodeHandle(nodeId, "spinner", handle);
-    return () => registerNodeHandle(nodeId, "spinner", null);
-  }, [nodeId, registerNodeHandle]);
+    registerHandle(nodeId, "spinner", handle);
+    return () => registerHandle(nodeId, "spinner", null);
+  }, [nodeId, registerHandle]);
 
   return <>{children}</>;
 }
 
 function SpinnerStatus() {
-  const spinnerRef = useCurrentNodeHandle<{ setSpeed: (next: number) => void }>("spinner");
+  const spinnerRef = useNodeHandle<{ setSpeed: (next: number) => void }>("spinner");
 
   useEffect(() => {
     spinnerRef.current?.setSpeed(2);
@@ -246,11 +250,11 @@ const playerByName = editorRef.current?.root?.getObjectByName("Player");
 const playerById = editorRef.current?.root?.getObjectByProperty("userData.prefabNodeId", "player");
 ```
 
-Treat names as a convenience surface, not the primary lookup key:
+Treat names as a convenience surface, with stable ids as the primary lookup key:
 
+* `editorRef.current?.getObject(id)` is the clearest stable authored-node lookup
 * names are not guaranteed unique
-* `getNodeObject(id)` is the clearest stable authored-node lookup
-* traversal metadata is applied to the prefab node transform object, not necessarily the inner mesh or model child
+* traversal metadata is applied to the prefab node transform object — the inner mesh or model child is one level deeper
 
 You can author extra `userData` from the editor with a `Data` component:
 
@@ -264,67 +268,21 @@ You can author extra `userData` from the editor with a `Data` component:
 }
 ```
 
-For batched authored updates, write through the store once:
-
-```tsx
-editorRef.current?.updateNodes([
-  {
-    id: "orb1",
-    update: (node) => ({
-      ...node,
-      components: {
-        ...node.components,
-        transform: {
-          ...node.components?.transform,
-          type: "Transform",
-          properties: {
-            ...node.components?.transform?.properties,
-            position: [1, 0, 0],
-          },
-        },
-      },
-    }),
-  },
-  {
-    id: "orb2",
-    update: (node) => ({
-      ...node,
-      components: {
-        ...node.components,
-        transform: {
-          ...node.components?.transform,
-          type: "Transform",
-          properties: {
-            ...node.components?.transform?.properties,
-            position: [-1, 0, 0],
-          },
-        },
-      },
-    }),
-  },
-]);
-```
-
-Custom component `View`s should use normal React and R3F behavior, such as `useFrame`, refs, and native Three.js APIs.
+Custom component `View`s use normal React and R3F behavior — `useFrame`, refs, and native Three.js APIs.
 
 ## Useful Exports
 
-* `GameCanvas`
-* `PrefabRoot`
-* `PrefabEditor`
-* `PrefabEditorMode`
-* `Prefab`
-* `GameObject`
-* `registerComponent`
-* `useAssetRuntime()` / `useCurrentNode()`
-* `useCurrentNodeObject()` / `useCurrentNodeHandle()`
-* `ground(...)`
-* `gameEvents` / `useGameEvent()` / `useClickEvent()`
-* `loadJson()` / `saveJson()`
-* `loadModel()` / `loadTexture()`
-* `loadSound()` / `loadFiles()`
-* `exportGLB()`
-* `computeParentWorldMatrix()`
+* `GameCanvas`, `PrefabRoot`, `PrefabEditor`, `PrefabEditorMode`
+* `Prefab`, `GameObject`, `ComponentData`, `PrefabNode`, `PrefabEditorRef`, `Scene`
+* `registerComponent`, `Component`, `ComponentViewProps`, `FieldDefinition`
+* `useScene`, `useEditorRef`, `useEditorContext`
+* `useNode`, `useNodeObject`, `useNodeHandle`, `useAssetRuntime`
+* `usePrefabStore`, `usePrefabStoreApi`
+* `gameEvents`, `useGameEvent`, `useClickEvent`
+* `loadJson`, `saveJson`, `loadFiles`, `loadModel`, `loadTexture`, `loadSound`
+* `exportGLB`, `exportGLBData`, `regenerateIds`, `computeParentWorldMatrix`
+* `ground`, `soundManager`
+* `FieldRenderer`, `Vector3Field`, `NumberField`, `StringField`, `BooleanField`, `SelectField`, `ColorField`
 
 ## Development
 

package/dist/index.d.ts

@@ -4,10 +4,12 @@ export { ground } from './helpers';
 export type { GroundOptions, Vec3 } from './helpers';
 export { sound as soundManager } from './helpers/SoundManager';
 export { default as PrefabEditor } from './tools/prefabeditor/PrefabEditor';
-export { PrefabEditorMode } from './tools/prefabeditor/PrefabEditor';
+export { PrefabEditorMode } from './tools/prefabeditor/PrefabRoot';
 export { default as PrefabRoot } from './tools/prefabeditor/PrefabRoot';
-export { useEditorContext } from './tools/prefabeditor/PrefabEditor';
+export { useEditorContext, useEditorRef } from './tools/prefabeditor/PrefabEditor';
 export type { EditorContextType } from './tools/prefabeditor/PrefabEditor';
+export { usePrefabStore, usePrefabStoreApi } from './tools/prefabeditor/prefabStore';
+export type { PrefabStoreApi, PrefabStoreState } from './tools/prefabeditor/prefabStore';
 export { denormalizePrefab } from './tools/prefabeditor/prefab';
 export { gameEvents, useClickEvent, useGameEvent } from './tools/prefabeditor/GameEvents';
 export type { ClickEventPayload, ContactEventPayload, GameEventHandler, GameEventMap } from './tools/prefabeditor/GameEvents';
@@ -16,10 +18,12 @@ export { FieldRenderer, FieldGroup, ListEditor, Label, Vector3Input, Vector3Fiel
 export { loadJson, saveJson, exportGLB, exportGLBData, regenerateIds, computeParentWorldMatrix, } from './tools/prefabeditor/utils';
 export type { ExportGLBOptions } from './tools/prefabeditor/utils';
 export { createModelNode, createImageNode, } from './tools/prefabeditor/prefab';
-export type { PrefabEditorProps, PrefabNode, PrefabEditorRef, SpawnOptions, } from './tools/prefabeditor/PrefabEditor';
+export type { PrefabEditorProps, PrefabNode, PrefabEditorRef, } from './tools/prefabeditor/PrefabEditor';
 export type { PrefabRootProps } from './tools/prefabeditor/PrefabRoot';
-export type { AssetRuntime, CurrentNodeRuntime, LiveHandleRef, LiveObjectRef, CurrentNodeHandleRef, CurrentNodeObjectRef } from './tools/prefabeditor/assetRuntime';
-export { useAssetRuntime, useCurrentNode, useCurrentNodeHandle, useCurrentNodeObject } from './tools/prefabeditor/assetRuntime';
+export type { AssetRuntime, NodeApi, LiveRef } from './tools/prefabeditor/assetRuntime';
+export { useAssetRuntime, useNode, useNodeHandle, useNodeObject } from './tools/prefabeditor/assetRuntime';
+export type { Scene } from './tools/prefabeditor/PrefabRoot';
+export { useScene } from './tools/prefabeditor/PrefabRoot';
 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';
@@ -32,4 +36,3 @@ export type { AssetLoadOptions } from './tools/dragdrop/DragDropLoader';
 export { loadModel, loadSound, loadTexture } from './tools/dragdrop/modelLoader';
 export type { LoadedModel, LoadedModels, ModelLoadResult, LoadedSound, LoadedSounds, SoundLoadResult, LoadedTexture, LoadedTextures, TextureLoadResult, ProgressCallback, } from './tools/dragdrop/modelLoader';
 export { ModelListViewer, SoundListViewer, ModelPicker, SoundPicker, TextureListViewer, TexturePicker, SingleModelViewer, SingleSoundViewer, SingleTextureViewer, SharedCanvas, } from './tools/assetviewer/page';
-export type { PrefabRootRef } from './tools/prefabeditor/PrefabRoot';

package/dist/index.js

@@ -5,9 +5,10 @@ export { ground } from './helpers';
 export { sound as soundManager } from './helpers/SoundManager';
 // Prefab Editor
 export { default as PrefabEditor } from './tools/prefabeditor/PrefabEditor';
-export { PrefabEditorMode } from './tools/prefabeditor/PrefabEditor';
+export { PrefabEditorMode } from './tools/prefabeditor/PrefabRoot';
 export { default as PrefabRoot } from './tools/prefabeditor/PrefabRoot';
-export { useEditorContext } from './tools/prefabeditor/PrefabEditor';
+export { useEditorContext, useEditorRef } from './tools/prefabeditor/PrefabEditor';
+export { usePrefabStore, usePrefabStoreApi } from './tools/prefabeditor/prefabStore';
 // Prefab Editor - Data API
 export { denormalizePrefab } from './tools/prefabeditor/prefab';
 export { gameEvents, useClickEvent, useGameEvent } from './tools/prefabeditor/GameEvents';
@@ -18,7 +19,8 @@ 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, useCurrentNode, useCurrentNodeHandle, useCurrentNodeObject } from './tools/prefabeditor/assetRuntime';
+export { useAssetRuntime, useNode, useNodeHandle, useNodeObject } from './tools/prefabeditor/assetRuntime';
+export { useScene } from './tools/prefabeditor/PrefabRoot';
 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';

package/dist/tools/prefabeditor/EditorTree.js

@@ -1,20 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { memo, useCallback, useState } from 'react';
 import { base, colors, tree } from './styles';
-import { useEditorContext } from './PrefabEditor';
+import { useEditorContext, useEditorRef } from './PrefabEditor';
 import { Dropdown } from './Dropdown';
 import { FileMenu, TreeContextMenu, TreeNodeMenu } from './EditorTreeMenus';
 import { createEmptyNode } from './prefab';
 import { usePrefabChildIds, usePrefabNode, usePrefabRootId, usePrefabStore, usePrefabStoreApi } from './prefabStore';
 export default function EditorTree({ selectedId, setSelectedId, getPrefab, onReplacePrefab, onImportPrefab, onUndo, onRedo, canUndo, canRedo }) {
     const { onFocusNode } = useEditorContext();
+    const editor = useEditorRef();
     const rootId = usePrefabRootId();
     const store = usePrefabStoreApi();
-    const addChild = usePrefabStore(state => state.addChild);
-    const duplicateNode = usePrefabStore(state => state.duplicateNode);
-    const deleteNode = usePrefabStore(state => state.deleteNode);
-    const toggleNodeFlag = usePrefabStore(state => state.toggleNodeFlag);
-    const moveNode = usePrefabStore(state => state.moveNode);
     const [draggedId, setDraggedId] = useState(null);
     const [dropTarget, setDropTarget] = useState(null);
     const [collapsedIds, setCollapsedIds] = useState(new Set());
@@ -31,30 +27,30 @@ export default function EditorTree({ selectedId, setSelectedId, getPrefab, onRep
     };
     const handleAddChild = (parentId) => {
         const newNode = createEmptyNode();
-        addChild(parentId, newNode);
+        editor.add(newNode, parentId);
         setSelectedId(newNode.id);
     };
     const handleDuplicate = (nodeId) => {
         if (nodeId === rootId)
             return;
-        const duplicatedId = duplicateNode(nodeId);
+        const duplicatedId = editor.duplicate(nodeId);
         if (duplicatedId)
             setSelectedId(duplicatedId);
     };
     const handleDelete = (nodeId) => {
         if (nodeId === rootId)
             return;
-        deleteNode(nodeId);
+        editor.remove(nodeId);
         if (selectedId === nodeId)
             setSelectedId(null);
     };
     const handleToggleDisabled = (nodeId) => {
-        toggleNodeFlag(nodeId, 'disabled');
+        editor.update(nodeId, n => (Object.assign(Object.assign({}, n), { disabled: !n.disabled })));
     };
     const handleToggleLocked = (nodeId) => {
         var _a;
         const willLock = !((_a = store.getState().nodesById[nodeId]) === null || _a === void 0 ? void 0 : _a.locked);
-        toggleNodeFlag(nodeId, 'locked');
+        editor.update(nodeId, n => (Object.assign(Object.assign({}, n), { locked: !n.locked })));
         if (willLock && selectedId === nodeId)
             setSelectedId(null);
     };
@@ -99,7 +95,7 @@ export default function EditorTree({ selectedId, setSelectedId, getPrefab, onRep
         if (!draggedId || draggedId === targetId)
             return;
         e.preventDefault();
-        moveNode(draggedId, targetId, getDropPosition(e, isRoot));
+        editor.move(draggedId, targetId, getDropPosition(e, isRoot));
         setDraggedId(null);
         setDropTarget(null);
     };

package/dist/tools/prefabeditor/EditorUI.js

@@ -15,23 +15,23 @@ import { hasComponent } from "./types";
 import EditorTree from './EditorTree';
 import { getAllComponentDefs } from './components/ComponentRegistry';
 import { createComponentData } from './prefab';
+import { useEditorRef } from './PrefabEditor';
 import { base, colors, inspector, componentCard } from './styles';
 import { usePrefabStore } from './prefabStore';
 function EditorUI({ selectedId, setSelectedId, getPrefab, onReplacePrefab, onImportPrefab, basePath, onUndo, onRedo, canUndo, canRedo }) {
     const [collapsed, setCollapsed] = useState(false);
     const rootId = usePrefabStore(state => state.rootId);
     const selectedNode = usePrefabStore(state => { var _a; return selectedId ? (_a = state.nodesById[selectedId]) !== null && _a !== void 0 ? _a : null : null; });
-    const updateNode = usePrefabStore(state => state.updateNode);
-    const deleteNode = usePrefabStore(state => state.deleteNode);
+    const editor = useEditorRef();
     const updateNodeHandler = (update) => {
         if (!selectedId)
             return;
-        updateNode(selectedId, update);
+        editor.update(selectedId, update);
     };
     const deleteNodeHandler = () => {
         if (!selectedId || selectedId === rootId)
             return;
-        deleteNode(selectedId);
+        editor.remove(selectedId);
         setSelectedId(null);
     };
     return _jsxs(_Fragment, { children: [_jsxs("div", { style: inspector.panel, children: [_jsxs("div", { style: base.header, onClick: () => setCollapsed(!collapsed), children: [_jsx("span", { children: "Inspector" }), _jsx("span", { children: collapsed ? '◀' : '▼' })] }), !collapsed && selectedNode && (_jsx(NodeInspector, { node: selectedNode, updateNode: updateNodeHandler, deleteNode: deleteNodeHandler, basePath: basePath }))] }), _jsx("div", { style: { position: 'absolute', top: 8, left: 8, zIndex: 20 }, children: _jsx(EditorTree, { selectedId: selectedId, setSelectedId: setSelectedId, getPrefab: getPrefab, onReplacePrefab: onReplacePrefab, onImportPrefab: onImportPrefab, onUndo: onUndo, onRedo: onRedo, canUndo: canUndo, canRedo: canRedo }) })] });

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

@@ -1,44 +1,21 @@
 import GameCanvas from "../../shared/GameCanvas";
-import { Object3D, Texture } from "three";
-import { GameObject, Prefab } from "./types";
+import { Prefab } from "./types";
+import { PrefabEditorMode, type Scene } from "./PrefabRoot";
 import type { ExportGLBOptions } from "./utils";
-export interface PrefabEditorRef {
-    root: Object3D | null;
-    getNode: (nodeId: string) => PrefabNode | null;
-    getNodeObject: (nodeId: string) => Object3D | null;
-    getNodeHandle: <T = unknown>(nodeId: string, kind: string) => T | null;
-    onSceneChange: (listener: (revision: number) => void) => () => void;
-    screenshot: () => void;
-    exportGLB: (options?: ExportGLBOptions) => Promise<ArrayBuffer | undefined>;
-    exportGLBData: () => Promise<ArrayBuffer | undefined>;
-    clearSelection: () => Promise<void>;
+export interface PrefabEditorRef extends Scene {
     save: () => Prefab;
     load: (prefab: Prefab, options?: {
         resetHistory?: boolean;
         notifyChange?: boolean;
     }) => void;
-    updateNode: (nodeId: string, update: (node: PrefabNode) => PrefabNode) => void;
-    updateNodes: (updates: Array<{
-        id: string;
-        update: (node: PrefabNode) => PrefabNode;
-    }>) => void;
-    deleteNode: (nodeId: string) => void;
-    duplicateNode: (nodeId: string) => string | null;
-    moveNode: (draggedId: string, targetId: string, position: "before" | "inside") => void;
-    addNode: (node: GameObject, options?: SpawnOptions) => GameObject;
-    addModel: (path: string, model: Object3D, options?: SpawnOptions) => GameObject;
-    addTexture: (path: string, texture: Texture, options?: SpawnOptions) => GameObject;
-}
-export interface SpawnOptions {
-    name?: string;
-    parentId?: string;
-    select?: boolean;
-}
-export type PrefabNode = Omit<GameObject, "children">;
-export declare enum PrefabEditorMode {
-    Edit = "edit",
-    Play = "play"
+    undo: () => void;
+    redo: () => void;
+    screenshot: () => void;
+    exportGLB: (options?: ExportGLBOptions) => Promise<ArrayBuffer | undefined>;
+    exportGLBData: () => Promise<ArrayBuffer | undefined>;
+    clearSelection: () => Promise<void>;
 }
+export type { PrefabNode } from "./PrefabRoot";
 export interface EditorContextType {
     mode: PrefabEditorMode;
     setMode: (mode: PrefabEditorMode) => void;
@@ -55,7 +32,9 @@ export interface EditorContextType {
     onExportGLB?: () => void;
 }
 export declare const EditorContext: import("react").Context<EditorContextType | null>;
+export declare const EditorRefContext: import("react").Context<PrefabEditorRef | null>;
 export declare function useEditorContext(): EditorContextType;
+export declare function useEditorRef(): PrefabEditorRef;
 export interface PrefabEditorProps {
     basePath?: string;
     initialPrefab?: Prefab;