@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/assets/cubemap-converter.js

@@ -0,0 +1,129 @@
+import { createValidatedShaderModule } from "../render/shader-validator.js";
+const EQUIRECT_TO_CUBEMAP_SHADER = /* wgsl */ `
+struct Uniforms {
+  faceSize: u32,
+  _pad: u32,
+  srcWidth: u32,
+  srcHeight: u32,
+};
+
+@group(0) @binding(0) var srcTex: texture_2d<f32>;
+@group(0) @binding(1) var dstTex: texture_storage_2d_array<rgba16float, write>;
+@group(0) @binding(2) var<uniform> uniforms: Uniforms;
+
+const PI: f32 = 3.141592653589793;
+
+fn faceDirToUV(face: u32, u: f32, v: f32) -> vec3<f32> {
+  let a = u * 2.0 - 1.0;
+  let b = v * 2.0 - 1.0;
+  switch face {
+    case 0u: { return vec3<f32>( 1.0, -b, -a); }  // +X
+    case 1u: { return vec3<f32>(-1.0, -b,  a); }  // -X
+    case 2u: { return vec3<f32>( a,  1.0,  b); }  // +Y
+    case 3u: { return vec3<f32>( a, -1.0, -b); }  // -Y
+    case 4u: { return vec3<f32>( a, -b,  1.0); }  // +Z
+    case 5u: { return vec3<f32>(-a, -b, -1.0); }  // -Z
+    default: { return vec3<f32>(0.0, 0.0, 0.0); }
+  }
+}
+
+fn dirToEquirect(dir: vec3<f32>, srcW: u32, srcH: u32) -> vec2<u32> {
+  let phi = atan2(dir.z, dir.x);
+  let theta = acos(clamp(dir.y, -1.0, 1.0));
+  let u = (phi / (2.0 * PI) + 0.5);
+  let v = theta / PI;
+  return vec2<u32>(u32(u * f32(srcW)), u32(v * f32(srcH)));
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let faceSize = uniforms.faceSize;
+  if (gid.x >= faceSize || gid.y >= faceSize) {
+    return;
+  }
+
+  let face = gid.z;
+  let u = (f32(gid.x) + 0.5) / f32(faceSize);
+  let v = (f32(gid.y) + 0.5) / f32(faceSize);
+
+  let dir = normalize(faceDirToUV(face, u, v));
+  let srcCoord = dirToEquirect(dir, uniforms.srcWidth, uniforms.srcHeight);
+
+  let color = textureLoad(srcTex, srcCoord, 0);
+  textureStore(dstTex, vec2<i32>(i32(gid.x), i32(gid.y)), i32(face), color);
+}
+`;
+export class EquirectToCubemapConverter {
+    device;
+    pipeline = null;
+    bindGroupLayout = null;
+    uniformBuffer = null;
+    constructor(device) {
+        this.device = device;
+    }
+    ensurePipeline() {
+        if (this.pipeline)
+            return;
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: "float" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d-array" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+            ],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: EQUIRECT_TO_CUBEMAP_SHADER, label: "CubemapConverter" });
+        const pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout],
+        });
+        this.pipeline = this.device.createComputePipeline({
+            layout: pipelineLayout,
+            compute: { module: shaderModule, entryPoint: "cs_main" },
+        });
+        this.uniformBuffer = this.device.createBuffer({
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    convert(srcTexture, options) {
+        this.ensurePipeline();
+        const faceSize = options.faceSize;
+        const dstFormat = options.dstFormat ?? "rgba16float";
+        const dstTexture = this.device.createTexture({
+            size: [faceSize, faceSize, 6],
+            format: dstFormat,
+            usage: GPUTextureUsage.STORAGE_BINDING |
+                GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_SRC,
+        });
+        const srcView = srcTexture.createView({
+            dimension: "2d",
+        });
+        const dstView = dstTexture.createView({
+            dimension: "2d-array",
+        });
+        const uniformData = new Uint32Array(4);
+        uniformData[0] = faceSize;
+        uniformData[1] = 0;
+        uniformData[2] = srcTexture.width;
+        uniformData[3] = srcTexture.height;
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, uniformData);
+        const bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: srcView },
+                { binding: 1, resource: dstView },
+                { binding: 2, resource: { buffer: this.uniformBuffer } },
+            ],
+        });
+        const encoder = this.device.createCommandEncoder();
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, bindGroup);
+        const workgroupsX = Math.ceil(faceSize / 8);
+        const workgroupsY = Math.ceil(faceSize / 8);
+        pass.dispatchWorkgroups(workgroupsX, workgroupsY, 6);
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+        return dstTexture;
+    }
+}

package/dist/core/src/assets/environment-manager.js

@@ -0,0 +1,84 @@
+import { EquirectToCubemapConverter } from "./cubemap-converter.js";
+import { IrradianceGenerator } from "./irradiance-generator.js";
+import { createEquirectangularGPUTexture, createGPUCubemap, loadCubemapFromFiles } from "./loader-cubemap.js";
+import { loadHDRFile } from "./loader-hdr.js";
+import { PrefilteredSpecularGenerator } from "./prefilter-generator.js";
+export class EnvironmentManager {
+    device;
+    equirectConverter;
+    irradianceGen;
+    prefilterGen;
+    faceSize;
+    prefilterLevels;
+    prefilterSamples;
+    currentEnv = null;
+    constructor(options) {
+        this.device = options.device;
+        this.equirectConverter = new EquirectToCubemapConverter(this.device);
+        this.irradianceGen = new IrradianceGenerator(this.device);
+        this.prefilterGen = new PrefilteredSpecularGenerator(this.device);
+        this.faceSize = options.faceSize ?? 256;
+        this.prefilterLevels = options.prefilterLevels ?? 5;
+        this.prefilterSamples = options.prefilterSamples ?? 512;
+    }
+    async loadFromEquirectangular(uri) {
+        const texData = await loadHDRFile(uri);
+        if (!texData)
+            throw new Error(`Failed to load HDR file: ${uri}`);
+        const equirectTex = createEquirectangularGPUTexture(this.device, texData, "rgba16float");
+        const cubemap = this.equirectConverter.convert(equirectTex, {
+            faceSize: this.faceSize,
+        });
+        equirectTex.destroy();
+        return this.generateIBLMaps(cubemap);
+    }
+    async loadFromCubemapFiles(faceUris) {
+        const cubemapData = await loadCubemapFromFiles(faceUris);
+        const cubemap = createGPUCubemap(this.device, cubemapData, "rgba16float");
+        return this.generateIBLMaps(cubemap);
+    }
+    async loadFromHDRData(texData) {
+        const equirectTex = createEquirectangularGPUTexture(this.device, texData, "rgba16float");
+        const cubemap = this.equirectConverter.convert(equirectTex, {
+            faceSize: this.faceSize,
+        });
+        equirectTex.destroy();
+        return this.generateIBLMaps(cubemap);
+    }
+    generateIBLMaps(cubemap) {
+        const irradiance = this.irradianceGen.generate(cubemap, {
+            faceSize: 32,
+        });
+        const prefilteredSpecular = this.prefilterGen.generateMipmapChain(cubemap, this.faceSize, this.prefilterLevels, this.prefilterSamples);
+        const envMap = {
+            cubemap,
+            irradiance,
+            prefilteredSpecular,
+            prefilteredMaxMip: this.prefilterLevels - 1,
+            brdfLUT: null,
+            faceSize: this.faceSize,
+        };
+        this.currentEnv = envMap;
+        return envMap;
+    }
+    getCurrentEnvironment() {
+        return this.currentEnv;
+    }
+    setBRDFLUT(lut) {
+        if (this.currentEnv) {
+            // Destroy the previous BRDF LUT texture before overwriting to avoid a leak.
+            this.currentEnv.brdfLUT?.destroy();
+            this.currentEnv.brdfLUT = lut;
+        }
+    }
+    destroy() {
+        if (!this.currentEnv)
+            return;
+        this.currentEnv.cubemap.destroy();
+        this.currentEnv.irradiance.destroy();
+        this.currentEnv.prefilteredSpecular.forEach((tex) => {
+            tex.destroy();
+        });
+        this.currentEnv = null;
+    }
+}

package/dist/core/src/assets/import-cache.js

@@ -0,0 +1,36 @@
+// ============================================================================
+// Import Cache — caches resolved ImportSettings keyed by model path
+// ============================================================================
+// The cache eliminates repeated sidecar resolution + HTTP requests on
+// subsequent loads of the same model. Two implementations:
+//   - MemoryImportCache: in-process Map, used in browser-only mode
+//   - SQLiteImportCache: persistent, used on the native host
+//
+// The cache is keyed by model file path. Entries are invalidated when the
+// source file or sidecar mtime changes.
+//
+/**
+ * In-memory import cache. Used when no host cache store is available or as
+ * a fallback when SQLite is unavailable. Does not persist across restarts.
+ */
+export class MemoryImportCache {
+    cache = new Map();
+    get(modelPath) {
+        return this.cache.get(modelPath) ?? null;
+    }
+    set(modelPath, entry) {
+        this.cache.set(modelPath, entry);
+    }
+    invalidate(modelPath) {
+        this.cache.delete(modelPath);
+    }
+    close() {
+        this.cache.clear();
+    }
+}
+/**
+ * Check if a cache entry is still valid given current file mtimes.
+ */
+export function isCacheEntryValid(entry, sourceMtime, sidecarMtime) {
+    return entry.sourceMtime === sourceMtime && entry.sidecarMtime === sidecarMtime;
+}

package/dist/core/src/assets/import-settings.js

@@ -0,0 +1,34 @@
+// ============================================================================
+// Import Settings — per-model normalization configuration (core types)
+// ============================================================================
+// These settings control how a model is normalized at import time:
+// up-axis conversion, unit scaling, node-transform baking, centering, auto-fit.
+//
+// Defined in core (not plugin-models) so the ImportCache can store them
+// without a cross-package dependency. Module-models re-exports these.
+//
+export function createDefaultImportSettings(parserUpAxis, parserUnits) {
+    return {
+        upAxis: parserUpAxis ?? "y",
+        units: parserUnits ?? "meters",
+        scale: 1.0,
+        rotation: [0, 0, 0, 1],
+        centerToOrigin: false,
+        autoFit: null,
+        nodeTransforms: "apply",
+        source: "default",
+    };
+}
+/** Merge two ImportSettings, with `override` taking priority on non-undefined fields. */
+export function mergeImportSettings(base, override, source) {
+    return {
+        upAxis: override.upAxis ?? base.upAxis,
+        units: override.units ?? base.units,
+        scale: override.scale ?? base.scale,
+        rotation: override.rotation ?? base.rotation,
+        centerToOrigin: override.centerToOrigin ?? base.centerToOrigin,
+        autoFit: override.autoFit ?? base.autoFit,
+        nodeTransforms: override.nodeTransforms ?? base.nodeTransforms,
+        source,
+    };
+}

package/dist/core/src/assets/importer.js

@@ -0,0 +1,78 @@
+export class AssetImporter {
+    loader;
+    constructor(loader) {
+        this.loader = loader;
+    }
+    async importGLB(data, options) {
+        const warnings = [];
+        const { meshes, nodes } = await this.loader.parseGLB(data);
+        // Apply scale: bake into vertex positions (uniform scale).
+        let processedMeshes = meshes;
+        if (options?.scale && options.scale !== 1) {
+            const s = options.scale;
+            processedMeshes.forEach((mesh) => {
+                const verts = mesh.vertices;
+                // Engine MeshData vertices are interleaved; position is at offset 0
+                // per vertex. The stride depends on the layout. We use the layout
+                // stride to find position offsets.
+                const stride = mesh.layout.stride / 4; // floats per vertex
+                for (let i = 0; i < mesh.vertexCount; i++) {
+                    const base = i * stride;
+                    verts[base + 0] *= s;
+                    verts[base + 1] *= s;
+                    verts[base + 2] *= s;
+                }
+            });
+        }
+        // Apply flipY: when flipY === false, flip UV V coordinate (1 - v).
+        // Default (flipY true/undefined) leaves UVs as-is (glTF convention).
+        if (options?.flipY === false) {
+            // UVs are not stored separately in engine MeshData; they're interleaved
+            // at offset 6-7 per vertex. Flip the V component.
+            processedMeshes.forEach((mesh) => {
+                const verts = mesh.vertices;
+                const stride = mesh.layout.stride / 4;
+                for (let i = 0; i < mesh.vertexCount; i++) {
+                    const base = i * stride;
+                    verts[base + 7] = 1 - verts[base + 7];
+                }
+            });
+        }
+        // Build a GLTFDocument-shaped object that retains mesh/node counts.
+        const document = {
+            asset: { version: "2.0" },
+            meshes: processedMeshes.map((m, i) => ({
+                name: `mesh_${i}`,
+                primitives: [{ attributes: {}, mode: 4 }],
+            })),
+            nodes,
+        };
+        return {
+            document,
+            model: { meshes: processedMeshes, nodes, name: "imported", format: "glb" },
+            binaryBuffer: null,
+            warnings,
+        };
+    }
+    async importGLTF(json, binaryData) {
+        const warnings = [];
+        const doc = json;
+        if (!doc.asset || !doc.asset.version) {
+            warnings.push("Missing asset.version in GLTF document.");
+        }
+        if (doc.asset?.version && !doc.asset.version.startsWith("2.")) {
+            warnings.push(`GLTF version ${doc.asset.version} — only 2.x is fully supported.`);
+        }
+        const { meshes, nodes } = await this.loader.parseGLTFJSON(doc);
+        return {
+            document: doc,
+            model: { meshes, nodes, name: "imported", format: "gltf" },
+            binaryBuffer: binaryData ? new Uint8Array(binaryData) : null,
+            warnings,
+        };
+    }
+    supportsFormat(extension) {
+        const ext = extension.toLowerCase().replace(".", "");
+        return ext === "glb" || ext === "gltf";
+    }
+}

package/dist/core/src/assets/index.js

@@ -0,0 +1,29 @@
+// Assets sub-barrel — re-exports all asset-related items.
+export { GPUResourceCache } from "./cache.js";
+export { EquirectToCubemapConverter } from "./cubemap-converter.js";
+export { EnvironmentManager } from "./environment-manager.js";
+export { AssetImporter } from "./importer.js";
+export { IrradianceGenerator } from "./irradiance-generator.js";
+export { detectAudioFormat, loadAudioFile, loadAudioFromBuffer, registerAudioLoader } from "./loader-audio.js";
+export { createEquirectangularGPUTexture, createGPUCubemap, loadCubemapFromDirectory, loadCubemapFromFiles } from "./loader-cubemap.js";
+export { loadDDSFromBuffer, loadDDSTexture, parseDDS } from "./loader-dds.js";
+export { loadEXRTexture, loadHDRFile, loadHDRTexture, parseEXR, parseHDR } from "./loader-hdr.js";
+export { GLBLoader } from "./loader-mesh.js";
+export { ShaderLoader } from "./loader-shader.js";
+export { createGPUTextureFromData, createSampler, detectTextureFormat, loadKTX2Texture, loadTexture, loadTextureFromImage, parseKTX2FromBuffer } from "./loader-texture.js";
+export { LODGenerator } from "./lod.js";
+export { AssetManager } from "./manager.js";
+export { bridgeMaterial, bridgeMaterials } from "./material-bridge.js";
+export { importMaterial, importModel, importSingleMesh } from "./model-importer.js";
+export { destroyGPUMesh, uploadMeshesToGPU, uploadMeshToGPU } from "./model-to-gpu.js";
+export { convertPluginMesh, convertPluginModel } from "./model-to-mesh.js";
+// Model normalization — transform math for import-time correction
+export { applyRootRotation, applyRootScale, applyUnitScale, applyUpAxisConversion, autoFit, centerToOrigin, computeBounds, isExtremeScale, maxDimension, UNIT_TO_METERS } from "./model-normalizer.js";
+// Import settings — per-model normalization configuration
+export { createDefaultImportSettings, mergeImportSettings } from "./import-settings.js";
+// Import cache — caches resolved ImportSettings keyed by model path
+export { isCacheEntryValid, MemoryImportCache } from "./import-cache.js";
+export { PrefilteredSpecularGenerator } from "./prefilter-generator.js";
+// Blob Storage & Asset Manifest
+export { makeBlobUri, parseBlobUri } from "./blob-store.js";
+export { createEmptyManifest, DEFAULT_CACHE_DIR, MANIFEST_FILENAME, packCacheKey, validateManifest } from "./manifest.js";

package/dist/core/src/assets/irradiance-generator.js

@@ -0,0 +1,179 @@
+import { createValidatedShaderModule } from "../render/shader-validator.js";
+const IRRADIANCE_SHADER = /* wgsl */ `
+struct Uniforms {
+  faceSize: u32,
+  sampleCount: u32,
+  _pad0: u32,
+  _pad1: u32,
+};
+
+@group(0) @binding(0) var srcTex: texture_2d_array<f32>;
+@group(0) @binding(1) var dstTex: texture_storage_2d_array<rgba16float, write>;
+@group(0) @binding(2) var<uniform> uniforms: Uniforms;
+@group(0) @binding(3) var srcSampler: sampler;
+
+const PI: f32 = 3.141592653589793;
+
+fn faceDirToUV(face: u32, u: f32, v: f32) -> vec3<f32> {
+  let a = u * 2.0 - 1.0;
+  let b = v * 2.0 - 1.0;
+  switch face {
+    case 0u: { return vec3<f32>( 1.0, -b, -a); }
+    case 1u: { return vec3<f32>(-1.0, -b,  a); }
+    case 2u: { return vec3<f32>( a,  1.0,  b); }
+    case 3u: { return vec3<f32>( a, -1.0, -b); }
+    case 4u: { return vec3<f32>( a, -b,  1.0); }
+    case 5u: { return vec3<f32>(-a, -b, -1.0); }
+    default: { return vec3<f32>(0.0, 0.0, 0.0); }
+  }
+}
+
+fn dirToFaceUV(dir: vec3<f32>) -> vec3<f32> {
+  let absX = abs(dir.x);
+  let absY = abs(dir.y);
+  let absZ = abs(dir.z);
+
+  var face: u32 = 0u;
+  var ma: f32 = 0.0;
+  var sc: f32 = 0.0;
+  var tc: f32 = 0.0;
+
+  if (absX > absY && absX > absZ) {
+    if (dir.x > 0.0) { face = 0u; sc = -dir.z; tc = -dir.y; ma = dir.x; }
+    else { face = 1u; sc = dir.z; tc = -dir.y; ma = -dir.x; }
+  } else if (absY > absZ) {
+    if (dir.y > 0.0) { face = 2u; sc = dir.x; tc = dir.z; ma = dir.y; }
+    else { face = 3u; sc = dir.x; tc = -dir.z; ma = -dir.y; }
+  } else {
+    if (dir.z > 0.0) { face = 4u; sc = dir.x; tc = -dir.y; ma = dir.z; }
+    else { face = 5u; sc = -dir.x; tc = -dir.y; ma = -dir.z; }
+  }
+
+  let u = (sc / ma + 1.0) * 0.5;
+  let v = (tc / ma + 1.0) * 0.5;
+  return vec3<f32>(u, v, f32(face));
+}
+
+fn sampleCubemap(dir: vec3<f32>) -> vec3<f32> {
+  let info = dirToFaceUV(dir);
+  let face = u32(info.z);
+  let u = info.x;
+  let v = info.y;
+  let coords = vec2<i32>(i32(u * f32(textureDimensions(srcTex, 0).x)), i32(v * f32(textureDimensions(srcTex, 0).y)));
+  return textureLoad(srcTex, coords, i32(face), 0).rgb;
+}
+
+fn tangentToWorld(N: vec3<f32>, tangent: vec3<f32>, bitangent: vec3<f32>, sample: vec3<f32>) -> vec3<f32> {
+  return normalize(tangent * sample.x + bitangent * sample.y + N * sample.z);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let faceSize = uniforms.faceSize;
+  if (gid.x >= faceSize || gid.y >= faceSize) { return; }
+
+  let face = gid.z;
+  let u = (f32(gid.x) + 0.5) / f32(faceSize);
+  let v = (f32(gid.y) + 0.5) / f32(faceSize);
+  let N = normalize(faceDirToUV(face, u, v));
+
+  let up = select(vec3<f32>(0.0, 1.0, 0.0), vec3<f32>(1.0, 0.0, 0.0), abs(N.y) > 0.999);
+  let tangent = normalize(cross(up, N));
+  let bitangent = cross(N, tangent);
+
+  var irradiance = vec3<f32>(0.0);
+  var sampleCount = 0u;
+
+  let phiSteps = 64u;
+  let thetaSteps = 32u;
+
+  for (var phiStep = 0u; phiStep < phiSteps; phiStep++) {
+    for (var thetaStep = 0u; thetaStep < thetaSteps; thetaStep++) {
+      let phi = (f32(phiStep) + 0.5) / f32(phiSteps) * 2.0 * PI;
+      let theta = (f32(thetaStep) + 0.5) / f32(thetaSteps) * 0.5 * PI;
+
+      let tangentSample = vec3<f32>(
+        sin(theta) * cos(phi),
+        sin(theta) * sin(phi),
+        cos(theta),
+      );
+
+      let sampleVec = tangentToWorld(N, tangent, bitangent, tangentSample);
+      irradiance += sampleCubemap(sampleVec) * cos(theta);
+      sampleCount++;
+    }
+  }
+
+  irradiance = irradiance * PI / f32(sampleCount);
+  textureStore(dstTex, vec2<i32>(i32(gid.x), i32(gid.y)), i32(face), vec4<f32>(irradiance, 1.0));
+}
+`;
+export class IrradianceGenerator {
+    device;
+    pipeline = null;
+    bindGroupLayout = null;
+    uniformBuffer = null;
+    sampler = null;
+    constructor(device) {
+        this.device = device;
+    }
+    ensurePipeline() {
+        if (this.pipeline)
+            return;
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: "float", viewDimension: "2d-array" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d-array" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, sampler: { type: "filtering" } },
+            ],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: IRRADIANCE_SHADER, label: "IrradianceGenerator" });
+        this.pipeline = this.device.createComputePipeline({
+            layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+            compute: { module: shaderModule, entryPoint: "cs_main" },
+        });
+        this.uniformBuffer = this.device.createBuffer({
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    generate(srcCubemap, options) {
+        this.ensurePipeline();
+        const faceSize = options.faceSize;
+        const dstTexture = this.device.createTexture({
+            size: [faceSize, faceSize, 6],
+            format: "rgba16float",
+            usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        const srcView = srcCubemap.createView({ dimension: "2d-array" });
+        const dstView = dstTexture.createView({ dimension: "2d-array" });
+        const uniformData = new Uint32Array(4);
+        uniformData[0] = faceSize;
+        uniformData[1] = 0;
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, uniformData);
+        const sampler = this.sampler ??= this.device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+        });
+        const bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: srcView },
+                { binding: 1, resource: dstView },
+                { binding: 2, resource: { buffer: this.uniformBuffer } },
+                { binding: 3, resource: sampler },
+            ],
+        });
+        const encoder = this.device.createCommandEncoder();
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.dispatchWorkgroups(Math.ceil(faceSize / 8), Math.ceil(faceSize / 8), 6);
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+        // GPUSampler has no destroy() — it's lightweight and GC'd. Cached on the
+        // instance via ??= above to avoid per-call allocation.
+        return dstTexture;
+    }
+}

package/dist/core/src/assets/loader-audio.js

@@ -0,0 +1,70 @@
+const EXTENSION_FORMAT_MAP = {
+    wav: "wav",
+    wave: "wav",
+    ogg: "ogg",
+    oga: "ogg",
+    mp3: "mp3",
+    flac: "flac",
+};
+export function detectAudioFormat(uri) {
+    const ext = uri.split(".").pop()?.toLowerCase() ?? "";
+    return EXTENSION_FORMAT_MAP[ext] ?? null;
+}
+export async function loadAudioFile(uri, engine) {
+    const format = detectAudioFormat(uri);
+    if (!format) {
+        throw new Error(`Unsupported audio format: ${uri}`);
+    }
+    // Lazy node:fs import — this module is reachable from the browser-side
+    // barrel, so node builtins must not be evaluated at import time. Fall back
+    // to fetch() when fs is unavailable (browser/worker realms).
+    let fsPromises = null;
+    try {
+        fsPromises = (await import("node:fs")).promises;
+    }
+    catch {
+        // node:fs unavailable (browser bundle) — use fetch below.
+    }
+    let data;
+    if (fsPromises) {
+        const buf = await fsPromises.readFile(uri);
+        data = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    }
+    else {
+        const res = await fetch(uri);
+        if (!res.ok)
+            throw new Error(`Failed to load audio "${uri}": HTTP ${res.status}`);
+        data = await res.arrayBuffer();
+    }
+    const desc = {
+        id: uri,
+        format,
+        samples: new Float32Array(data.byteLength / 4),
+    };
+    const view = new DataView(data);
+    for (let i = 0; i < desc.samples.length; i++) {
+        desc.samples[i] = view.getFloat32(i * 4, true);
+    }
+    engine.loadBuffer(desc);
+    return desc;
+}
+export async function loadAudioFromBuffer(format, data, engine) {
+    const desc = {
+        id: `buffer-${Date.now()}`,
+        format,
+        samples: new Float32Array(data.byteLength / 4),
+    };
+    const view = new DataView(data);
+    for (let i = 0; i < desc.samples.length; i++) {
+        desc.samples[i] = view.getFloat32(i * 4, true);
+    }
+    engine.loadBuffer(desc);
+    return desc;
+}
+export function registerAudioLoader(manager, engine) {
+    for (const ext of Object.keys(EXTENSION_FORMAT_MAP)) {
+        manager.registerLoader(ext, async (uri) => {
+            return loadAudioFile(uri, engine);
+        });
+    }
+}