@ringozz/react-godot 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,94 @@
+# @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.
+
+## Installation
+
+```sh
+bun add @ringozz/react-godot @ringozz/godot react
+```
+
+`@ringozz/godot` and `react` (`^19.2`) are peer dependencies. Configure the JSX runtime in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@ringozz/react-godot"
+  }
+}
+```
+
+## 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`).
+
+## Example
+
+```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';
+
+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 a component
+
+```tsx
+function App() {
+  return (
+    <WorldEnvironment>
+      <Environment attach="environment" backgroundColor={[0.05, 0.1, 0.25]} />
+    </WorldEnvironment>
+  );
+}
+```
+
+## How elements map to Godot
+
+- 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:
+
+  ```tsx
+  <StaticBody3D>
+    <CollisionShape3D>
+      <BoxShape3D attach="shape" size={[1, 1, 1]} />
+    </CollisionShape3D>
+    <MeshInstance3D>
+      <BoxMesh attach="mesh" />
+      <StandardMaterial3D attach="materialOverride" />
+    </MeshInstance3D>
+  </StaticBody3D>
+  ```
+
+  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.
+
+## Notes
+
+- `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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/react-godot",
   "author": "Vladimir Davidovich",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React reconciler bindings for Godot Engine via @ringozz/godot",
   "type": "module",
   "main": "./src/index.ts",
@@ -12,7 +12,8 @@
     "./jsx-dev-runtime": "./src/react-jsx.ts"
   },
   "files": [
-    "src/"
+    "src/",
+    "*.md"
   ],
   "dependencies": {
     "react-reconciler": "^0.33.0"