react-three-game 0.0.16 → 0.0.18

package/README.md

@@ -30,14 +30,6 @@ Scenes are JSON prefabs. Components are registered modules. Hierarchy is declara
   }} />
 ```
 
-## Styling
-
-The prefab editor UI ships with **inline styles** (no Tailwind / CSS framework required). That means you can install and render it without any additional build-time CSS configuration.
-
-If you want to fully restyle the editor, you can:
-- Wrap `PrefabEditor` in your own layout and override positioning.
-- Fork/compose the editor UI components (they’re plain React components).
-
 ## Quick Start
 
 ```bash
@@ -108,28 +100,100 @@ interface GameObject {
 
 ## Custom Components
 
-```tsx
+Extend the engine by registering your own components. Components have two parts:
+- **Editor**: UI for inspector panel (edit mode)
+- **View**: Three.js runtime renderer (play mode)
+
+### Component Interface
+
+```typescript
 import { Component } from 'react-three-game';
 
-const LaserComponent: Component = {
-  name: 'Laser',
+interface Component {
+  name: string;
+  Editor: FC<{ component: any; onUpdate: (newComp: any) => void }>;
+  View?: FC<{ properties: any; children?: React.ReactNode }>;
+  defaultProperties: any;
+}
+```
+
+### Example: Rotator Component
+
+```tsx
+import { Component, registerComponent } from 'react-three-game';
+import { useFrame } from '@react-three/fiber';
+import { useRef } from 'react';
+
+const RotatorComponent: Component = {
+  name: 'Rotator',
+  
   Editor: ({ component, onUpdate }) => (
-    <input 
-      value={component.properties.damage} 
-      onChange={e => onUpdate({ damage: +e.target.value })}
-    />
-  ),
-  View: ({ properties }) => (
-    <pointLight color="red" intensity={properties.damage} />
+    <div>
+      <label>Speed</label>
+      <input 
+        type="number"
+        value={component.properties.speed ?? 1.0}
+        onChange={e => onUpdate({ ...component.properties, speed: parseFloat(e.target.value) })}
+      />
+      <label>Axis</label>
+      <select 
+        value={component.properties.axis ?? 'y'}
+        onChange={e => onUpdate({ ...component.properties, axis: e.target.value })}
+      >
+        <option value="x">X</option>
+        <option value="y">Y</option>
+        <option value="z">Z</option>
+      </select>
+    </div>
   ),
-  defaultProperties: { damage: 10 }
+  
+  View: ({ properties, children }) => {
+    const ref = useRef();
+    const speed = properties.speed ?? 1.0;
+    const axis = properties.axis ?? 'y';
+    
+    useFrame((state, delta) => {
+      if (ref.current) {
+        ref.current.rotation[axis] += delta * speed;
+      }
+    });
+    
+    return <group ref={ref}>{children}</group>;
+  },
+  
+  defaultProperties: { speed: 1.0, axis: 'y' }
 };
 
-// Register
-import { registerComponent } from 'react-three-game';
-registerComponent(LaserComponent);
+// Register before using PrefabEditor
+registerComponent(RotatorComponent);
+```
+
+### Usage in Prefab JSON
+
+```json
+{
+  "id": "spinning-cube",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [0, 1, 0] } },
+    "geometry": { "type": "Geometry", "properties": { "geometryType": "box" } },
+    "material": { "type": "Material", "properties": { "color": "#ff6b6b" } },
+    "rotator": { "type": "Rotator", "properties": { "speed": 2.0, "axis": "y" } }
+  }
+}
 ```
 
+### Wrapper vs Leaf Components
+
+**Wrapper components** (accept `children`) wrap the rendered content:
+- Use for behaviors that need to manipulate the scene graph (animations, controllers)
+- Example: Rotator wraps mesh to apply rotation
+
+**Leaf components** (no `children`) render as siblings:
+- Use for standalone effects (lights, particles, audio sources)
+- Example: SpotLight renders a `<spotLight>` element
+
+The engine automatically detects component type by checking if `View` accepts `children` prop.
+
 ## Built-in Components
 
 | Component | Properties |
@@ -158,41 +222,13 @@ Transform gizmos (T/R/S keys), drag-to-reorder tree, import/export JSON, edit/pl
 ### Transform Hierarchy
 - Local transforms stored in JSON (relative to parent)
 - World transforms computed at runtime via matrix multiplication
-- `computeParentWorldMatrix(root, targetId)` traverses tree for parent's world matrix
 - TransformControls extract world matrix → compute parent inverse → derive new local transform
 
 ### GPU Instancing
-Enable with `model.properties.instanced = true`:
-```json
-{
-  "components": {
-    "model": { 
-      "type": "Model", 
-      "properties": { 
-        "filename": "tree.glb",
-        "instanced": true
-      }
-    }
-  }
-}
-```
-Uses drei's `<Merged>` + `<InstancedRigidBodies>` for physics. World-space transforms, terminal nodes.
+Enable with `model.properties.instanced = true` for optimized repeated geometry. Uses drei's `<Merged>` + `<InstancedRigidBodies>`.
 
 ### Model Loading
-- Supports GLB/GLTF (Draco compression) and FBX
-- Singleton loaders in `modelLoader.ts`
-- Draco decoder from `https://www.gstatic.com/draco/v1/decoders/`
-- Auto-loads when `model.properties.filename` detected
-
-### WebGPU Renderer
-```tsx
-<Canvas gl={async ({ canvas }) => {
-  const renderer = new WebGPURenderer({ canvas, shadowMap: true });
-  await renderer.init(); // Required
-  return renderer;
-}}>
-```
-Use `MeshStandardNodeMaterial` not `MeshStandardMaterial`.
+Supports GLB/GLTF (with Draco compression) and FBX. Models auto-load when `model.properties.filename` is detected.
 
 ## Patterns
 
@@ -202,15 +238,6 @@ import levelData from './prefabs/arena.json';
 <PrefabRoot data={levelData} />
 ```
 
-### Mix with React Components
-```jsx
-<Physics>
-  <PrefabRoot data={environment} />
-  <Player />
-  <AIEnemies />
-</Physics>
-```
-
 ### Update Prefab Nodes
 ```typescript
 function updatePrefabNode(root: GameObject, id: string, update: (node: GameObject) => GameObject): GameObject {
@@ -222,58 +249,6 @@ function updatePrefabNode(root: GameObject, id: string, update: (node: GameObjec
 }
 ```
 
-## AI Agent Reference
-
-### Prefab JSON Schema
-```typescript
-{
-  "id": "unique-id",
-  "root": {
-    "id": "root-id",
-    "components": {
-      "transform": {
-        "type": "Transform",
-        "properties": {
-          "position": [x, y, z],      // world units
-          "rotation": [x, y, z],      // radians
-          "scale": [x, y, z]          // multipliers
-        }
-      },
-      "geometry": {
-        "type": "Geometry",
-        "properties": {
-          "geometryType": "box" | "sphere" | "plane" | "cylinder" | "cone" | "torus",
-          "args": [/* geometry-specific */]
-        }
-      },
-      "material": {
-        "type": "Material",
-        "properties": {
-          "color": "#rrggbb",
-          "texture": "/path/to/texture.jpg",
-          "metalness": 0.0-1.0,
-          "roughness": 0.0-1.0
-        }
-      },
-      "physics": {
-        "type": "Physics",
-        "properties": {
-          "type": "dynamic" | "fixed"
-        }
-      },
-      "model": {
-        "type": "Model",
-        "properties": {
-          "filename": "/models/asset.glb",
-          "instanced": true
-        }
-      }
-    },
-    "children": [/* recursive GameObjects */]
-  }
-}
-```
-
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -3,5 +3,7 @@ export { default as PrefabEditor } from './tools/prefabeditor/PrefabEditor';
 export { default as PrefabRoot } from './tools/prefabeditor/PrefabRoot';
 export { DragDropLoader } from './tools/dragdrop/DragDropLoader';
 export { TextureListViewer, ModelListViewer, SoundListViewer, SharedCanvas, } from './tools/assetviewer/page';
+export { registerComponent } from './tools/prefabeditor/components/ComponentRegistry';
+export type { Component } from './tools/prefabeditor/components/ComponentRegistry';
 export * from './helpers';
 export type { Prefab, GameObject } from './tools/prefabeditor/types';

package/dist/index.js

@@ -4,5 +4,7 @@ export { default as PrefabEditor } from './tools/prefabeditor/PrefabEditor';
 export { default as PrefabRoot } from './tools/prefabeditor/PrefabRoot';
 export { DragDropLoader } from './tools/dragdrop/DragDropLoader';
 export { TextureListViewer, ModelListViewer, SoundListViewer, SharedCanvas, } from './tools/assetviewer/page';
+// Component Registry
+export { registerComponent } from './tools/prefabeditor/components/ComponentRegistry';
 // Helpers
 export * from './helpers';

package/dist/tools/prefabeditor/EditorTree.js

@@ -65,6 +65,17 @@ export default function EditorTree({ prefabData, setPrefabData, selectedId, setS
             overflow: "hidden",
             textOverflow: "ellipsis",
         },
+        dragHandle: {
+            width: 14,
+            height: 14,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            marginRight: 4,
+            opacity: 0.4,
+            cursor: "grab",
+            fontSize: 10,
+        },
         contextMenu: {
             position: "fixed",
             zIndex: 50,
@@ -165,38 +176,36 @@ export default function EditorTree({ prefabData, setPrefabData, selectedId, setS
     };
     // Drag and Drop
     const handleDragStart = (e, id) => {
-        e.stopPropagation();
         if (id === prefabData.root.id) {
-            e.preventDefault(); // Cannot drag root
+            e.preventDefault();
             return;
         }
-        setDraggedId(id);
         e.dataTransfer.effectAllowed = "move";
+        e.dataTransfer.setData("text/plain", id);
+        setDraggedId(id);
+    };
+    const handleDragEnd = () => {
+        setDraggedId(null);
     };
     const handleDragOver = (e, targetId) => {
-        e.preventDefault();
-        e.stopPropagation();
         if (!draggedId || draggedId === targetId)
             return;
-        // Check for cycles: target cannot be a descendant of dragged node
         const draggedNode = findNode(prefabData.root, draggedId);
         if (draggedNode && findNode(draggedNode, targetId))
             return;
+        e.preventDefault();
         e.dataTransfer.dropEffect = "move";
     };
     const handleDrop = (e, targetId) => {
-        e.preventDefault();
-        e.stopPropagation();
         if (!draggedId || draggedId === targetId)
             return;
+        e.preventDefault();
         setPrefabData(prev => {
             var _a;
             const newRoot = JSON.parse(JSON.stringify(prev.root));
-            // Check cycle again on the fresh tree
-            const draggedNodeRef = findNode(newRoot, draggedId);
-            if (draggedNodeRef && findNode(draggedNodeRef, targetId))
+            const draggedNode = findNode(newRoot, draggedId);
+            if (draggedNode && findNode(draggedNode, targetId))
                 return prev;
-            // Remove from old parent
             const parent = findParent(newRoot, draggedId);
             if (!parent)
                 return prev;
@@ -204,7 +213,6 @@ export default function EditorTree({ prefabData, setPrefabData, selectedId, setS
             if (!nodeToMove)
                 return prev;
             parent.children = parent.children.filter(c => c.id !== draggedId);
-            // Add to new parent
             const target = findNode(newRoot, targetId);
             if (target) {
                 target.children = target.children || [];
@@ -220,7 +228,7 @@ export default function EditorTree({ prefabData, setPrefabData, selectedId, setS
         const isSelected = node.id === selectedId;
         const isCollapsed = collapsedIds.has(node.id);
         const hasChildren = node.children && node.children.length > 0;
-        return (_jsxs("div", { children: [_jsxs("div", { style: Object.assign(Object.assign(Object.assign({}, styles.row), (isSelected ? styles.rowSelected : null)), { paddingLeft: `${depth * 10 + 6}px` }), onClick: (e) => { e.stopPropagation(); setSelectedId(node.id); }, onContextMenu: (e) => handleContextMenu(e, node.id), draggable: node.id !== prefabData.root.id, onDragStart: (e) => handleDragStart(e, node.id), onDragOver: (e) => handleDragOver(e, node.id), onDrop: (e) => handleDrop(e, node.id), onPointerEnter: (e) => {
+        return (_jsxs("div", { children: [_jsxs("div", { style: Object.assign(Object.assign(Object.assign({}, styles.row), (isSelected ? styles.rowSelected : null)), { paddingLeft: `${depth * 10 + 6}px`, cursor: node.id !== prefabData.root.id ? "grab" : "pointer" }), draggable: node.id !== prefabData.root.id, onClick: (e) => { e.stopPropagation(); setSelectedId(node.id); }, onContextMenu: (e) => handleContextMenu(e, node.id), onDragStart: (e) => handleDragStart(e, node.id), onDragEnd: handleDragEnd, onDragOver: (e) => handleDragOver(e, node.id), onDrop: (e) => handleDrop(e, node.id), onPointerEnter: (e) => {
                         if (!isSelected)
                             e.currentTarget.style.background = "rgba(255,255,255,0.06)";
                     }, onPointerLeave: (e) => {
@@ -230,7 +238,11 @@ export default function EditorTree({ prefabData, setPrefabData, selectedId, setS
                                 e.currentTarget.style.opacity = "0.9";
                             }, onPointerLeave: (e) => {
                                 e.currentTarget.style.opacity = "0.55";
-                            }, children: isCollapsed ? '▶' : '▼' }), _jsx("span", { style: styles.idText, children: node.id })] }), !isCollapsed && node.children && (_jsx("div", { children: node.children.map(child => renderNode(child, depth + 1)) }))] }, node.id));
+                            }, children: isCollapsed ? '▶' : '▼' }), node.id !== prefabData.root.id && (_jsx("span", { style: styles.dragHandle, onPointerEnter: (e) => {
+                                e.currentTarget.style.opacity = "0.9";
+                            }, onPointerLeave: (e) => {
+                                e.currentTarget.style.opacity = "0.4";
+                            }, children: "\u22EE\u22EE" })), _jsx("span", { style: styles.idText, children: node.id })] }), !isCollapsed && node.children && (_jsx("div", { children: node.children.map(child => renderNode(child, depth + 1)) }))] }, node.id));
     };
     return (_jsxs(_Fragment, { children: [_jsxs("div", { style: Object.assign(Object.assign({}, styles.panel), { width: isTreeCollapsed ? 'auto' : '14rem' }), onClick: closeContextMenu, children: [_jsxs("div", { style: styles.panelHeader, onClick: (e) => { e.stopPropagation(); setIsTreeCollapsed(!isTreeCollapsed); }, onPointerEnter: (e) => {
                             e.currentTarget.style.background = "rgba(255,255,255,0.08)";

package/dist/tools/prefabeditor/EditorUI.js

@@ -179,13 +179,7 @@ function NodeInspector({ node, updateNode, deleteNode, transformMode, setTransfo
             setAddComponentType(available[0] || "");
         }
     }, [componentKeys, addComponentType, node.components, allComponentKeys]);
-    return _jsxs("div", { style: s.root, children: [_jsx("div", { style: s.section, children: _jsx("input", { style: s.input, value: node.id, onChange: e => updateNode(n => (Object.assign(Object.assign({}, n), { id: e.target.value }))) }) }), _jsxs("div", { style: Object.assign(Object.assign(Object.assign({}, s.row), s.section), { paddingBottom: 6 }), children: [_jsx("label", { style: Object.assign(Object.assign({}, s.label), { marginBottom: 0 }), children: "Components" }), _jsx("button", { onClick: deleteNode, style: s.smallDanger, title: "Delete node", children: "\u2715" })] }), _jsxs("div", { style: s.section, children: [_jsx("label", { style: s.label, children: "Mode" }), _jsx("div", { style: { display: 'flex', gap: 6 }, children: ["translate", "rotate", "scale"].map(mode => (_jsx("button", { onClick: () => setTransformMode(mode), style: Object.assign(Object.assign(Object.assign({}, s.button), { flex: 1 }), (transformMode === mode ? s.buttonActive : null)), onPointerEnter: (e) => {
-                                if (transformMode !== mode)
-                                    e.currentTarget.style.background = 'rgba(255,255,255,0.08)';
-                            }, onPointerLeave: (e) => {
-                                if (transformMode !== mode)
-                                    e.currentTarget.style.background = 'transparent';
-                            }, children: mode[0].toUpperCase() }, mode))) })] }), node.components && Object.entries(node.components).map(([key, comp]) => {
+    return _jsxs("div", { style: s.root, children: [_jsx("div", { style: s.section, children: _jsx("input", { style: s.input, value: node.id, onChange: e => updateNode(n => (Object.assign(Object.assign({}, n), { id: e.target.value }))) }) }), _jsxs("div", { style: Object.assign(Object.assign(Object.assign({}, s.row), s.section), { paddingBottom: 6 }), children: [_jsx("label", { style: Object.assign(Object.assign({}, s.label), { marginBottom: 0 }), children: "Components" }), _jsx("button", { onClick: deleteNode, style: s.smallDanger, title: "Delete node", children: "\u2715" })] }), node.components && Object.entries(node.components).map(([key, comp]) => {
                 if (!comp)
                     return null;
                 const componentDef = ALL_COMPONENTS[comp.type];
@@ -196,7 +190,7 @@ function NodeInspector({ node, updateNode, deleteNode, transformMode, setTransfo
                                         const components = Object.assign({}, n.components);
                                         delete components[key];
                                         return Object.assign(Object.assign({}, n), { components });
-                                    }), style: s.smallDanger, title: "Remove component", children: "\u2715" })] }), EditorComp ? (_jsx(EditorComp, { component: comp, onUpdate: (newProps) => updateNode(n => (Object.assign(Object.assign({}, n), { components: Object.assign(Object.assign({}, n.components), { [key]: Object.assign(Object.assign({}, comp), { properties: Object.assign(Object.assign({}, comp.properties), newProps) }) }) }))), basePath: basePath })) : null] }, key));
+                                    }), style: s.smallDanger, title: "Remove component", children: "\u2715" })] }), EditorComp ? (_jsx(EditorComp, { component: comp, onUpdate: (newProps) => updateNode(n => (Object.assign(Object.assign({}, n), { components: Object.assign(Object.assign({}, n.components), { [key]: Object.assign(Object.assign({}, comp), { properties: Object.assign(Object.assign({}, comp.properties), newProps) }) }) }))), basePath: basePath, transformMode: transformMode, setTransformMode: setTransformMode })) : null] }, key));
             }), _jsxs("div", { style: Object.assign(Object.assign({}, s.section), { borderBottom: 'none', paddingBottom: 0 }), children: [_jsx("label", { style: s.label, children: "Add Component" }), _jsxs("div", { style: { display: 'flex', gap: 6 }, children: [_jsx("select", { style: s.select, value: addComponentType, onChange: e => setAddComponentType(e.target.value), children: allComponentKeys.filter(k => { var _a; return !((_a = node.components) === null || _a === void 0 ? void 0 : _a[k.toLowerCase()]); }).map(k => (_jsx("option", { value: k, children: k }, k))) }), _jsx("button", { style: Object.assign(Object.assign({}, s.addButton), (!addComponentType ? s.disabled : null)), disabled: !addComponentType, onClick: () => {
                                     var _a;
                                     if (!addComponentType)

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

@@ -1,5 +1,5 @@
 import React from "react";
-import * as THREE from 'three';
+import { Object3D, Group } from "three";
 export type InstanceData = {
     id: string;
     position: [number, number, number];
@@ -13,10 +13,10 @@ export type InstanceData = {
 export declare function GameInstanceProvider({ children, models, onSelect, registerRef }: {
     children: React.ReactNode;
     models: {
-        [filename: string]: THREE.Object3D;
+        [filename: string]: Object3D;
     };
     onSelect?: (id: string | null) => void;
-    registerRef?: (id: string, obj: THREE.Object3D | null) => void;
+    registerRef?: (id: string, obj: Object3D | null) => void;
 }): import("react/jsx-runtime").JSX.Element;
 export declare const GameInstance: React.ForwardRefExoticComponent<{
     id: string;
@@ -27,4 +27,4 @@ export declare const GameInstance: React.ForwardRefExoticComponent<{
     physics?: {
         type: "dynamic" | "fixed";
     };
-} & React.RefAttributes<THREE.Group<THREE.Object3DEventMap>>>;
+} & React.RefAttributes<Group<import("three").Object3DEventMap>>>;

package/dist/tools/prefabeditor/InstanceProvider.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React, { createContext, useContext, useMemo, useRef, useState, useEffect, useCallback } from "react";
 import { Merged } from '@react-three/drei';
-import * as THREE from 'three';
 import { InstancedRigidBodies } from "@react-three/rapier";
+import { Mesh, Matrix4 } from "three";
+// Helper functions for comparison
 function arrayEquals(a, b) {
     if (a === b)
         return true;
@@ -30,6 +31,7 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
         setInstances(prev => {
             const idx = prev.findIndex(i => i.id === instance.id);
             if (idx !== -1) {
+                // Update existing if changed
                 if (instanceEquals(prev[idx], instance)) {
                     return prev;
                 }
@@ -37,6 +39,7 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
                 copy[idx] = instance;
                 return copy;
             }
+            // Add new
             return [...prev, instance];
         });
     }, []);
@@ -47,14 +50,14 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
             return prev.filter(i => i.id !== id);
         });
     }, []);
-    // Flatten all model meshes once
+    // Flatten all model meshes once (models → flat mesh parts)
     const { flatMeshes, modelParts } = useMemo(() => {
         const flatMeshes = {};
         const modelParts = {};
         Object.entries(models).forEach(([modelKey, model]) => {
             const root = model;
             root.updateWorldMatrix(false, true);
-            const rootInverse = new THREE.Matrix4().copy(root.matrixWorld).invert();
+            const rootInverse = new Matrix4().copy(root.matrixWorld).invert();
             let partIndex = 0;
             root.traverse((obj) => {
                 if (obj.isMesh) {
@@ -62,7 +65,7 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
                     const relativeTransform = obj.matrixWorld.clone().premultiply(rootInverse);
                     geom.applyMatrix4(relativeTransform);
                     const partKey = `${modelKey}__${partIndex}`;
-                    flatMeshes[partKey] = new THREE.Mesh(geom, obj.material);
+                    flatMeshes[partKey] = new Mesh(geom, obj.material);
                     partIndex++;
                 }
             });
@@ -70,7 +73,7 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
         });
         return { flatMeshes, modelParts };
     }, [models]);
-    // Group instances by meshPath + physics type
+    // Group instances by meshPath + physics type for batch rendering
     const grouped = useMemo(() => {
         var _a;
         const groups = {};
@@ -104,7 +107,7 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
                 const partCount = modelParts[modelKey] || 0;
                 if (partCount === 0)
                     return null;
-                // Restrict meshes to just this model's parts for this Merged
+                // Create mesh subset for this specific model
                 const meshesForModel = {};
                 for (let i = 0; i < partCount; i++) {
                     const partKey = `${modelKey}__${i}`;
@@ -113,7 +116,7 @@ export function GameInstanceProvider({ children, models, onSelect, registerRef }
                 return (_jsx(Merged, { meshes: meshesForModel, castShadow: true, receiveShadow: true, children: (instancesMap) => (_jsx(NonPhysicsInstancedGroup, { modelKey: modelKey, group: group, partCount: partCount, instancesMap: instancesMap, onSelect: onSelect, registerRef: registerRef })) }, key));
             })] }));
 }
-// Physics instancing stays the same
+// Render physics-enabled instances using InstancedRigidBodies
 function InstancedRigidGroup({ group, modelKey, partCount, flatMeshes }) {
     const instances = useMemo(() => group.instances.map(inst => ({
         key: inst.id,
@@ -126,12 +129,17 @@ function InstancedRigidGroup({ group, modelKey, partCount, flatMeshes }) {
             return (_jsx("instancedMesh", { args: [mesh.geometry, mesh.material, group.instances.length], castShadow: true, receiveShadow: true, frustumCulled: false }, i));
         }) }));
 }
-// Non-physics instanced visuals: per-instance group using Merged's Instance components
+// Render non-physics instances using Merged's per-instance groups
 function NonPhysicsInstancedGroup({ modelKey, group, partCount, instancesMap, onSelect, registerRef }) {
     const clickValid = useRef(false);
-    const handlePointerDown = (e) => { e.stopPropagation(); clickValid.current = true; };
-    const handlePointerMove = () => { if (clickValid.current)
-        clickValid.current = false; };
+    const handlePointerDown = (e) => {
+        e.stopPropagation();
+        clickValid.current = true;
+    };
+    const handlePointerMove = () => {
+        if (clickValid.current)
+            clickValid.current = false;
+    };
     const handlePointerUp = (e, id) => {
         if (clickValid.current) {
             e.stopPropagation();
@@ -146,7 +154,7 @@ function NonPhysicsInstancedGroup({ modelKey, group, partCount, instancesMap, on
                 return _jsx(Instance, {}, i);
             }) }, inst.id))) }));
 }
-// --- GameInstance: just registers an instance, renders nothing ---
+// GameInstance component: registers an instance for batch rendering (renders nothing itself)
 export const GameInstance = React.forwardRef(({ id, modelUrl, position, rotation, scale, physics = undefined, }, ref) => {
     const ctx = useContext(GameInstanceContext);
     const addInstance = ctx === null || ctx === void 0 ? void 0 : ctx.addInstance;
@@ -167,6 +175,6 @@ export const GameInstance = React.forwardRef(({ id, modelUrl, position, rotation
             removeInstance(instance.id);
         };
     }, [addInstance, removeInstance, instance]);
-    // No visual here – provider will render visuals for all instances
+    // No visual rendering - provider handles all instanced visuals
     return null;
 });