react-three-game 0.0.48 → 0.0.49

package/.github/copilot-instructions.md

@@ -15,7 +15,6 @@ interface Prefab { id?: string; name?: string; root: GameObject; }
 interface GameObject {
   id: string;                    // Use crypto.randomUUID() for new nodes
   disabled?: boolean;
-  hidden?: boolean;
   components?: Record<string, { type: string; properties: any }>;
   children?: GameObject[];
 }
@@ -38,11 +37,17 @@ const MyComponent: Component = {
 | File | Purpose |
 |------|---------|
 | `src/index.ts` | All public exports - add new features here |
-| `src/tools/prefabeditor/PrefabRoot.tsx` | Recursive scene renderer, world matrix math |
-| `src/tools/prefabeditor/PrefabEditor.tsx` | Edit/play mode, physics pause, JSON import/export |
+| `src/tools/prefabeditor/PrefabRoot.tsx` | Pure renderer - renders prefab as Three.js objects for R3F integration |
+| `src/tools/prefabeditor/PrefabEditor.tsx` | Managed scene with editor UI and play/pause controls for physics |
 | `src/tools/prefabeditor/utils.ts` | Tree helpers: `findNode`, `updateNode`, `deleteNode`, `cloneNode` |
 | `src/shared/GameCanvas.tsx` | WebGPU renderer setup (use `MeshStandardNodeMaterial`) |
 
+## Usage Modes
+
+**GameCanvas + PrefabRoot**: Pure renderer for embedding prefab data in standard R3F applications. Minimal wrapper - just renders the prefab as Three.js objects. Requires manual `<Physics>` setup. Physics always active. Use this to integrate prefabs into larger R3F scenes.
+
+**PrefabEditor**: Managed scene with editor UI and play/pause controls for physics. Full authoring tool for level design and prototyping. Includes canvas, physics, transform gizmos, and inspector. Physics only runs in play mode. Can pass R3F components as children.
+
 ## Critical Patterns
 
 ### Tree Manipulation (Immutable)

package/README.md

@@ -14,7 +14,13 @@ npm i react-three-game @react-three/fiber @react-three/rapier three
 npx skills add https://github.com/prnthh/react-three-game-skill
 ```
 
-## Usage
+## Usage Modes
+
+**GameCanvas + PrefabRoot**: Pure renderer for embedding prefab data in standard R3F applications. Minimal wrapper - just renders the prefab as Three.js objects. Requires manual `<Physics>` setup. Physics always active. Use this to integrate prefabs into larger R3F scenes.
+
+**PrefabEditor**: Managed scene with editor UI and play/pause controls for physics. Full authoring tool for level design and prototyping. Includes canvas, physics, transform gizmos, and inspector. Physics only runs in play mode. Can pass R3F components as children.
+
+## Basic Usage
 
 ```jsx
 import { Physics } from '@react-three/rapier';
@@ -57,7 +63,6 @@ import { GameCanvas, PrefabRoot } from 'react-three-game';
 interface GameObject {
   id: string;
   disabled?: boolean;
-  hidden?: boolean;
   components?: Record<string, { type: string; properties: any }>;
   children?: GameObject[];
 }
@@ -70,7 +75,7 @@ interface GameObject {
 | Transform | `position`, `rotation`, `scale` — all `[x,y,z]` arrays, rotation in radians |
 | Geometry | `geometryType`: box/sphere/plane/cylinder, `args`: dimension array |
 | Material | `color`, `texture?`, `metalness?`, `roughness?` |
-| Physics | `type`: dynamic/fixed |
+| Physics | `type`: dynamic/fixed/kinematicPosition/kinematicVelocity, `mass?`, `restitution?` (bounciness), `friction?`, plus any Rapier props |
 | Model | `filename` (GLB/FBX path), `instanced?` for GPU batching |
 | SpotLight | `color`, `intensity`, `angle`, `penumbra` |
 
@@ -133,14 +138,21 @@ The `FieldRenderer` component auto-generates editor UI from a field schema:
 }
 ```
 
-## Visual Editor
+## Prefab Editor
 
 ```jsx
 import { PrefabEditor } from 'react-three-game';
+
+// Standalone editor
 <PrefabEditor initialPrefab={sceneData} onPrefabChange={setSceneData} />
+
+// With custom R3F components
+<PrefabEditor initialPrefab={sceneData}>
+  <CustomComponent />
+</PrefabEditor>
 ```
 
-Keys: **T**ranslate / **R**otate / **S**cale. Drag tree nodes to reparent. Import/export JSON.
+Keys: **T**ranslate / **R**otate / **S**cale. Drag tree nodes to reparent. Import/export JSON. Physics only runs in play mode.
 
 ## Internals
 

package/dist/helpers/index.d.ts

@@ -18,8 +18,6 @@ export interface GroundOptions {
     repeatCount?: [number, number];
     /** Physics body type. Defaults to "fixed". */
     physicsType?: "fixed" | "dynamic" | "kinematic";
-    /** Set true to hide the node. */
-    hidden?: boolean;
     /** Set true to disable the node. */
     disabled?: boolean;
 }

package/dist/helpers/index.js

@@ -8,11 +8,10 @@
  * - Physics (fixed by default)
  */
 export function ground(options = {}) {
-    const { id = "ground", size = 50, position = [0, 0, 0], rotation = [-Math.PI / 2, 0, 0], scale = [1, 1, 1], color = "white", texture, repeat = texture ? true : false, repeatCount = [25, 25], physicsType = "fixed", hidden = false, disabled = false, } = options;
+    const { id = "ground", size = 50, position = [0, 0, 0], rotation = [-Math.PI / 2, 0, 0], scale = [1, 1, 1], color = "white", texture, repeat = texture ? true : false, repeatCount = [25, 25], physicsType = "fixed", disabled = false, } = options;
     return {
         id,
         disabled,
-        hidden,
         components: {
             transform: {
                 type: "Transform",

package/dist/tools/prefabeditor/PrefabRoot.js

@@ -108,7 +108,7 @@ export const PrefabRoot = forwardRef(({ editMode, data, onPrefabChange, selected
 export function GameObjectRenderer(props) {
     var _a, _b, _c;
     const node = props.gameObject;
-    if (!node || node.hidden || node.disabled)
+    if (!node || node.disabled)
         return null;
     const isInstanced = (_c = (_b = (_a = node.components) === null || _a === void 0 ? void 0 : _a.model) === null || _b === void 0 ? void 0 : _b.properties) === null || _c === void 0 ? void 0 : _c.instanced;
     const prevInstancedRef = useRef(undefined);

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

@@ -1,10 +1,5 @@
+import type { RigidBodyOptions } from "@react-three/rapier";
 import { Component } from "./ComponentRegistry";
-export interface PhysicsProps {
-    type: "fixed" | "dynamic";
-    collider?: string;
-    mass?: number;
-    restitution?: number;
-    friction?: number;
-}
+export type PhysicsProps = RigidBodyOptions;
 declare const PhysicsComponent: Component;
 export default PhysicsComponent;

package/dist/tools/prefabeditor/components/PhysicsComponent.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 } from "react/jsx-runtime";
 import { RigidBody } from "@react-three/rapier";
 import { FieldRenderer } from "./Input";
@@ -9,10 +20,12 @@ const physicsFields = [
         options: [
             { value: 'dynamic', label: 'Dynamic' },
             { value: 'fixed', label: 'Fixed' },
+            { value: 'kinematicPosition', label: 'Kinematic Position' },
+            { value: 'kinematicVelocity', label: 'Kinematic Velocity' },
         ],
     },
     {
-        name: 'collider',
+        name: 'colliders',
         type: 'select',
         label: 'Collider',
         options: [
@@ -22,24 +35,65 @@ const physicsFields = [
             { value: 'ball', label: 'Ball (sphere)' },
         ],
     },
+    {
+        name: 'mass',
+        type: 'number',
+        label: 'Mass',
+    },
+    {
+        name: 'restitution',
+        type: 'number',
+        label: 'Restitution (Bounciness)',
+        min: 0,
+        max: 1,
+        step: 0.1,
+    },
+    {
+        name: 'friction',
+        type: 'number',
+        label: 'Friction',
+        min: 0,
+        step: 0.1,
+    },
+    {
+        name: 'linearDamping',
+        type: 'number',
+        label: 'Linear Damping',
+        min: 0,
+        step: 0.1,
+    },
+    {
+        name: 'angularDamping',
+        type: 'number',
+        label: 'Angular Damping',
+        min: 0,
+        step: 0.1,
+    },
+    {
+        name: 'gravityScale',
+        type: 'number',
+        label: 'Gravity Scale',
+        step: 0.1,
+    },
 ];
 function PhysicsComponentEditor({ component, onUpdate }) {
-    return (_jsx(FieldRenderer, { fields: physicsFields, values: component.properties, onChange: 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 }) {
-    const colliders = properties.collider || (properties.type === 'fixed' ? 'trimesh' : 'hull');
+    const { type, colliders } = properties, otherProps = __rest(properties, ["type", "colliders"]);
+    const colliderType = colliders || (type === 'fixed' ? 'trimesh' : 'hull');
     // 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
-        ? `${properties.type || 'dynamic'}_${colliders}_${position === null || position === void 0 ? void 0 : position.join(',')}_${rotation === null || rotation === void 0 ? void 0 : rotation.join(',')}`
-        : `${properties.type || 'dynamic'}_${colliders}`;
-    return (_jsx(RigidBody, { type: properties.type, colliders: colliders, position: position, rotation: rotation, scale: scale, children: children }, rbKey));
+        ? `${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));
 }
 const PhysicsComponent = {
     name: 'Physics',
     Editor: PhysicsComponentEditor,
     View: PhysicsComponentView,
     nonComposable: true,
-    defaultProperties: { type: 'dynamic', collider: 'hull' }
+    defaultProperties: { type: 'dynamic', colliders: 'hull' }
 };
 export default PhysicsComponent;

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

@@ -7,7 +7,6 @@ export interface GameObject {
     id: string;
     name?: string;
     disabled?: boolean;
-    hidden?: boolean;
     children?: GameObject[];
     components?: {
         [key: string]: ComponentData | undefined;

package/package.json

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

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

@@ -1 +1,7 @@
 Agent skill for [react-three-game](https://github.com/prnthh/react-three-game)
+
+Gives your agent the ability to make 3D scenes, physics simulations and games.
+
+```
+npx skills add https://github.com/prnthh/react-three-game-skill
+```

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

@@ -82,7 +82,6 @@ Every game object follows this schema:
 interface GameObject {
   id: string;
   disabled?: boolean;
-  hidden?: boolean;
   components?: Record<string, { type: string; properties: any }>;
   children?: GameObject[];
 }
@@ -117,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" or "fixed" |
+| Physics | `Physics` | `type`: dynamic/fixed/kinematicPosition/kinematicVelocity, `mass?`, `restitution?`, `friction?`, `linearDamping?`, `angularDamping?`, `gravityScale?`, plus any Rapier RigidBody props |
 | 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]` |
@@ -165,7 +164,7 @@ Use radians: `1.57` = 90°, `3.14` = 180°, `-1.57` = -90°
 
 ### Usage Modes
 
-**GameCanvas + PrefabRoot**: Production gameplay. Requires explicit `<Physics>` wrapper. Physics always active. Can compose with other R3F components. For headless mode, use `<PrefabRoot>` without GameCanvas.
+**GameCanvas + PrefabRoot**: Pure renderer for embedding prefab data in standard R3F applications. Minimal wrapper - just renders the prefab as Three.js objects. Requires manual `<Physics>` setup. Physics always active. Use this to integrate prefabs into larger R3F scenes.
 
 ```jsx
 import { Physics } from '@react-three/rapier';
@@ -174,16 +173,19 @@ import { GameCanvas, PrefabRoot } from 'react-three-game';
 <GameCanvas>
   <Physics>
     <PrefabRoot data={prefabData} />
+    <CustomComponent />
   </Physics>
 </GameCanvas>
 ```
 
-**PrefabEditor**: Level editors, scene authoring, prototyping. Includes canvas, physics, UI. Physics activates in play mode only.
+**PrefabEditor**: Managed scene with editor UI and play/pause controls for physics. Full authoring tool for level design and prototyping. Includes canvas, physics, transform gizmos, and inspector. Physics only runs in play mode. Can pass R3F components as children.
 
 ```jsx
 import { PrefabEditor } from 'react-three-game';
 
-<PrefabEditor initialPrefab={prefabData} />
+<PrefabEditor initialPrefab={prefabData}>
+  <CustomComponent />
+</PrefabEditor>
 ```
 
 ### Tree Utilities

package/src/helpers/index.ts

@@ -25,8 +25,6 @@ export interface GroundOptions {
 	/** Physics body type. Defaults to "fixed". */
 	physicsType?: "fixed" | "dynamic" | "kinematic";
 
-	/** Set true to hide the node. */
-	hidden?: boolean;
 	/** Set true to disable the node. */
 	disabled?: boolean;
 }
@@ -52,14 +50,12 @@ export function ground(options: GroundOptions = {}): GameObject {
 		repeat = texture ? true : false,
 		repeatCount = [25, 25],
 		physicsType = "fixed",
-		hidden = false,
 		disabled = false,
 	} = options;
 
 	return {
 		id,
 		disabled,
-		hidden,
 		components: {
 			transform: {
 				type: "Transform",

package/src/tools/prefabeditor/PrefabRoot.tsx

@@ -175,7 +175,7 @@ export const PrefabRoot = forwardRef<PrefabRootRef, {
 
 export function GameObjectRenderer(props: RendererProps) {
     const node = props.gameObject;
-    if (!node || node.hidden || node.disabled) return null;
+    if (!node || node.disabled) return null;
 
     const isInstanced = node.components?.model?.properties?.instanced;
     const prevInstancedRef = useRef<boolean | undefined>(undefined);

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

@@ -1,17 +1,11 @@
 import { RigidBody, RapierRigidBody } from "@react-three/rapier";
+import type { RigidBodyOptions } from "@react-three/rapier";
 import type { ReactNode } from 'react';
-import { useEffect, useRef } from 'react';
 import { Component } from "./ComponentRegistry";
 import { FieldRenderer, FieldDefinition } from "./Input";
-import { Quaternion, Euler } from 'three';
+import { ComponentData } from "../types";
 
-export interface PhysicsProps {
-    type: "fixed" | "dynamic";
-    collider?: string;
-    mass?: number;
-    restitution?: number;
-    friction?: number;
-}
+export type PhysicsProps = RigidBodyOptions;
 
 const physicsFields: FieldDefinition[] = [
     {
@@ -21,10 +15,12 @@ const physicsFields: FieldDefinition[] = [
         options: [
             { value: 'dynamic', label: 'Dynamic' },
             { value: 'fixed', label: 'Fixed' },
+            { value: 'kinematicPosition', label: 'Kinematic Position' },
+            { value: 'kinematicVelocity', label: 'Kinematic Velocity' },
         ],
     },
     {
-        name: 'collider',
+        name: 'colliders',
         type: 'select',
         label: 'Collider',
         options: [
@@ -34,20 +30,60 @@ const physicsFields: FieldDefinition[] = [
             { value: 'ball', label: 'Ball (sphere)' },
         ],
     },
+    {
+        name: 'mass',
+        type: 'number',
+        label: 'Mass',
+    },
+    {
+        name: 'restitution',
+        type: 'number',
+        label: 'Restitution (Bounciness)',
+        min: 0,
+        max: 1,
+        step: 0.1,
+    },
+    {
+        name: 'friction',
+        type: 'number',
+        label: 'Friction',
+        min: 0,
+        step: 0.1,
+    },
+    {
+        name: 'linearDamping',
+        type: 'number',
+        label: 'Linear Damping',
+        min: 0,
+        step: 0.1,
+    },
+    {
+        name: 'angularDamping',
+        type: 'number',
+        label: 'Angular Damping',
+        min: 0,
+        step: 0.1,
+    },
+    {
+        name: 'gravityScale',
+        type: 'number',
+        label: 'Gravity Scale',
+        step: 0.1,
+    },
 ];
 
-function PhysicsComponentEditor({ component, onUpdate }: { component: { properties: { type?: 'dynamic' | 'fixed'; collider?: string;[k: string]: any } }; onUpdate: (props: Partial<Record<string, any>>) => void }) {
+function PhysicsComponentEditor({ component, onUpdate }: { component: ComponentData; onUpdate: (newComp: any) => void }) {
     return (
         <FieldRenderer
             fields={physicsFields}
             values={component.properties}
-            onChange={onUpdate}
+            onChange={(props) => onUpdate({ ...component, properties: { ...component.properties, ...props } })}
         />
     );
 }
 
 interface PhysicsViewProps {
-    properties: { type?: 'dynamic' | 'fixed'; collider?: string };
+    properties: PhysicsProps;
     editMode?: boolean;
     children?: ReactNode;
     position?: [number, number, number];
@@ -56,22 +92,24 @@ interface PhysicsViewProps {
 }
 
 function PhysicsComponentView({ properties, children, position, rotation, scale, editMode }: PhysicsViewProps) {
-    const colliders = properties.collider || (properties.type === 'fixed' ? 'trimesh' : 'hull');
+    const { type, colliders, ...otherProps } = properties;
+    const colliderType = colliders || (type === 'fixed' ? 'trimesh' : 'hull');
 
     // 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
-        ? `${properties.type || 'dynamic'}_${colliders}_${position?.join(',')}_${rotation?.join(',')}`
-        : `${properties.type || 'dynamic'}_${colliders}`;
+        ? `${type || 'dynamic'}_${colliderType}_${position?.join(',')}_${rotation?.join(',')}`
+        : `${type || 'dynamic'}_${colliderType}`;
 
     return (
         <RigidBody
             key={rbKey}
-            type={properties.type}
-            colliders={colliders as any}
+            type={type}
+            colliders={colliderType as any}
             position={position}
             rotation={rotation}
             scale={scale}
+            {...otherProps}
         >
             {children}
         </RigidBody>
@@ -83,7 +121,7 @@ const PhysicsComponent: Component = {
     Editor: PhysicsComponentEditor,
     View: PhysicsComponentView,
     nonComposable: true,
-    defaultProperties: { type: 'dynamic', collider: 'hull' }
+    defaultProperties: { type: 'dynamic', colliders: 'hull' }
 };
 
-export default PhysicsComponent;
+export default PhysicsComponent;

package/src/tools/prefabeditor/types.ts

@@ -8,7 +8,6 @@ export interface GameObject {
     id: string;
     name?: string;
     disabled?: boolean;
-    hidden?: boolean;
     children?: GameObject[];
     components?: {
         [key: string]: ComponentData | undefined;