react-three-game 0.0.58 → 0.0.60

package/dist/tools/prefabeditor/PrefabRoot.js

@@ -13,7 +13,7 @@ import { forwardRef, useCallback, useContext, useEffect, useImperativeHandle, us
 import { BoxHelper, Euler, Matrix4, Quaternion, SRGBColorSpace, TextureLoader, Vector3, } from "three";
 import { getComponent, registerComponent, getNonComposableKeys } from "./components/ComponentRegistry";
 import components from "./components";
-import { loadModel } from "../dragdrop/modelLoader";
+import { loadModel } from "../dragdrop";
 import { GameInstance, GameInstanceProvider, useInstanceCheck } from "./InstanceProvider";
 import { focusCameraOnObject, updateNode } from "./utils";
 import { EditorContext } from "./EditorContext";
@@ -40,15 +40,9 @@ export const PrefabRoot = forwardRef(({ editMode, data, onPrefabChange, selected
     const injectModel = useCallback((filename, model) => {
         setModels(m => (Object.assign(Object.assign({}, m), { [filename]: model })));
     }, []);
-    const injectTexture = useCallback((filename, file) => {
+    const injectTexture = useCallback((filename, texture) => {
         loading.current.add(filename);
-        const url = URL.createObjectURL(file);
-        const loader = new TextureLoader();
-        loader.load(url, tex => {
-            tex.colorSpace = SRGBColorSpace;
-            setTextures(t => (Object.assign(Object.assign({}, t), { [filename]: tex })));
-            URL.revokeObjectURL(url);
-        }, undefined, () => URL.revokeObjectURL(url));
+        setTextures(t => (Object.assign(Object.assign({}, t), { [filename]: texture })));
     }, []);
     useImperativeHandle(ref, () => ({
         root: rootRef.current,
@@ -120,8 +114,10 @@ export const PrefabRoot = forwardRef(({ editMode, data, onPrefabChange, selected
                 ? `${basePath}${file}`
                 : `${basePath}/${file}`;
             const res = yield loadModel(path);
-            res.success && res.model &&
-                setModels(m => (Object.assign(Object.assign({}, m), { [file]: res.model })));
+            const model = res.model;
+            if (res.success && model) {
+                setModels(m => (Object.assign(Object.assign({}, m), { [file]: model })));
+            }
         }));
         const loader = new TextureLoader();
         texturesToLoad.forEach(file => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-three-game",
-  "version": "0.0.58",
-  "description": "Batteries included React Three Fiber game engine",
+  "version": "0.0.60",
+  "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

@@ -124,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
@@ -167,20 +169,23 @@ 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>
 ```
 
+`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
@@ -231,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
@@ -379,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,159 @@
-// 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, LoadedTexture } from "./modelLoader";
+import { canParseModelFile, canParseTextureFile, parseModelFromFile, parseTextureFromFile } from "./modelLoader";
 
-interface DragDropLoaderProps {
-    onModelLoaded: (model: any, filename: string) => void;
+export interface AssetLoadOptions {
+    onModelLoaded?: (model: LoadedModel, filename: string, file: File) => void | Promise<void>;
+    onTextureLoaded?: (texture: LoadedTexture, filename: string, file: File) => void | Promise<void>;
+    onUnhandledFile?: (file: File) => void | Promise<void>;
+    onFilesLoaded?: (files: File[]) => void | Promise<void>;
+    onLoadError?: (error: unknown, filename: string, file: File) => void | Promise<void>;
 }
 
-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 {
-            console.error("Model parse error:", result.error);
-        }
-    });
+type DivProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onDrop" | "onDragOver">;
+
+export interface DragDropLoaderProps extends AssetLoadOptions, DivProps {
+    children?: ReactNode;
 }
 
-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;
+export interface FilePickerProps extends AssetLoadOptions, DivProps {
+    accept?: string;
+    children?: ReactNode;
+    multiple?: boolean;
+}
+
+const DEFAULT_ACCEPT = ".glb,.gltf,.fbx,.png,.jpg,.jpeg,.webp,.gif,.bmp,.svg";
+
+function getFiles(fileList?: FileList | null) {
+    return fileList ? Array.from(fileList) : [];
+}
+
+export async function loadFiles(
+    files: File[],
+    { onModelLoaded, onTextureLoaded, onUnhandledFile, onFilesLoaded, onLoadError }: AssetLoadOptions,
+) {
+    await Promise.all(
+        files.map(async (file) => {
+            const shouldParseModel = canParseModelFile(file);
+            const shouldParseTexture = canParseTextureFile(file);
+
+            if (shouldParseModel) {
+                const result = await parseModelFromFile(file);
+
+                if (result.success && result.model) {
+                    await onModelLoaded?.(result.model, file.name, file);
+                    return;
+                }
+
+                if (onLoadError) {
+                    await onLoadError(result.error, file.name, file);
+                    return;
+                }
+
+                console.error("Model parse error:", result.error);
+                return;
+            }
+
+            if (shouldParseTexture) {
+                const result = await parseTextureFromFile(file);
+
+                if (result.success && result.texture) {
+                    await onTextureLoaded?.(result.texture, file.name, file);
+                    return;
+                }
+
+                if (onLoadError) {
+                    await onLoadError(result.error, file.name, file);
+                    return;
+                }
+
+                console.error("Texture parse error:", result.error);
+                return;
+            }
+
+            if (onUnhandledFile) {
+                await onUnhandledFile(file);
+            }
+        }),
+    );
+
+    await onFilesLoaded?.(files);
+}
+
+function reportFileLoadError(error: unknown) {
+    console.error("File load error:", error);
 }
 
-// FilePicker component
-interface FilePickerProps {
-    onModelLoaded: (model: any, filename: string) => void;
+function createLoadHandlers(options: AssetLoadOptions) {
+    return {
+        onFilesLoaded: options.onFilesLoaded,
+        onModelLoaded: options.onModelLoaded,
+        onTextureLoaded: options.onTextureLoaded,
+        onUnhandledFile: options.onUnhandledFile,
+        onLoadError: options.onLoadError,
+    } satisfies AssetLoadOptions;
 }
 
-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);
     }
-    // Ref for the hidden input
-    const inputId = "file-picker-input";
+
+    function handleDragOver(event: DragEvent<HTMLDivElement>) {
+        event.preventDefault();
+        event.stopPropagation();
+    }
+
+    return (
+        <div {...divProps} onDrop={handleDrop} onDragOver={handleDragOver}>
+            {children}
+        </div>
+    );
+}
+
+export function FilePicker({
+    accept = DEFAULT_ACCEPT,
+    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();
+        }
+    }
+
     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 { AssetLoadOptions, DragDropLoaderProps, FilePickerProps } from "./DragDropLoader";
+export { loadModel, loadTexture, parseModelFromFile, parseTextureFromFile } from "./modelLoader";
+export type { LoadedModel, LoadedTexture, ModelLoadResult, ProgressCallback, TextureLoadResult } from "./modelLoader";