react-three-game 0.0.49 → 0.0.50

package/README.md

@@ -163,9 +163,13 @@ Keys: **T**ranslate / **R**otate / **S**cale. Drag tree nodes to reparent. Impor
 ## Tree Utilities
 
 ```typescript
-import { findNode, updateNode, deleteNode, cloneNode } from 'react-three-game';
+import { findNode, updateNode, updateNodeById, deleteNode, cloneNode, exportGLBData } from 'react-three-game';
 
-const updated = updateNode(root, nodeId, n => ({ ...n, disabled: true }));
+const node = findNode(root, nodeId);
+const updated = updateNode(root, nodeId, n => ({ ...n, disabled: true }));  // or updateNodeById
+const afterDelete = deleteNode(root, nodeId);
+const cloned = cloneNode(node);
+const glbData = await exportGLBData(sceneRoot);  // export scene to GLB ArrayBuffer
 ```
 
 ## Development

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

@@ -1,8 +1,10 @@
 import { Group, Matrix4, Object3D, Texture } from "three";
 import { ThreeEvent } from "@react-three/fiber";
 import { Prefab, GameObject as GameObjectType } from "./types";
+import type { RapierRigidBody } from "@react-three/rapier";
 export interface PrefabRootRef {
     root: Group | null;
+    rigidBodyRefs: Map<string, RapierRigidBody | null>;
 }
 export declare const PrefabRoot: import("react").ForwardRefExoticComponent<{
     editMode?: boolean;
@@ -20,6 +22,7 @@ interface RendererProps {
     onSelect?: (id: string) => void;
     onClick?: (event: ThreeEvent<PointerEvent>, entity: GameObjectType) => void;
     registerRef: (id: string, obj: Object3D | null) => void;
+    registerRigidBodyRef: (id: string, rb: RapierRigidBody | null) => void;
     loadedModels: Record<string, Object3D>;
     loadedTextures: Record<string, Texture>;
     editMode?: boolean;

package/dist/tools/prefabeditor/PrefabRoot.js

@@ -30,16 +30,21 @@ export const PrefabRoot = forwardRef(({ editMode, data, onPrefabChange, selected
     const [textures, setTextures] = useState({});
     const loading = useRef(new Set());
     const objectRefs = useRef({});
+    const rigidBodyRefs = useRef(new Map());
     const [selectedObject, setSelectedObject] = useState(null);
     const rootRef = useRef(null);
     useImperativeHandle(ref, () => ({
-        root: rootRef.current
+        root: rootRef.current,
+        rigidBodyRefs: rigidBodyRefs.current
     }), []);
     const registerRef = useCallback((id, obj) => {
         objectRefs.current[id] = obj;
         if (id === selectedId)
             setSelectedObject(obj);
     }, [selectedId]);
+    const registerRigidBodyRef = useCallback((id, rb) => {
+        rigidBodyRefs.current.set(id, rb);
+    }, []);
     useEffect(() => {
         const originalError = console.error;
         console.error = (...args) => {
@@ -103,7 +108,7 @@ export const PrefabRoot = forwardRef(({ editMode, data, onPrefabChange, selected
             });
         });
     }, [data, models, textures]);
-    return (_jsxs("group", { ref: rootRef, children: [_jsx(GameInstanceProvider, { models: models, selectedId: selectedId, editMode: editMode, onSelect: editMode ? onSelect : undefined, registerRef: registerRef, children: _jsx(GameObjectRenderer, { gameObject: data.root, selectedId: selectedId, onSelect: editMode ? onSelect : undefined, onClick: onClick, registerRef: registerRef, loadedModels: models, loadedTextures: textures, editMode: editMode, parentMatrix: IDENTITY }) }), editMode && (_jsxs(_Fragment, { children: [_jsx(MapControls, { makeDefault: true }), selectedObject && (_jsx(TransformControls, { object: selectedObject, mode: transformMode, space: "local", onObjectChange: onTransformChange, translationSnap: snapResolution > 0 ? snapResolution : undefined, rotationSnap: snapResolution > 0 ? snapResolution : undefined, scaleSnap: snapResolution > 0 ? snapResolution : undefined }, `transform-${snapResolution}`))] }))] }));
+    return (_jsxs("group", { ref: rootRef, children: [_jsx(GameInstanceProvider, { models: models, selectedId: selectedId, editMode: editMode, onSelect: editMode ? onSelect : undefined, registerRef: registerRef, children: _jsx(GameObjectRenderer, { gameObject: data.root, selectedId: selectedId, onSelect: editMode ? onSelect : undefined, onClick: onClick, registerRef: registerRef, registerRigidBodyRef: registerRigidBodyRef, loadedModels: models, loadedTextures: textures, editMode: editMode, parentMatrix: IDENTITY }) }), editMode && (_jsxs(_Fragment, { children: [_jsx(MapControls, { makeDefault: true }), selectedObject && (_jsx(TransformControls, { object: selectedObject, mode: transformMode, space: "local", onObjectChange: onTransformChange, translationSnap: snapResolution > 0 ? snapResolution : undefined, rotationSnap: snapResolution > 0 ? snapResolution : undefined, scaleSnap: snapResolution > 0 ? snapResolution : undefined }, `transform-${snapResolution}`))] }))] }));
 });
 export function GameObjectRenderer(props) {
     var _a, _b, _c;
@@ -160,7 +165,7 @@ function InstancedNode({ gameObject, parentMatrix = IDENTITY, editMode, register
     }
     return (_jsx(GameInstance, { id: gameObject.id, modelUrl: (_k = (_j = (_h = gameObject.components) === null || _h === void 0 ? void 0 : _h.model) === null || _j === void 0 ? void 0 : _j.properties) === null || _k === void 0 ? void 0 : _k.filename, position: worldPosition, rotation: worldRotation, scale: worldScale, physics: physicsProps }));
 }
-function StandardNode({ gameObject, selectedId, onSelect, onClick, registerRef, loadedModels, loadedTextures, editMode, parentMatrix = IDENTITY, }) {
+function StandardNode({ gameObject, selectedId, onSelect, onClick, registerRef, registerRigidBodyRef, loadedModels, loadedTextures, editMode, parentMatrix = IDENTITY, }) {
     var _a, _b, _c, _d, _e, _f;
     const groupRef = useRef(null);
     const helperRef = useRef(null);
@@ -193,12 +198,12 @@ function StandardNode({ gameObject, selectedId, onSelect, onClick, registerRef,
     const physicsDef = hasPhysics ? getComponent("Physics") : null;
     const isInstanced = (_e = (_d = (_c = gameObject.components) === null || _c === void 0 ? void 0 : _c.model) === null || _d === void 0 ? void 0 : _d.properties) === null || _e === void 0 ? void 0 : _e.instanced;
     const physicsKey = `physics_${gameObject.id}_${isInstanced ? 'instanced' : 'standard'}`;
-    const inner = (_jsxs("group", { onPointerDown: editMode ? onDown : undefined, onPointerMove: editMode ? () => (clickValid.current = false) : undefined, onPointerUp: editMode ? onUp : undefined, children: [renderCoreNode(gameObject, { loadedModels, loadedTextures, editMode, registerRef }, parentMatrix), (_f = gameObject.children) === null || _f === void 0 ? void 0 : _f.map(child => (_jsx(GameObjectRenderer, { gameObject: child, selectedId: selectedId, onSelect: onSelect, onClick: onClick, registerRef: registerRef, loadedModels: loadedModels, loadedTextures: loadedTextures, editMode: editMode, parentMatrix: world }, child.id)))] }));
+    const inner = (_jsxs("group", { onPointerDown: editMode ? onDown : undefined, onPointerMove: editMode ? () => (clickValid.current = false) : undefined, onPointerUp: editMode ? onUp : undefined, children: [renderCoreNode(gameObject, { loadedModels, loadedTextures, editMode, registerRef }, parentMatrix), (_f = gameObject.children) === null || _f === void 0 ? void 0 : _f.map(child => (_jsx(GameObjectRenderer, { gameObject: child, selectedId: selectedId, onSelect: onSelect, onClick: onClick, registerRef: registerRef, registerRigidBodyRef: registerRigidBodyRef, loadedModels: loadedModels, loadedTextures: loadedTextures, editMode: editMode, parentMatrix: world }, child.id)))] }));
     if (editMode) {
-        return (_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, editMode: editMode, children: inner }, physicsKey)) : null] }));
+        return (_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, editMode: editMode, nodeId: gameObject.id, registerRigidBodyRef: registerRigidBodyRef, children: inner }, physicsKey)) : null] }));
     }
     if (hasPhysics && (physicsDef === null || physicsDef === void 0 ? void 0 : physicsDef.View)) {
-        return (_jsx(physicsDef.View, { properties: physics.properties, position: transform.position, rotation: transform.rotation, scale: transform.scale, editMode: editMode, children: inner }, physicsKey));
+        return (_jsx(physicsDef.View, { properties: physics.properties, position: transform.position, rotation: transform.rotation, scale: transform.scale, editMode: editMode, nodeId: gameObject.id, registerRigidBodyRef: registerRigidBodyRef, children: inner }, physicsKey));
     }
     return (_jsx("group", { ref: groupRef, position: transform.position, rotation: transform.rotation, scale: transform.scale, onPointerDown: onDown, onPointerMove: () => (clickValid.current = false), onPointerUp: onUp, children: inner }));
 }

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

@@ -1,3 +1,12 @@
 import { Component } from './ComponentRegistry';
+import { MeshStandardMaterialProperties } from 'three';
+export interface MaterialProps extends Omit<MeshStandardMaterialProperties, 'args'> {
+    texture?: string;
+    repeat?: boolean;
+    repeatCount?: [number, number];
+    generateMipmaps?: boolean;
+    minFilter?: string;
+    magFilter?: string;
+}
 declare const MaterialComponent: Component;
 export default MaterialComponent;

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

@@ -1,3 +1,14 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { SingleTextureViewer, TextureListViewer } from '../../assetviewer/page';
 import { useEffect, useState } from 'react';
@@ -25,6 +36,13 @@ function MaterialComponentEditor({ component, onUpdate, basePath = "" }) {
     const fields = [
         { name: 'color', type: 'color', label: 'Color' },
         { name: 'wireframe', type: 'boolean', label: 'Wireframe' },
+        { name: 'transparent', type: 'boolean', label: 'Transparent' },
+        { name: 'opacity', type: 'number', label: 'Opacity', min: 0, max: 1, step: 0.01 },
+        { name: 'metalness', type: 'number', label: 'Metalness', min: 0, max: 1, step: 0.01 },
+        { name: 'roughness', type: 'number', label: 'Roughness', min: 0, max: 1, step: 0.01 },
+        { name: 'transmission', type: 'number', label: 'Transmission', min: 0, max: 1, step: 0.01 },
+        { name: 'thickness', type: 'number', label: 'Thickness', min: 0, step: 0.1 },
+        { name: 'ior', type: 'number', label: 'IOR (Index of Refraction)', min: 1, max: 2.333, step: 0.01 },
         {
             name: 'texture',
             type: 'custom',
@@ -80,6 +98,9 @@ function MaterialComponentView({ properties, loadedTextures }) {
     const minFilter = (properties === null || properties === void 0 ? void 0 : properties.minFilter) || 'LinearMipmapLinearFilter';
     const magFilter = (properties === null || properties === void 0 ? void 0 : properties.magFilter) || 'LinearFilter';
     const texture = textureName && loadedTextures ? loadedTextures[textureName] : undefined;
+    // Destructure all material props and separate custom texture handling props
+    const _b = properties || {}, { texture: _texture, repeat: _repeat, repeatCount: _repeatCount, generateMipmaps: _generateMipmaps, minFilter: _minFilter, magFilter: _magFilter, map: _map } = _b, // Filter out map since we set it explicitly
+    materialProps = __rest(_b, ["texture", "repeat", "repeatCount", "generateMipmaps", "minFilter", "magFilter", "map"]);
     const minFilterMap = {
         NearestFilter,
         LinearFilter,
@@ -116,8 +137,7 @@ function MaterialComponentView({ properties, loadedTextures }) {
     if (!properties) {
         return _jsx("meshStandardMaterial", { color: "red", wireframe: true });
     }
-    const { color, wireframe = false } = properties;
-    return (_jsx("meshStandardMaterial", { color: color, wireframe: wireframe, map: finalTexture, transparent: !!finalTexture }, (_a = finalTexture === null || finalTexture === void 0 ? void 0 : finalTexture.uuid) !== null && _a !== void 0 ? _a : 'no-texture'));
+    return (_jsx("meshStandardMaterial", Object.assign({ map: finalTexture }, materialProps), (_a = finalTexture === null || finalTexture === void 0 ? void 0 : finalTexture.uuid) !== null && _a !== void 0 ? _a : 'no-texture'));
 }
 const MaterialComponent = {
     name: 'Material',
@@ -126,7 +146,11 @@ const MaterialComponent = {
     nonComposable: true,
     defaultProperties: {
         color: '#ffffff',
-        wireframe: false
+        wireframe: false,
+        transparent: false,
+        opacity: 1,
+        metalness: 0,
+        roughness: 1
     }
 };
 export default MaterialComponent;

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

@@ -11,6 +11,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { jsx as _jsx } from "react/jsx-runtime";
 import { RigidBody } from "@react-three/rapier";
+import { useRef, useEffect } from 'react';
 import { FieldRenderer } from "./Input";
 const physicsFields = [
     {
@@ -79,15 +80,27 @@ const physicsFields = [
 function PhysicsComponentEditor({ component, onUpdate }) {
     return (_jsx(FieldRenderer, { fields: physicsFields, values: component.properties, onChange: (props) => onUpdate(Object.assign(Object.assign({}, component), { properties: Object.assign(Object.assign({}, component.properties), props) })) }));
 }
-function PhysicsComponentView({ properties, children, position, rotation, scale, editMode }) {
+function PhysicsComponentView({ properties, children, position, rotation, scale, editMode, nodeId, registerRigidBodyRef }) {
     const { type, colliders } = properties, otherProps = __rest(properties, ["type", "colliders"]);
     const colliderType = colliders || (type === 'fixed' ? 'trimesh' : 'hull');
+    const rigidBodyRef = useRef(null);
+    // Register RigidBody ref when it's available
+    useEffect(() => {
+        if (nodeId && registerRigidBodyRef && rigidBodyRef.current) {
+            registerRigidBodyRef(nodeId, rigidBodyRef.current);
+        }
+        return () => {
+            if (nodeId && registerRigidBodyRef) {
+                registerRigidBodyRef(nodeId, null);
+            }
+        };
+    }, [nodeId, registerRigidBodyRef]);
     // In edit mode, include position/rotation in key to force remount when transform changes
     // This ensures the RigidBody debug visualization updates even when physics is paused
     const rbKey = editMode
         ? `${type || 'dynamic'}_${colliderType}_${position === null || position === void 0 ? void 0 : position.join(',')}_${rotation === null || rotation === void 0 ? void 0 : rotation.join(',')}`
         : `${type || 'dynamic'}_${colliderType}`;
-    return (_jsx(RigidBody, Object.assign({ type: type, colliders: colliderType, position: position, rotation: rotation, scale: scale }, otherProps, { children: children }), rbKey));
+    return (_jsx(RigidBody, Object.assign({ ref: rigidBodyRef, type: type, colliders: colliderType, position: position, rotation: rotation, scale: scale }, otherProps, { children: children }), rbKey));
 }
 const PhysicsComponent = {
     name: 'Physics',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-three-game",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "Batteries included React Three Fiber game engine",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/react-three-game-skill/react-three-game/SKILL.md

@@ -116,7 +116,7 @@ Scenes are defined as JSON prefabs with a root node containing children:
 | Transform | `Transform` | `position: [x,y,z]`, `rotation: [x,y,z]` (radians), `scale: [x,y,z]` |
 | Geometry | `Geometry` | `geometryType`: box/sphere/plane/cylinder, `args`: dimension array |
 | Material | `Material` | `color`, `texture?`, `metalness?`, `roughness?`, `repeat?`, `repeatCount?` |
-| Physics | `Physics` | `type`: dynamic/fixed/kinematicPosition/kinematicVelocity, `mass?`, `restitution?`, `friction?`, `linearDamping?`, `angularDamping?`, `gravityScale?`, plus any Rapier RigidBody props |
+| Physics | `Physics` | `type`: dynamic/fixed/kinematicPosition/kinematicVelocity, `mass?`, `restitution?`, `friction?`, `linearDamping?`, `angularDamping?`, `gravityScale?`, plus any Rapier RigidBody props - [See advanced physics guide](./rules/ADVANCED_PHYSICS.md) |
 | Model | `Model` | `filename` (GLB/FBX path), `instanced?` for GPU batching |
 | SpotLight | `SpotLight` | `color`, `intensity`, `angle`, `penumbra`, `distance?`, `castShadow?` |
 | DirectionalLight | `DirectionalLight` | `color`, `intensity`, `castShadow?`, `targetOffset?: [x,y,z]` |
@@ -191,102 +191,71 @@ import { PrefabEditor } from 'react-three-game';
 ### Tree Utilities
 
 ```typescript
-import { updateNodeById, findNode, deleteNode, cloneNode, exportGLBData } from 'react-three-game';
+import { findNode, updateNode, updateNodeById, deleteNode, cloneNode, exportGLBData } from 'react-three-game';
 
-const updated = updateNodeById(root, nodeId, node => ({ ...node, disabled: true }));
 const node = findNode(root, nodeId);
+const updated = updateNode(root, nodeId, n => ({ ...n, disabled: true }));  // or updateNodeById (identical)
 const afterDelete = deleteNode(root, nodeId);
 const cloned = cloneNode(node);
 const glbData = await exportGLBData(sceneRoot);
 ```
 
-## Level Patterns
+## Hybrid JSON + R3F Children Pattern
 
-### Floor
+**Prefabs define static scene structure, R3F children add dynamic behavior**:
 
-```json
-{
-  "id": "floor",
-  "components": {
-    "transform": { "type": "Transform", "properties": { "position": [0, -0.5, 0] } },
-    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [40, 1, 40] } },
-    "material": { "type": "Material", "properties": { "texture": "/textures/floor.png", "repeat": true, "repeatCount": [20, 20] } },
-    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
-  }
-}
-```
-
-### Platform
-
-```json
-{
-  "id": "platform",
-  "components": {
-    "transform": { "type": "Transform", "properties": { "position": [-8, 2, -5] } },
-    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [6, 0.5, 4] } },
-    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
-  }
-}
-```
-
-### Ramp
-
-```json
-{
-  "id": "ramp",
-  "components": {
-    "transform": { "type": "Transform", "properties": { "position": [-12, 1, -5], "rotation": [0, 0, 0.3] } },
-    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [5, 0.3, 3] } },
-    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
-  }
-}
-```
-
-### Wall Pattern
-### Wall
+```tsx
+import { useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { PrefabEditor, findNode } from 'react-three-game';
+import type { PrefabEditorRef } from 'react-three-game';
 
-```json
-{
-  "id": "wall",
-  "components": {
-    "transform": { "type": "Transform", "properties": { "position": [0, 3, -20] } },
-    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [40, 7, 1] } },
-    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
-  }
+function DynamicLight() {
+  const lightRef = useRef<THREE.SpotLight>(null!);
+  
+  useFrame(({ clock }) => {
+    lightRef.current.intensity = 100 + Math.sin(clock.elapsedTime) * 50;
+  });
+  
+  return <spotLight ref={lightRef} position={[10, 15, 10]} angle={0.5} />;
 }
-```
 
-### Lighting
-
-```json
-[
-  { "id": "spot", "components": { "transform": { "properties": { "position": [10, 15, 10] } }, "spotlight": { "type": "SpotLight", "properties": { "intensity": 200, "angle": 0.8, "castShadow": true } } } },
-  { "id": "ambient", "components": { "ambientlight": { "type": "AmbientLight", "properties": { "intensity": 0.4 } } } }
-]
+<PrefabEditor initialPrefab={staticScenePrefab}>
+  <DynamicLight />
+  <CustomController />
+</PrefabEditor>
 ```
 
-### Text
-
-```json
-{
-  "id": "text",
-  "components": {
-    "transform": { "type": "Transform", "properties": { "position": [0, 3, 0] } },
-    "text": { "type": "Text", "properties": { "text": "Welcome", "font": "/fonts/font.ttf", "size": 1, "depth": 0.1 } }
-  }
-}
-```
+**Use cases**: Player controllers, AI behaviors, procedural animation, real-time effects.
 
-### Model
+## Quick Reference Examples
 
 ```json
-{
-  "id": "model",
-  "components": {
-    "transform": { "type": "Transform", "properties": { "position": [0, 0, 0], "scale": [1.5, 1.5, 1.5] } },
-    "model": { "type": "Model", "properties": { "filename": "/models/tree.glb" } }
-  }
-}
+// Static geometry with physics (floor, wall, platform, ramp)
+{ "id": "floor", "components": {
+  "transform": { "type": "Transform", "properties": { "position": [0, -0.5, 0] } },
+  "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [40, 1, 40] } },
+  "material": { "type": "Material", "properties": { "texture": "/textures/floor.png", "repeat": true, "repeatCount": [20, 20] } },
+  "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+}}
+
+// Lighting
+{ "id": "spot", "components": {
+  "transform": { "type": "Transform", "properties": { "position": [10, 15, 10] } },
+  "spotlight": { "type": "SpotLight", "properties": { "intensity": 200, "angle": 0.8, "castShadow": true } }
+}}
+
+// 3D Text
+{ "id": "title", "components": {
+  "transform": { "type": "Transform", "properties": { "position": [0, 3, 0] } },
+  "text": { "type": "Text", "properties": { "text": "Welcome", "font": "/fonts/font.ttf", "size": 1, "depth": 0.1 } }
+}}
+
+// GLB Model
+{ "id": "tree", "components": {
+  "transform": { "type": "Transform", "properties": { "position": [0, 0, 0], "scale": [1.5, 1.5, 1.5] } },
+  "model": { "type": "Model", "properties": { "filename": "/models/tree.glb" } }
+}}
 ```
 
 ## Editor
@@ -301,6 +270,21 @@ import { PrefabEditor } from 'react-three-game';
 
 Keyboard shortcuts: **T** (Translate), **R** (Rotate), **S** (Scale)
 
+### Camera Control
+
+By default, `PrefabEditor` uses an orbit camera. **Override it by adding a custom camera with `makeDefault`**:
+
+```tsx
+import { PerspectiveCamera } from '@react-three/drei';
+import { PrefabEditor } from 'react-three-game';
+
+<PrefabEditor initialPrefab={prefab}>
+  <PerspectiveCamera makeDefault position={[0, 5, 10]} fov={75} />
+</PrefabEditor>
+```
+
+Any R3F camera component works: `PerspectiveCamera`, `OrthographicCamera`, or custom camera controllers.
+
 ### Programmatic Updates
 
 ```jsx

package/react-three-game-skill/react-three-game/rules/ADVANCED_PHYSICS.md

@@ -0,0 +1,349 @@
+# Advanced Physics & Patterns
+
+## Physics Type Decision Tree
+
+```
+Need physics?
+├─ No  → Don't add Physics component
+└─ Yes → Does it move?
+    ├─ Never moves (walls, floor, static props)
+    │   └─ type: "fixed"
+    │
+    ├─ Moves via forces/gravity (balls, boxes, ragdolls)
+    │   └─ type: "dynamic"
+    │       ├─ Fast moving? → ccd: true
+    │       └─ Heavy? → mass: 10+
+    │
+    ├─ Scripted animation (moving platforms, doors)
+    │   └─ type: "kinematicPosition"
+    │       └─ Update transform via updateNodeById
+    │
+    └─ Velocity-driven (conveyor belts, wind zones)
+        └─ type: "kinematicVelocity"
+            └─ Set velocity via RigidBody ref
+```
+
+**Type descriptions**:
+- **fixed**: Immovable, infinite mass (ground, walls, buildings)
+- **dynamic**: Affected by forces and gravity (player, projectiles, props)
+- **kinematicPosition**: Move via code, push dynamic bodies (elevators, doors)
+- **kinematicVelocity**: Set constant velocity, push dynamic bodies (conveyors)
+
+**Performance tip**: Use `fixed` for anything that never moves - it's cheapest.
+
+## Physics Material Properties
+
+Complete reference for `Physics` component properties:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'dynamic'` \| `'fixed'` \| `'kinematicPosition'` \| `'kinematicVelocity'` | `'dynamic'` | Body type (see decision tree above) |
+| `mass` | `number` | `1` | Body mass (dynamic only) |
+| `restitution` | `number` | `0` | Bounciness (0 = no bounce, 1 = perfect bounce) |
+| `friction` | `number` | `0.5` | Surface friction (0 = ice, 1+ = sticky) |
+| `linearDamping` | `number` | `0` | Velocity decay (0 = none, 1 = full stop) |
+| `angularDamping` | `number` | `0` | Rotation decay |
+| `gravityScale` | `number` | `1` | Gravity multiplier (0 = floating, 2 = heavy) |
+| `lockTranslations` | `boolean` | `false` | Freeze position |
+| `lockRotations` | `boolean` | `false` | Freeze rotation |
+| `enabledTranslations` | `[bool, bool, bool]` | `[true, true, true]` | Lock per axis (X, Y, Z) |
+| `enabledRotations` | `[bool, bool, bool]` | `[true, true, true]` | Lock rotation per axis |
+| `ccd` | `boolean` | `false` | Continuous collision detection (fast objects) |
+| `sensor` | `boolean` | `false` | Trigger only, no collision response |
+| `collisionGroups` | `number` | - | Rapier collision groups bitfield |
+| `solverGroups` | `number` | - | Rapier solver groups bitfield |
+
+**Example - Bouncy Ball**:
+```json
+{
+  "physics": {
+    "type": "Physics",
+    "properties": {
+      "type": "dynamic",
+      "mass": 0.5,
+      "restitution": 0.9,
+      "friction": 0.1,
+      "linearDamping": 0.05
+    }
+  }
+}
+```
+
+**Example - Ice Surface**:
+```json
+{
+  "physics": {
+    "type": "Physics",
+    "properties": {
+      "type": "fixed",
+      "friction": 0,
+      "restitution": 0.1
+    }
+  }
+}
+```
+
+## Force & Impulse Application
+
+Access RigidBody refs via `PrefabRootRef.rigidBodyRefs` to apply physics forces to prefab objects:
+
+```tsx
+import { useRef, useEffect } from 'react';
+import { PrefabEditor } from 'react-three-game';
+import type { PrefabEditorRef } from 'react-three-game';
+import type { RapierRigidBody } from '@react-three/rapier';
+
+function ForceApplier({ editorRef }: { editorRef: React.RefObject<PrefabEditorRef> }) {
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const rootRef = editorRef.current?.rootRef.current;
+      if (!rootRef) return;
+      
+      // Access RigidBody ref by node ID
+      const rigidBody = rootRef.rigidBodyRefs.get('ball') as RapierRigidBody;
+      
+      if (rigidBody) {
+        // Apply upward impulse
+        rigidBody.applyImpulse({ x: 0, y: 5, z: 0 }, true);
+        
+        // Or apply continuous force
+        rigidBody.addForce({ x: 0, y: 10, z: 0 }, true);
+        
+        // Apply torque
+        rigidBody.applyTorqueImpulse({ x: 0, y: 1, z: 0 }, true);
+      }
+    }, 2000);
+    
+    return () => clearInterval(interval);
+  }, [editorRef]);
+  
+  return null;
+}
+
+function Scene() {
+  const editorRef = useRef<PrefabEditorRef>(null);
+  
+  return (
+    <PrefabEditor ref={editorRef} initialPrefab={prefab}>
+      <ForceApplier editorRef={editorRef} />
+    </PrefabEditor>
+  );
+}
+```
+
+**Alternative: Custom R3F components**
+
+For fully custom physics objects, create R3F components with their own RigidBody refs:
+
+```tsx
+import { useRef } from 'react';
+import { RigidBody } from '@react-three/rapier';
+import type { RapierRigidBody } from '@react-three/rapier';
+import { useFrame } from '@react-three/fiber';
+import { PrefabEditor } from 'react-three-game';
+
+function PhysicsBall() {
+  const rigidBodyRef = useRef<RapierRigidBody>(null);
+  
+  useFrame(() => {
+    if (rigidBodyRef.current) {
+      // Apply jump force on interval
+      rigidBodyRef.current.applyImpulse({ x: 0, y: 5, z: 0 }, true);
+    }
+  });
+  
+  return (
+    <RigidBody ref={rigidBodyRef} position={[0, 5, 0]} type="dynamic">
+      <mesh castShadow>
+        <sphereGeometry args={[0.5, 32, 32]} />
+        <meshStandardMaterial color="orange" />
+      </mesh>
+    </RigidBody>
+  );
+}
+
+<PrefabEditor initialPrefab={prefab}>
+  <PhysicsBall />
+</PrefabEditor>
+```
+
+**Alternative: Kinematic position updates**
+
+For smooth animated movement without forces, use `kinematicPosition` and update via `updateNodeById`:
+
+```tsx
+import { useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { PrefabEditor, updateNodeById } from 'react-three-game';
+import type { PrefabEditorRef } from 'react-three-game';
+
+function KinematicMover({ editorRef }: { editorRef: React.RefObject<PrefabEditorRef> }) {
+  useFrame(({ clock }) => {
+    const prefab = editorRef.current?.prefab;
+    if (!prefab) return;
+    
+    const y = 2 + Math.sin(clock.elapsedTime * 2) * 3;
+    
+    const newRoot = updateNodeById(prefab.root, "platform", node => ({
+      ...node,
+      components: {
+        ...node.components,
+        transform: {
+          ...node.components!.transform!,
+          properties: {
+            ...node.components!.transform!.properties,
+            position: [0, y, 0]
+          }
+        }
+      }
+    }));
+    
+    editorRef.current!.setPrefab({ ...prefab, root: newRoot });
+  });
+  
+  return null;
+}
+```
+
+**Rapier RigidBody methods**:
+- `applyImpulse(vector, wakeUp)` - Instantaneous velocity change
+- `addForce(vector, wakeUp)` - Continuous force application
+- `applyTorqueImpulse(vector, wakeUp)` - Rotational impulse
+- `addTorque(vector, wakeUp)` - Continuous torque
+- `setLinvel(vector, wakeUp)` - Set linear velocity directly
+- `setAngvel(vector, wakeUp)` - Set angular velocity directly
+
+## Tilted Surfaces & Containment
+
+**⚠️ Tilted walls don't contain objects** - physics objects slide off angled surfaces.
+
+### ❌ Wrong Approach
+```json
+{
+  "id": "tilted-wall",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "rotation": [0, 0, 0.3] } },
+    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [10, 5, 1] } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+  }
+}
+```
+Objects will **slide off** the tilted surface.
+
+### ✅ Correct Pattern - Perpendicular Walls
+```json
+{
+  "id": "container",
+  "children": [
+    {
+      "id": "floor",
+      "components": {
+        "transform": { "type": "Transform", "properties": { "position": [0, 0, 0] } },
+        "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [20, 1, 20] } },
+        "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+      }
+    },
+    {
+      "id": "wall-north",
+      "components": {
+        "transform": { "type": "Transform", "properties": { "position": [0, 2.5, -10] } },
+        "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [20, 5, 1] } },
+        "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+      }
+    },
+    {
+      "id": "wall-south",
+      "components": {
+        "transform": { "type": "Transform", "properties": { "position": [0, 2.5, 10] } },
+        "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [20, 5, 1] } },
+        "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+      }
+    },
+    {
+      "id": "wall-east",
+      "components": {
+        "transform": { "type": "Transform", "properties": { "position": [10, 2.5, 0] } },
+        "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [1, 5, 20] } },
+        "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+      }
+    },
+    {
+      "id": "wall-west",
+      "components": {
+        "transform": { "type": "Transform", "properties": { "position": [-10, 2.5, 0] } },
+        "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [1, 5, 20] } },
+        "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+      }
+    }
+  ]
+}
+```
+
+**Key principle**: Walls must be **perpendicular to gravity** to contain dynamic objects.
+
+## Instanced Physics
+
+When using `"instanced": true` on models, physics behaves differently than standard objects. **All instances of the same model share a single `InstancedRigidBodies` component** for optimal GPU performance.
+
+### Standard vs Instanced Physics
+
+| Aspect | Standard Physics | Instanced Physics |
+|--------|------------------|-------------------|
+| RigidBody Component | Individual `<RigidBody>` per object | Single `<InstancedRigidBodies>` for all instances |
+| Ref Access | `rigidBodyRefs.get(nodeId)` returns single RigidBody | Not accessible via `rigidBodyRefs` |
+| Force Application | Direct per-object | Must access via InstancedRigidBodies ref |
+| Collider Type | `hull` (dynamic) or `trimesh` (fixed) | Same, auto-selected |
+| Performance | One draw call per object | One draw call for all instances |
+
+### Defining Instanced Objects
+
+Set `"instanced": true` in the model component. **All instances of the same model+physics type are automatically batched**:
+
+```json
+{
+  "id": "tree1",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [0, 0, 0] } },
+    "model": { "type": "Model", "properties": { "filename": "models/tree.glb", "instanced": true } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+  }
+}
+```
+
+Add multiple instances - they'll be automatically batched:
+
+```json
+{
+  "id": "tree2",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [5, 0, 3] } },
+    "model": { "type": "Model", "properties": { "filename": "models/tree.glb", "instanced": true } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+  }
+}
+```
+
+### Force Application on Instanced Objects
+
+**Instanced physics bodies are not individually accessible.** For objects requiring force/impulse control, use non-instanced physics (`"instanced": false` or omit the property).
+
+### When to Use Instanced Physics
+
+✅ **Good for:**
+- Many copies of the same static object (trees, rocks, buildings)
+- Large scenes with 100+ similar objects
+- Fixed physics bodies that never move
+- Background props and decorations
+
+❌ **Avoid for:**
+- Objects requiring individual force/impulse control
+- Dynamic objects with unique behaviors
+- Objects that need to be individually removed/spawned
+- Fewer than ~20 instances (overhead not worth it)
+
+### Performance Notes
+
+- **Batching**: All instances with the same `filename` and `physics.type` are rendered in a single draw call
+- **Scale handling**: Visual scale is applied per-instance, but collider scale may differ
+- **Transform updates**: Use `updateNodeById` to move instances (triggers re-sync)
+- **Memory**: One set of GPU buffers shared across all instances

package/src/tools/prefabeditor/PrefabRoot.tsx

@@ -11,6 +11,7 @@ import { GameInstance, GameInstanceProvider, useInstanceCheck } from "./Instance
 import { updateNode } from "./utils";
 import { PhysicsProps } from "./components/PhysicsComponent";
 import { EditorContext } from "./EditorContext";
+import type { RapierRigidBody } from "@react-three/rapier";
 
 components.forEach(registerComponent);
 
@@ -18,6 +19,7 @@ const IDENTITY = new Matrix4();
 
 export interface PrefabRootRef {
     root: Group | null;
+    rigidBodyRefs: Map<string, RapierRigidBody | null>;
 }
 
 export const PrefabRoot = forwardRef<PrefabRootRef, {
@@ -40,11 +42,13 @@ export const PrefabRoot = forwardRef<PrefabRootRef, {
     const [textures, setTextures] = useState<Record<string, Texture>>({});
     const loading = useRef(new Set<string>());
     const objectRefs = useRef<Record<string, Object3D | null>>({});
+    const rigidBodyRefs = useRef<Map<string, RapierRigidBody | null>>(new Map());
     const [selectedObject, setSelectedObject] = useState<Object3D | null>(null);
     const rootRef = useRef<Group>(null);
 
     useImperativeHandle(ref, () => ({
-        root: rootRef.current
+        root: rootRef.current,
+        rigidBodyRefs: rigidBodyRefs.current
     }), []);
 
     const registerRef = useCallback((id: string, obj: Object3D | null) => {
@@ -52,6 +56,10 @@ export const PrefabRoot = forwardRef<PrefabRootRef, {
         if (id === selectedId) setSelectedObject(obj);
     }, [selectedId]);
 
+    const registerRigidBodyRef = useCallback((id: string, rb: RapierRigidBody | null) => {
+        rigidBodyRefs.current.set(id, rb);
+    }, []);
+
     useEffect(() => {
         const originalError = console.error;
         console.error = (...args: any[]) => {
@@ -145,6 +153,7 @@ export const PrefabRoot = forwardRef<PrefabRootRef, {
                     onSelect={editMode ? onSelect : undefined}
                     onClick={onClick}
                     registerRef={registerRef}
+                    registerRigidBodyRef={registerRigidBodyRef}
                     loadedModels={models}
                     loadedTextures={textures}
                     editMode={editMode}
@@ -278,6 +287,7 @@ function StandardNode({
     onSelect,
     onClick,
     registerRef,
+    registerRigidBodyRef,
     loadedModels,
     loadedTextures,
     editMode,
@@ -341,6 +351,7 @@ function StandardNode({
                     onSelect={onSelect}
                     onClick={onClick}
                     registerRef={registerRef}
+                    registerRigidBodyRef={registerRigidBodyRef}
                     loadedModels={loadedModels}
                     loadedTextures={loadedTextures}
                     editMode={editMode}
@@ -379,6 +390,8 @@ function StandardNode({
                         rotation={transform.rotation}
                         scale={transform.scale}
                         editMode={editMode}
+                        nodeId={gameObject.id}
+                        registerRigidBodyRef={registerRigidBodyRef}
                     >{inner}</physicsDef.View>
                 ) : null}
             </>
@@ -394,6 +407,8 @@ function StandardNode({
                 rotation={transform.rotation}
                 scale={transform.scale}
                 editMode={editMode}
+                nodeId={gameObject.id}
+                registerRigidBodyRef={registerRigidBodyRef}
             >{inner}</physicsDef.View>
         );
     }
@@ -419,6 +434,7 @@ interface RendererProps {
     onSelect?: (id: string) => void;
     onClick?: (event: ThreeEvent<PointerEvent>, entity: GameObjectType) => void;
     registerRef: (id: string, obj: Object3D | null) => void;
+    registerRigidBodyRef: (id: string, rb: RapierRigidBody | null) => void;
     loadedModels: Record<string, Object3D>;
     loadedTextures: Record<string, Texture>;
     editMode?: boolean;

package/src/tools/prefabeditor/components/MaterialComponent.tsx

@@ -15,9 +15,19 @@ import {
     LinearMipmapNearestFilter,
     LinearMipmapLinearFilter,
     MinificationTextureFilter,
-    MagnificationTextureFilter
+    MagnificationTextureFilter,
+    MeshStandardMaterialProperties
 } from 'three';
 
+export interface MaterialProps extends Omit<MeshStandardMaterialProperties, 'args'> {
+    texture?: string;
+    repeat?: boolean;
+    repeatCount?: [number, number];
+    generateMipmaps?: boolean;
+    minFilter?: string;
+    magFilter?: string;
+}
+
 function TexturePicker({
     value,
     onChange,
@@ -71,6 +81,13 @@ function MaterialComponentEditor({ component, onUpdate, basePath = "" }: { compo
     const fields: FieldDefinition[] = [
         { name: 'color', type: 'color', label: 'Color' },
         { name: 'wireframe', type: 'boolean', label: 'Wireframe' },
+        { name: 'transparent', type: 'boolean', label: 'Transparent' },
+        { name: 'opacity', type: 'number', label: 'Opacity', min: 0, max: 1, step: 0.01 },
+        { name: 'metalness', type: 'number', label: 'Metalness', min: 0, max: 1, step: 0.01 },
+        { name: 'roughness', type: 'number', label: 'Roughness', min: 0, max: 1, step: 0.01 },
+        { name: 'transmission', type: 'number', label: 'Transmission', min: 0, max: 1, step: 0.01 },
+        { name: 'thickness', type: 'number', label: 'Thickness', min: 0, step: 0.1 },
+        { name: 'ior', type: 'number', label: 'IOR (Index of Refraction)', min: 1, max: 2.333, step: 0.01 },
         {
             name: 'texture',
             type: 'custom',
@@ -135,7 +152,7 @@ function MaterialComponentEditor({ component, onUpdate, basePath = "" }: { compo
 }
 
 // View for Material component
-function MaterialComponentView({ properties, loadedTextures }: { properties: any, loadedTextures?: Record<string, Texture> }) {
+function MaterialComponentView({ properties, loadedTextures }: { properties: MaterialProps, loadedTextures?: Record<string, Texture> }) {
     const textureName = properties?.texture;
     const repeat = properties?.repeat;
     const repeatCount = properties?.repeatCount;
@@ -144,6 +161,18 @@ function MaterialComponentView({ properties, loadedTextures }: { properties: any
     const magFilter = properties?.magFilter || 'LinearFilter';
     const texture = textureName && loadedTextures ? loadedTextures[textureName] : undefined;
 
+    // Destructure all material props and separate custom texture handling props
+    const { 
+        texture: _texture, 
+        repeat: _repeat, 
+        repeatCount: _repeatCount, 
+        generateMipmaps: _generateMipmaps,
+        minFilter: _minFilter,
+        magFilter: _magFilter,
+        map: _map, // Filter out map since we set it explicitly
+        ...materialProps 
+    } = properties || {};
+
     const minFilterMap: Record<string, MinificationTextureFilter> = {
         NearestFilter,
         LinearFilter,
@@ -180,15 +209,11 @@ function MaterialComponentView({ properties, loadedTextures }: { properties: any
         return <meshStandardMaterial color="red" wireframe />;
     }
 
-    const { color, wireframe = false } = properties;
-
     return (
         <meshStandardMaterial
             key={finalTexture?.uuid ?? 'no-texture'}
-            color={color}
-            wireframe={wireframe}
             map={finalTexture}
-            transparent={!!finalTexture}
+            {...materialProps}
         />
     );
 }
@@ -200,7 +225,11 @@ const MaterialComponent: Component = {
     nonComposable: true,
     defaultProperties: {
         color: '#ffffff',
-        wireframe: false
+        wireframe: false,
+        transparent: false,
+        opacity: 1,
+        metalness: 0,
+        roughness: 1
     }
 };
 

package/src/tools/prefabeditor/components/PhysicsComponent.tsx

@@ -1,6 +1,7 @@
 import { RigidBody, RapierRigidBody } from "@react-three/rapier";
 import type { RigidBodyOptions } from "@react-three/rapier";
 import type { ReactNode } from 'react';
+import { useRef, useEffect } from 'react';
 import { Component } from "./ComponentRegistry";
 import { FieldRenderer, FieldDefinition } from "./Input";
 import { ComponentData } from "../types";
@@ -89,11 +90,26 @@ interface PhysicsViewProps {
     position?: [number, number, number];
     rotation?: [number, number, number];
     scale?: [number, number, number];
+    nodeId?: string;
+    registerRigidBodyRef?: (id: string, rb: RapierRigidBody | null) => void;
 }
 
-function PhysicsComponentView({ properties, children, position, rotation, scale, editMode }: PhysicsViewProps) {
+function PhysicsComponentView({ properties, children, position, rotation, scale, editMode, nodeId, registerRigidBodyRef }: PhysicsViewProps) {
     const { type, colliders, ...otherProps } = properties;
     const colliderType = colliders || (type === 'fixed' ? 'trimesh' : 'hull');
+    const rigidBodyRef = useRef<RapierRigidBody>(null);
+
+    // Register RigidBody ref when it's available
+    useEffect(() => {
+        if (nodeId && registerRigidBodyRef && rigidBodyRef.current) {
+            registerRigidBodyRef(nodeId, rigidBodyRef.current);
+        }
+        return () => {
+            if (nodeId && registerRigidBodyRef) {
+                registerRigidBodyRef(nodeId, null);
+            }
+        };
+    }, [nodeId, registerRigidBodyRef]);
 
     // In edit mode, include position/rotation in key to force remount when transform changes
     // This ensures the RigidBody debug visualization updates even when physics is paused
@@ -104,6 +120,7 @@ function PhysicsComponentView({ properties, children, position, rotation, scale,
     return (
         <RigidBody
             key={rbKey}
+            ref={rigidBodyRef}
             type={type}
             colliders={colliderType as any}
             position={position}