@ringozz/godot 4.7.2-626 → 4.7.2-628

package/src/runtime.ts

@@ -1,107 +1,107 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-/** Shared runtime: platform-specific native-module selection lives in
- *  `boot.ts` (desktop) / `boot.browser.ts` (web, via the `exports` `./boot`
- *  entry's `browser` condition). `_mod` is the native module — the desktop
- *  addon's `module.exports` or the wasm module's `.default`.
- *
- *  The boot leaf is imported by **package self-reference** (`@ringozz/godot/boot`),
- *  not by relative path: a bare specifier resolves through this package's own
- *  `exports` map (whose `./boot` entry's `browser` condition selects
- *  `boot.browser.ts` on web) exactly like the entrypoint's
- *  `import { preloadGodot } from '@ringozz/godot/boot'`, so both sides land on the
- *  same absolute path and share ONE `boot.browser.ts` module instance. (A relative
- *  `./boot.ts` import would let a consumer's bundler realpath it into
- *  `node_modules/.bun/...` while the entrypoint keeps the `node_modules/@ringozz/godot`
- *  path — two instances, and the preload handoff below would read `null`.)
- */
-import { getNativeModule } from '@ringozz/godot/boot';
-const { default: _mod } = getNativeModule() as any;
-
-/** Godot instance */
-import type { GodotInstance } from '../gen/classes/GodotInstance.ts';
-export const getGodot = _mod.getGodot as () => GodotInstance;
-
-/** Base constructor for all Godot object wrappers. */
-export interface GodotVar {
-    free(): void;
-}
-export const GodotVar = _mod.GodotVar as (new (...args: unknown[]) => GodotVar) & {
-    assign<T extends GodotVar>(target: T, props: Record<string, unknown>): T;
-};
-
-/** Unified entry point:
- *  - _C(this,    methodId, ...args)    → instance method
- *  - _C(classId, methodId, ...args)    → static method
- *  - _C(null,    methodId, ...args)    → singleton lookup (_getInstance) or internal
- *  - _C(0n,      methodId, ...args)    → utility function (BigInt tags the call;
- *                                         arg types resolve by name at runtime)
- */
-export const _C = _mod._C as (...args: unknown[]) => unknown;
-
-/** Resolve a string name to its integer handle. */
-export const _S = _mod._S as (name: string) => number;
-
-/** Register Godot object wrapper. */
-export const _R = _mod._R as (typeId: number, ctor: Function) => string;
-
-/**
- * Value-type dispatch on tuple receivers: `_V(typeId, methodId, receiver, ...args)`.
- * `methodId == SX_valueCtor` constructs (`_V(typeId, ctorSentinel, ctorIndex, ...args)`),
- * negative ids are operators, non-negative ids are builtin methods.
- */
-export const _V = _mod._V as (...args: unknown[]) => unknown;
-
-/**
- * Build a typed value-type Variant for a Variant-typed slot by resolving the
- * property's type from the node; returns a GodotVar carrier the consuming `_C`
- * unwraps. Used by react-hooks' useTween (tweenProperty final_val).
- */
-export const toValueType = _mod.toValueType as (node: GodotVar, propName: string, value: unknown) => unknown;
-
-/** Stage bytes into the web MEMFS (Godot's `copyToFS`); undefined on desktop. */
-export const stageFile = (_mod as any).stageFile as ((path: string, bytes: Uint8Array) => void) | undefined;
-
-/** Get a Signal value from an Object by signal name, or connect a callback when 3rd arg given. */
-export const _G = _mod._G as (target: GodotVar, signalNameId: number, callback?: unknown) => unknown;
-
-/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/requestAnimationFrame) */
-export const requestAnimationFrame = _mod.requestAnimationFrame as typeof globalThis.requestAnimationFrame ?? globalThis.requestAnimationFrame;
-
-/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/cancelAnimationFrame) */
-export const cancelAnimationFrame = _mod.cancelAnimationFrame as typeof globalThis.cancelAnimationFrame ?? globalThis.cancelAnimationFrame;
-
-// One-shot callbacks of in-flight `_P` awaits. The connection's JSCallable holds
-// only a weak reference to the callback, so without this the function could be
-// GC'd before the signal fires. A module root is the only retention Bun reliably
-// traces: neither `_P`'s closure cells nor a Set attached to the signal's object
-// wrapper survive a full GC while the await is pending (the await machinery
-// discards the promise `_P` returns, and Bun may collect the emitter's wrapper).
-// Removed as soon as the signal fires or the connect fails.
-const pendingCallbacks = new Set<(...args: any[]) => void>();
-
-/** Make a Signal PromiseLike: connects a one-shot callback that resolves with the args tuple. */
-export function _P(signal: any, onfulfilled?: any, onrejected?: any) {
-    return new Promise<any>((resolve, reject) => {
-        if (signal.isNull()) {
-            reject(new Error('Cannot await a null Signal'));
-            return;
-        }
-        const cb = (...args: any[]) => {
-            pendingCallbacks.delete(cb);
-            signal.disconnect(cb);
-            resolve(args);
-        };
-        pendingCallbacks.add(cb);
-        const res = signal.connect(cb);
-        if (res !== 0) {
-            pendingCallbacks.delete(cb);
-            reject(new Error('Failed to connect signal: error code ' + res));
-        }
-    }).then(onfulfilled, onrejected);
-}
-
-/** Cleanup callbacks run once by `runGodot` just before the engine is freed; may be async. */
-export const cleanupHooks: Set<() => void | Promise<void>> = new Set();
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+/** Shared runtime: platform-specific native-module selection lives in
+ *  `boot.ts` (desktop) / `boot.browser.ts` (web, via the `exports` `./boot`
+ *  entry's `browser` condition). `_mod` is the native module — the desktop
+ *  addon's `module.exports` or the wasm module's `.default`.
+ *
+ *  The boot leaf is imported by **package self-reference** (`@ringozz/godot/boot`),
+ *  not by relative path: a bare specifier resolves through this package's own
+ *  `exports` map (whose `./boot` entry's `browser` condition selects
+ *  `boot.browser.ts` on web) exactly like the entrypoint's
+ *  `import { preloadGodot } from '@ringozz/godot/boot'`, so both sides land on the
+ *  same absolute path and share ONE `boot.browser.ts` module instance. (A relative
+ *  `./boot.ts` import would let a consumer's bundler realpath it into
+ *  `node_modules/.bun/...` while the entrypoint keeps the `node_modules/@ringozz/godot`
+ *  path — two instances, and the preload handoff below would read `null`.)
+ */
+import { getNativeModule } from '@ringozz/godot/boot';
+const { default: _mod } = getNativeModule() as any;
+
+/** Godot instance */
+import type { GodotInstance } from '../gen/classes/GodotInstance.ts';
+export const getGodot = _mod.getGodot as () => GodotInstance;
+
+/** Base constructor for all Godot object wrappers. */
+export interface GodotVar {
+    free(): void;
+}
+export const GodotVar = _mod.GodotVar as (new (...args: unknown[]) => GodotVar) & {
+    assign<T extends GodotVar>(target: T, props: Record<string, unknown>): T;
+};
+
+/** Unified entry point:
+ *  - _C(this,    methodId, ...args)    → instance method
+ *  - _C(classId, methodId, ...args)    → static method
+ *  - _C(null,    methodId, ...args)    → singleton lookup (_getInstance) or internal
+ *  - _C(0n,      methodId, ...args)    → utility function (BigInt tags the call;
+ *                                         arg types resolve by name at runtime)
+ */
+export const _C = _mod._C as (...args: unknown[]) => unknown;
+
+/** Resolve a string name to its integer handle. */
+export const _S = _mod._S as (name: string) => number;
+
+/** Register Godot object wrapper. */
+export const _R = _mod._R as (typeId: number, ctor: Function) => string;
+
+/**
+ * Value-type dispatch on tuple receivers: `_V(typeId, methodId, receiver, ...args)`.
+ * `methodId == SX_valueCtor` constructs (`_V(typeId, ctorSentinel, ctorIndex, ...args)`),
+ * negative ids are operators, non-negative ids are builtin methods.
+ */
+export const _V = _mod._V as (...args: unknown[]) => unknown;
+
+/**
+ * Build a typed value-type Variant for a Variant-typed slot by resolving the
+ * property's type from the node; returns a GodotVar carrier the consuming `_C`
+ * unwraps. Used by react-hooks' useTween (tweenProperty final_val).
+ */
+export const toValueType = _mod.toValueType as (node: GodotVar, propName: string, value: unknown) => unknown;
+
+/** Stage bytes into the web MEMFS (Godot's `copyToFS`); undefined on desktop. */
+export const stageFile = (_mod as any).stageFile as ((path: string, bytes: Uint8Array) => void) | undefined;
+
+/** Get a Signal value from an Object by signal name, or connect a callback when 3rd arg given. */
+export const _G = _mod._G as (target: GodotVar, signalNameId: number, callback?: unknown) => unknown;
+
+/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/requestAnimationFrame) */
+export const requestAnimationFrame = _mod.requestAnimationFrame as typeof globalThis.requestAnimationFrame ?? globalThis.requestAnimationFrame;
+
+/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DedicatedWorkerGlobalScope/cancelAnimationFrame) */
+export const cancelAnimationFrame = _mod.cancelAnimationFrame as typeof globalThis.cancelAnimationFrame ?? globalThis.cancelAnimationFrame;
+
+// One-shot callbacks of in-flight `_P` awaits. The connection's JSCallable holds
+// only a weak reference to the callback, so without this the function could be
+// GC'd before the signal fires. A module root is the only retention Bun reliably
+// traces: neither `_P`'s closure cells nor a Set attached to the signal's object
+// wrapper survive a full GC while the await is pending (the await machinery
+// discards the promise `_P` returns, and Bun may collect the emitter's wrapper).
+// Removed as soon as the signal fires or the connect fails.
+const pendingCallbacks = new Set<(...args: any[]) => void>();
+
+/** Make a Signal PromiseLike: connects a one-shot callback that resolves with the args tuple. */
+export function _P(signal: any, onfulfilled?: any, onrejected?: any) {
+    return new Promise<any>((resolve, reject) => {
+        if (signal.isNull()) {
+            reject(new Error('Cannot await a null Signal'));
+            return;
+        }
+        const cb = (...args: any[]) => {
+            pendingCallbacks.delete(cb);
+            signal.disconnect(cb);
+            resolve(args);
+        };
+        pendingCallbacks.add(cb);
+        const res = signal.connect(cb);
+        if (res !== 0) {
+            pendingCallbacks.delete(cb);
+            reject(new Error('Failed to connect signal: error code ' + res));
+        }
+    }).then(onfulfilled, onrejected);
+}
+
+/** Cleanup callbacks run once by `runGodot` just before the engine is freed; may be async. */
+export const cleanupHooks: Set<() => void | Promise<void>> = new Set();

package/src/transcoder.browser.ts

@@ -0,0 +1,28 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Browser condition of `@ringozz/godot/transcoder` (see `exports` `./transcoder`):
+// resolves the spark.js-backed transcoder from the web platform package, handing
+// it the container helpers it needs (see that package's `CtexHelpers`). This is
+// the only place the platform package is referenced, and a desktop bundle resolves
+// `transcoder.ts` instead — so it and `@ludicon/spark.js` never appear in a desktop
+// build.
+//
+// The (large, all-format) encoder chunk is fetched as soon as this module is
+// evaluated — i.e. with the app, alongside the engine boot and the asset fetches —
+// rather than starting when the first `.ctex` arrives, so it stays off the
+// time-to-first-texture critical path. The WebGPU device and shaders are still
+// created lazily, on the first transcode.
+
+import * as ctex from './web-image.ts';
+import type { CtexTranscoder } from './web-image.ts';
+
+/** Resolves to the spark.js-backed transcoder, or `null` if it can't load (so staging keeps the raw RGBA8 decode). */
+export const transcoder: Promise<CtexTranscoder | null> = import('@ringozz/godot-web-wasm32/spark').then(
+	({ createSparkTranscoder }) => createSparkTranscoder(ctex),
+	(err) => {
+		console.warn('[godot] built-in texture transcoder unavailable; web textures stay raw RGBA8:', err);
+		return null;
+	},
+);

package/src/transcoder.ts

@@ -0,0 +1,15 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Desktop (default) condition of `@ringozz/godot/transcoder`: there is no web
+// texture transcoder, so `.ctex` staging — which only runs on web anyway — keeps
+// the raw RGBA8 decode. The `browser` condition swaps in `transcoder.browser.ts`
+// (see `exports` `./transcoder`), which resolves the spark.js-backed transcoder
+// from the web platform package; keeping this in its own module means a desktop
+// bundle resolves this file and never references either.
+
+import type { CtexTranscoder } from './web-image.ts';
+
+/** Resolves to the platform's `.ctex` transcoder, or `null` when it has none. */
+export const transcoder: Promise<CtexTranscoder | null> = Promise.resolve(null);