@ringozz/react-godot 1.0.0-3 → 1.0.0-4

package/README.md

@@ -1,94 +1,280 @@
-# @ringozz/react-godot
+# `@ringozz/react-godot`
 
-React bindings for the Godot Engine, built on [`@ringozz/godot`](../godot/README.md). A custom `react-reconciler` host config lets you build Godot scenes declaratively with JSX.
+Declarative, component-driven **Godot 4** scene graph management in React. Built for high-performance applications using `@ringozz/godot`.
 
-## Installation
+---
 
-```sh
-bun add @ringozz/react-godot @ringozz/godot react
+## Overview
+
+`@ringozz/react-godot` brings a **React Three Fiber (R3F)**-like developer experience to Godot. It provides a custom React reconciler that renders React components directly into Godot's live engine scene tree (`SceneTree`).
+
+If you are familiar with React Three Fiber, the core paradigms will feel instantly recognizable:
+- **Declarative Nodes**: Godot 3D/2D nodes (e.g., `<RigidBody3D>`, `<Camera3D>`, `<DirectionalLight3D>`) map directly to JSX components.
+- **Resource Attachment**: Use the `attach` prop to assign nested Godot resources (materials, shapes, meshes, environments) directly to parent properties.
+- **Reactive Engine Loop**: Use hooks like `useSignal` to hook into Godot signals (`processFrame`, `windowInput`) without triggering React state re-renders.
+
+---
+
+## Installation & Setup
+
+### 1. Dependencies
+
+```bash
+npm install @ringozz/react-godot react
 ```
 
-`@ringozz/godot` and `react` (`^19.2`) are peer dependencies. Configure the JSX runtime in `tsconfig.json`:
+### 2. TypeScript Configuration (`tsconfig.json`)
+
+To enable custom JSX element resolution for Godot nodes, configure `jsxImportSource` and module settings in `tsconfig.json`:
 
 ```json
 {
   "compilerOptions": {
+    "module": "esnext",
+    "target": "es2025",
     "jsx": "react-jsx",
-    "jsxImportSource": "@ringozz/react-godot"
+    "jsxImportSource": "@ringozz/react-godot",
+    "rewriteRelativeImportExtensions": true,
+    "verbatimModuleSyntax": true
   }
 }
 ```
 
-## API
-
-```ts
-import { createRoot, createPortal, useSignal, useMutableCallback, type ComponentProps } from '@ringozz/react-godot';
-```
+---
 
-- **`createRoot(parent: Node)`** — mounts a React tree into a Godot `Node` (e.g. `SceneTree.root`). Returns `{ render, unmount }`; `render` resolves when the commit completes. StrictMode is enabled only when `NODE_ENV === 'development'`.
-- **`createPortal(children, container)`** — renders into another Godot `Node` (a `CanvasLayer` for overlays, a `SubViewport`, a dedicated parent node). The container must be a `Node` — portals cannot target `Resource`s. Unmounting frees the portal's children.
-- **`useSignal<T extends (...args: any[]) => any>(signal, handler)`** — connects a Godot `Signal` for the component's lifetime, disconnecting on unmount. Uses a mutable callback ref, so the handler always sees fresh state.
-- **`useMutableCallback<T>(fn)`** — returns a `RefObject<T>` whose `.current` always holds the latest `fn`.
-- **`ComponentProps<typeof ClassName>`** — full prop validation for an element (Godot properties + `children`/`ref` + `object`/`attach`).
+## Application Entry & Portal Rendering
 
-## Example
+### 1. Mounting with `createRoot(parent: Node)`
+`createRoot` is the primary entry point for mounting a React component tree into a Godot target `Node` (typically `SceneTree.root`).
 
 ```tsx
 import { Engine } from '@ringozz/godot/Engine';
 import { SceneTree } from '@ringozz/godot/SceneTree';
-import { Label } from '@ringozz/godot/Label';
-import { createRoot, useSignal } from '@ringozz/react-godot';
-import { useRef } from 'react';
+import { createRoot } from '@ringozz/react-godot';
+import { App } from './App';
 
 const tree = Engine.getMainLoop() as SceneTree;
 const { render } = createRoot(tree.root);
 
-function Hud() {
-  const label = useRef<Label>(null);
-  useSignal(tree.processFrame, () => {
-    if (label.current) label.current.text = String(Math.floor(performance.now() / 1000));
-  });
-  return <Label ref={label} position={[16, 16]} text="ticking" />;
-}
-
-render(<Hud />);
+render(<App />);
 ```
 
-### Render a component
+- Returns `{ render, unmount }`.
+- Enables React `StrictMode` automatically in development (`NODE_ENV === 'development'`).
+
+### 2. Render Portals with `createPortal(children, container)`
+`createPortal` allows rendering a React sub-tree into a different Godot `Node` in the hierarchy—such as a `CanvasLayer` for 2D UI overlays, a `SubViewport`, or an isolated container node.
 
 ```tsx
-function App() {
-  return (
-    <WorldEnvironment>
-      <Environment attach="environment" backgroundColor={[0.05, 0.1, 0.25]} />
-    </WorldEnvironment>
+import { createPortal } from '@ringozz/react-godot';
+import { Label } from '@ringozz/godot/Label';
+
+function Overlay({ overlayNode }: { overlayNode: Node }) {
+  return createPortal(
+    <Label text="HUD Overlay" position={[20, 20]} />,
+    overlayNode
   );
 }
 ```
 
-## How elements map to Godot
+- **Container Constraint**: The target `container` must be a Godot `Node` (it cannot target `Resource` instances).
+- **Cleanup**: Unmounting the portal safely disposes of and frees its child Godot nodes.
 
-- Each element instantiates its class via `ClassDB.instantiate(type)` (or uses an existing instance passed through the `object` prop, which bypasses instantiation and `.reference()`s `RefCounted` objects).
-- **`attach="prop"`** sets the element as a named property of its parent instead of adding it as a child — use it for resources. A physics body's shape goes on the **shape resource element**, never on the `CollisionShape3D` node:
+---
 
+## Core Concepts & Patterns
+
+### 1. Existing Objects with `object` Prop
+
+If you already have a pre-existing Godot `Node` or `Resource` instance (e.g. instantiated from C++ or loaded from disk), pass it via the `object` prop to adopt it into the React component tree instead of letting the reconciler instantiate a new object:
+
+```tsx
+<Node object={myExistingGodotNode}>
+  {/* Children attached to existing node */}
+</Node>
+```
+
+### 2. Resource Nesting with `attach`
+
+In Godot, nodes often hold references to `Resource` objects (such as shapes, meshes, materials, or environments). Use the `attach` prop to automatically assign a child resource to a specific property on its parent:
+
+```tsx
+/* Attaching a shape to CollisionShape3D */
+<CollisionShape3D>
+  <BoxShape3D attach="shape" size={[1, 1, 1]} />
+</CollisionShape3D>
+
+/* Attaching a material override to MeshInstance3D */
+<MeshInstance3D>
+  <BoxMesh attach="mesh" />
+  <StandardMaterial3D attach="materialOverride" albedoColor={[1, 0, 0]} />
+</MeshInstance3D>
+
+/* Attaching physics material to RigidBody3D */
+<RigidBody3D>
+  <PhysicsMaterial attach="physicsMaterialOverride" bounce={0.8} />
+</RigidBody3D>
+
+/* Attaching environment to WorldEnvironment */
+<WorldEnvironment>
+  <Environment attach="environment" backgroundColor={[0.1, 0.1, 0.2]} />
+</WorldEnvironment>
+```
+
+### 2. Properties & Helper Types
+
+Props map directly to Godot node setters and properties. Helper arrays are automatically cast to Godot types:
+
+- **Vectors**: `position={[0, 1, 0]}`, `scale={[2, 2, 2]}`
+- **Colors**: `albedoColor={[1, 0.2, 0.2]}` or `Color` objects
+- **Sub-properties / Dash props**: Set individual vector/color components directly using dash syntax:
   ```tsx
-  <StaticBody3D>
-    <CollisionShape3D>
-      <BoxShape3D attach="shape" size={[1, 1, 1]} />
-    </CollisionShape3D>
-    <MeshInstance3D>
-      <BoxMesh attach="mesh" />
-      <StandardMaterial3D attach="materialOverride" />
-    </MeshInstance3D>
-  </StaticBody3D>
+  <BoxMesh attach="mesh" size-x={0.5} size-y={1.0} size-z={0.5} />
   ```
 
-  The `attach` value may not change across updates.
-- **`object` prop**: pass an existing Godot instance (nodes or resources) to render rather than create one.
-- **Text**: standalone text nodes are unsupported. A single string child is mapped to the node's `text` property — fine for `Label`/`Label3D` — but arrays/mixed string children throw; use a `text` prop instead.
+### 3. Engine Signals & Event Subscription (`useSignal`)
+
+Subscribe to Godot engine signals cleanly with `useSignal`.
+
+```tsx
+import { Engine } from '@ringozz/godot';
+import { SceneTree } from '@ringozz/godot/SceneTree';
+import { useSignal } from '@ringozz/react-godot';
+
+const tree = Engine.getMainLoop() as SceneTree;
+const root = tree.root;
+
+// Subscribe to frame updates (process loop)
+useSignal(tree.processFrame, () => {
+  // Update animations, camera matrix, physics targets, etc.
+});
+
+// Subscribe to window input events
+useSignal(root.windowInput, (event) => {
+  if (event instanceof InputEventMouseMotion) {
+    // Handle mouse motion
+  }
+  // IMPORTANT: Always free transient input event objects
+  event.free();
+});
+```
+
+> **Memory Tip**: Godot input events should be explicitly freed by calling `event.free()` inside your signal handler.
+
+---
+
+## Full Example
+
+Below is a complete interactive 3D physics scene with custom camera controls and physics bodies:
+
+```tsx
+import { Color, Key, MouseButton, Vector3, Engine } from '@ringozz/godot';
+import { BoxMesh } from '@ringozz/godot/BoxMesh';
+import { BoxShape3D } from '@ringozz/godot/BoxShape3D';
+import { Camera3D } from '@ringozz/godot/Camera3D';
+import { CollisionShape3D } from '@ringozz/godot/CollisionShape3D';
+import { DirectionalLight3D } from '@ringozz/godot/DirectionalLight3D';
+import { BGMode, Environment, ToneMapper } from '@ringozz/godot/Environment';
+import { InputEventMouseButton } from '@ringozz/godot/InputEventMouseButton';
+import { InputEventMouseMotion } from '@ringozz/godot/InputEventMouseMotion';
+import { MeshInstance3D } from '@ringozz/godot/MeshInstance3D';
+import { PhysicsMaterial } from '@ringozz/godot/PhysicsMaterial';
+import { RigidBody3D } from '@ringozz/godot/RigidBody3D';
+import { SceneTree } from '@ringozz/godot/SceneTree';
+import { SphereMesh } from '@ringozz/godot/SphereMesh';
+import { SphereShape3D } from '@ringozz/godot/SphereShape3D';
+import { StandardMaterial3D } from '@ringozz/godot/StandardMaterial3D';
+import { StaticBody3D } from '@ringozz/godot/StaticBody3D';
+import { WorldEnvironment } from '@ringozz/godot/WorldEnvironment';
+import { useSignal, type ComponentProps } from '@ringozz/react-godot';
+import { useRef, type ReactElement } from 'react';
+
+const tree = Engine.getMainLoop() as SceneTree;
+const root = tree.root;
+
+function PhysBody({ color, shape, children, ...rest }: {
+  color: Color | number[];
+  shape: ReactElement;
+} & ComponentProps<typeof RigidBody3D>) {
+  return (
+    <RigidBody3D {...rest}>
+      <MeshInstance3D>
+        {children}
+        <StandardMaterial3D attach="materialOverride" albedoColor={color} />
+      </MeshInstance3D>
+      <CollisionShape3D>{shape}</CollisionShape3D>
+    </RigidBody3D>
+  );
+}
+
+export function App() {
+  const cameraRef = useRef<Camera3D>(null);
+  const isDragging = useRef(false);
+  const yaw = useRef(0.7);
+  const pitch = useRef(0.3);
+  const zoom = useRef(7);
+
+  useSignal(root.windowInput, (event) => {
+    if (event instanceof InputEventMouseMotion && isDragging.current) {
+      yaw.current -= event.relative.x * 0.005;
+      pitch.current = Math.max(-1.4, Math.min(1.4, pitch.current + event.relative.y * 0.005));
+    } else if (event instanceof InputEventMouseButton) {
+      if (event.buttonIndex === MouseButton.MOUSE_BUTTON_LEFT) {
+        isDragging.current = event.pressed;
+      }
+    }
+    event.free();
+  });
+
+  useSignal(tree.processFrame, () => {
+    const camera = cameraRef.current;
+    if (!camera) return;
+
+    const cx = zoom.current * Math.cos(pitch.current) * Math.sin(yaw.current);
+    const cy = zoom.current * Math.sin(pitch.current) + 1;
+    const cz = zoom.current * Math.cos(pitch.current) * Math.cos(yaw.current);
+    camera.position = new Vector3(cx, cy, cz);
+    camera.lookAt(new Vector3(0, 1, 0), new Vector3(0, 1, 0));
+  });
+
+  return (
+    <>
+      <WorldEnvironment>
+        <Environment attach="environment" tonemapMode={ToneMapper.TONE_MAPPER_AGX} backgroundMode={BGMode.BG_COLOR} backgroundColor={[0.05, 0.1, 0.25]} />
+      </WorldEnvironment>
+      <DirectionalLight3D name="Sun" rotation={[-0.8, 0.5, 0]} />
+      <Camera3D name="Camera" ref={cameraRef} />
+
+      {/* Physics Sphere */}
+      <PhysBody name="BouncySphere" position={[0, 4, 0]} color={[0.2, 1, 0.2]}
+        shape={<SphereShape3D attach="shape" radius={0.5} />}>
+        <SphereMesh attach="mesh" radius={0.5} height={1} />
+        <PhysicsMaterial attach="physicsMaterialOverride" bounce={0.8} />
+      </PhysBody>
+
+      {/* Ground Plane */}
+      <StaticBody3D name="Ground">
+        <CollisionShape3D>
+          <BoxShape3D attach="shape" size={[10, 0.1, 10]} />
+        </CollisionShape3D>
+        <MeshInstance3D>
+          <BoxMesh attach="mesh" size-x={10} size-y={0.1} size-z={10} />
+          <StandardMaterial3D attach="materialOverride" albedoColor={[0.2, 0.2, 0.25]} />
+        </MeshInstance3D>
+      </StaticBody3D>
+    </>
+  );
+}
+```
+
+---
 
-## Notes
+## API Summary
 
-- `Node` children are added/moved with `addChild`/`moveChild`/`removeChild`; unmounting a subtree calls `free()` on each deleted instance.
-- Portals and other non-React children of a root container are never touched by the reconciler.
-- See the demo in the repo (`dev/DemoApp.tsx`) for physics, camera controls, and a portal HUD, and `AGENTS.md` for reconciler internals.
+| Export | Type | Description |
+| :--- | :--- | :--- |
+| `createRoot(parent)` | Function | Mounts a React component tree into a target Godot `Node` (e.g. `tree.root`). Returns `{ render, unmount }`. |
+| `createPortal(children, container)` | Function | Renders children into a target Godot `Node` (e.g. `CanvasLayer` or `SubViewport`). |
+| `useSignal(signal, callback)` | Hook | Connects a callback to a Godot object signal (e.g. `tree.processFrame`, `node.treeEntered`). Disconnects on unmount. |
+| `useMutableCallback(fn)` | Hook | Returns a `RefObject` whose `.current` always points to the latest callback implementation. |
+| `ComponentProps<T>` | Type | Utility type to infer valid React JSX props for any Godot node class `T`. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/react-godot",
   "author": "Vladimir Davidovich",
-  "version": "1.0.0-3",
+  "version": "1.0.0-4",
   "description": "A React renderer for Godot Engine via @ringozz/godot",
   "type": "module",
   "main": "./src/index.ts",
@@ -16,11 +16,11 @@
     "*.md"
   ],
   "dependencies": {
+    "@ringozz/godot": "^4.7.1-7",
     "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0"
   },
   "peerDependencies": {
-    "@ringozz/godot": "^4.7.1-6",
     "@types/react": "^19.2.0",
     "react": "^19.2.0"
   }