@ringozz/react-godot 4.7.2-583 → 4.7.2-592

package/README.md

@@ -123,9 +123,9 @@ Note for physics bodies: `attach="shape"` goes on the shape **resource** element
 
 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.
+- **Vectors / value types**: value types are **named tuples** — flat (`Vector3`, `Color`, `Rect2`, …) are scalar-labeled tuples (`Vector3 = [x, y, z]`, `Color = [r, g, b, a?]`); nested (`AABB`/`Transform2D`/`Basis`/`Transform3D`/`Projection`) are row-labeled tuples of the flat element alias (`Transform3D = [x, y, z, origin]`, each row a `Vector3`), so `position={[0, 1, 0]}`, `transform={[[1, 0, 0], [0, 1, 0], [0, 0, 1], [10, 20, 30]]}`. Getters return the same labeled shape (`node.position` is `[x, y, z]`); direct setters accept them too (`node.position = [1, 2, 3]`). **Wrong-arity arrays fail typecheck** (`position={[1, 2]}` errors) — except `Color`'s trailing `a`, which is optional (`[r, g, b, a?]`, alpha defaults 1; it's the only value type with a partial scalar ctor). The math API lives as named functions per type module — `import * as v3 from '@ringozz/godot/Vector3'`, then `v3.normalized(v)`, `v3.dot(a, b)`; construction uses `fromXxx` factories (`basis.fromAxisAngle(axis, angle)`, `transform3d.fromBasisOrigin(basis, origin)`).
+- **Colors**: `albedoColor={[1, 0.2, 0.2]}` (a `Color` is just `[r, g, b, a?]`).
+- **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. The same element-aware conversion applies to **direct setters and method args**: `gradient.colors = [[1, 0, 0, 1], [0, 1, 0, 1]]`, `addPoint(0.5, [1, 0, 0, 1])`, and `PhysicsRayQueryParameters3D.create([1, 2, 3], [4, 5, 6])` all accept tuples.
 - **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
@@ -176,7 +176,8 @@ Signal handlers are connected **before** value props are applied within a commit
 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 { Engine, Key, MouseButton } from '@ringozz/godot';
+import type { Color } from '@ringozz/godot';
 import { BoxMesh } from '@ringozz/godot/BoxMesh';
 import { BoxShape3D } from '@ringozz/godot/BoxShape3D';
 import { Camera3D } from '@ringozz/godot/Camera3D';
@@ -201,7 +202,7 @@ const tree = Engine.getMainLoop() as SceneTree;
 const root = tree.root;
 
 function PhysBody({ color, shape, children, ...rest }: {
-  color: Color | number[];
+  color: Color;
   shape: ReactElement;
 } & ComponentProps<typeof RigidBody3D>) {
   return (
@@ -224,8 +225,8 @@ export function App() {
 
   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));
+      yaw.current -= event.relative[0] * 0.005;
+      pitch.current = Math.max(-1.4, Math.min(1.4, pitch.current + event.relative[1] * 0.005));
     } else if (event instanceof InputEventMouseButton) {
       if (event.buttonIndex === MouseButton.MOUSE_BUTTON_LEFT) {
         isDragging.current = event.pressed;
@@ -241,8 +242,8 @@ export function App() {
     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));
+    camera.position = [cx, cy, cz];
+    camera.lookAt([0, 1, 0], [0, 1, 0]);
   });
 
   return (
@@ -283,7 +284,7 @@ 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`. |
+| `useTween<NodeT>(create, deps)` | Hook | Reactive tween-as-prop-value. Returns `[spring, tweenRef]` — spread `spring` onto a node; `tweenRef.current` is the live native `Tween`. The optional node type (`useTween<Node3D>`) types `to`/`from` array goals as that node's value-type tuples. |
 | `ComponentProps<T>` | Type | Utility type to infer valid React JSX props for any Godot node class `T`. |
 
 ## Animating props with `useTween`
@@ -291,9 +292,9 @@ export function App() {
 `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] },
+const [spring, tweenRef] = useTween<Node3D>(() => ({
+  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: () => {},
@@ -302,7 +303,8 @@ const [spring, tweenRef] = useTween(() => ({
 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.
+- **`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.
+- **Node-typed goals**: call `useTween<Node3D>(...)` so `to`/`from` are typed against that node's props — `position: [0, 2, 0]` and nested `basis: [[…]]` infer as `Vector3`/`Basis`, with no `as Vector3` casts. A bare `useTween(...)` keeps array goals loose (`number[]`).
 - **`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.

package/package.json

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

package/src/react-hooks.ts

@@ -6,10 +6,10 @@ 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, useMemo, useRef } from 'react';
+import { toValueType, type GodotVar } from '@ringozz/godot/runtime';
 
 // Tween/PropertyTweener are only type-used here; value-reference them so their
 // `_R` class registration isn't tree-shaken (otherwise createTween's wrapper
@@ -47,7 +47,21 @@ export function useSignal<T extends (...args: any[]) => any>(signal: Signal<T>,
 // identity diff drops them, so nothing restarts); changing deps creates a new
 // tween (the previous one is killed).
 
-export type TweenValue = number | number[] | GodotVar;
+// Value-type goals are named tuples on the JS side — flat ones are `number[]`,
+// nested ones (Transform2D/Basis/Transform3D/Projection/AABB) are `number[][]`.
+//
+// When the caller passes a node instance type (e.g. `useTween<Node3D>`), `to`
+// /`from` are contextually typed against that node's settable props, so each
+// array goal infers as the property's value-type tuple (Vector3, Basis, …). A
+// bare `useTween(...)` call keeps the loose behavior below (`number[]` goals).
+export type TweenValue = number | number[] | number[][] | GodotVar;
+
+// Settable props whose value is tween-compatible (numeric, value-type tuples,
+// GodotVar); excludes bool/string/signal/container/method props. Mapping over
+// `keyof N` lets `to` be contextually typed with the node's value-type tuples.
+type TweenableProps<T> = {
+  [K in keyof T as T[K] extends TweenValue ? K : never]: T[K];
+};
 
 export interface TweenConfig {
   /** Seconds (default 1). */
@@ -62,11 +76,11 @@ export interface TweenConfig {
   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;
+export interface TweenProps<P extends Record<string, unknown> = Record<string, TweenValue>> {
+  /** Start values, applied on the first build (mount) before animating to `to`. */
+  from?: Partial<P>;
+  /** Target values — one assigner is returned per key. */
+  to: P;
   config?: TweenConfig;
   /** Seconds; per-tweener PropertyTweener.setDelay. */
   delay?: number;
@@ -79,23 +93,19 @@ export interface TweenProps<T extends Record<string, TweenValue> = Record<string
   onFinished?: () => void;
 }
 
-export type Spring<T extends Record<string, TweenValue>> = { [K in keyof T]: T[K] };
+export type Spring<P extends Record<string, unknown>> = { [K in keyof P]: P[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;
-}
+// tweenProperty/set reject generic JS arrays, so array goals are reconstructed
+// as the property's value type by `toValueType` (resolves the node's
+// property type and returns a GodotVar carrier the `_C` tween path unwraps;
+// non-array goals pass through unchanged).
 
-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>;
+function makeSpring<P extends Record<string, unknown>>(
+  tweenRef: { current: Tween | null },
+  props: TweenProps<P>,
+): Spring<P> {
+  const config = props.config ?? {};
+  const spring = {} as Spring<P>;
   let started = false;
   let applyFrom = false;
 
@@ -128,15 +138,18 @@ function makeSpring<T extends Record<string, TweenValue>>(
       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>] {
+    spring[key as keyof P] = assigner as unknown as P[keyof P];
+  }
+  return spring;
+}
+
+export function useTween<
+  T extends Instance = any,
+  P extends Partial<TweenableProps<T>> = Partial<TweenableProps<T>>,
+>(
+  create: () => TweenProps<P>,
+  deps: unknown[] = [],
+): [Spring<P>, 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 */

package/src/react-types.ts

@@ -4,7 +4,7 @@
 
 import type React from 'react';
 import type { Object } from '@ringozz/godot/Object';
-import type { Signal, ValueTypes, GodotDictionary } from '@ringozz/godot';
+import type { Signal, GodotDictionary } from '@ringozz/godot';
 import type { PackedScene } from '@ringozz/godot/PackedScene';
 
 // Identity check sensitive to readonly (deferred-conditional trick; the
@@ -39,29 +39,27 @@ type SettableKey<T, K extends keyof T> =
 
 // Container props accept plain JS forms: JSX values flow through
 // `Instance.assign` (`napi_to_variant_typed`), which builds packed arrays,
-// Godot `Array`s, and `Dictionary`s from JS arrays/objects. Only gen heap
-// containers (10 packed + `GodotArray` + `GodotDictionary`) implement
-// `Iterable`, so that is the gate; `get(index: number)` recovers the concrete
-// element type (packed class getters return it even though the class generic
-// defaults to `any`). Scalar-packed -> `number[]`/`string[]`; element-packed
-// -> `(E | number[])[]` (instances or value-type tuples); `GodotArray<E>` ->
-// `(E | number[])[]`; `GodotDictionary<K,V>` -> `Record<string, V>`.
+// Godot `Array`s, and `Dictionary`s from JS arrays/objects. Every gen heap
+// container implements `Iterable` and has `get(index: number)`; `get` recovers
+// the concrete element type (packed class getters return it even though the
+// class generic defaults to `any`), and `GodotDictionary` routes to
+// `Record<string, V>` first. Scalar-packed -> `number[]`/`string[]`;
+// element-packed -> `(E | number[])[]` (instances or value-type tuples);
+// `GodotArray<E>` -> `(E | number[])[]`; `GodotDictionary<K,V>` ->
+// `Record<string, V>`.
 type ContainerForm<T> =
     T extends GodotDictionary<any, infer V> ? Record<string, V>
     : T extends { get(index: number): infer E } ? (E extends number | string ? E[] : (E | number[])[])
-    : T extends Iterable<infer E> ? E[]
     : never;
 
 // JSX props are settable instance members, typed as the reconciler's
-// `Instance.assign` accepts them: ValueTypes also accept JSX arrays, signals
-// (getter `Signal<CB>`, setter `CB | null`) take the callback directly, and
-// containers accept plain JS arrays/objects. Maps over `keyof T`
-// (homomorphic) so optional/readonly modifiers survive.
+// `Instance.assign` accepts them: value types are plain tuples (the getter
+// type IS the array form), signals (getter `Signal<CB>`, setter `CB | null`)
+// take the callback directly, and containers accept plain JS arrays/objects.
+// Maps over `keyof T` (homomorphic) so optional/readonly modifiers survive.
 type Properties<T> = {
     [K in keyof T as SettableKey<T, K>]:
-        T[K] extends ValueTypes ? T[K] | number[]
-        : T[K] extends Signal<infer CB> ? CB | null
-        : T[K] extends GodotDictionary<any, any> ? T[K] | ContainerForm<T[K]>
+        T[K] extends Signal<infer CB> ? CB | null
         : T[K] extends Iterable<unknown> ? T[K] | ContainerForm<T[K]>
         : T[K];
 };