@ringozz/godot-web-wasm32 4.7.2-639 → 4.7.2-641

package/README.md

@@ -4,6 +4,10 @@ Godot Engine compiled to **WebAssembly** (`wasm32`, no threads), plus the web ad
 
 On web, `@ringozz/godot` dispatches here and this package initializes the engine with Emscripten + emnapi, binding it to a `<canvas>`.
 
+## Web texture transcoder
+
+`@ringozz/godot-web-wasm32/spark` exports `createSparkTranscoder(helpers)`, the hook `@ringozz/godot`'s web `.ctex` staging installs. It rebuilds an imported texture's embedded PNG/WebP payloads as a device-native block-compressed container with `@ludicon/spark.js` (WebGPU), choosing the format from the staged resource path: normal maps → BC5/EAC-RG, alpha albedo and HDR/sky → BC7/ASTC, terrain weight planes → BC4/EAC-R, colour and ORM → BC1/ETC2 first (each chain falls back to BC7/ASTC, then to the raw RGBA8 decode). Every layer of an array/cubemap is encoded in parallel. The helpers are injected structurally so this package never imports `@ringozz/godot`; `@ludicon/spark.js`'s codec shaders carry a non-commercial EULA (the JS is MIT), so every install pulls it — see `@ringozz/godot`'s README for the licensing note.
+
 ## Symbolizing wasm stack traces
 
 The package ships a symbol map next to the wasm: `gen/godot.web.template_release.wasm32.nothreads.js.symbols`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ringozz/godot-web-wasm32",
   "author": "Vladimir Davidovich",
-  "version": "4.7.2-639",
+  "version": "4.7.2-641",
   "description": "Godot Engine build for @ringozz/godot",
   "publishConfig": {
     "access": "public"

package/src/spark.ts

@@ -17,6 +17,10 @@
 // codec shaders carry a non-commercial EULA (the JS is MIT), so it is part of
 // every install — see the licensing note in `@ringozz/godot`'s README.
 //
+// The block format is chosen from the staged resource path (see
+// {@link pickSparkFormat}); a `.ctex` product keeps the source asset's name
+// (`Rock05_Normal.png.webp-<hash>.ctex`), which is what the rules key on.
+//
 // WebGPU, not spark's WebGL2 (SparkGL) path: WebGL2 has no
 // `getCompressedTexImage`, so sparkGL never exposes the encoded bytes (it reads
 // its block buffer back with `readPixels` internally). Only the WebGPU encoder's
@@ -59,25 +63,34 @@ export interface CtexHelpers {
 	pickGodotFormats(): number[];
 	mipChainLength(width: number, height: number): number;
 	mipLevelDimensions(width: number, height: number, level: number): [number, number];
+	/** Bytes per 4x4 block of a Godot `Image::Format` (see `web-image.ts`). */
+	blockBytes(format: number): number;
 	BLOB_TABLE_OFFSET: number;
+	FORMAT_DXT1: number;
+	FORMAT_RGTC_R: number;
+	FORMAT_RGTC_RG: number;
 	FORMAT_BPTC_RGBA: number;
+	FORMAT_ETC2_R11: number;
+	FORMAT_ETC2_RG11: number;
+	FORMAT_ETC2_RGB8: number;
 	FORMAT_ASTC_4x4: number;
 }
 
-/** The transcoder callback shape installed by `@ringozz/godot`'s `.ctex` staging. */
-export type SparkTranscoder = (bytes: Uint8Array) => Promise<Uint8Array | null>;
+/**
+ * The transcoder callback shape installed by `@ringozz/godot`'s `.ctex` staging.
+ * `path` is the resource path being staged, used to pick the block format.
+ */
+export type SparkTranscoder = (bytes: Uint8Array, path: string) => Promise<Uint8Array | null>;
 
-// Spark needs the exact WebGPU format string to allocate the output texture (it
-// validates the resolved format when `outputMipLevel` is given). Ordered
-// best-first; a target must be both uploadable by the device (Godot's caps, via
-// `pickGodotFormats`) and encodable by spark.
+// One encodable block format: the spark name, the Godot `Image::Format` it maps
+// to, and the exact WebGPU format string spark needs to allocate the output
+// texture (validated when `outputMipLevel` is given).
 interface SparkTarget {
+	name: string;
 	godot: number;
-	spark: string;
 	webgpu: GPUTextureFormat;
 }
 
-const BLOCK_BYTES = 16; // BC7 / ASTC 4x4
 // WebGPU usage flags (TS 7's lib.dom declares the `GPU*` types but not the value
 // namespaces, so spell out the fixed ABI values).
 const BUFFER_COPY_DST = 0x0008;
@@ -90,13 +103,28 @@ const MAP_MODE_READ = 0x0001;
 interface SparkContext {
 	spark: Spark;
 	device: GPUDevice;
-	target: SparkTarget;
+	/** Device ∩ spark-supported targets, in no particular order. */
+	targets: SparkTarget[];
 }
 
-// Lazily created once per page; `null` means WebGPU (or a usable format) is
-// unavailable, so every transcode declines and the raw RGBA8 decode is used.
+// Lazily created once per page; `null` means WebGPU is unavailable, so every
+// transcode declines and the raw RGBA8 decode is used.
 let context: Promise<SparkContext | null> | null = null;
 
+// The format table, built against the Godot constants core passes in.
+function targetTable(ctex: CtexHelpers): SparkTarget[] {
+	return [
+		{ name: 'bc1-rgb', godot: ctex.FORMAT_DXT1, webgpu: 'bc1-rgba-unorm' },
+		{ name: 'bc4-r', godot: ctex.FORMAT_RGTC_R, webgpu: 'bc4-r-unorm' },
+		{ name: 'bc5-rg', godot: ctex.FORMAT_RGTC_RG, webgpu: 'bc5-rg-unorm' },
+		{ name: 'bc7-rgba', godot: ctex.FORMAT_BPTC_RGBA, webgpu: 'bc7-rgba-unorm' },
+		{ name: 'eac-r', godot: ctex.FORMAT_ETC2_R11, webgpu: 'eac-r11unorm' },
+		{ name: 'eac-rg', godot: ctex.FORMAT_ETC2_RG11, webgpu: 'eac-rg11unorm' },
+		{ name: 'etc2-rgb', godot: ctex.FORMAT_ETC2_RGB8, webgpu: 'etc2-rgb8unorm' },
+		{ name: 'astc-4x4-rgba', godot: ctex.FORMAT_ASTC_4x4, webgpu: 'astc-4x4-unorm' },
+	];
+}
+
 function getContext(ctex: CtexHelpers): Promise<SparkContext | null> {
 	context ??= (async () => {
 		const gpu = typeof navigator !== 'undefined' ? navigator.gpu : undefined;
@@ -111,12 +139,8 @@ function getContext(ctex: CtexHelpers): Promise<SparkContext | null> {
 		const device = await adapter.requestDevice({ requiredFeatures: Spark.getRequiredFeatures(adapter) });
 		const spark = await Spark.create(device);
 		const caps = new Set(ctex.pickGodotFormats());
-		const targets: SparkTarget[] = [
-			{ godot: ctex.FORMAT_BPTC_RGBA, spark: 'bc7-rgba', webgpu: 'bc7-rgba-unorm' },
-			{ godot: ctex.FORMAT_ASTC_4x4, spark: 'astc-rgba', webgpu: 'astc-4x4-unorm' },
-		];
-		const target = targets.find((t) => caps.has(t.godot) && spark.isFormatSupported(t.spark));
-		return target ? { spark, device, target } : null;
+		const targets = targetTable(ctex).filter((t) => caps.has(t.godot) && spark.isFormatSupported(t.name));
+		return { spark, device, targets };
 	})().catch((err) => {
 		console.warn('[godot] spark.js unavailable; web textures stay raw RGBA8:', err);
 		return null;
@@ -124,6 +148,48 @@ function getContext(ctex: CtexHelpers): Promise<SparkContext | null> {
 	return context;
 }
 
+// ---------------------------------------------------------------------------
+// File-name -> format rules, mirroring the three.js viewer's policy (Wartales):
+// normals are 2-channel, alpha albedo and the HDR/sky magnitude stay RGBA,
+// terrain weights are 1-channel, and colour + ORM use the smallest 8 B/block
+// format.
+// ---------------------------------------------------------------------------
+
+// `(?<![a-z0-9])`/`(?![a-z0-9])` bound a role token to a name separator without
+// matching it inside a word: `tile_normal`/`normal.webparray` match, `abnormal`
+// and `normalize` do not.
+const RGBA = ['bc7-rgba', 'astc-4x4-rgba'];
+const COLOR = ['bc1-rgb', 'etc2-rgb', ...RGBA];
+
+// Ordered, first match wins. The normal/weight chains keep an RGBA last resort
+// so a role whose single/dual-channel format the device lacks still compresses
+// (Godot rebuilds a normal's z; a weight shader reads `.r`).
+const RULES: { re: RegExp; chain: string[] }[] = [
+	{ re: /albedoalpha/i, chain: RGBA }, // cutout albedo, whose alpha is real
+	{ re: /(?<![a-z0-9])(hdr|skybox|sky|panorama)(?![a-z0-9])/i, chain: RGBA }, // magnitude in alpha
+	{ re: /(?<![a-z0-9])(normal|nrm|normalmap)s?(?![a-z0-9])/i, chain: ['bc5-rg', 'eac-rg', ...RGBA] },
+	{ re: /(?<![a-z0-9])(splat|weight)s?(?![a-z0-9])/i, chain: ['bc4-r', 'eac-r', ...RGBA] },
+];
+
+/**
+ * The block-format preference chain for a staged resource path, most preferred
+ * first. Pure, so it is unit-testable without WebGPU.
+ */
+export function pickSparkFormat(path: string): string[] {
+	return RULES.find((rule) => rule.re.test(path))?.chain ?? COLOR;
+}
+
+// The first chain entry the device can host, or `null` to decline (raw RGBA8).
+function pickTarget(ctx: SparkContext, path: string): SparkTarget | null {
+	for (const name of pickSparkFormat(path)) {
+		const target = ctx.targets.find((t) => t.name === name);
+		if (target) {
+			return target;
+		}
+	}
+	return null;
+}
+
 const align256 = (n: number): number => (n + 255) & ~255;
 
 // Reads every mip level of `texture` into the container's data region. For
@@ -139,6 +205,7 @@ async function readInto(
 	width: number,
 	height: number,
 	levels: number,
+	bytesPerBlock: number,
 ): Promise<void> {
 	// Where each level sits in the readback buffer. Offsets/`bytesPerRow` must be
 	// multiples of the block size; 256 satisfies that and any 4-byte rule.
@@ -149,7 +216,7 @@ async function readInto(
 		const cols = Math.ceil(w / 4);
 		const rows = Math.ceil(h / 4);
 		const offset = align256(total);
-		const stride = align256(cols * BLOCK_BYTES);
+		const stride = align256(cols * bytesPerBlock);
 		layout.push({ offset, stride, cols, rows });
 		total = offset + stride * rows;
 	}
@@ -182,7 +249,7 @@ async function readInto(
 		const view = new Uint8Array(buffer.getMappedRange());
 		let p = dataOffset;
 		for (const { offset, stride, cols, rows } of layout) {
-			const tight = cols * BLOCK_BYTES;
+			const tight = cols * bytesPerBlock;
 			if (stride === tight) {
 				// Unpadded (a power-of-two-ish width): the level's blocks are
 				// contiguous, so copy the whole level in one go rather than a
@@ -213,6 +280,7 @@ const encodable = (layer: { width: number; height: number }): boolean =>
 async function transcodeLayer(
 	ctex: CtexHelpers,
 	ctx: SparkContext,
+	target: SparkTarget,
 	bytes: Uint8Array,
 	layer: CtexLayer,
 	out: Uint8Array,
@@ -225,7 +293,7 @@ async function transcodeLayer(
 	const texture = ctx.device.createTexture({
 		size: [width, height, 1],
 		mipLevelCount: levels,
-		format: ctx.target.webgpu,
+		format: target.webgpu,
 		usage: TEXTURE_BINDING | TEXTURE_COPY_DST | TEXTURE_COPY_SRC,
 	});
 	try {
@@ -233,13 +301,23 @@ async function transcodeLayer(
 			throw new Error(`layer decoded as ${bitmap.width}x${bitmap.height}, expected ${width}x${height}`);
 		}
 		await ctx.spark.encodeTexture(bitmap, {
-			format: ctx.target.spark,
+			format: target.name,
 			mips: true,
 			mipmapCount: levels,
 			outputTexture: texture,
 			outputMipLevel: 0,
 		});
-		await readInto(ctex, ctx.device, texture, out, outOffset, width, height, levels);
+		await readInto(
+			ctex,
+			ctx.device,
+			texture,
+			out,
+			outOffset,
+			width,
+			height,
+			levels,
+			ctex.blockBytes(target.godot),
+		);
 	} finally {
 		bitmap.close();
 		texture.destroy();
@@ -250,7 +328,7 @@ async function transcodeLayer(
 // own output texture), so the GPU queue stays fed and the per-layer round trips
 // overlap instead of stacking. Spark encodes 2D textures, so layers are separate
 // encodes; layer `i`'s `.ctex` body lands at `BLOB_TABLE_OFFSET + i * stride`.
-async function transcode(ctex: CtexHelpers, bytes: Uint8Array): Promise<Uint8Array | null> {
+async function transcode(ctex: CtexHelpers, bytes: Uint8Array, path: string): Promise<Uint8Array | null> {
 	const layers = ctex.parseCtex(bytes);
 	if (!layers || !encodable(layers[0])) {
 		return null; // not PNG/WebP-embedded, or a size spark would have to resize
@@ -259,12 +337,27 @@ async function transcode(ctex: CtexHelpers, bytes: Uint8Array): Promise<Uint8Arr
 	if (!ctx) {
 		return null;
 	}
+	const target = pickTarget(ctx, path);
+	if (!target) {
+		return null; // no encodable format for this texture on this device
+	}
 	const { width, height } = layers[0];
 	const levels = ctex.mipChainLength(width, height);
-	const { bytes: out, stride } = ctex.allocateCtex(bytes, layers.length, width, height, levels - 1, ctx.target.godot);
+	const { bytes: out, stride } = ctex.allocateCtex(bytes, layers.length, width, height, levels - 1, target.godot);
 	await Promise.all(
 		layers.map((layer, i) =>
-			transcodeLayer(ctex, ctx, bytes, layer, out, ctex.BLOB_TABLE_OFFSET + i * stride, width, height, levels),
+			transcodeLayer(
+				ctex,
+				ctx,
+				target,
+				bytes,
+				layer,
+				out,
+				ctex.BLOB_TABLE_OFFSET + i * stride,
+				width,
+				height,
+				levels,
+			),
 		),
 	);
 	return out;
@@ -272,9 +365,10 @@ async function transcode(ctex: CtexHelpers, bytes: Uint8Array): Promise<Uint8Arr
 
 /**
  * Builds the transcoder that `@ringozz/godot` installs for web `.ctex` staging,
- * given its container helpers. Any failure (no WebGPU, unsupported format, decode
- * problem) declines so the caller falls back to the raw RGBA8 decode; it never
- * throws.
+ * given its container helpers. The block format is chosen from the staged
+ * resource path ({@link pickSparkFormat}). Any failure (no WebGPU, no usable
+ * format, decode problem) declines so the caller falls back to the raw RGBA8
+ * decode; it never throws.
  */
 export function createSparkTranscoder(ctex: CtexHelpers): SparkTranscoder {
 	// Kick off the WebGPU device (and the format probe) as soon as the encoder is
@@ -283,9 +377,9 @@ export function createSparkTranscoder(ctex: CtexHelpers): SparkTranscoder {
 	// `.ctex` files behind device creation. `getContext` memoizes, and a failure
 	// just declines every transcode (raw RGBA8 fallback).
 	void getContext(ctex);
-	return async (bytes) => {
+	return async (bytes, path) => {
 		try {
-			return await transcode(ctex, bytes);
+			return await transcode(ctex, bytes, path);
 		} catch (err) {
 			console.warn('[godot] spark transcode failed; using raw RGBA8:', err);
 			return null;