@ringozz/godot 4.7.2-639 → 4.7.2-641

package/README.md

@@ -77,7 +77,7 @@ const b = basis.fromAxisAngle([0, 1, 0], 1.57);
 
 ### Async resource loading
 
-The engine loads pre-baked native resources (`.scn`, `.ctex`, …) through `ResourceLoader`. On desktop these are real files (`res://` = cwd); on web there is no filesystem, so the asset's bundled files — `.import` sidecars as text and imported products (`.scn`/`.ctex`) as emitted asset paths — are staged into Emscripten's in-memory MEMFS (transient, no IndexedDB, no persistent copy) by the generated asset modules, handing the fetched bytes straight to MEMFS via Godot's own `copyToFS` (`FS.createDataFile` with `canOwn` — zero copy, JS-heap only). On web, compressed-texture products are decoded first: for `.ctex` (and the layered `.ctexarray` / `.ccube` / `.ccubearray`) the embedded PNG/WebP blobs go through the browser's `createImageBitmap` and the container is rebuilt as raw RGBA (`DATA_FORMAT_IMAGE`) — per layer for arrays — so no image codec runs in wasm. A built-in **transcoder** instead rebuilds the container as a device-native block-compressed texture (BC7/ASTC, via `@ludicon/spark.js`), encoding every layer of an array/cubemap in parallel; its chunk is fetched along with the rest of the app (so it isn't on the critical path to the first texture), the WebGPU device is warmed as soon as it lands, and any decode/encode failure falls back to the raw RGBA path. `.ctex3d` has its own layout and is left to the engine. The source file itself is never fetched.
+The engine loads pre-baked native resources (`.scn`, `.ctex`, …) through `ResourceLoader`. On desktop these are real files (`res://` = cwd); on web there is no filesystem, so the asset's bundled files — `.import` sidecars as text and imported products (`.scn`/`.ctex`) as emitted asset paths — are staged into Emscripten's in-memory MEMFS (transient, no IndexedDB, no persistent copy) by the generated asset modules, handing the fetched bytes straight to MEMFS via Godot's own `copyToFS` (`FS.createDataFile` with `canOwn` — zero copy, JS-heap only). On web, compressed-texture products are decoded first: for `.ctex` (and the layered `.ctexarray` / `.ccube` / `.ccubearray`) the embedded PNG/WebP blobs go through the browser's `createImageBitmap` and the container is rebuilt as raw RGBA (`DATA_FORMAT_IMAGE`) — per layer for arrays — so no image codec runs in wasm. A built-in **transcoder** instead rebuilds the container as a device-native block-compressed texture via `@ludicon/spark.js`, choosing the format from the source file's name — normal maps → BC5/EAC-RG, alpha albedo and HDR/sky → BC7/ASTC, terrain weight planes → BC4/EAC-R, everything else (colour/ORM) → BC1/ETC2 first, each with a BC7/ASTC and finally a raw-RGBA fallback — and encoding every layer of an array/cubemap in parallel; its chunk is fetched along with the rest of the app (so it isn't on the critical path to the first texture), the WebGPU device is warmed as soon as it lands, and any decode/encode failure falls back to the raw RGBA path. `.ctex3d` has its own layout and is left to the engine. The source file itself is never fetched.
 
 ```ts
 import { loadResourceAsync } from '@ringozz/godot/load';

package/package.json

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

package/src/load.ts

@@ -15,14 +15,15 @@ import { decodeCtex } from './web-image.ts';
 /**
  * Produces the bytes staged for a `.ctex`: the platform transcoder (resolved
  * once by `@ringozz/godot/transcoder`) when it yields a result, otherwise the raw
- * RGBA8 browser decode. Never throws — a failed transcode degrades to the
- * uncompressed path.
+ * RGBA8 browser decode. `path` (the resource path being staged) is forwarded so
+ * the transcoder can pick a block format from the file name. Never throws — a
+ * failed transcode degrades to the uncompressed path.
  */
-async function transcodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+async function transcodeCtex(bytes: Uint8Array, path: string): Promise<Uint8Array> {
     const encode = await transcoder;
     if (encode) {
         try {
-            const out = await encode(bytes);
+            const out = await encode(bytes, path);
             if (out) {
                 return out;
             }
@@ -137,7 +138,7 @@ async function materialize([resPath, entry]: [string, AssetFile]): Promise<void>
 			// transcoder (e.g. spark.js) may instead rebuild the container as a
 			// device-native block-compressed texture by the built-in transcoder —
 			// except for `EXACT_TEXTURE_RE`'s routes, which must stay raw (see there).
-			bytes = EXACT_TEXTURE_RE.test(resPath) ? await decodeCtex(bytes) : await transcodeCtex(bytes);
+			bytes = EXACT_TEXTURE_RE.test(resPath) ? await decodeCtex(bytes) : await transcodeCtex(bytes, resPath);
 		}
 	} else {
 		return;

package/src/web-image.ts

@@ -26,9 +26,16 @@ const SUB_HEADER_SIZE = 16;
 const DATA_FORMAT_PNG = 1;
 const DATA_FORMAT_WEBP = 2;
 
-// `Image::Format` targets we emit (`core/io/image.h`). Only BC7 and ASTC: both
-// are 4x4/16-byte formats, which is why the size math needs no format table.
-export const FORMAT_BPTC_RGBA = 22;
+// `Image::Format` targets we emit (`core/io/image.h`). Every compressed target
+// is a 4x4 block format; they differ only in bytes per block, so the size math
+// is a small table rather than a per-format switch.
+export const FORMAT_DXT1 = 17; // BC1
+export const FORMAT_RGTC_R = 20; // BC4
+export const FORMAT_RGTC_RG = 21; // BC5
+export const FORMAT_BPTC_RGBA = 22; // BC7
+export const FORMAT_ETC2_R11 = 26; // EAC R
+export const FORMAT_ETC2_RG11 = 28; // EAC RG
+export const FORMAT_ETC2_RGB8 = 30;
 export const FORMAT_ASTC_4x4 = 35;
 
 // Image-body data starts here: outer header + sub-header.
@@ -37,9 +44,30 @@ export const BLOB_TABLE_OFFSET = OUTER_HEADER_SIZE + SUB_HEADER_SIZE;
 const DATA_FORMAT_IMAGE = 0;
 const FORMAT_RGBA8 = 5;
 const RGBA8_PIXEL_SIZE = 4;
+
 const FORMAT_BIT_STREAM = 1 << 22;
 const MAGIC_LAYERED = 0x4c; // 'GSTL'; 'GST2' (0x32) is the single-image layout
 
+// Bytes per 4x4 block for each compressed target; RGBA8 is 4 bytes/pixel.
+const BLOCK_BYTES: Record<number, number> = {
+	[FORMAT_DXT1]: 8,
+	[FORMAT_ETC2_RGB8]: 8,
+	[FORMAT_ETC2_R11]: 8,
+	[FORMAT_RGTC_R]: 8,
+	[FORMAT_RGTC_RG]: 16,
+	[FORMAT_ETC2_RG11]: 16,
+	[FORMAT_BPTC_RGBA]: 16,
+	[FORMAT_ASTC_4x4]: 16,
+};
+
+/**
+ * Bytes per 4x4 block of a compressed `Image::Format` target (RGBA8 reports 4,
+ * its bytes per pixel). Unknown formats fall back to a 16-byte block.
+ */
+export function blockBytes(format: number): number {
+	return format === FORMAT_RGBA8 ? RGBA8_PIXEL_SIZE : (BLOCK_BYTES[format] ?? 16);
+}
+
 export interface CtexLayer {
 	/** `DATA_FORMAT_PNG` (1) / `DATA_FORMAT_WEBP` (2). */
 	dataFormat: number;
@@ -132,12 +160,12 @@ export function mipChainLength(width: number, height: number): number {
 }
 
 // Bytes of one `DATA_FORMAT_IMAGE` image body: sub-header + tightly packed
-// levels. RGBA8 is 4 bytes/pixel; BC7/ASTC are 16-byte 4x4 blocks whose
-// dimensions round up, matching `Image::_get_dst_image_size`.
+// levels. RGBA8 is 4 bytes/pixel; compressed targets are 4x4 blocks (8 or 16
+// bytes) whose dimensions round up, matching `Image::_get_dst_image_size`.
 function bodySize(width: number, height: number, mipmaps: number, format: number): number {
 	const rgba8 = format === FORMAT_RGBA8;
 	const block = rgba8 ? 1 : 4;
-	const bytesPerBlock = rgba8 ? RGBA8_PIXEL_SIZE : 16;
+	const bytesPerBlock = blockBytes(format);
 	let dataSize = 0;
 	for (let level = 0; level <= mipmaps; level++) {
 		const [w, h] = mipLevelDimensions(width, height, level);
@@ -192,10 +220,10 @@ export function allocateCtex(
 // ---------------------------------------------------------------------------
 
 /**
- * Compressed `Image::Format` targets for an RGBA texture, best first, filtered
- * to what the running device can actually upload. A list because the encoder may
- * also reject a format the browser exposes (e.g. spark skips BC on iOS); the
- * caller walks it until one is encodable.
+ * Compressed `Image::Format` targets the running device can upload. A list
+ * because the encoder may also reject a format the browser exposes (e.g. spark
+ * skips BC on iOS); the caller intersects it with spark's supported set, and
+ * order here is not significant (the encoder has its own preference chain).
  */
 export function pickGodotFormats(): number[] {
 	let gl: WebGL2RenderingContext | null = null;
@@ -226,9 +254,20 @@ export function pickGodotFormats(): number[] {
 		if (exts.has('EXT_texture_compression_bptc')) {
 			formats.push(FORMAT_BPTC_RGBA);
 		}
+		if (exts.has('EXT_texture_compression_rgtc')) {
+			formats.push(FORMAT_RGTC_RG);
+			formats.push(FORMAT_RGTC_R);
+		}
 		if (exts.has('WEBGL_compressed_texture_astc')) {
 			formats.push(FORMAT_ASTC_4x4);
 		}
+		if (exts.has('WEBGL_compressed_texture_s3tc')) {
+			formats.push(FORMAT_DXT1);
+		}
+		// ETC2/EAC is core WebGL2 (ES 3.0), which is how Godot's web config
+		// reports it (`etc2_supported = true` for non-GLES-over-GL) — so these
+		// are always uploadable, independent of any extension.
+		formats.push(FORMAT_ETC2_RGB8, FORMAT_ETC2_RG11, FORMAT_ETC2_R11);
 	} finally {
 		// Don't retain the probe context for the page's lifetime.
 		gl.getExtension('WEBGL_lose_context')?.loseContext();
@@ -238,10 +277,11 @@ export function pickGodotFormats(): number[] {
 
 /**
  * Transforms fetched `.ctex` bytes into replacement bytes, or `null` to decline
- * (staging then keeps the raw RGBA8 decode). Produced by `transcoder*.ts` and
- * installed by `load.ts`'s staging.
+ * (staging then keeps the raw RGBA8 decode). `path` is the resource path being
+ * staged, so a platform transcoder can pick a block format from the file name.
+ * Produced by `transcoder*.ts` and installed by `load.ts`'s staging.
  */
-export type CtexTranscoder = (bytes: Uint8Array) => Promise<Uint8Array | null>;
+export type CtexTranscoder = (bytes: Uint8Array, path: string) => Promise<Uint8Array | null>;
 
 /**
  * Decodes the embedded PNG/WebP payloads of a `.ctex` with the browser's