react-three-game 0.0.45 → 0.0.46

package/dist/tools/prefabeditor/PrefabRoot.js

@@ -11,7 +11,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { MapControls, TransformControls, useHelper } from "@react-three/drei";
 import { forwardRef, useCallback, useContext, useEffect, useImperativeHandle, useRef, useState } from "react";
 import { BoxHelper, Euler, Matrix4, Quaternion, SRGBColorSpace, TextureLoader, Vector3, } from "three";
-import { getComponent, registerComponent } from "./components/ComponentRegistry";
+import { getComponent, registerComponent, getNonComposableKeys } from "./components/ComponentRegistry";
 import components from "./components";
 import { loadModel } from "../dragdrop/modelLoader";
 import { GameInstance, GameInstanceProvider, useInstanceCheck } from "./InstanceProvider";
@@ -245,13 +245,15 @@ function computeParentWorldMatrix(root, targetId) {
     return result !== null && result !== void 0 ? result : IDENTITY;
 }
 function renderCoreNode(gameObject, ctx, parentMatrix) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     const geometry = (_a = gameObject.components) === null || _a === void 0 ? void 0 : _a.geometry;
     const material = (_b = gameObject.components) === null || _b === void 0 ? void 0 : _b.material;
     const model = (_c = gameObject.components) === null || _c === void 0 ? void 0 : _c.model;
+    const text = (_d = gameObject.components) === null || _d === void 0 ? void 0 : _d.text;
     const geometryDef = geometry && getComponent("Geometry");
     const materialDef = material && getComponent("Material");
     const modelDef = model && getComponent("Model");
+    const textDef = text && getComponent("Text");
     const contextProps = {
         loadedModels: ctx.loadedModels,
         loadedTextures: ctx.loadedTextures,
@@ -263,7 +265,7 @@ function renderCoreNode(gameObject, ctx, parentMatrix) {
     const leaves = [];
     if (gameObject.components) {
         Object.entries(gameObject.components)
-            .filter(([k]) => !["geometry", "material", "model", "transform", "physics"].includes(k))
+            .filter(([k]) => !getNonComposableKeys().includes(k))
             .forEach(([key, comp]) => {
             if (!(comp === null || comp === void 0 ? void 0 : comp.type))
                 return;
@@ -285,6 +287,9 @@ function renderCoreNode(gameObject, ctx, parentMatrix) {
     else if (geometry && (geometryDef === null || geometryDef === void 0 ? void 0 : geometryDef.View)) {
         core = (_jsxs("mesh", { castShadow: true, receiveShadow: true, children: [_jsx(geometryDef.View, Object.assign({ properties: geometry.properties }, contextProps)), material && (materialDef === null || materialDef === void 0 ? void 0 : materialDef.View) && (_jsx(materialDef.View, Object.assign({ properties: material.properties }, contextProps), "material")), leaves] }));
     }
+    else if (text && (textDef === null || textDef === void 0 ? void 0 : textDef.View)) {
+        core = (_jsxs(_Fragment, { children: [_jsx(textDef.View, Object.assign({ properties: text.properties }, contextProps)), leaves] }));
+    }
     else {
         core = _jsx(_Fragment, { children: leaves });
     }

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

@@ -10,7 +10,9 @@ export interface Component {
     }>;
     defaultProperties: any;
     View?: FC<any>;
+    nonComposable?: boolean;
 }
 export declare function registerComponent(component: Component): void;
 export declare function getComponent(name: string): Component | undefined;
 export declare function getAllComponents(): Record<string, Component>;
+export declare function getNonComposableKeys(): string[];

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

@@ -11,3 +11,8 @@ export function getComponent(name) {
 export function getAllComponents() {
     return Object.assign({}, REGISTRY);
 }
+export function getNonComposableKeys() {
+    return Object.values(REGISTRY)
+        .filter(c => c.nonComposable)
+        .map(c => c.name.toLowerCase());
+}

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

@@ -77,6 +77,7 @@ const GeometryComponent = {
     name: 'Geometry',
     Editor: GeometryComponentEditor,
     View: GeometryComponentView,
+    nonComposable: true,
     defaultProperties: {
         geometryType: 'box',
         args: GEOMETRY_ARGS.box.defaults,

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

@@ -3,7 +3,7 @@ import { SingleTextureViewer, TextureListViewer } from '../../assetviewer/page';
 import { useEffect, useState } from 'react';
 import { FieldRenderer, Input } from './Input';
 import { useMemo } from 'react';
-import { DoubleSide, RepeatWrapping, ClampToEdgeWrapping, SRGBColorSpace, NearestFilter, LinearFilter, NearestMipmapNearestFilter, NearestMipmapLinearFilter, LinearMipmapNearestFilter, LinearMipmapLinearFilter } from 'three';
+import { RepeatWrapping, ClampToEdgeWrapping, SRGBColorSpace, NearestFilter, LinearFilter, NearestMipmapNearestFilter, NearestMipmapLinearFilter, LinearMipmapNearestFilter, LinearMipmapLinearFilter } from 'three';
 function TexturePicker({ value, onChange, basePath }) {
     const [textureFiles, setTextureFiles] = useState([]);
     const [showPicker, setShowPicker] = useState(false);
@@ -117,12 +117,13 @@ function MaterialComponentView({ properties, loadedTextures }) {
         return _jsx("meshStandardMaterial", { color: "red", wireframe: true });
     }
     const { color, wireframe = false } = properties;
-    return (_jsx("meshStandardMaterial", { color: color, wireframe: wireframe, map: finalTexture, transparent: !!finalTexture, side: DoubleSide }, (_a = finalTexture === null || finalTexture === void 0 ? void 0 : finalTexture.uuid) !== null && _a !== void 0 ? _a : 'no-texture'));
+    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'));
 }
 const MaterialComponent = {
     name: 'Material',
     Editor: MaterialComponentEditor,
     View: MaterialComponentView,
+    nonComposable: true,
     defaultProperties: {
         color: '#ffffff',
         wireframe: false

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

@@ -58,6 +58,7 @@ const ModelComponent = {
     name: 'Model',
     Editor: ModelComponentEditor,
     View: ModelComponentView,
+    nonComposable: true,
     defaultProperties: {
         filename: '',
         instanced: false

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

@@ -39,6 +39,7 @@ const PhysicsComponent = {
     name: 'Physics',
     Editor: PhysicsComponentEditor,
     View: PhysicsComponentView,
+    nonComposable: true,
     defaultProperties: { type: 'dynamic', collider: 'hull' }
 };
 export default PhysicsComponent;

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

@@ -0,0 +1,3 @@
+import { Component } from "./ComponentRegistry";
+declare const TextComponent: Component;
+export default TextComponent;

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

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FieldRenderer } from "./Input";
+import { Text } from 'three-text/three/react';
+import { useRef, useState, useCallback } from 'react';
+// Initialize HarfBuzz path for font shaping
+Text.setHarfBuzzPath('/fonts/hb.wasm');
+function TextComponentEditor({ component, onUpdate, }) {
+    const fields = [
+        {
+            name: 'text',
+            type: 'string',
+            label: 'Text',
+            placeholder: 'Enter text...',
+        },
+        {
+            name: 'color',
+            type: 'color',
+            label: 'Color',
+        },
+        {
+            name: 'font',
+            type: 'string',
+            label: 'Font',
+            placeholder: '/fonts/NotoSans-Regular.ttf',
+        },
+        {
+            name: 'size',
+            type: 'number',
+            label: 'Size',
+            min: 0.01,
+            step: 0.1,
+        },
+        {
+            name: 'depth',
+            type: 'number',
+            label: 'Depth',
+            min: 0,
+            step: 0.1,
+        },
+        {
+            name: 'width',
+            type: 'number',
+            label: 'Width',
+            min: 0,
+            step: 0.5,
+        },
+        {
+            name: 'align',
+            type: 'select',
+            label: 'Align',
+            options: [
+                { value: 'left', label: 'Left' },
+                { value: 'center', label: 'Center' },
+                { value: 'right', label: 'Right' },
+            ],
+        },
+    ];
+    return (_jsx(FieldRenderer, { fields: fields, values: component.properties, onChange: onUpdate }));
+}
+function TextComponentView({ properties }) {
+    const { text = '', font, size, depth, width, align, color } = properties;
+    const textContent = String(text || '');
+    const meshRef = useRef(null);
+    const [offset, setOffset] = useState([0, 0, 0]);
+    const handleLoad = useCallback((_geometry, info) => {
+        if (info === null || info === void 0 ? void 0 : info.planeBounds) {
+            const bounds = info.planeBounds;
+            // Calculate X offset based on alignment
+            let centerX = 0;
+            if (align === 'center') {
+                centerX = -(bounds.min.x + bounds.max.x) / 2;
+            }
+            else if (align === 'right') {
+                centerX = -bounds.max.x;
+            }
+            else {
+                // left alignment
+                centerX = -bounds.min.x;
+            }
+            const centerY = -(bounds.min.y + bounds.max.y) / 2;
+            setOffset([centerX, centerY, 0]);
+        }
+    }, [align]);
+    if (!textContent)
+        return null;
+    return (_jsx("group", { position: offset, children: _jsx(Text, { ref: meshRef, font: font, size: size, depth: depth, layout: { align, width }, color: color, onLoad: handleLoad, children: textContent }) }));
+}
+const TextComponent = {
+    name: 'Text',
+    Editor: TextComponentEditor,
+    View: TextComponentView,
+    nonComposable: true,
+    defaultProperties: {
+        text: 'Hello World',
+        color: '#888888',
+        font: '/fonts/NotoSans-Regular.ttf',
+        size: 0.5,
+        depth: 0,
+        width: 5,
+        align: 'center',
+    }
+};
+export default TextComponent;

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

@@ -41,6 +41,7 @@ function TransformComponentEditor({ component, onUpdate }) {
 const TransformComponent = {
     name: 'Transform',
     Editor: TransformComponentEditor,
+    nonComposable: true,
     defaultProperties: {
         position: [0, 0, 0],
         rotation: [0, 0, 0],

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

@@ -5,6 +5,7 @@ import PhysicsComponent from './PhysicsComponent';
 import SpotLightComponent from './SpotLightComponent';
 import DirectionalLightComponent from './DirectionalLightComponent';
 import ModelComponent from './ModelComponent';
+import TextComponent from './TextComponent';
 export default [
     GeometryComponent,
     TransformComponent,
@@ -12,5 +13,6 @@ export default [
     PhysicsComponent,
     SpotLightComponent,
     DirectionalLightComponent,
-    ModelComponent
+    ModelComponent,
+    TextComponent
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-three-game",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "description": "Batteries included React Three Fiber game engine",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -24,7 +24,8 @@
     "@react-three/rapier": ">=2.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "three": ">=0.182.0"
+    "three": ">=0.182.0",
+    "three-text": ">=0.4.4"
   },
   "devDependencies": {
     "@react-three/drei": "^10.7.7",

package/skill/SKILL.md

@@ -0,0 +1,491 @@
+# react-three-game
+
+A Claude Code skill for working with react-three-game, a JSON-first 3D game engine built on React Three Fiber, WebGPU, and Rapier Physics.
+
+## When to Use This Skill
+
+Use this skill when:
+- Creating or modifying 3D game scenes with react-three-game
+- Working with prefab JSON structures
+- Setting up physics-enabled game objects
+- Creating custom components with editor UI (see Editor Mode section)
+
+## Core Concepts
+
+### GameObject Structure
+
+Every game object follows this schema:
+
+```typescript
+interface GameObject {
+  id: string;
+  disabled?: boolean;
+  hidden?: boolean;
+  components?: Record<string, { type: string; properties: any }>;
+  children?: GameObject[];
+}
+```
+
+### Prefab JSON Format
+
+Scenes are defined as JSON prefabs with a root node containing children:
+
+```json
+{
+  "root": {
+    "id": "scene",
+    "children": [
+      {
+        "id": "my-object",
+        "components": {
+          "transform": { "type": "Transform", "properties": { "position": [0, 0, 0] } },
+          "geometry": { "type": "Geometry", "properties": { "geometryType": "box" } },
+          "material": { "type": "Material", "properties": { "color": "#ff0000" } }
+        }
+      }
+    ]
+  }
+}
+```
+
+## Built-in Components
+
+| Component | Type | Key Properties |
+|-----------|------|----------------|
+| 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" |
+| 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]` |
+| Text | `Text` | `text`, `font`, `size`, `depth`, `width`, `align`, `color` |
+
+### Geometry Args by Type
+
+| geometryType | args array |
+|--------------|------------|
+| `box` | `[width, height, depth]` |
+| `sphere` | `[radius, widthSegments, heightSegments]` |
+| `plane` | `[width, height]` |
+| `cylinder` | `[radiusTop, radiusBottom, height, radialSegments]` |
+
+### Material Texture Options
+
+```json
+{
+  "type": "Material",
+  "properties": {
+    "color": "white",
+    "texture": "/textures/path/to/texture.png",
+    "repeat": true,
+    "repeatCount": [4, 4]
+  }
+}
+```
+
+- Use `"color": "white"` with textures for accurate texture colors
+- `repeatCount: [x, y]` tiles the texture; match to geometry dimensions for proper scaling
+
+### Rotation Reference
+
+Rotations use radians. Common values:
+- `1.57` = 90° (π/2)
+- `3.14` = 180° (π)
+- `-1.57` = -90° (rotate plane flat: `rotation: [-1.57, 0, 0]`)
+
+## Common Patterns
+
+### Usage Modes
+
+The library supports two modes:
+
+**Play Mode** (default) - Immediate rendering without any editor UI. Use `GameCanvas` with `PrefabRoot` for a clean game experience.
+
+**Editor Mode** - Visual GUI using `PrefabEditor` for scene inspection and custom component development. See the [Editor Mode](#editor-mode) section at the end of this document.
+
+### Basic Scene Setup (Play Mode)
+
+```jsx
+import { Physics } from '@react-three/rapier';
+import { GameCanvas, PrefabRoot } from 'react-three-game';
+
+<GameCanvas>
+  <Physics>
+    <PrefabRoot data={prefabData} />
+  </Physics>
+</GameCanvas>
+```
+
+### Tree Manipulation Utilities
+
+```typescript
+import { findNode, updateNode, updateNodeById, deleteNode, cloneNode } from 'react-three-game';
+
+// Update a node by ID (optimized - avoids unnecessary object creation)
+const updated = updateNodeById(root, nodeId, node => ({ ...node, disabled: true }));
+
+// Find a node
+const node = findNode(root, nodeId);
+
+// Delete a node
+const afterDelete = deleteNode(root, nodeId);
+
+// Clone a node
+const cloned = cloneNode(node);
+```
+
+## Building Game Levels
+
+### Complete Prefab Structure
+
+```json
+{
+  "id": "level-id",
+  "name": "Level Name",
+  "root": {
+    "id": "root",
+    "enabled": true,
+    "visible": true,
+    "components": { ... },
+    "children": [ ... ]
+  }
+}
+```
+
+### Floor/Ground Pattern
+
+```json
+{
+  "id": "main-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": { "color": "white", "texture": "/textures/GreyboxTextures/greybox_dark_grid.png", "repeat": true, "repeatCount": [20, 20] } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+  }
+}
+```
+
+### Platform Pattern
+
+Floating platforms use "fixed" physics and smaller box geometry:
+
+```json
+{
+  "id": "platform-1",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [-8, 2, -5] } },
+    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [6, 0.5, 4] } },
+    "material": { "type": "Material", "properties": { "color": "white", "texture": "/textures/GreyboxTextures/greybox_teal_grid.png", "repeat": true, "repeatCount": [3, 2] } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed" } }
+  }
+}
+```
+
+### Ramp Pattern
+
+Rotate on the Z-axis to create inclined surfaces:
+
+```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
+
+Tall thin boxes positioned at boundaries:
+
+```json
+{
+  "id": "wall-back",
+  "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" } }
+  }
+}
+```
+
+### Three-Point Lighting Setup
+
+Good lighting uses main, fill, and accent lights:
+
+```json
+[
+  { "id": "main-light", "components": { "transform": { "properties": { "position": [10, 15, 10] } }, "spotlight": { "type": "SpotLight", "properties": { "color": "#ffffff", "intensity": 200, "angle": 0.8, "castShadow": true } } } },
+  { "id": "fill-light", "components": { "transform": { "properties": { "position": [-10, 12, -5] } }, "spotlight": { "type": "SpotLight", "properties": { "color": "#b0c4de", "intensity": 80, "angle": 0.9 } } } },
+  { "id": "accent-light", "components": { "transform": { "properties": { "position": [0, 10, -15] } }, "spotlight": { "type": "SpotLight", "properties": { "color": "#ffd700", "intensity": 50, "angle": 0.4 } } } }
+]
+```
+
+### Available Greybox Textures
+
+Located in `/textures/GreyboxTextures/`:
+- `greybox_dark_grid.png` - dark floors
+- `greybox_light_grid.png` - light surfaces
+- `greybox_teal_grid.png`, `greybox_purple_grid.png`, `greybox_orange_grid.png` - colored platforms
+- `greybox_red_grid.png`, `greybox_blue_grid.png` - obstacles/hazards
+- `greybox_yellow_grid.png`, `greybox_lime_grid.png`, `greybox_green_grid.png` - special areas
+
+### Metallic/Special Materials
+
+For goal platforms or special objects, use metalness and roughness:
+
+```json
+{
+  "type": "Material",
+  "properties": {
+    "color": "#FFD700",
+    "metalness": 0.8,
+    "roughness": 0.2
+  }
+}
+```
+
+### Text Component
+
+3D text rendering using `three-text`. The Text component is non-composable (cannot have children).
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `text` | string | `"Hello World"` | Text content to display |
+| `color` | string | `"#888888"` | Text color (hex or CSS color) |
+| `font` | string | `"/fonts/NotoSans-Regular.ttf"` | Path to TTF font file |
+| `size` | number | `0.5` | Font size in world units |
+| `depth` | number | `0` | 3D extrusion depth (0 for flat text) |
+| `width` | number | `5` | Text block width for wrapping/alignment |
+| `align` | string | `"center"` | Horizontal alignment: `"left"`, `"center"`, `"right"` |
+
+```json
+{
+  "id": "title-text",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [0, 3, 0] } },
+    "text": {
+      "type": "Text",
+      "properties": {
+        "text": "Welcome",
+        "color": "#ffffff",
+        "size": 1,
+        "depth": 0.1,
+        "align": "center"
+      }
+    }
+  }
+}
+```
+
+### Model Placement
+
+GLB models don't need geometry/material components:
+
+```json
+{
+  "id": "tree-1",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [-12, 0, 10], "scale": [1.5, 1.5, 1.5] } },
+    "model": { "type": "Model", "properties": { "filename": "models/environment/tree.glb" } }
+  }
+}
+```
+
+Available models: `models/environment/tree.glb`, `models/environment/servers.glb`, `models/environment/cubeart.glb`
+
+## Editor Mode
+
+Use editor mode when building scenes visually or creating custom components with inspector UI.
+
+### Using the Visual Editor
+
+```jsx
+import { PrefabEditor } from 'react-three-game';
+
+<PrefabEditor
+  initialPrefab={sceneData}
+  onPrefabChange={setSceneData}
+/>
+```
+
+The editor provides a full GUI with:
+- Scene hierarchy tree for navigating and selecting objects
+- Component inspector panel for editing properties
+- Transform gizmos for manipulating objects visually
+- Keyboard shortcuts: **T** (Translate), **R** (Rotate), **S** (Scale)
+
+### Programmatic Updates with PrefabEditor
+
+Use the editor ref to update prefabs programmatically:
+
+```jsx
+import { useRef } from 'react';
+import { PrefabEditor, updateNodeById } from 'react-three-game';
+import type { PrefabEditorRef, Prefab } from 'react-three-game';
+
+function Game() {
+  const editorRef = useRef<PrefabEditorRef>(null);
+
+  const movePlayer = () => {
+    if (!editorRef.current) return;
+    const prefab = editorRef.current.prefab;
+    const newRoot = updateNodeById(prefab.root, "player", node => ({
+      ...node,
+      components: {
+        ...node.components,
+        transform: {
+          ...node.components!.transform!,
+          properties: { ...node.components!.transform!.properties, position: [5, 0, 0] }
+        }
+      }
+    }));
+    editorRef.current.setPrefab({ ...prefab, root: newRoot });
+  };
+
+  return (
+    <PrefabEditor ref={editorRef} initialPrefab={sceneData}>
+      {/* Children render inside the Canvas - can use useFrame here */}
+    </PrefabEditor>
+  );
+}
+```
+
+The `PrefabEditorRef` provides:
+- `prefab` - current prefab state
+- `setPrefab(prefab)` - update the prefab
+- `screenshot()` - save canvas as PNG
+- `exportGLB()` - export scene as GLB
+
+### Live Node Updates with useFrame
+
+To animate objects by updating the prefab JSON at runtime, pass a child component to `PrefabEditor` that uses `useFrame`:
+
+```tsx
+import { useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import { PrefabEditor, updateNodeById } from "react-three-game";
+import type { Prefab, PrefabEditorRef } from "react-three-game";
+
+// Animation component runs inside the editor's Canvas
+function PlayerAnimator({ editorRef }: { editorRef: React.RefObject<PrefabEditorRef | null> }) {
+  const velocityRef = useRef({ x: 0, z: 0 });
+
+  useFrame(() => {
+    if (!editorRef.current) return;
+
+    const prefab = editorRef.current.prefab;
+    const newRoot = updateNodeById(prefab.root, "player", (node) => {
+      const transform = node.components?.transform?.properties;
+      if (!transform) return node;
+
+      const pos = transform.position as [number, number, number];
+      return {
+        ...node,
+        components: {
+          ...node.components,
+          transform: {
+            ...node.components!.transform!,
+            properties: {
+              ...transform,
+              position: [pos[0] + velocityRef.current.x * 0.02, pos[1], pos[2] + velocityRef.current.z * 0.02],
+            },
+          },
+        },
+      };
+    });
+
+    if (newRoot !== prefab.root) {
+      editorRef.current.setPrefab({ ...prefab, root: newRoot });
+    }
+  });
+
+  return null;
+}
+
+// Usage
+function Game() {
+  const editorRef = useRef<PrefabEditorRef>(null);
+
+  return (
+    <PrefabEditor ref={editorRef} initialPrefab={sceneData}>
+      <PlayerAnimator editorRef={editorRef} />
+    </PrefabEditor>
+  );
+}
+```
+
+Key points:
+- Pass animation components as `children` to `PrefabEditor` - they render inside the Canvas
+- Access prefab via `editorRef.current.prefab` and update via `editorRef.current.setPrefab()`
+- `updateNodeById` is optimized to avoid recreating unchanged branches
+- Store mutable state (velocities, timers) in refs to avoid re-renders
+
+### Creating a Custom Component
+
+```tsx
+import { Component, registerComponent, FieldRenderer, FieldDefinition } from 'react-three-game';
+
+const myFields: FieldDefinition[] = [
+  { name: 'speed', type: 'number', label: 'Speed', step: 0.1 },
+  { name: 'enabled', type: 'boolean', label: 'Enabled' },
+];
+
+const MyComponent: Component = {
+  name: 'MyComponent',
+  Editor: ({ component, onUpdate }) => (
+    <FieldRenderer fields={myFields} values={component.properties} onChange={onUpdate} />
+  ),
+  View: ({ properties, children }) => {
+    // Runtime behavior here
+    return <group>{children}</group>;
+  },
+  defaultProperties: { speed: 1, enabled: true }
+};
+
+registerComponent(MyComponent);
+```
+
+### Field Types for Editor UI
+
+| Type | Description | Options |
+|------|-------------|---------|
+| `vector3` | X/Y/Z inputs | `snap?: number` |
+| `number` | Numeric input | `min?`, `max?`, `step?` |
+| `string` | Text input | `placeholder?` |
+| `color` | Color picker | - |
+| `boolean` | Checkbox | - |
+| `select` | Dropdown | `options: { value, label }[]` |
+| `custom` | Custom render function | `render: (props) => ReactNode` |
+
+## Dependencies
+
+Required peer dependencies:
+- `@react-three/fiber`
+- `@react-three/rapier`
+- `three`
+
+Install with:
+```bash
+npm i react-three-game @react-three/fiber @react-three/rapier three
+```
+
+## File Structure
+
+```
+/src                 → library source (published to npm)
+/docs                → Next.js demo site
+/dist                → built output
+```
+
+## Development Commands
+
+```bash
+npm run dev     # tsc --watch + docs site
+npm run build   # build to /dist
+npm run release # build + publish
+```

package/skill/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@react-three-game/skills",
+  "version": "0.0.1",
+  "description": "Agent skill for working with react-three-game - a JSON-first 3D game engine",
+  "repository": {
+    "url": "https://github.com/prnth/react-three-game/tree/main/skill"
+  },
+  "keywords": [
+    "agentic",
+    "skill",
+    "react-three-fiber",
+    "game-engine",
+    "3d",
+    "webgpu"
+  ],
+  "license": "MIT"
+}

package/src/tools/prefabeditor/PrefabRoot.tsx

@@ -4,7 +4,7 @@ import { BoxHelper, Euler, Group, Matrix4, Object3D, Quaternion, SRGBColorSpace,
 import { ThreeEvent } from "@react-three/fiber";
 
 import { Prefab, GameObject as GameObjectType } from "./types";
-import { getComponent, registerComponent } from "./components/ComponentRegistry";
+import { getComponent, registerComponent, getNonComposableKeys } from "./components/ComponentRegistry";
 import components from "./components";
 import { loadModel } from "../dragdrop/modelLoader";
 import { GameInstance, GameInstanceProvider, useInstanceCheck } from "./InstanceProvider";
@@ -488,10 +488,12 @@ function renderCoreNode(
     const geometry = gameObject.components?.geometry;
     const material = gameObject.components?.material;
     const model = gameObject.components?.model;
+    const text = gameObject.components?.text;
 
     const geometryDef = geometry && getComponent("Geometry");
     const materialDef = material && getComponent("Material");
     const modelDef = model && getComponent("Model");
+    const textDef = text && getComponent("Text");
 
     const contextProps = {
         loadedModels: ctx.loadedModels,
@@ -506,7 +508,7 @@ function renderCoreNode(
 
     if (gameObject.components) {
         Object.entries(gameObject.components)
-            .filter(([k]) => !["geometry", "material", "model", "transform", "physics"].includes(k))
+            .filter(([k]) => !getNonComposableKeys().includes(k))
             .forEach(([key, comp]) => {
                 if (!comp?.type) return;
                 const def = getComponent(comp.type);
@@ -551,6 +553,13 @@ function renderCoreNode(
                 {leaves}
             </mesh>
         );
+    } else if (text && textDef?.View) {
+        core = (
+            <>
+                <textDef.View properties={text.properties} {...contextProps} />
+                {leaves}
+            </>
+        );
     } else {
         core = <>{leaves}</>;
     }

package/src/tools/prefabeditor/components/ComponentRegistry.ts

@@ -12,6 +12,8 @@ export interface Component {
     defaultProperties: any;
     // Allow View to accept extra props for special cases (like material)
     View?: FC<any>;
+    // Non-composable components have special rendering logic in PrefabRoot
+    nonComposable?: boolean;
 }
 
 const REGISTRY: Record<string, Component> = {};
@@ -30,3 +32,9 @@ export function getComponent(name: string): Component | undefined {
 export function getAllComponents(): Record<string, Component> {
     return { ...REGISTRY };
 }
+
+export function getNonComposableKeys(): string[] {
+    return Object.values(REGISTRY)
+        .filter(c => c.nonComposable)
+        .map(c => c.name.toLowerCase());
+}

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

@@ -110,6 +110,7 @@ const GeometryComponent: Component = {
     name: 'Geometry',
     Editor: GeometryComponentEditor,
     View: GeometryComponentView,
+    nonComposable: true,
     defaultProperties: {
         geometryType: 'box',
         args: GEOMETRY_ARGS.box.defaults,

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

@@ -4,7 +4,6 @@ import { Component } from './ComponentRegistry';
 import { FieldRenderer, FieldDefinition, Input } from './Input';
 import { useMemo } from 'react';
 import {
-    DoubleSide,
     RepeatWrapping,
     ClampToEdgeWrapping,
     SRGBColorSpace,
@@ -190,7 +189,6 @@ function MaterialComponentView({ properties, loadedTextures }: { properties: any
             wireframe={wireframe}
             map={finalTexture}
             transparent={!!finalTexture}
-            side={DoubleSide}
         />
     );
 }
@@ -199,6 +197,7 @@ const MaterialComponent: Component = {
     name: 'Material',
     Editor: MaterialComponentEditor,
     View: MaterialComponentView,
+    nonComposable: true,
     defaultProperties: {
         color: '#ffffff',
         wireframe: false

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

@@ -112,6 +112,7 @@ const ModelComponent: Component = {
     name: 'Model',
     Editor: ModelComponentEditor,
     View: ModelComponentView,
+    nonComposable: true,
     defaultProperties: {
         filename: '',
         instanced: false

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

@@ -82,6 +82,7 @@ const PhysicsComponent: Component = {
     name: 'Physics',
     Editor: PhysicsComponentEditor,
     View: PhysicsComponentView,
+    nonComposable: true,
     defaultProperties: { type: 'dynamic', collider: 'hull' }
 };
 

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

@@ -0,0 +1,136 @@
+import { Component } from "./ComponentRegistry";
+import { FieldRenderer, FieldDefinition } from "./Input";
+import { Text } from 'three-text/three/react';
+import { useRef, useState, useCallback } from 'react';
+import { BufferGeometry, Mesh } from "three";
+
+// Initialize HarfBuzz path for font shaping
+Text.setHarfBuzzPath('/fonts/hb.wasm');
+
+function TextComponentEditor({
+    component,
+    onUpdate,
+}: {
+    component: any;
+    onUpdate: (newProps: any) => void;
+}) {
+    const fields: FieldDefinition[] = [
+        {
+            name: 'text',
+            type: 'string',
+            label: 'Text',
+            placeholder: 'Enter text...',
+        },
+        {
+            name: 'color',
+            type: 'color',
+            label: 'Color',
+        },
+        {
+            name: 'font',
+            type: 'string',
+            label: 'Font',
+            placeholder: '/fonts/NotoSans-Regular.ttf',
+        },
+        {
+            name: 'size',
+            type: 'number',
+            label: 'Size',
+            min: 0.01,
+            step: 0.1,
+        },
+        {
+            name: 'depth',
+            type: 'number',
+            label: 'Depth',
+            min: 0,
+            step: 0.1,
+        },
+        {
+            name: 'width',
+            type: 'number',
+            label: 'Width',
+            min: 0,
+            step: 0.5,
+        },
+        {
+            name: 'align',
+            type: 'select',
+            label: 'Align',
+            options: [
+                { value: 'left', label: 'Left' },
+                { value: 'center', label: 'Center' },
+                { value: 'right', label: 'Right' },
+            ],
+        },
+    ];
+
+    return (
+        <FieldRenderer
+            fields={fields}
+            values={component.properties}
+            onChange={onUpdate}
+        />
+    );
+}
+
+function TextComponentView({ properties }: { properties: any }) {
+    const { text = '', font, size, depth, width, align, color } = properties;
+    const textContent = String(text || '');
+    const meshRef = useRef<Mesh>(null);
+    const [offset, setOffset] = useState<[number, number, number]>([0, 0, 0]);
+
+    const handleLoad = useCallback((_geometry: BufferGeometry, info: any) => {
+        if (info?.planeBounds) {
+            const bounds = info.planeBounds;
+            // Calculate X offset based on alignment
+            let centerX = 0;
+            if (align === 'center') {
+                centerX = -(bounds.min.x + bounds.max.x) / 2;
+            } else if (align === 'right') {
+                centerX = -bounds.max.x;
+            } else {
+                // left alignment
+                centerX = -bounds.min.x;
+            }
+            const centerY = -(bounds.min.y + bounds.max.y) / 2;
+            setOffset([centerX, centerY, 0]);
+        }
+    }, [align]);
+
+    if (!textContent) return null;
+
+    return (
+        <group position={offset}>
+            <Text
+                ref={meshRef}
+                font={font}
+                size={size}
+                depth={depth}
+                layout={{ align, width }}
+                color={color}
+                onLoad={handleLoad}
+            >
+                {textContent}
+            </Text>
+        </group>
+    );
+}
+
+const TextComponent: Component = {
+    name: 'Text',
+    Editor: TextComponentEditor,
+    View: TextComponentView,
+    nonComposable: true,
+    defaultProperties: {
+        text: 'Hello World',
+        color: '#888888',
+        font: '/fonts/NotoSans-Regular.ttf',
+        size: 0.5,
+        depth: 0,
+        width: 5,
+        align: 'center',
+    }
+};
+
+export default TextComponent;

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

@@ -104,6 +104,7 @@ function TransformComponentEditor({ component, onUpdate }: {
 const TransformComponent: Component = {
     name: 'Transform',
     Editor: TransformComponentEditor,
+    nonComposable: true,
     defaultProperties: {
         position: [0, 0, 0],
         rotation: [0, 0, 0],

package/src/tools/prefabeditor/components/index.ts

@@ -5,6 +5,7 @@ import PhysicsComponent from './PhysicsComponent';
 import SpotLightComponent from './SpotLightComponent';
 import DirectionalLightComponent from './DirectionalLightComponent';
 import ModelComponent from './ModelComponent';
+import TextComponent from './TextComponent';
 
 export default [
     GeometryComponent,
@@ -13,6 +14,7 @@ export default [
     PhysicsComponent,
     SpotLightComponent,
     DirectionalLightComponent,
-    ModelComponent
+    ModelComponent,
+    TextComponent
 ];