@ringozz/godot 4.7.2-639 → 4.7.2-643

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-643",
   "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-643",
+    "@ringozz/godot-windows-x86_64": "^4.7.2-643",
+    "@ringozz/godot-web-wasm32": "^4.7.2-643"
   },
   "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

@@ -12,8 +12,8 @@
 // a single parse/allocate pair covers everything — a container is just a list of
 // layers.
 //
-// Exposes the container/format helpers, `pickGodotFormats` (probing the WebGL2
-// extensions GLES3 checks) and `decodeCtex` — the default staging path, which
+// Exposes the container/format helpers, `pickGodotFormats` (the driver's
+// compressed-format list) and `decodeCtex` — the default staging path, which
 // decodes the PNG/WebP payloads with the browser and rebuilds a raw RGBA8
 // container so no image codec runs in wasm. The optional compressed-transcode
 // hook lives in load.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);
@@ -181,21 +209,55 @@ export function allocateCtex(
 }
 
 // ---------------------------------------------------------------------------
-// Capability probing. Godot's Compatibility (GLES3) renderer is what the web
-// wasm build uses, and it only uploads a compressed format natively when the
-// matching GL extension is present; this build compiles in NO decompressors, so
-// a format the device can't upload breaks the texture rather than degrading.
-// It selects formats for layered/3D textures exactly as for 2D — the
-// `astc_layered_supported`/`astc_3d_supported` flags it computes are only used
-// to derive `astc_supported`/`astc_hdr_supported` — so this probe covers texture
-// arrays and cubemaps too.
+// Capability probing. GLES3 uploads a compressed format only when its config
+// reports it supported, and this build compiles in NO decompressors, so a format
+// the device can't upload breaks the texture rather than degrading. Ask the
+// driver (`COMPRESSED_TEXTURE_FORMATS`) rather than reading extension names:
+// Chrome on Windows lists no ETC2/EAC and rejects those uploads, while
+// `config.cpp` would still route one to it. RGTC arrays are the one place 2D and
+// layered differ — `_texture_set_data` force-decompresses them for
+// `TEXTURE_2D_ARRAY`, gated here on `Image::can_decompress("s3tc")`.
 // ---------------------------------------------------------------------------
 
+// `CompressedTexture` GL enums -> Godot `Image::Format`, for the targets the
+// encoder can emit; only the unsigned-normal variants (their siblings share it).
+const GL_TO_GODOT_FORMAT: Record<number, number> = {
+	0x83f0: FORMAT_DXT1, // COMPRESSED_RGB_S3TC_DXT1_EXT
+	0x8dbb: FORMAT_RGTC_R, // COMPRESSED_RED_RGTC1_EXT
+	0x8dbd: FORMAT_RGTC_RG, // COMPRESSED_RED_GREEN_RGTC2_EXT
+	0x8e8c: FORMAT_BPTC_RGBA, // COMPRESSED_RGBA_BPTC_UNORM_EXT
+	0x9270: FORMAT_ETC2_R11, // COMPRESSED_R11_EAC
+	0x9272: FORMAT_ETC2_RG11, // COMPRESSED_RG11_EAC
+	0x9274: FORMAT_ETC2_RGB8, // COMPRESSED_RGB8_ETC2
+	0x93b0: FORMAT_ASTC_4x4, // COMPRESSED_RGBA_ASTC_4x4_KHR
+};
+
+/** Enabled before reading the list — a browser may only list a format once its extension is enabled. */
+const PROBED_EXTENSIONS = [
+	'EXT_texture_compression_bptc',
+	'EXT_texture_compression_rgtc',
+	'WEBGL_compressed_texture_s3tc',
+	'WEBGL_compressed_texture_astc',
+	'WEBGL_compressed_texture_etc',
+];
+
+/** The Godot targets among a driver's `COMPRESSED_TEXTURE_FORMATS` list, in list order and deduplicated (pure). */
+export function godotFormatsFor(glFormats: ArrayLike<number>): number[] {
+	const formats = new Set<number>();
+	for (let i = 0; i < glFormats.length; i++) {
+		const godot = GL_TO_GODOT_FORMAT[glFormats[i]!];
+		if (godot !== undefined) {
+			formats.add(godot);
+		}
+	}
+	return [...formats];
+}
+
 /**
- * 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;
@@ -220,28 +282,24 @@ export function pickGodotFormats(): number[] {
 	if (!gl) {
 		return [];
 	}
-	const formats: number[] = [];
 	try {
-		const exts = new Set(gl.getSupportedExtensions() ?? []);
-		if (exts.has('EXT_texture_compression_bptc')) {
-			formats.push(FORMAT_BPTC_RGBA);
-		}
-		if (exts.has('WEBGL_compressed_texture_astc')) {
-			formats.push(FORMAT_ASTC_4x4);
+		for (const name of PROBED_EXTENSIONS) {
+			gl.getExtension(name);
 		}
+		return godotFormatsFor(gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS) as ArrayLike<number>);
 	} finally {
 		// Don't retain the probe context for the page's lifetime.
 		gl.getExtension('WEBGL_lose_context')?.loseContext();
 	}
-	return formats;
 }
 
 /**
  * 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