@ringozz/react-godot 4.7.2-604 → 4.7.2-614

package/README.md

@@ -90,6 +90,19 @@ If you already have a pre-existing Godot `Node`, `Resource`, or `PackedScene` in
 - **A `PackedScene` `object` is instantiated once per host mount** — each element gets a fresh node tree; the result is a plain `Node` (not `.reference()`'d) freed on unmount. The same `PackedScene` can feed multiple elements; give same-type siblings stable `key`s.
 - **Dynamic same-type sibling lists need stable `key`s.** Godot host nodes are identity, not content: React reconciles keyless siblings by position, so deleting the *first* of two same-type siblings reuses its Godot node for the survivor. A plain state re-render does this too, and Bun's web dev server makes it especially likely — its React Fast Refresh re-renders the edited component **in place** (no app re-run), reusing the same fibers and Godot nodes, so a deleted sibling's node can survive on its neighbor and the neighbor's node is freed. Add `key="..."` to each dynamically toggled same-type sibling to keep nodes pinned to the right elements.
 
+### 1b. Attaching a Script with `script`
+
+Use the `script` prop to attach a `Script` resource (e.g. an imported GDScript `.gd` module) to a node on creation. The script is attached **before the node enters the tree**, so Godot fires `_ready` and auto-enables the script's `_process`/`_input` — no manual `set_process(true)`/`set_process_input(true)` calls needed:
+
+```tsx
+import controller from './camera_controller.gd';
+
+<Camera3D script={use(controller)} current={true} fov={55} />
+```
+
+- **Attach before tree entry means `_ready`/`_process`/`_input` work.** Attaching to an already-in-tree node (e.g. in a `useEffect`) never fires `_ready` and leaves `_process`/`_input` disabled — prefer `script` over an effect for scripted nodes.
+- **`script` is immutable on a mounted instance.** A re-render that changes `script` on an existing element throws — remount with a new `key` to swap the compiled script.
+
 ### 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:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/react-godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-604",
+  "version": "4.7.2-614",
   "description": "A React renderer for Godot Engine via @ringozz/godot",
   "publishConfig": {
     "access": "public"
@@ -23,7 +23,7 @@
     "*.md"
   ],
   "dependencies": {
-    "@ringozz/godot": "^4.7.2-604",
+    "@ringozz/godot": "^4.7.2-614",
     "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0"
   },

package/src/react-fiber.ts

@@ -33,7 +33,7 @@ const EMPTY = Object.freeze({});
 const attachments = new WeakMap<Instance, string>();
 
 export function createInstance<T extends Instance>(type: Type, props: Props, root: Container, hostContext: HostContext, internalHandle: Reconciler.OpaqueHandle): T {
-  let { attach, object, ...rest } = props;
+  let { attach, object, script, ...rest } = props;
   if (object instanceof PackedScene)
     object = object.instantiate();
   else if (object instanceof RefCounted)
@@ -43,6 +43,9 @@ export function createInstance<T extends Instance>(type: Type, props: Props, roo
   if (attach)
     attachments.set(instance, attach);
 
+  if (script)
+    instance.setScript(script);
+
   commitUpdate(instance, type, EMPTY, rest, internalHandle);
   return instance;
 }
@@ -271,12 +274,14 @@ function isEqual(a: unknown, b: unknown) {
 }
 
 export function commitUpdate(instance: Instance, type: Type, prevProps: Props, nextProps: Props, internalHandle: Reconciler.OpaqueHandle): void {
-  const { attach: attachOld, object: objectOld, ref: refOld, children: childrenOld, ...restOld } = prevProps;
-  const { attach: attachNew, object: objectNew, ref: refNew, children: childrenNew, ...restNew } = nextProps;
+  const { attach: attachOld, object: objectOld, script: scriptOld, ref: refOld, children: childrenOld, ...restOld } = prevProps;
+  const { attach: attachNew, object: objectNew, script: scriptNew, ref: refNew, children: childrenNew, ...restNew } = nextProps;
   if (attachOld !== attachNew)
     throw new Error(`Cannot change attachment ${attachOld} to ${attachNew}`);
   if (objectOld !== objectNew)
     throw new Error(`Cannot change the \`object\` of a mounted instance (${objectOld} -> ${objectNew}); remount with a new key`);
+  if (scriptOld !== scriptNew)
+    throw new Error(`Cannot change the \`script\` of a mounted instance (${scriptOld} -> ${scriptNew}); remount with a new key`);
 
   const toText = (c: unknown) => Array.isArray(c) ? c.join('') : c as string;
   if (shouldSetTextContent(type, prevProps)) restOld['text'] = toText(childrenOld);

package/src/react-types.ts

@@ -6,6 +6,7 @@ import type React from 'react';
 import type { Object } from '@ringozz/godot/Object';
 import type { Signal, GodotDictionary } from '@ringozz/godot';
 import type { PackedScene } from '@ringozz/godot/PackedScene';
+import type { Script } from '@ringozz/godot/Script';
 
 // Identity check sensitive to readonly (deferred-conditional trick; the
 // comparison lives in return-type position, so it is independent of
@@ -24,6 +25,14 @@ export type InstanceProps<T extends Instance = Instance> = {
   object?: T | PackedScene;
   /** Attaches the element to a named property of the parent instead of adding it as a child. */
   attach?: string;
+  /** Attaches a Script (e.g. a GDScript) to the instance on creation, via
+   * `Object.setScript` *before* the node enters the tree. Attaching pre-tree —
+   * as opposed to in a mount effect on an already-in-tree node — lets Godot's
+   * NOTIFICATION_READY auto-enable the script's `_process`/`_input` (an
+   * already-in-tree node never fires `_ready`, so those callbacks stay
+   * disabled and must be enabled manually). Script is a method-only member of
+   * `Object` (not a settable property), so it gets dedicated handling here. */
+  script?: Script;
 };
 
 type ReactProps<P> = React.PropsWithChildren<React.RefAttributes<P>>;