react-three-game 0.0.57 → 0.0.59

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

@@ -1,33 +1,54 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useRef, useEffect } from "react";
+import { useRef, useEffect, useMemo, useState } from "react";
 import { BooleanField, ColorField, FieldGroup, NumberField } from "./Input";
-import { useHelper } from "@react-three/drei";
 import { SpotLightHelper } from "three";
+import { useFrame } from "@react-three/fiber";
+const spotLightDefaults = {
+    color: '#ffffff',
+    intensity: 1,
+    angle: Math.PI / 6,
+    penumbra: 0.5,
+    distance: 100,
+    castShadow: true,
+};
 function SpotLightComponentEditor({ component, onUpdate }) {
-    return (_jsxs(FieldGroup, { children: [_jsx(ColorField, { name: "color", label: "Color", values: component.properties, onChange: onUpdate }), _jsx(NumberField, { name: "intensity", label: "Intensity", values: component.properties, onChange: onUpdate, min: 0, step: 0.1, fallback: 1 }), _jsx(NumberField, { name: "angle", label: "Angle", values: component.properties, onChange: onUpdate, min: 0, max: Math.PI, step: 0.05, fallback: Math.PI / 6 }), _jsx(NumberField, { name: "penumbra", label: "Penumbra", values: component.properties, onChange: onUpdate, min: 0, max: 1, step: 0.05, fallback: 0.5 }), _jsx(NumberField, { name: "distance", label: "Distance", values: component.properties, onChange: onUpdate, min: 0, step: 1, fallback: 100 }), _jsx(BooleanField, { name: "castShadow", label: "Cast Shadow", values: component.properties, onChange: onUpdate, fallback: true })] }));
+    const values = Object.assign(Object.assign({}, spotLightDefaults), component.properties);
+    return (_jsxs(FieldGroup, { children: [_jsx(ColorField, { name: "color", label: "Color", values: values, onChange: onUpdate }), _jsx(NumberField, { name: "intensity", label: "Intensity", values: values, onChange: onUpdate, min: 0, step: 0.1, fallback: 1 }), _jsx(NumberField, { name: "angle", label: "Angle", values: values, onChange: onUpdate, min: 0, max: Math.PI, step: 0.05, fallback: Math.PI / 6 }), _jsx(NumberField, { name: "penumbra", label: "Penumbra", values: values, onChange: onUpdate, min: 0, max: 1, step: 0.05, fallback: 0.5 }), _jsx(NumberField, { name: "distance", label: "Distance", values: values, onChange: onUpdate, min: 0, step: 1, fallback: 100 }), _jsx(BooleanField, { name: "castShadow", label: "Cast Shadow", values: values, onChange: onUpdate, fallback: true })] }));
 }
 function SpotLightView({ properties, editMode, isSelected }) {
-    var _a, _b, _c, _d, _e, _f;
-    const color = (_a = properties.color) !== null && _a !== void 0 ? _a : '#ffffff';
-    const intensity = (_b = properties.intensity) !== null && _b !== void 0 ? _b : 1.0;
-    const angle = (_c = properties.angle) !== null && _c !== void 0 ? _c : Math.PI / 6;
-    const penumbra = (_d = properties.penumbra) !== null && _d !== void 0 ? _d : 0.5;
-    const distance = (_e = properties.distance) !== null && _e !== void 0 ? _e : 100;
-    const castShadow = (_f = properties.castShadow) !== null && _f !== void 0 ? _f : true;
+    const merged = Object.assign(Object.assign({}, spotLightDefaults), properties);
+    const color = merged.color;
+    const intensity = merged.intensity;
+    const angle = merged.angle;
+    const penumbra = merged.penumbra;
+    const distance = merged.distance;
+    const castShadow = merged.castShadow;
     const spotLightRef = useRef(null);
     const targetRef = useRef(null);
-    useHelper(editMode && isSelected ? spotLightRef : null, SpotLightHelper, color);
+    const [spotLight, setSpotLight] = useState(null);
+    const spotLightHelper = useMemo(() => spotLight ? new SpotLightHelper(spotLight, color) : null, [spotLight, color]);
+    useEffect(() => {
+        return () => {
+            spotLightHelper === null || spotLightHelper === void 0 ? void 0 : spotLightHelper.dispose();
+        };
+    }, [spotLightHelper]);
     useEffect(() => {
         if (spotLightRef.current && targetRef.current) {
             spotLightRef.current.target = targetRef.current;
+            setSpotLight(spotLightRef.current);
         }
     }, []);
-    return (_jsxs(_Fragment, { children: [_jsx("spotLight", { ref: spotLightRef, color: color, intensity: intensity, angle: angle, penumbra: penumbra, distance: distance, castShadow: castShadow, "shadow-mapSize-width": 1024, "shadow-mapSize-height": 1024, "shadow-bias": -0.0001, "shadow-normalBias": 0.02 }), _jsx("object3D", { ref: targetRef, position: [0, -5, 0] }), editMode && (_jsxs(_Fragment, { children: [_jsxs("mesh", { children: [_jsx("sphereGeometry", { args: [0.2, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true })] }), _jsxs("mesh", { position: [0, -5, 0], children: [_jsx("sphereGeometry", { args: [0.15, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true, opacity: 0.5, transparent: true })] })] }))] }));
+    useFrame(() => {
+        if (spotLightHelper && editMode && isSelected) {
+            spotLightHelper.update();
+        }
+    });
+    return (_jsxs(_Fragment, { children: [_jsx("spotLight", { ref: spotLightRef, color: color, intensity: intensity, angle: angle, penumbra: penumbra, distance: distance, castShadow: castShadow, "shadow-mapSize-width": 1024, "shadow-mapSize-height": 1024, "shadow-bias": -0.0001, "shadow-normalBias": 0.02 }), editMode && isSelected && spotLightHelper && (_jsx("primitive", { object: spotLightHelper })), _jsx("object3D", { ref: targetRef, position: [0, -5, 0] }), editMode && (_jsxs(_Fragment, { children: [_jsxs("mesh", { children: [_jsx("sphereGeometry", { args: [0.2, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true })] }), _jsxs("mesh", { position: [0, -5, 0], children: [_jsx("sphereGeometry", { args: [0.15, 8, 6] }), _jsx("meshBasicMaterial", { color: color, wireframe: true, opacity: 0.5, transparent: true })] })] }))] }));
 }
 const SpotLightComponent = {
     name: 'SpotLight',
     Editor: SpotLightComponentEditor,
     View: SpotLightView,
-    defaultProperties: {}
+    defaultProperties: spotLightDefaults
 };
 export default SpotLightComponent;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-three-game",
-  "version": "0.0.57",
-  "description": "Batteries included React Three Fiber game engine",
+  "version": "0.0.59",
+  "description": "high performance 3D game engine for React",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -81,12 +81,15 @@ Every game object follows this schema:
 ```typescript
 interface GameObject {
   id: string;
+  name?: string;
   disabled?: boolean;
   components?: Record<string, { type: string; properties: any }>;
   children?: GameObject[];
 }
 ```
 
+`disabled` is the canonical visibility toggle. Transforms are local to the parent node.
+
 ### Prefab JSON Format
 
 Scenes are defined as JSON prefabs with a root node containing children:
@@ -121,6 +124,8 @@ Scenes are defined as JSON prefabs with a root node containing children:
 | SpotLight | `SpotLight` | `color`, `intensity`, `angle`, `penumbra`, `distance?`, `castShadow?` |
 | DirectionalLight | `DirectionalLight` | `color`, `intensity`, `castShadow?`, `targetOffset?: [x,y,z]` |
 | AmbientLight | `AmbientLight` | `color`, `intensity` |
+| Environment | `Environment` | `intensity`, `resolution` |
+| Camera | `Camera` | `fov`, `near`, `far`, `zoom` |
 | Text | `Text` | `text`, `font`, `size`, `depth`, `width`, `align`, `color` |
 
 ### Text Component
@@ -164,21 +169,24 @@ Use radians: `1.57` = 90°, `3.14` = 180°, `-1.57` = -90°
 
 ### 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.
+**PrefabRoot**: Pure renderer for embedding prefab data in standard R3F applications. Render it inside a regular `@react-three/fiber` `Canvas`. `GameCanvas` provides the WebGPU canvas setup. Add a `Physics` wrapper to enable physics. Use this to integrate prefabs into larger R3F scenes.
 
 ```jsx
+import { Canvas } from '@react-three/fiber';
 import { Physics } from '@react-three/rapier';
-import { GameCanvas, PrefabRoot } from 'react-three-game';
+import { PrefabRoot } from 'react-three-game';
 
-<GameCanvas>
+<Canvas>
   <Physics>
     <PrefabRoot data={prefabData} />
     <CustomComponent />
   </Physics>
-</GameCanvas>
+</Canvas>
 ```
 
-**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.
+`GameCanvas` provides the library's WebGPU canvas setup.
+
+**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. Editor actions live under `Menu > File`, and exports under `Menu > Export`.
 
 ```jsx
 import { PrefabEditor } from 'react-three-game';
@@ -228,6 +236,36 @@ function DynamicLight() {
 
 **Use cases**: Player controllers, AI behaviors, procedural animation, real-time effects.
 
+## World Scene Pattern
+
+The current world demo combines prefab-authored level geometry with runtime React behavior:
+
+- Static level layout, props, and collision live in prefab JSON.
+- `Environment` can wrap sky geometry or lighting content for a full scene backdrop.
+- `Camera` can live in the prefab so view-only scenes and editor scenes share the same authored viewpoint.
+- Runtime logic can use `useFrame` plus `updateNodeById` to animate prefab entities without abandoning the JSON scene model.
+
+```json
+{
+  "id": "environment",
+  "components": {
+    "environment": {
+      "type": "Environment",
+      "properties": { "intensity": 1, "resolution": 256 }
+    }
+  },
+  "children": [
+    {
+      "id": "sky",
+      "components": {
+        "geometry": { "type": "Geometry", "properties": { "geometryType": "sphere", "args": [100, 32, 16] } },
+        "material": { "type": "Material", "properties": { "texture": "/textures/skybox/skybox1.jpg", "side": "BackSide", "materialType": "basic" } }
+      }
+    }
+  ]
+}
+```
+
 ## Quick Reference Examples
 
 ```json
@@ -376,6 +414,26 @@ const MyComponent: Component = {
 registerComponent(MyComponent);
 ```
 
+Use the component in prefab JSON by adding a component entry whose `type` matches the registered component name:
+
+```json
+{
+  "components": {
+    "mycomponent": {
+      "type": "MyComponent",
+      "properties": {
+        "speed": 1
+      }
+    }
+  }
+}
+```
+
+Rules:
+- Call `registerComponent(MyComponent)` before rendering `<PrefabEditor>` or `<PrefabRoot>` with prefab data that uses it.
+- `type` must match the registered component name exactly (`name: 'MyComponent'` -> `"type": "MyComponent"`).
+- Use `View` to render visible content, wrap `children`, or add runtime behavior with hooks like `useFrame`.
+
 **Field types**: `vector3`, `number`, `string`, `color`, `boolean`, `select`, `custom`
 
 ## Game Events

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

@@ -48,6 +48,7 @@ Complete reference for `Physics` component properties:
 | `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 |
+| `colliders` | `'hull'` \| `'trimesh'` \| `'cuboid'` \| `'ball'` | auto | Collider shape override (`fixed` defaults to `trimesh`, others to `hull`) |
 | `ccd` | `boolean` | `false` | Continuous collision detection (fast objects) |
 | `sensor` | `boolean` | `false` | Trigger only, no collision response |
 | `activeCollisionTypes` | `'all'` | - | Enable kinematic/fixed collision detection (default: dynamic only) |
@@ -284,21 +285,21 @@ Objects will **slide off** the tilted surface.
 
 ## 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.
+When using `"instanced": true` on models, physics behaves differently than standard objects. Physics instancing is designed for batched `fixed` and `dynamic` bodies, where instances of the same model share an `InstancedRigidBodies` path for better performance.
 
 ### Standard vs Instanced Physics
 
 | Aspect | Standard Physics | Instanced Physics |
 |--------|------------------|-------------------|
-| RigidBody Component | Individual `<RigidBody>` per object | Single `<InstancedRigidBodies>` for all instances |
+| RigidBody Component | Individual `<RigidBody>` per object | Single `<InstancedRigidBodies>` group per model + supported physics type |
 | 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 |
+| Collider Type | `hull` (dynamic) or `trimesh` (fixed) | Auto-selected by instanced physics path |
 | 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**:
+Set `"instanced": true` in the model component. **Instances with the same model path and supported physics type are automatically batched**:
 
 ```json
 {
@@ -326,7 +327,7 @@ Add multiple instances - they'll be automatically batched:
 
 ### 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).
+**Instanced physics bodies are not individually accessible.** For objects requiring force/impulse control, kinematic motion, or per-body refs, use non-instanced physics (`"instanced": false` or omit the property).
 
 ### When to Use Instanced Physics
 
@@ -345,6 +346,7 @@ Add multiple instances - they'll be automatically batched:
 ### Performance Notes
 
 - **Batching**: All instances with the same `filename` and `physics.type` are rendered in a single draw call
+- **Supported body types**: The instanced physics path is intended for `fixed` and `dynamic` bodies; use standard non-instanced physics for kinematic bodies
 - **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/index.ts

@@ -50,7 +50,7 @@ export { entityEvents, useEntityEvent } from './tools/prefabeditor/GameEvents';
 export type { EntityEventType, EntityEventPayload } from './tools/prefabeditor/GameEvents';
 
 // Asset Tools
-export { DragDropLoader } from './tools/dragdrop/DragDropLoader';
+export * from './tools/dragdrop';
 export {
   TextureListViewer,
   ModelListViewer,

package/src/tools/assetviewer/page.tsx

@@ -2,7 +2,7 @@ import { Canvas } from "@react-three/fiber";
 import { OrbitControls, Stage, View, PerspectiveCamera } from "@react-three/drei";
 import { Component as ReactComponent, Suspense, useEffect, useState, useRef } from "react";
 import { TextureLoader } from "three";
-import { loadModel } from "../dragdrop/modelLoader";
+import { loadModel } from "../dragdrop";
 
 class ErrorBoundary extends ReactComponent<{ onError?: () => void; children: React.ReactNode }, { hasError: boolean }> {
     constructor(props: any) {

package/src/tools/dragdrop/DragDropLoader.tsx

@@ -1,73 +1,136 @@
-// DragDropLoader.tsx
-import { useEffect, ChangeEvent } from "react";
-import { parseModelFromFile } from "./modelLoader";
+import { ChangeEvent, useRef } from "react";
+import type { DragEvent, HTMLAttributes, MouseEvent, ReactNode } from "react";
+import type { LoadedModel } from "./modelLoader";
+import { canParseModelFile, parseModelFromFile } from "./modelLoader";
 
-interface DragDropLoaderProps {
-    onModelLoaded: (model: any, filename: string) => void;
+export interface FileLoadOptions {
+    onModelLoaded?: (model: LoadedModel, filename: string, file: File) => void | Promise<void>;
+    onFileLoaded?: (file: File) => void | Promise<void>;
+    onFilesLoaded?: (files: File[]) => void | Promise<void>;
+    onModelError?: (error: unknown, filename: string, file: File) => void | Promise<void>;
+    parseModels?: boolean;
 }
 
-function handleFiles(files: File[], onModelLoaded: (model: any, filename: string) => void) {
-    files.forEach(async (file) => {
-        const result = await parseModelFromFile(file);
-        if (result.success && result.model) {
-            onModelLoaded(result.model, file.name);
-        } else {
+type DivProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onDrop" | "onDragOver">;
+
+export interface DragDropLoaderProps extends FileLoadOptions, DivProps {
+    children?: ReactNode;
+}
+
+export interface FilePickerProps extends FileLoadOptions, DivProps {
+    accept?: string;
+    children?: ReactNode;
+    multiple?: boolean;
+}
+
+function getFiles(fileList?: FileList | null) {
+    return fileList ? Array.from(fileList) : [];
+}
+
+export async function loadFiles(
+    files: File[],
+    { onModelLoaded, onFileLoaded, onFilesLoaded, onModelError, parseModels = true }: FileLoadOptions,
+) {
+    await Promise.all(
+        files.map(async (file) => {
+            await onFileLoaded?.(file);
+
+            if (!parseModels || !canParseModelFile(file) || (!onModelLoaded && !onModelError)) {
+                return;
+            }
+
+            const result = await parseModelFromFile(file);
+
+            if (result.success && result.model) {
+                await onModelLoaded?.(result.model, file.name, file);
+                return;
+            }
+
+            if (onModelError) {
+                await onModelError(result.error, file.name, file);
+                return;
+            }
+
             console.error("Model parse error:", result.error);
-        }
-    });
+        }),
+    );
+
+    await onFilesLoaded?.(files);
 }
 
-export function DragDropLoader({ onModelLoaded }: DragDropLoaderProps) {
-    useEffect(() => {
-        function handleDrop(e: DragEvent) {
-            e.preventDefault();
-            e.stopPropagation();
-            const files = e.dataTransfer?.files ? Array.from(e.dataTransfer.files) : [];
-            handleFiles(files, onModelLoaded);
-        }
-        function handleDragOver(e: DragEvent) {
-            e.preventDefault();
-            e.stopPropagation();
-        }
-        window.addEventListener("drop", handleDrop);
-        window.addEventListener("dragover", handleDragOver);
-        return () => {
-            window.removeEventListener("drop", handleDrop);
-            window.removeEventListener("dragover", handleDragOver);
-        };
-    }, [onModelLoaded]);
-    return null;
+function reportFileLoadError(error: unknown) {
+    console.error("File load error:", error);
 }
 
-// FilePicker component
-interface FilePickerProps {
-    onModelLoaded: (model: any, filename: string) => void;
+function createLoadHandlers(options: FileLoadOptions) {
+    return {
+        onFileLoaded: options.onFileLoaded,
+        onFilesLoaded: options.onFilesLoaded,
+        onModelError: options.onModelError,
+        onModelLoaded: options.onModelLoaded,
+        parseModels: options.parseModels,
+    } satisfies FileLoadOptions;
 }
 
-export function FilePicker({ onModelLoaded }: FilePickerProps) {
-    function onChange(e: ChangeEvent<HTMLInputElement>) {
-        const files = e.target.files ? Array.from(e.target.files) : [];
-        handleFiles(files, onModelLoaded);
+export function DragDropLoader({
+    children,
+    ...divProps
+}: DragDropLoaderProps) {
+    const loadOptions = createLoadHandlers(divProps);
+
+    function handleDrop(event: DragEvent<HTMLDivElement>) {
+        event.preventDefault();
+        event.stopPropagation();
+
+        void loadFiles(getFiles(event.dataTransfer?.files), loadOptions).catch(reportFileLoadError);
+    }
+
+    function handleDragOver(event: DragEvent<HTMLDivElement>) {
+        event.preventDefault();
+        event.stopPropagation();
+    }
+
+    return (
+        <div {...divProps} onDrop={handleDrop} onDragOver={handleDragOver}>
+            {children}
+        </div>
+    );
+}
+
+export function FilePicker({
+    accept = ".glb,.gltf,.fbx",
+    children,
+    multiple = true,
+    ...divProps
+}: FilePickerProps) {
+    const inputRef = useRef<HTMLInputElement>(null);
+    const { onClick, ...wrapperProps } = divProps;
+    const loadOptions = createLoadHandlers(divProps);
+
+    function onChange(event: ChangeEvent<HTMLInputElement>) {
+        void loadFiles(getFiles(event.target.files), loadOptions).catch(reportFileLoadError);
+        event.target.value = "";
+    }
+
+    function handleClick(event: MouseEvent<HTMLDivElement>) {
+        onClick?.(event);
+
+        if (!event.defaultPrevented) {
+            inputRef.current?.click();
+        }
     }
-    // Ref for the hidden input
-    const inputId = "file-picker-input";
+
     return (
-        <>
+        <div {...wrapperProps} onClick={handleClick}>
             <input
-                id={inputId}
+                ref={inputRef}
                 type="file"
-                accept=".glb,.gltf,.fbx"
-                multiple
+                accept={accept}
+                multiple={multiple}
                 onChange={onChange}
-                className="hidden"
+                hidden
             />
-            <button
-                className="px-3 py-1 bg-blue-500/20 hover:bg-blue-500/30 border border-blue-400/40 hover:border-blue-400/60 text-blue-200 hover:text-blue-100 text-xs font-medium transition-all"
-                type="button"
-                onClick={() => document.getElementById(inputId)?.click()}
-            >
-                Select Files
-            </button>
-        </>
+            {children ?? "Select Files"}
+        </div>
     );
 }

package/src/tools/dragdrop/index.ts

@@ -0,0 +1,4 @@
+export { DragDropLoader, FilePicker, loadFiles } from "./DragDropLoader";
+export type { DragDropLoaderProps, FileLoadOptions, FilePickerProps } from "./DragDropLoader";
+export { loadModel, parseModelFromFile } from "./modelLoader";
+export type { LoadedModel, ModelLoadResult, ProgressCallback } from "./modelLoader";