@ringozz/react-godot 1.0.0-8 → 4.7.2-570

package/README.md

@@ -88,7 +88,7 @@ If you already have a pre-existing Godot `Node`, `Resource`, or `PackedScene` in
 
 - **`object` is immutable on a mounted instance.** It selects the host instance once, at creation. A re-render that changes `object` on an existing element throws (`Cannot change the \`object\` of a mounted instance`) because React cannot swap a fiber's Godot node — remount with a new `key` instead.
 - **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; the web dev server's React Fast Refresh makes it especially likely). Add `key="..."` to each dynamically toggled same-type sibling to keep nodes pinned to the right elements.
+- **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.
 
 ### 2. Resource Nesting with `attach`
 
@@ -117,18 +117,24 @@ In Godot, nodes often hold references to `Resource` objects (such as shapes, mes
 </WorldEnvironment>
 ```
 
-### 2. Properties & Helper Types
+Note for physics bodies: `attach="shape"` goes on the shape **resource** element (e.g. `<BoxShape3D attach="shape" />`), never on the `CollisionShape3D` node itself — `Node.add_child` requires a `Node`, and shapes are `Resource`s, so an `attach` on `CollisionShape3D` adds the shape as a child node and fails. Likewise, mesh children of a physics body must be wrapped in a `MeshInstance3D` (a `RigidBody3D`/`StaticBody3D` has no `mesh`/`materialOverride` props to attach to).
+
+### 3. 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
+- **Packed arrays**: `Packed*Array`-typed props (e.g. `Gradient.colors`/`offsets`) accept plain JS arrays — elements convert with the array's element type, so `colors={[[0.5, 0, 0, 1], [1, 1, 1, 1]]}` works; `new PackedVector2Array([[1, 2], [3, 4]])` works too.
+- **Array-typed props** (`GodotArray`, e.g. `CodeEdit.lineLengthGuidelines`, `Font.fallbacks`) accept plain JS arrays directly — they become a Godot `Array`.
 - **Sub-properties / Dash props**: Set individual vector/color components directly using dash syntax:
   ```tsx
   <BoxMesh attach="mesh" size-x={0.5} size-y={1.0} size-z={0.5} />
   ```
 
-### 3. Engine Signals & Event Subscription (`useSignal`)
+**Text content**: text nodes are unsupported, but string/number children — and arrays of all-string/all-number children — are flattened into the node's `text` prop, so `<Label>Hello</Label>` works. Mixed children (containing elements) throw; use an explicit `text` prop instead, and never pass string children to a node without a `text` prop.
+
+### 4. Engine Signals & Event Subscription (`useSignal`)
 
 Subscribe to Godot engine signals cleanly with `useSignal`.
 
@@ -161,6 +167,8 @@ Signal **JSX props** (`pressed`, `toggled`, `valueChanged`, `textSubmitted`, ...
 <HSlider value={round} valueChanged={(v) => setRound(v)} />
 ```
 
+Signal handlers are connected **before** value props are applied within a commit (`Instance.assign`), so the handler a render installs is already current when a value setter fires its signal (e.g. `Range.value` emits `value_changed`). Note that programmatic value sets still emit (Godot semantics) — if you feed a slider's `value` back from your own state, guard the handler (e.g. compare against the live store) or the emission loops back into your reducer.
+
 `ComponentProps` only exposes writable members: read-only props (e.g. `Node.multiplayer`) and methods are not settable props.
 
 ## Full Example
@@ -275,4 +283,30 @@ export function App() {
 | `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. |
+| `useTween(create, deps)` | Hook | Reactive tween-as-prop-value. Returns `[spring, tweenRef]` — spread `spring` onto a node; `tweenRef.current` is the live native `Tween`. |
 | `ComponentProps<T>` | Type | Utility type to infer valid React JSX props for any Godot node class `T`. |
+
+## Animating props with `useTween`
+
+`useTween` animates a node's properties declaratively. You describe the target values once per `to` key; spreading the returned `spring` onto a node binds the tween to it. Re-rendering with the same `deps` keeps the same tween (nothing restarts); changing `deps` creates a new `Tween` and animates from the current values.
+
+```tsx
+const [spring, tweenRef] = useTween(() => ({
+  from: { position: [0, 0, 0] },
+  to:   { position: [0, 2, 0], globalRotation: [0, 90, 0] },
+  config: { duration: 0.6, transition: TransitionType.TRANS_QUAD, ease: EaseType.EASE_IN_OUT },
+  delay: 0, loops: 1, immediate: false,
+  onFinished: () => {},
+}), [x, z]);
+
+return <Node3D {...spring} />;
+```
+
+- **`spring`** holds one function per `to` key (spread them all onto the node; each contributes its own prop's tweener to the shared `Tween`). Array values are converted to the property's value type.
+- **`tweenRef.current`** is the **live native Godot `Tween`**, created when the node mounts (null before that): `tweenRef.current?.kill()`, `?.pause()`, `?.play()`, `?.setSpeedScale(n)`, `?.isRunning()`, `?.finished`…
+- **`config`** maps to the Godot Tween API: `duration` (seconds), `transition`/`ease` (`TransitionType`/`EaseType` — the tween's defaults), `easing` (a `[0,1]→[0,1]` function → `setCustomInterpolator`), `speedScale`.
+- **`onStart`** fires when the tween is created/bound (on mount or when `deps` change), before it starts stepping.
+- **`onFinished`** fires on natural completion only (Godot's `finished` signal); `kill()`/unmount don't fire it, so no stale callbacks.
+- **Unwrapping**: replacing a springed prop with a plain value (e.g. dropping `{...spring}` for `position={[9, 0, 0]}`) does not stop the running tween — it keeps animating to its target and the tween's value wins over the plain value. Stop it with `tweenRef.current?.kill()`.
+
+

package/package.json

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

package/src/react-fiber.ts

@@ -3,7 +3,7 @@
 ***********************************************************************/
 
 import { ClassDB } from '@ringozz/godot/ClassDB';
-import type { Node } from '@ringozz/godot/Node';
+import { Node } from '@ringozz/godot/Node';
 import { Object as Instance } from '@ringozz/godot/Object';
 import { PackedScene } from '@ringozz/godot/PackedScene';
 import { RefCounted } from '@ringozz/godot/RefCounted';
@@ -178,7 +178,10 @@ export function getInstanceFromScope(scopeInstance: unknown): Instance | null {
 }
 
 export function detachDeletedInstance(node: Instance): void {
-  node.free();
+  if (node instanceof Node)
+    node.queueFree();
+  else
+    node.free();
 }
 
 export function maySuspendCommit(type: Type, props: Props) {

package/src/react-hooks.ts

@@ -3,8 +3,19 @@
 ***********************************************************************/
 
 import type { Signal } from '@ringozz/godot';
+import type { Node } from '@ringozz/godot/Node';
+import type { Object as Instance } from '@ringozz/godot/Object';
+import { PropertyTweener } from '@ringozz/godot/PropertyTweener';
+import type { GodotVar } from '@ringozz/godot/runtime';
+import { Tween, type EaseType, type TransitionType } from '@ringozz/godot/Tween';
 import type React from 'react';
-import { useEffect, useRef } from 'react';
+import { useEffect, useMemo, useRef } from 'react';
+
+// Tween/PropertyTweener are only type-used here; value-reference them so their
+// `_R` class registration isn't tree-shaken (otherwise createTween's wrapper
+// falls back to an ancestor class and loses pause/play/tweenProperty).
+void Tween;
+void PropertyTweener;
 
 export function useMutableCallback<T>(fn: T): React.RefObject<T> {
   const ref = useRef<T>(fn);
@@ -23,3 +34,115 @@ export function useSignal<T extends (...args: any[]) => any>(signal: Signal<T>,
   /* oxlint-disable-next-line react-hooks/exhaustive-deps */
   }, [signal.getObjectId(), signal.getName()]);
 }
+
+// ---- useTween: tween-as-prop-value ----
+//
+// useTween(create, deps) returns [spring, tweenRef]. `spring` holds one
+// value-assigner per `to` key — a plain function spread onto the node
+// (`<Node3D {...spring} />`). Instance.assign (C++) treats any function on a
+// non-signal prop as a value-assigner and invokes it with (node, nativeName);
+// each contributes its own prop's tweener to one shared native Tween created on
+// the first invocation. `tweenRef.current` is that Tween (null until mounted).
+// Re-rendering with the same deps keeps the same assigners (the reconciler's
+// identity diff drops them, so nothing restarts); changing deps creates a new
+// tween (the previous one is killed).
+
+export type TweenValue = number | number[] | GodotVar;
+
+export interface TweenConfig {
+  /** Seconds (default 1). */
+  duration?: number;
+  /** Tween.setTrans — the default for the tween's tweeners. */
+  transition?: TransitionType;
+  /** Tween.setEase — the default for the tween's tweeners. */
+  ease?: EaseType;
+  /** PropertyTweener.setCustomInterpolator — a [0,1]→[0,1] easing function. */
+  easing?: (t: number) => number;
+  /** Tween.setSpeedScale. */
+  speedScale?: number;
+}
+
+export interface TweenProps<T extends Record<string, TweenValue> = Record<string, TweenValue>> {
+  /** Start values, applied on the first build (mount) before animating to `to`. */
+  from?: Partial<T>;
+  /** Target values — one assigner is returned per key. */
+  to: T;
+  config?: TweenConfig;
+  /** Seconds; per-tweener PropertyTweener.setDelay. */
+  delay?: number;
+  /** Tween.setLoops (0 = infinite). */
+  loops?: number;
+  /** Snap to `to` instead of animating. */
+  immediate?: boolean;
+  onStart?: () => void;
+  /** Fires on natural completion only (Godot's `finished`); kills/unmount don't fire it. */
+  onFinished?: () => void;
+}
+
+export type Spring<T extends Record<string, TweenValue>> = { [K in keyof T]: T[K] };
+
+// tweenProperty/set reject JS arrays, so array goals are reconstructed as the
+// property's value type (read via get(native).constructor).
+function toValueType(node: Instance, native: string, value: TweenValue): unknown {
+  if (!Array.isArray(value)) return value;
+  const Ctor = (node.get(native) as any)?.constructor;
+  if (typeof Ctor === 'function') return new Ctor(...value);
+  return value;
+}
+
+function makeSpring<T extends Record<string, TweenValue>>(
+  tweenRef: { current: Tween | null },
+  props: TweenProps<T>,
+): Spring<T> {
+  const config = props.config ?? {};
+  const spring = {} as Spring<T>;
+  let started = false;
+  let applyFrom = false;
+
+  for (const [key, value] of Object.entries(props.to)) {
+    const fromValue = props.from?.[key];
+    const assigner = (node: Instance, native: string) => {
+      if (props.immediate) {
+        tweenRef.current?.kill();
+        tweenRef.current = null;
+        node.set(native, toValueType(node, native, value));
+        return;
+      }
+      if (!started) {
+        started = true;
+        applyFrom = tweenRef.current === null; // first build (mount) ⇒ apply `from`
+        tweenRef.current?.kill();
+        const t = (node as unknown as Node).createTween();
+        tweenRef.current = t;
+        if (config.transition !== undefined) t.setTrans(config.transition);
+        if (config.ease !== undefined) t.setEase(config.ease);
+        if (config.speedScale !== undefined) t.setSpeedScale(config.speedScale);
+        if (props.loops !== undefined) t.setLoops(props.loops);
+        if (props.onFinished) t.finished.connect(props.onFinished);
+        t.bindNode(node as unknown as Node);
+        t.setParallel(true);
+        props.onStart?.();
+      }
+      const tw = tweenRef.current!.tweenProperty(node, native, toValueType(node, native, value), config.duration ?? 1);
+      if (applyFrom && fromValue !== undefined) tw.from(toValueType(node, native, fromValue));
+      if (props.delay !== undefined) tw.setDelay(props.delay);
+      if (config.easing) tw.setCustomInterpolator(config.easing);
+    };
+    spring[key as keyof T] = assigner as unknown as T[keyof T];
+  }
+  return spring;
+}
+
+export function useTween<T extends Record<string, TweenValue>>(
+  create: () => TweenProps<T>,
+  deps: unknown[] = [],
+): [Spring<T>, React.RefObject<Tween | null>] {
+  const tweenRef = useRef<Tween | null>(null);
+  // 'create' is intentionally re-evaluated via `deps`, not listed here.
+  /* oxlint-disable-next-line react-hooks/exhaustive-deps */
+  const spring = useMemo(() => makeSpring(tweenRef, create()), deps);
+  // No unmount kill: the tween is `createTween()`-bound to the node, so Godot
+  // kills it when the node exits the tree. A `useEffect` cleanup would also run
+  // on StrictMode's synthetic mount teardown and kill the just-created tween.
+  return [spring, tweenRef];
+}