@ringozz/godot 4.7.2-661 → 4.7.2-676

package/README.md

@@ -52,8 +52,9 @@ await import('./app.ts'); // may now import @ringozz/godot / react-godot freely
 | `@ringozz/godot/ClassName` | Classes, one per module — e.g. `@ringozz/godot/Label`, `@ringozz/godot/Node` |
 | `@ringozz/godot/runtime` | Low-level dispatch: `_C`, `_S`, `_R`, `_G`, `_P`, `_V`, `toValueType`, `getGodot`, `GodotVar` |
 | `@ringozz/godot/boot` | Platform boot: `getNativeModule()`; web `preloadGodot()` (awaited before importing the app; no-op on desktop) |
-| `@ringozz/godot/load` | Async resource loading: `loadResourceAsync`, `loadAsset`, `loadAssetPack` (native `.pck` packs) |
-| `@ringozz/godot/pack` | `buildAssetPacks()` + the `godot pack` subcommand: bake a project's `.pck`(s) + loose-texture manifest, one pack per level (its scene, or the `.gltfx` its plan lives in) |
+| `@ringozz/godot/load` | Async resource loading: `loadResourceAsync`, `loadAsset`, `loadAssetPack` (native `.pck` packs), `configurePacks`/`loadPackEntry` (content packs) |
+| `@ringozz/godot/bake` | `buildAssetPacks(opts, run?)` + the `godot pack` subcommand: bake the project's boot `.pck` plus one per declared content pack, with their loose-texture documents. `opts.cwd` picks the project root and `run` replaces the editor, so a test can bake a temp project |
+| `@ringozz/godot/pack` | The pack protocol the bake writes and the plugin/runtime read: `PACK_DOC`/`RELEASE`/`FILES_DIR` and the boot's names, `parseDoc`/`serializeDoc`/`parseRelease`, `packEntries`/`godotEntry`/`entryId`/`pckOf`, and `resolveEntry` (what to mount and stage for one entry) |
 | `@ringozz/godot/debug` | `initDebug()`, `dumpStr`, `snapshot`, `inspect`, `click`, `find`, `gc` |
 
 Class-scoped enums use bare names (import `ProcessMode` from `@ringozz/godot/Node`, not `NodeProcessMode`).
@@ -95,15 +96,37 @@ const tex   = await loadResourceAsync('res://textures/icon.jpg', Texture2D); //
 
 ### Asset packs
 
-`godot pack` (the `godot` bin, `@ringozz/godot/pack`) bakes a project's assets for the runtime: it imports them, asks `dump-deps.gd` for each source's packed closure and its loose (WebP-backed) textures — including a level's plan, which names refs no resource edge exposes — and exports native `.pck`s — the engine-converted binary resources plus a remap table — through the project's committed `export_presets.cfg`. `loadAssetPack(url)` fetches a pack into MEMFS and hands it to `ProjectSettings.loadResourcePack`; packs are add-only, so several can be mounted and `res://` resolves across all of them.
+`godot pack` (the `godot` bin, `@ringozz/godot/bake`) bakes a project's assets for the runtime: it imports them, asks `dump-deps.gd` for every source's loose (WebP-backed) textures — including a plan, which names refs no resource edge exposes (it warns when a plan resolves no ref at all, or is stamped under another `extras` namespace — that reading has no static check) — and exports one native `.pck` — the engine-converted binary resources plus a remap table — through the project's committed `export_presets.cfg`. `loadAssetPack(url)` fetches a pack into MEMFS and hands it to `ProjectSettings.loadResourcePack`; packs are add-only, so several can be mounted and `res://` resolves across all of them.
 
-The bake always splits: **one pack per level, plus a shared pack**, so a host fetches the shared data and only the level it is playing. A level is its scene — or, in a project that builds levels from their plans at run time, the `.gltfx` its plan lives in; a project with neither under its roots gets a single `shared.pck`. What the runtime reads is `.godot/packs/packs.json` beside the packs: which packs exist, which sources each owns, and which loose sources the host must stage per file (the WebP-backed textures are transcoded). The preload plugin mounts the right packs per asset, so importing a level pulls in the shared pack and that level's, nothing else. How the split is decided — and why it needs no configuration — is in `AGENTS.md`.
+The bake produces **one boot pack** — the project's own sources, exported through its committed `export_presets.cfg` preset, and always mounted by the preload plugin, which is what makes a scene's own run-time paths (a script named by a constant, a level chosen at run time) resolvable — plus **one pack per directory under `dlc/` that declares itself with a `package.json`**: that file gives the pack its name, its dependencies on other packs and its `exports` entries, the pack is that directory and nothing else (the bake rewrites the preset's one `exclude_filter` line per pack), and the bake fails if a pack references anything but the boot sources and its declared dependencies. The boot pack's document is `.godot/packs/packs.json` (`needs` = which loose files each source needs staged, `stage` = the descriptor and product of each loose file the pack owns); a content pack's is a `pack.json` emitted beside its `.pck` (`PACK_DOC` — not `package.json`, which is the pack's own manifest in its source directory, an input the bake reads) (its declared fields plus `needs`/`stage` — the same document the boot's `packs.json` is). Deploying those packs independently — versioning, an index, a CDN — is the host's business, not the bake's.
 
 ```ts
 import { loadAssetPack } from '@ringozz/godot/load';
 await loadAssetPack('/packs/shared.pck');   // usually the preload plugin does this per asset
 ```
 
+### Content packs
+
+A content pack is deployed apart from the app, so nothing about it is in the bundle: the runtime reads a **release** (which version of which pack to mount — a `bun.lock`, or the plain map a local bake emits) and each mounted pack's document, then loads a declared entry. Point the runtime at the packs once, at start-up:
+
+```ts
+import { configurePacks } from '@ringozz/godot/load';
+// The host owns the base: a pack's name, its version and one of its files, addressed its own way.
+configurePacks({
+	at: (name, version, file) => `https://cdn.example/packs/${name}@${version}/${file}`,
+	release: 'https://cdn.example/packs/release.json',   // or the map itself: `{ '@tiv/beach': { version, deps } }`
+});
+```
+
+The boot pack — the app's own sources, which ship beside it — needs no config: the bake renders it into a module (`.godot/packs/boot-pack.js`: its `.pck`, plus a bundled URL per loose product it owns), which every imported asset pulls in, and `configurePacks` merges, so the app's `at` and the boot's config may land in either order. A pack declares its entries (`exports` → the `godot` condition, the `res://` path) and ships **no entry module**: the preload plugin serves one, built from the bake's documents, with one named export per entry. So importing a pack is an ordinary import — and the bake emits the types it resolves to (`package.d.ts`, named by the pack's `types`):
+
+```ts
+import { level } from '@tiv/dlc-beach';   // → a PackedScene, via loadPackEntry(pack, 'level', …)
+```
+
+Mounting is add-only, so every pack in the closure stays mounted for the page's lifetime.
+
+
 ### Asset imports
 
 Asset imports are resolved by `@ringozz/godot/preload` (a Bun plugin, registered via `bunfig.toml` preload for `bun run`/`bun test` and via `[serve.static] plugins` for `Bun.serve`'s fullstack HTML routes; the module's default export is the single plugin object) into a module per asset. Only **JS imports** are virtualized — HTML asset references (`<link rel="icon">`, `<img src>`) and CSS `url()` refs fall through to Bun's normal (content-hashed) asset handling, so favicons and other web assets co-exist with Godot imports:
@@ -113,7 +136,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, import.meta.hot.data, ready)` — 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`/`gdshader`/`gdshaderinc`) 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`/`.gdshader`/`.gdshaderinc`) 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()`:
+Each asset module's default export is its load **promise** (`const { materialize, load } = loadAsset(resPath, Class, files, import.meta.hot.data, mounting)` — the default is `load`, memoized on the module's HMR data), started eagerly at module import, and it also exports a `materialize` promise (its files staged). The files Godot reads are bundled into the module — `.import` sidecars are inlined as text, imported products (`.ctex`) are emitted as files — from the bake's document, never from scanning the source text: `dump-deps.gd` walked the project at bake time and wrote, per source, the loose (WebP-backed) texture sources the wasm engine cannot decode, and the pack's `stage` gives each of those its sidecar and its product. A packed source resolves inside the mounted `.pck` (the engine-converted resources plus a remap table); only its loose textures are staged per file, transcoded in the browser. The `mounting` promise comes from the bake's boot pack — the module the bake generates beside the packs (`.godot/packs/boot-pack.js`): its `.pck`, plus a bundled URL for every loose product it owns — so importing any asset is also what mounts the app's own pack, and the runtime can stage a content pack's loose files even when the boot owns them. 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';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-661",
+  "version": "4.7.2-676",
   "description": "Node-API bindings for Godot Engine — call Godot classes from JavaScript",
   "publishConfig": {
     "access": "public"
@@ -27,6 +27,7 @@
     },
     "./load": "./src/load.ts",
     "./pack": "./src/pack.ts",
+    "./bake": "./src/bake.ts",
     "./transcoder": {
       "browser": "./src/transcoder.browser.ts",
       "default": "./src/transcoder.ts"
@@ -66,9 +67,9 @@
     "precision": "single"
   },
   "optionalDependencies": {
-    "@ringozz/godot-macos-arm64": "^4.7.2-661",
-    "@ringozz/godot-windows-x86_64": "^4.7.2-661",
-    "@ringozz/godot-web-wasm32": "^4.7.2-661"
+    "@ringozz/godot-macos-arm64": "^4.7.2-676",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-676",
+    "@ringozz/godot-web-wasm32": "^4.7.2-676"
   },
   "peerDependencies": {
     "@types/bun": "*"

package/src/assets.d.ts

@@ -30,7 +30,7 @@ declare module '*.gdshaderinc' {
 	export default asset;
 	export const materialize: Promise<unknown>;
 }
-
+
 declare module '*.tres' {
 	import type { Resource } from '@ringozz/godot/Resource';
 	const asset: Promise<Resource>;
@@ -108,6 +108,15 @@ declare module '*.svg' {
 	export const materialize: Promise<unknown>;
 }
 
+// The layer manifest `godot/addons/sourcewebp` imports into a `.ctexarray` (a texture array whose
+// layers are source WebP bytes); its product is what is staged.
+declare module '*.webparray' {
+	import type { CompressedTexture2DArray } from '@ringozz/godot/CompressedTexture2DArray';
+	const asset: Promise<CompressedTexture2DArray>;
+	export default asset;
+	export const materialize: Promise<unknown>;
+}
+
 declare module '*.exr' {
 	import type { TextureLayered } from '@ringozz/godot/TextureLayered';
 	const asset: Promise<TextureLayered>;