@ringozz/godot 4.7.2-597 → 4.7.2-612

package/README.md

@@ -99,7 +99,7 @@ import foo from './models/foo.gltf';
 const scene = await foo;          // PackedScene
 ```
 
-Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, deps, import.meta.hot.data)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its own files plus its deps' files). It statically imports its own files Godot reads — `.import` sidecars and native text sources (`tscn`/`tres`/`po`) via the `text` loader, imported products (`.scn`/`.ctex`) via the `file` loader — and imports its **dependencies as generated modules too**, waiting only for their `materialize` before loading itself (dep loads start at module evaluation and run concurrently). Text-based source assets (`.gltf`/`.tscn`/`.tres`/`.obj`) are scanned for references (`res://` paths and relative paths ending in known asset extensions); referenced source assets become dep modules, raw `.mtl` files (OBJ materials) are recursed into, and raw `.bin` buffers are import-time only. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
+Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, deps, import.meta.hot.data)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its own files plus its deps' files). The files Godot reads are bundled into the module — `.import` sidecars and native text sources (`tscn`/`tres`/`po`/`gd`) are inlined as text, imported products (`.scn`/`.ctex`) are emitted as files — and the module imports its **dependencies as generated modules too**, waiting only for their `materialize` before loading itself (dep loads start at module evaluation and run concurrently). Text-based source assets (`.gltf`/`.tscn`/`.tres`/`.obj`/`.gd`) are scanned for references (`res://` paths and relative paths ending in known asset extensions); referenced loadable assets become dep modules, native-text leaves are staged as raw text so the engine loads them by `res://` on web, raw `.mtl` files (OBJ materials) are recursed into, and raw `.bin` buffers are import-time only. The modules are virtual (namespace `godot`), and every import of the same asset resolves to the same one (evaluated once) — so the promise is a stable singleton, read with `await` or React 19's `use()`:
 
 ```tsx
 import foo from './models/foo.gltf';
@@ -115,7 +115,7 @@ function Foo() {
 </Suspense>
 ```
 
-Each extension maps to its Godot class (source assets only — `gltf`/`tscn`/`obj` → `PackedScene`, `jpg`/`jpeg`/`png`/`webp` → `CompressedTexture2D`, `svg` → `Texture2D`, `exr`/`hdr` → `TextureLayered`, `wav` → `AudioStreamWAV`, `ogg` → `AudioStreamOggVorbis`, `mp3` → `AudioStreamMP3`, `ttf`/`otf` → `FontFile`, `tres` → `Resource`, `po` → `Translation`), declared in `src/assets.d.ts`. Imported products (`.scn`/`.ctex`) are never imported directly.
+Each extension maps to its Godot class (source assets only — `gltf`/`tscn`/`obj` → `PackedScene`, `gd` → `GDScript`, `jpg`/`jpeg`/`png`/`webp`/`svg` → `CompressedTexture2D`, `exr`/`hdr` → `TextureLayered`, `wav` → `AudioStreamWAV`, `ogg` → `AudioStreamOggVorbis`, `mp3` → `AudioStreamMP3`, `ttf`/`otf` → `FontFile`, `tres` → `Resource`, `po` → `Translation`), declared in `src/assets.d.ts`. Imported products (`.scn`/`.ctex`) are never imported directly. `.gd` scripts import as `Promise<GDScript>`, so `import script from './x.gd'; const gd = await script;` works like any other resource — and when a `.tscn` references the same `.gd`, Godot's `ResourceLoader` cache returns the same instance (parsed once).
 
 Textures are shared only through Godot's `ResourceLoader` path cache. The glTF import pipeline may produce per-scene texture instances (same `res://` path, separate objects), so don't assume two scenes referencing the same image share one texture object.
 
@@ -143,4 +143,4 @@ initDebug();
 
 ## Development
 
-`gen/` is generated (and gitignored) by `dev/codegen.ts` from `godot --dump-extension-api-with-docs`. Regenerate + typecheck with `bun run prebuild`. Build the native addon with `bun run build`. See [`AGENTS.md`](../../AGENTS.md) for the full workflow.
+`gen/` is generated (and gitignored) by `dev/codegen.ts` from `godot --dump-extension-api-with-docs`. From the repo root: `bun run prebuild` (codegen + typecheck), `bun run predev` (imports `dev/assets/` via the editor), `bun run build` (native addon), `bun run test`, and `bun run dev` (web dev server). See [`AGENTS.md`](../../AGENTS.md) for the full workflow.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-597",
+  "version": "4.7.2-612",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -58,9 +58,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-597",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-597",
-    "@ringozz/godot-web-wasm32": "^4.7.2-597"
+    "@ringozz/godot-macos-arm64": "^4.7.2-612",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-612",
+    "@ringozz/godot-web-wasm32": "^4.7.2-612"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/assets.d.ts

@@ -10,6 +10,13 @@
 // a stable module singleton, so it can be passed to React's `use()` under
 // `<Suspense>`.
 
+declare module '*.gd' {
+	import type { GDScript } from '@ringozz/godot/GDScript';
+	const asset: Promise<GDScript>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
 declare module '*.tres' {
 	import type { Resource } from '@ringozz/godot/Resource';
 	const asset: Promise<Resource>;

package/src/preload.ts

@@ -32,6 +32,7 @@ const FORMATS: Record<string, { cls?: string; scan?: boolean; native?: boolean }
 	gltf: { cls: 'PackedScene', scan: true },
 	tscn: { cls: 'PackedScene', scan: true, native: true },
 	obj: { cls: 'PackedScene', scan: true },
+	gd: { cls: 'GDScript', scan: true, native: true },
 	jpg: { cls: 'CompressedTexture2D' },
 	jpeg: { cls: 'CompressedTexture2D' },
 	png: { cls: 'CompressedTexture2D' },
@@ -78,24 +79,36 @@ function parseSidecarDest(text: string): string | null {
 	return remap ? remap[1] : null;
 }
 
-// Generalized reference extraction for text-based source assets: absolute
-// `res://` paths (Godot scenes/resources) and relative path tokens ending in a
-// known asset extension (glTF uris, OBJ/MTL textures). The literal dot before
-// the extension avoids matching MIME types inside `data:` URIs.
-const RES_RE = /res:\/\/[\w./\\-]+/g;
-const REL_RE = new RegExp(`([\\w./\\\\-]+\\.(?:${Object.keys(FORMATS).join('|')}))`, 'g');
-
+// Reference extraction for text-based source assets: absolute `res://` paths
+// (Godot scenes/resources) and relative path tokens ending in a known asset
+// extension (glTF uris, OBJ/MTL textures). The literal dot before the extension
+// avoids matching MIME types inside `data:` URIs. Regexes are built fresh per
+// call: a `/g` instance is stateful, and reusing one module-level regex across
+// many files misbehaves under the dev server's bundler (a stale lastIndex
+// shifted a scan's results). The `//` fragment right after `res:` is a mere
+// path remainder of the `res://` match, not a real relative ref, so it's
+// skipped (otherwise it mis-resolves as a Windows UNC `\\…` path).
+//
+// The extension must TERMINATE a token: `(?![\w.])` rejects matches where the
+// extension is only the head of a longer identifier or a dotted sub-field, e.g.
+// `X.po` in `X.position`, `foo.gd` in `foo.gd.position`, or `scene.tscn2`. A
+// real relative ref (`foo.po`, `x.gd`, `ui/scene.tscn`) always ends its token.
+// `String.raw` keeps the `\w` escapes intact — a plain template literal would
+// drop the backslashes, turning `\w` into `w` (a wrong guard `(?![w.])`).
+const REL_TERM = String.raw`(?![\w.])`;
+const REL_PATTERN = String.raw`([\w./\\-]+\.(?:` + Object.keys(FORMATS).join('|') + `))` + REL_TERM;
 function extractRefs(text: string): string[] {
 	const refs: string[] = [];
-	for (const m of text.matchAll(RES_RE)) refs.push(m[0]);
-	for (const m of text.matchAll(REL_RE)) refs.push(m[1]);
+	for (const m of text.matchAll(/res:\/\/[\w./\\-]+/g)) refs.push(m[0]);
+	const rel = new RegExp(REL_PATTERN, 'g');
+	for (const m of text.matchAll(rel)) if (!m[1].startsWith('/')) refs.push(m[1]);
 	return refs;
 }
 
 /**
  * Adds a source asset's own files to `files`: imported assets contribute their
  * `.import` sidecar (text) + imported product (file); native text formats
- * (tscn/tres/po) contribute the file itself (text).
+ * (tscn/tres/po/gd) contribute the file itself (text).
  */
 function addSource(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
 	const impAbs = srcAbs + '.import';
@@ -106,16 +119,23 @@ function addSource(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
 			files.set(dest, 'file');
 		}
 	} else if (isNativeText(srcAbs)) {
-		files.set(resOf(srcAbs), 'text');
+		stageNativeText(srcAbs, files);
 	}
 }
 
+/** Stages a native text source (`res://` path → `text`) so web staging + inlining picks it up. */
+function stageNativeText(srcAbs: string, files: Map<string, 'text' | 'file'>): void {
+	files.set(resOf(srcAbs), 'text');
+}
+
 /**
- * Collects the referenced source assets (deps) of a text source: source assets
- * become dep modules (each handles its own transitive deps); raw text formats
- * without a sidecar (`.mtl`) are recursed into. Buffers (`.bin`) are skipped.
+ * Collects the referenced source assets (deps) of a text source: every referenced
+ * source asset is staged (native text → `files`, products → dep modules), and
+ * loadable source assets also become dep modules so their own files + transitive
+ * deps are handled. Raw text formats without a sidecar (`.mtl`) are recursed into.
+ * Buffers (`.bin`) are skipped.
  */
-function collectDeps(abs: string, visited: Set<string>, deps: string[]): void {
+function collectDeps(abs: string, visited: Set<string>, deps: string[], files: Map<string, 'text' | 'file'>): void {
 	if (visited.has(abs)) {
 		return;
 	}
@@ -130,10 +150,22 @@ function collectDeps(abs: string, visited: Set<string>, deps: string[]): void {
 		if (visited.has(refAbs)) {
 			continue;
 		}
+		// Stage native text (e.g. `.gd`, nested `.tscn`) so the engine loads it
+		// by `res://` on web (idempotent); loadable assets also become dep
+		// modules for their own files + transitive deps.
 		if (isSourceAsset(refAbs)) {
-			deps.push(refAbs);
-		} else if (isScannableText(refAbs)) {
-			collectDeps(refAbs, visited, deps);
+			if (isNativeText(refAbs)) {
+				visited.add(refAbs);
+				stageNativeText(refAbs, files);
+			}
+			if (CLASS_BY_EXT[extOf(refAbs)]) {
+				deps.push(refAbs);
+			}
+		}
+		// Any scannable ref (a source's own text, or a raw leaf like `.mtl`) is
+		// recursed into so its internal `res://` refs are traced/staged too.
+		if (isScannableText(refAbs)) {
+			collectDeps(refAbs, visited, deps, files);
 		}
 	}
 }
@@ -142,7 +174,7 @@ function analyze(abs: string): { files: Map<string, 'text' | 'file'>; deps: stri
 	const files = new Map<string, 'text' | 'file'>();
 	const deps: string[] = [];
 	addSource(abs, files);
-	collectDeps(abs, new Set(), deps);
+	collectDeps(abs, new Set(), deps, files);
 	return { files, deps };
 }
 
@@ -156,15 +188,20 @@ function ensureModule(abs: string): string {
 		`import { ${cls} } from '@ringozz/godot/${cls}';`,
 	];
 	const map: string[] = [];
-	let ti = 0;
 	let fi = 0;
+	// Text files (own `.tscn`/`.tres`/`.po`, `.import` sidecars, staged `.gd`
+	// leaves) are inlined as string literals — Bun's `with { type: 'text' }`
+	// import resolves to a null/default under the dev server's HMR wrapper for
+	// a module's own path; products (`.scn`/`.ctex`) are fetched by path.
 	for (const [resPath, kind] of files) {
 		const absP = resolve(ROOT, resPath.slice('res://'.length));
-		const v = kind === 'text' ? `c${ti++}` : `f${fi++}`;
-		const type = kind === 'text' ? 'text' : 'file';
-		const field = kind === 'text' ? 'content' : 'path';
-		imports.push(`import ${v} from ${JSON.stringify(absP)} with { type: '${type}' };`);
-		map.push(`  ${JSON.stringify(resPath)}: { ${field}: ${v} },`);
+		if (kind === 'text') {
+			map.push(`  ${JSON.stringify(resPath)}: { content: ${JSON.stringify(readFileSync(absP, 'utf8'))} },`);
+			continue;
+		}
+		const v = `f${fi++}`;
+		imports.push(`import ${v} from ${JSON.stringify(absP)} with { type: 'file' };`);
+		map.push(`  ${JSON.stringify(resPath)}: { path: ${v} },`);
 	}
 	deps.forEach((dep, i) => imports.push(`import * as dep${i} from ${JSON.stringify(dep)};`));