@ringozz/godot 4.7.1-4 → 4.7.1-555

package/src/debug.ts

@@ -2,88 +2,134 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-import { Rect2, Vector3 } from './index.ts';
+import { MouseButton, Rect2, str, varToStr, Vector2, Vector3 } from './index.ts';
 import { CanvasItem } from '../gen/classes/CanvasItem.ts';
 import { ClassDB } from '../gen/classes/ClassDB.ts';
 import { Control } from '../gen/classes/Control.ts';
 import { DisplayServer } from '../gen/classes/DisplayServer.ts';
 import { Engine } from '../gen/classes/Engine.ts';
+import { InputEventMouseButton } from '../gen/classes/InputEventMouseButton.ts';
 import { Node } from '../gen/classes/Node.ts';
 import { Node3D } from '../gen/classes/Node3D.ts';
 import { OS } from '../gen/classes/OS.ts';
+import { SceneTree } from '../gen/classes/SceneTree.ts';
 import { Time } from '../gen/classes/Time.ts';
+import type { Window } from '../gen/classes/Window.ts';
+
+const tree = Engine.getMainLoop() as SceneTree;
 
 /**
- * Dump a Godot object's properties as an indented string.
- * Uses `getPropertyList()` + `get()` to safely introspect — never invokes JS getters.
+ * Dump a Godot value or object as a string.
+ * Value types (vectors, arrays, dictionaries, …) render via Godot's `str()`.
+ * Objects dump via Godot's `var_to_str` — its own property walk + recursion —
+ * with the node's `name` prepended when present.
  *
- * @param obj - Any Godot wrapper (Node, Resource, etc.) or plain value
- * @param depth - Max recursion depth into sub-objects (default 2)
- * @param maxProps - Max properties to show per object (default 30)
+ * @param obj - Any Godot wrapper (Node, Resource, …), value type, or plain value
  */
-export function dumpStr(obj: unknown, depth = 2, maxProps = 30): string {
-  if (obj == null || typeof obj !== 'object') return String(obj);
-  let cls: string;
-  try { cls = (obj as any).getClass?.(); } catch { cls = (obj as any).constructor?.name ?? typeof obj; }
-  if (!cls) return String(obj);
-  const lines = [`[${cls}]`];
-  let count = 0;
-  try {
-    const plist = (obj as any).getPropertyList?.();
-    if (plist?.size) {
-      for (let i = 0; i < plist.size() && count < maxProps; i++) {
-        const name = plist.get(i).get('name');
-        if (!name || (name + '').startsWith('_')) continue;
-        let val: unknown;
-        try { val = (obj as any).get(name); } catch { val = '<err>'; }
-        if (typeof val === 'object' && val !== null && depth > 1)
-          lines.push(`  ${name}:\n${indent(dumpStr(val, depth - 1, maxProps), '    ')}`);
-        else
-          lines.push(`  ${name}: ${String(val)}`);
-        count++;
-      }
-    }
-  } catch { /* not a GodotVar */ }
-  return lines.join('\n');
-}
+export function dumpStr(obj: unknown): string {
+    if (obj == null || typeof obj !== 'object') return String(obj);
+
+    // Value types & heap containers (Vector3, Array, Dictionary, …) have no getClass() —
+    // let Godot's str() render them.
+    if (!(obj as any).getClass) return str(obj as any);
 
-function indent(s: string, prefix: string): string { return s.split('\n').join('\n' + prefix); }
+    const dump = varToStr(obj as any);
+    let name: unknown;
+    try { name = (obj as any).name; } catch { name = undefined; }
+    return name === undefined || name === null || name === '' ? dump : `${name}: ${dump}`;
+}
 
 /**
- * Serialize a scene subtree as a tree-formatted string.
+ * Serialize a scene subtree as a tree-formatted string, optionally filtered.
+ *
+ * Emits one line per node: `Class "name" (N children)`. When `pattern` is a
+ * string, only lines containing it (case-insensitive) are kept; a `RegExp`
+ * matches against the full line.
  *
- * @param node - Root node to start from
+ * @param pattern - Optional substring or `RegExp` to filter the lines
+ * @param node - Root node to start from (defaults to the scene tree's root Window)
  * @param depth - Max depth (default 99)
  */
-export function dumpTreeStr(node: Node, depth = 99): string {
-  const lines: string[] = [];
-  (function walk(n: Node, d: number, ind: string) {
-    if (d <= 0) return;
-    lines.push(`${ind}${n.getClass()} "${n.name}" (${n.getChildCount()} children)`);
-    for (let i = 0; i < n.getChildCount(); i++) {
-      const c = n.getChild(i);
-      if (c) walk(c as Node, d - 1, ind + '  ');
-    }
-  })(node, depth, '');
-  return lines.join('\n');
+export function snapshot(pattern?: string | RegExp, node?: Node, depth = 99): string {
+    const root = node ?? tree.root;
+    const lines: string[] = [];
+    (function walk(n: Node, d: number, ind: string) {
+        if (d <= 0) return;
+        const count = n.getChildCount();
+        const line = `${ind}${n.getClass()} "${n.name}" (${count} children)`;
+        const keep = !pattern || (pattern instanceof RegExp ? pattern.test(line) : line.toLowerCase().includes(pattern.toLowerCase()));
+        if (keep) lines.push(line);
+        for (let i = 0; i < count; i++) {
+            const c = n.getChild(i);
+            if (c) walk(c as Node, d - 1, ind + '  ');
+        }
+    })(root, depth, '');
+    return lines.join('\n');
+}
+
+/**
+ * Resolve a node from the scene root by absolute NodePath (`/root/...`) or
+ * name glob (`findChild`). Returns `null` when not found.
+ */
+function resolveNode(path: string, root: Window): Node | null {
+    if (path.startsWith('/')) return root.getNode(path);
+    return root.findChild(path, true, false);
+}
+
+/**
+ * Resolve a node by path (absolute NodePath or name glob) from the scene root
+ * and dump it via {@link dumpStr}.
+ *
+ * @param path - An absolute NodePath like `/root/Box`, or a `findChild` name/glob pattern
+ */
+export function inspect(path: string): string | null {
+    const node = resolveNode(path, tree.root);
+    return node ? dumpStr(node) : null;
 }
 
 /**
- * Return a snapshot of engine runtime stats as a formatted string.
+ * Synthesize a left-click at the center of a {@link Control} matched by `path`.
  *
- * Includes process frames, FPS, physics frames, node count, time scale,
- * and main-loop class.
+ * Press and release are pushed through `Window.pushInput` (the GUI-routing
+ * path — `Input.parseInputEvent` doesn't reliably reach `Control.guiInput` on
+ * the wasm build). Positions are in device space (logical × `contentScaleFactor`).
+ *
+ * @param path - An absolute NodePath like `/root/...`, or a `findChild` name/glob pattern
+ * @returns The node's `dumpStr`, or `null` if not found or not a `Control`
  */
-export function statsStr(): string {
-  const tree = Engine.getMainLoop() as any;
-  return [
-    `Frames:     ${Engine.getProcessFrames()}`,
-    `FPS:        ${Engine.getFramesPerSecond()}`,
-    `Physics:    ${Engine.getPhysicsFrames()}`,
-    `Nodes:      ${tree.getNodeCount()}`,
-    `Time scale: ${Engine.timeScale}`,
-    `Main loop:  ${Engine.getMainLoop().getClass()}`,
-  ].join('\n');
+export function click(path: string): string | null {
+    const root = tree.root;
+    const node = resolveNode(path, root);
+    if (!(node instanceof Control)) return null;
+    const rect = node.getGlobalRect();
+    const scale = root!.contentScaleFactor;
+    const position = new Vector2(
+        (rect.position.x + rect.size.x / 2) * scale,
+        (rect.position.y + rect.size.y / 2) * scale,
+    );
+    const press = (down: boolean) => {
+        const event = new InputEventMouseButton();
+        event.position = position;
+        event.globalPosition = position;
+        event.buttonIndex = MouseButton.MOUSE_BUTTON_LEFT;
+        event.pressed = down;
+        root!.pushInput(event);
+    };
+    press(true);
+    setTimeout(() => press(false), 50);
+    return dumpStr(node);
+}
+
+/**
+ * Enumerate nodes in the scene by name pattern and/or class, in tree order.
+ *
+ * @param pattern - Name glob matched by `findChildren` (default `"*"`)
+ * @param type - Class name to filter by, e.g. `"RigidBody3D"` (default `""` = any)
+ * @param node - Root node to search under (defaults to the scene tree's root Window)
+ */
+export function find(pattern = '*', type = '', node?: Node): Node[] {
+    const root = node ?? tree.root;
+    return [...root.findChildren(pattern, type, true, false)];
 }
 
 /**
@@ -91,16 +137,43 @@ export function statsStr(): string {
  * Requires the `--expose-gc` Node.js flag.
  */
 export function gc(): string {
-  const before = process.memoryUsage().heapUsed;
-  if ((globalThis as any).Bun)
-    (globalThis as any).Bun.gc(true);
-  else if (globalThis.gc)
-    globalThis.gc({ type: 'major', execution: 'sync' });
-  else
-    return 'gc() unavailable — need --expose-gc';
-
-  const after = process.memoryUsage().heapUsed;
-  return `GC: freed ${((before - after) / 1024).toFixed(0)} KB`;
+    const before = globalThis.process?.memoryUsage?.().heapUsed;
+    if (globalThis.Bun)
+        globalThis.Bun.gc(true);
+    else if (globalThis.gc)
+        globalThis.gc({ type: 'major', execution: 'sync' });
+    else
+        return 'gc() unavailable — need --expose-gc';
+
+    const after = globalThis.process?.memoryUsage?.().heapUsed;
+    const freed = typeof before === 'number' && typeof after === 'number' ? (before - after) / 1024 : 0;
+    return `GC: freed ${freed.toFixed(0)} KB`;
+}
+
+/**
+ * `DOMRect` is not a global in Bun (desktop), but `getBoundingClientRect()`
+ * constructs one. Install a minimal spec-compatible polyfill on desktop so the
+ * helper works identically on desktop and web (browsers already define it).
+ */
+function ensureDOMRect(): void {
+    if (typeof (globalThis as any).DOMRect !== 'undefined') return;
+    (globalThis as any).DOMRect = class DOMRect {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        constructor(x = 0, y = 0, width = 0, height = 0) {
+            this.x = x;
+            this.y = y;
+            this.width = width;
+            this.height = height;
+        }
+        get left() { return this.x; }
+        get top() { return this.y; }
+        get right() { return this.x + this.width; }
+        get bottom() { return this.y + this.height; }
+        toJSON() { return { x: this.x, y: this.y, width: this.width, height: this.height }; }
+    };
 }
 
 /**
@@ -111,109 +184,115 @@ export function gc(): string {
  *   breakpoints in any module.
  * - Registers an `uncaughtException` handler that logs but keeps the process
  *   alive for interactive debugging.
+ * - Polyfills `DOMRect` (needed by `getBoundingClientRect()` on desktop).
  */
 export function initDebug(): void {
-  globalThis.process?.on('uncaughtException', (err, origin) => {
-    console.error(`\n✗ ${origin}:`, err.stack);
-  });
-
-  Object.defineProperty(CanvasItem.prototype, 'getBoundingClientRect', {
-    configurable: true,
-    value(this: CanvasItem): DOMRect | null {
-      const scale = DisplayServer.screenGetScale();
-      if (this instanceof Control) {
-        const rc = (this as Control).getGlobalRect();
-        return new DOMRect(
-          rc.position.x / scale, rc.position.y / scale,
-          rc.size.x / scale, rc.size.y / scale,
-        );
-      }
-
-      if (typeof (this as any).getRect !== 'function') return null;
-
-      const rect = (this as any).getRect() as Rect2;
-      const t = this.getScreenTransform();
-
-      const pos = rect.position;
-      const sz = rect.size;
-      const tx = t.x;
-      const ty = t.y;
-      const to = t.origin;
-
-      const x0 = pos.x, y0 = pos.y;
-      const x1 = x0 + sz.x, y1 = y0 + sz.y;
-      const txx = tx.x, txy = tx.y;
-      const tyx = ty.x, tyy = ty.y;
-      const tox = to.x, toy = to.y;
-
-      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-      const accum = (px: number, py: number) => {
-        if (px < minX) minX = px; if (py < minY) minY = py;
-        if (px > maxX) maxX = px; if (py > maxY) maxY = py;
-      };
-
-      accum(txx * x0 + tyx * y0 + tox, txy * x0 + tyy * y0 + toy);
-      accum(txx * x1 + tyx * y0 + tox, txy * x1 + tyy * y0 + toy);
-      accum(txx * x0 + tyx * y1 + tox, txy * x0 + tyy * y1 + toy);
-      accum(txx * x1 + tyx * y1 + tox, txy * x1 + tyy * y1 + toy);
-
-      return new DOMRect(
-        minX / scale, minY / scale,
-        (maxX - minX) / scale, (maxY - minY) / scale,
-      );
-    },
-  });
-
-  Object.defineProperty(Node3D.prototype, 'getBoundingClientRect', {
-    configurable: true,
-    value(this: Node3D): DOMRect | null {
-      if (typeof (this as any).getAabb !== 'function') return null;
-
-      const aabb = (this as any).getAabb();
-      const gt = this.globalTransform;
-      const viewport = this.getViewport();
-      if (!viewport) return null;
-      const camera = viewport.getCamera3d();
-      if (!camera) return null;
-      const scale = DisplayServer.screenGetScale();
-
-      const b = gt.basis;
-      const bx = b.x, by = b.y, bz = b.z;
-      const o = gt.origin;
-      const p = aabb.position, e = aabb.end;
-
-      const [px, py, pz] = [p.x, p.y, p.z];
-      const [ex, ey, ez] = [e.x, e.y, e.z];
-      const [bxx, bxy, bxz] = [bx.x, bx.y, bx.z];
-      const [byx, byy, byz] = [by.x, by.y, by.z];
-      const [bzx, bzy, bzz] = [bz.x, bz.y, bz.z];
-      const [ox, oy, oz] = [o.x, o.y, o.z];
-
-      const corners = [
-        [px, py, pz], [ex, py, pz], [px, ey, pz], [ex, ey, pz],
-        [px, py, ez], [ex, py, ez], [px, ey, ez], [ex, ey, ez],
-      ];
-
-      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-
-      for (const [cx, cy, cz] of corners) {
-        const wx = bxx * cx + byx * cy + bzx * cz + ox;
-        const wy = bxy * cx + byy * cy + bzy * cz + oy;
-        const wz = bxz * cx + byz * cy + bzz * cz + oz;
-        const s = camera.unprojectPosition(new Vector3(wx, wy, wz));
-        if (s.x < minX) minX = s.x; if (s.y < minY) minY = s.y;
-        if (s.x > maxX) maxX = s.x; if (s.y > maxY) maxY = s.y;
-      }
-
-      return new DOMRect(
-        minX / scale, minY / scale,
-        (maxX - minX) / scale, (maxY - minY) / scale,
-      );
-    },
-  });
-
-  (globalThis as any).$ = {
-    Engine, OS, ClassDB, Time,
-    dumpStr, dumpTreeStr, statsStr, gc,
-  };
+    globalThis.process?.on?.('uncaughtException', (err, origin) => {
+        console.error(`\n✗ ${origin}:`, err.stack);
+    });
+
+    ensureDOMRect();
+
+    Object.defineProperty(CanvasItem.prototype, 'getBoundingClientRect', {
+        configurable: true,
+        value(this: CanvasItem): DOMRect | null {
+            const scale = DisplayServer.screenGetScale();
+            if (this instanceof Control) {
+                const rc = (this as Control).getGlobalRect();
+                return new DOMRect(
+                    rc.position.x / scale, rc.position.y / scale,
+                    rc.size.x / scale, rc.size.y / scale,
+                );
+            }
+
+            if (typeof (this as any).getRect !== 'function') return null;
+
+            const rect = (this as any).getRect() as Rect2;
+            const t = this.getScreenTransform();
+
+            const pos = rect.position;
+            const sz = rect.size;
+            const tx = t.x;
+            const ty = t.y;
+            const to = t.origin;
+
+            const x0 = pos.x, y0 = pos.y;
+            const x1 = x0 + sz.x, y1 = y0 + sz.y;
+            const txx = tx.x, txy = tx.y;
+            const tyx = ty.x, tyy = ty.y;
+            const tox = to.x, toy = to.y;
+
+            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+            const accum = (px: number, py: number) => {
+                if (px < minX) minX = px; if (py < minY) minY = py;
+                if (px > maxX) maxX = px; if (py > maxY) maxY = py;
+            };
+
+            accum(txx * x0 + tyx * y0 + tox, txy * x0 + tyy * y0 + toy);
+            accum(txx * x1 + tyx * y0 + tox, txy * x1 + tyy * y0 + toy);
+            accum(txx * x0 + tyx * y1 + tox, txy * x0 + tyy * y1 + toy);
+            accum(txx * x1 + tyx * y1 + tox, txy * x1 + tyy * y1 + toy);
+
+            return new DOMRect(
+                minX / scale, minY / scale,
+                (maxX - minX) / scale, (maxY - minY) / scale,
+            );
+        },
+    });
+
+    Object.defineProperty(Node3D.prototype, 'getBoundingClientRect', {
+        configurable: true,
+        value(this: Node3D): DOMRect | null {
+            if (typeof (this as any).getAabb !== 'function') return null;
+
+            const aabb = (this as any).getAabb();
+            const gt = this.globalTransform;
+            const viewport = this.getViewport();
+            if (!viewport) return null;
+            const camera = viewport.getCamera3d();
+            if (!camera) return null;
+            const scale = DisplayServer.screenGetScale();
+
+            const b = gt.basis;
+            const bx = b.x, by = b.y, bz = b.z;
+            const o = gt.origin;
+            const p = aabb.position, e = aabb.end;
+
+            const [px, py, pz] = [p.x, p.y, p.z];
+            const [ex, ey, ez] = [e.x, e.y, e.z];
+            const [bxx, bxy, bxz] = [bx.x, bx.y, bx.z];
+            const [byx, byy, byz] = [by.x, by.y, by.z];
+            const [bzx, bzy, bzz] = [bz.x, bz.y, bz.z];
+            const [ox, oy, oz] = [o.x, o.y, o.z];
+
+            const corners = [
+                [px, py, pz], [ex, py, pz], [px, ey, pz], [ex, ey, pz],
+                [px, py, ez], [ex, py, ez], [px, ey, ez], [ex, ey, ez],
+            ];
+
+            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+
+            for (const [cx, cy, cz] of corners) {
+                const wx = bxx * cx + byx * cy + bzx * cz + ox;
+                const wy = bxy * cx + byy * cy + bzy * cz + oy;
+                const wz = bxz * cx + byz * cy + bzz * cz + oz;
+                const s = camera.unprojectPosition(new Vector3(wx, wy, wz));
+                if (s.x < minX) minX = s.x; if (s.y < minY) minY = s.y;
+                if (s.x > maxX) maxX = s.x; if (s.y > maxY) maxY = s.y;
+            }
+
+            return new DOMRect(
+                minX / scale, minY / scale,
+                (maxX - minX) / scale, (maxY - minY) / scale,
+            );
+        },
+    });
+
+    (globalThis as any).$ = {
+        Engine, OS, ClassDB, Time,
+        dumpStr, snapshot, inspect, click, find, gc,
+        get tree(): SceneTree { return tree; },
+        get paused(): boolean { return tree.paused; },
+        set paused(v: boolean) { tree.paused = v; },
+    };
 }

package/src/index.ts

@@ -10,7 +10,7 @@ import { GodotInstance } from '../gen/classes/GodotInstance.ts';
 import { SceneTree } from '../gen/classes/SceneTree.ts';
 import { Window } from '../gen/classes/Window.ts';
 import { gc } from './debug.ts';
-import { cancelAnimationFrame, getGodot, requestAnimationFrame } from './runtime.ts';
+import { cancelAnimationFrame, cleanupHooks, getGodot, requestAnimationFrame } from './runtime.ts';
 
 // ---- make sure these classes are not tree-shaked ----
 void ValueTypes;
@@ -26,7 +26,7 @@ Object.assign(globalThis as any, { requestAnimationFrame, cancelAnimationFrame }
 export async function runGodot(signal?: AbortSignal, unmount?: () => PromiseLike<void>) {
     signal?.throwIfAborted();
     signal?.addEventListener('abort', () => {
-        (Engine.getMainLoop() as SceneTree).quit();
+        (Engine.getMainLoop() as SceneTree)?.quit();
     }, { once: true });
 
     const godot = getGodot();
@@ -34,7 +34,19 @@ export async function runGodot(signal?: AbortSignal, unmount?: () => PromiseLike
         await new Promise(requestAnimationFrame);
 
     await unmount?.();
-    console.log(gc());
+    while (cleanupHooks.size) {
+        const hooks = Array.from(cleanupHooks); cleanupHooks.clear();
+        await Promise.all(hooks.map((hook) => hook()));
+    }
+
+    // Let pending Napi wrapper finalizers run before tearing down the engine:
+    // Bun.gc(true) marks unreachable wrappers but their ~GodotVar/~Variant
+    // (which unrefs RefCounted objects) only runs on later macrotasks — and one
+    // wrapper's finalizer can free others. Freeing the engine first would report
+    // every still-referenced RefCounted as leaked, so drain a few gc+tick rounds.
+    for (let i = 0; i < 4; i++) {
+        console.log(gc());
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
     return godot.free();
 }
-