@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/assets/index.d.ts

@@ -0,0 +1,20 @@
+export type { AtlasDrawContext, AtlasLayout, AtlasOptions, AtlasPixels, AtlasRect, AtlasSource, AtlasTexture, AtlasTextureOptions, } from './atlas.js';
+export { createAtlasTexture, extrudePixels, packAtlas } from './atlas.js';
+export type { BakeKind, BakeManifest, BakeManifestEntry } from './baked.js';
+export { BAKE_MANIFEST_VERSION, readBakeManifest } from './baked.js';
+export type { AssetReader, AudioDecoder, Bundle, BundleError, BundleEvents, BundleOptions, BundleProgress, ReadResult, } from './bundle.js';
+export { createBundle } from './bundle.js';
+export type { AssetCache, AssetCacheOptions, AssetCacheStats } from './cache.js';
+export { createAssetCache } from './cache.js';
+export type { GltfAccessorType, GltfAlphaMode, GltfAnimation, GltfAnimationChannel, GltfAnimationPath, GltfBounds, GltfCamera, GltfClearcoat, GltfComponentType, GltfDocument, GltfFilter, GltfImage, GltfInterpolation, GltfIor, GltfJson, GltfJsonAccessor, GltfJsonAnimation, GltfJsonAnimationChannel, GltfJsonAnimationSampler, GltfJsonBufferView, GltfJsonCamera, GltfJsonInterpolation, GltfJsonLight, GltfJsonMaterial, GltfJsonMesh, GltfJsonMeshoptView, GltfJsonNode, GltfJsonPrimitive, GltfJsonSkin, GltfJsonSource, GltfJsonSparse, GltfJsonTextureInfo, GltfJsonTextureTransform, GltfJsonVariantMapping, GltfLight, GltfMaterial, GltfMaterialExtensions, GltfMesh, GltfMorphTarget, GltfNode, GltfPrimitive, GltfSampler, GltfSheen, GltfSkin, GltfSpecular, GltfTexture, GltfTextureTransform, GltfTransmission, GltfVariantMapping, GltfVolume, GltfWrap, TextureRef, Vec3, Vec4, } from './gltf.js';
+export { composeTrs, decodeDataUri, GltfError, parseGltf, transformUv } from './gltf.js';
+export type { GltfImageSource, GltfLitMode, GltfMorph, GltfSceneLights, GltfSceneNode, LoadGltfOptions, } from './gltf-load.js';
+export { applyGltfCamera, GLTF_LIT_WGSL, GltfScene, gltfSamplerKind, interleave3d, interleave3dTangent, loadGltf, } from './gltf-load.js';
+export type { GltfSkeleton, SkinnedVertices } from './gltf-skin.js';
+export { interleaveSkinned, skeletonFromSkin } from './gltf-skin.js';
+export type { Ktx2DataFormat, Ktx2Level, Ktx2Supercompression, Ktx2Texture, } from './ktx2.js';
+export { isKtx2, Ktx2Error, ktx2ToWebGpuFormat, parseKtx2 } from './ktx2.js';
+export type { AssetKind, AssetOf, AtlasAsset, AtlasEntry, AudioEntry, BytesEntry, GltfEntry, ImageEntry, JsonEntry, Manifest, ManifestEntry, TextEntry, TextureArrayEntry, TextureEntry, } from './manifest.js';
+export { defineManifest } from './manifest.js';
+export type { MeshoptFilter, MeshoptMode } from './meshopt.js';
+export { decodeMeshopt, MeshoptError } from './meshopt.js';

package/dist/assets/index.js

@@ -0,0 +1,10 @@
+export { createAtlasTexture, extrudePixels, packAtlas } from './atlas.js';
+export { BAKE_MANIFEST_VERSION, readBakeManifest } from './baked.js';
+export { createBundle } from './bundle.js';
+export { createAssetCache } from './cache.js';
+export { composeTrs, decodeDataUri, GltfError, parseGltf, transformUv } from './gltf.js';
+export { applyGltfCamera, GLTF_LIT_WGSL, GltfScene, gltfSamplerKind, interleave3d, interleave3dTangent, loadGltf, } from './gltf-load.js';
+export { interleaveSkinned, skeletonFromSkin } from './gltf-skin.js';
+export { isKtx2, Ktx2Error, ktx2ToWebGpuFormat, parseKtx2 } from './ktx2.js';
+export { defineManifest } from './manifest.js';
+export { decodeMeshopt, MeshoptError } from './meshopt.js';

package/dist/assets/ktx2.d.ts

@@ -0,0 +1,71 @@
+/**
+ * KTX2 container reader: header, level index and the basic data format descriptor of a
+ * `.ktx2` file, each mip level as a view into the file's bytes (nothing copied). It reads the
+ * container only: Zstd / ZLIB-supercompressed levels and BasisLZ / UASTC Basis payloads are
+ * detected and reported (`supercompression`, no `levels`), not decoded, and nothing is
+ * uploaded (that needs a compressed-format texture path in `render`).
+ *
+ * `ktx2ToWebGpuFormat(vkFormat)` names the WebGPU format a level's bytes are in, when there is
+ * one (BC needs the `texture-compression-bc` device feature, ETC2 / EAC `-etc2`, ASTC `-astc`).
+ */
+/** Malformed or truncated KTX2 data. */
+export declare class Ktx2Error extends Error {
+    constructor(message: string);
+}
+/** `supercompressionScheme`: how the levels are packed on top of `vkFormat`. */
+export type Ktx2Supercompression = 'none' | 'basislz' | 'zstd' | 'zlib';
+/** One mip level: its bytes (a view into the file) and its size in texels. */
+export interface Ktx2Level {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+}
+/** The basic data format descriptor's colour fields (Khronos Data Format spec). */
+export interface Ktx2DataFormat {
+    /** `KHR_DF_MODEL_*`: 1 RGBSDA, 128+ block-compressed (BC1 128, BC7 135, ETC2 161, ASTC 162), 166 UASTC, 163 ETC1S. */
+    colorModel: number;
+    /** `KHR_DF_PRIMARIES_*`: 1 BT.709 / sRGB. */
+    colorPrimaries: number;
+    /** `KHR_DF_TRANSFER_*`: 1 linear, 2 sRGB. */
+    transferFunction: number;
+    /** `KHR_DF_FLAG_*`: bit 0 premultiplied alpha. */
+    flags: number;
+}
+/** A parsed KTX2 file. */
+export interface Ktx2Texture {
+    /** The Vulkan `VkFormat` of the level data (0 `VK_FORMAT_UNDEFINED` for Basis payloads). */
+    vkFormat: number;
+    /** Bytes per component for uncompressed formats (1 for block-compressed ones). */
+    typeSize: number;
+    width: number;
+    /** 0 for a 1D texture. */
+    height: number;
+    /** 0 for a 1D or 2D texture. */
+    depth: number;
+    /** 0 when the texture is not an array. */
+    layers: number;
+    /** 6 for a cube map, else 1. */
+    faces: number;
+    /**
+     * Mip levels, largest first; each holds every layer and face of that level. Empty when
+     * `supercompression` is not `'none'` (the payload needs a decoder this reader does not have).
+     */
+    levels: Ktx2Level[];
+    /** How many levels the file says it has (1 when it asks the reader to generate mips). */
+    levelCount: number;
+    /** The basic descriptor's colour fields, or null when the file has none. */
+    dataFormat: Ktx2DataFormat | null;
+    supercompression: Ktx2Supercompression;
+}
+/** True when `bytes` starts with the KTX2 identifier. */
+export declare function isKtx2(bytes: Uint8Array): boolean;
+/**
+ * Read a KTX2 file's header, data format and levels. Throws `Ktx2Error` for a bad identifier,
+ * a truncated file or a level that runs past the end.
+ */
+export declare function parseKtx2(bytes: Uint8Array): Ktx2Texture;
+/**
+ * The WebGPU texture format a `VkFormat` stores, or null when WebGPU has none (or the file
+ * holds a Basis payload, `vkFormat` 0, that must be transcoded first).
+ */
+export declare function ktx2ToWebGpuFormat(vkFormat: number): GPUTextureFormat | null;

package/dist/assets/ktx2.js

@@ -0,0 +1,213 @@
+/**
+ * KTX2 container reader: header, level index and the basic data format descriptor of a
+ * `.ktx2` file, each mip level as a view into the file's bytes (nothing copied). It reads the
+ * container only: Zstd / ZLIB-supercompressed levels and BasisLZ / UASTC Basis payloads are
+ * detected and reported (`supercompression`, no `levels`), not decoded, and nothing is
+ * uploaded (that needs a compressed-format texture path in `render`).
+ *
+ * `ktx2ToWebGpuFormat(vkFormat)` names the WebGPU format a level's bytes are in, when there is
+ * one (BC needs the `texture-compression-bc` device feature, ETC2 / EAC `-etc2`, ASTC `-astc`).
+ */
+/** Malformed or truncated KTX2 data. */
+export class Ktx2Error extends Error {
+    constructor(message) {
+        super(`ktx2: ${message}`);
+        this.name = 'Ktx2Error';
+    }
+}
+const IDENTIFIER = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
+const HEADER_BYTES = 80;
+const LEVEL_INDEX_BYTES = 24;
+const SCHEMES = ['none', 'basislz', 'zstd', 'zlib'];
+/** True when `bytes` starts with the KTX2 identifier. */
+export function isKtx2(bytes) {
+    if (bytes.byteLength < IDENTIFIER.length)
+        return false;
+    for (let i = 0; i < IDENTIFIER.length; i++)
+        if (bytes[i] !== IDENTIFIER[i])
+            return false;
+    return true;
+}
+/**
+ * Read a KTX2 file's header, data format and levels. Throws `Ktx2Error` for a bad identifier,
+ * a truncated file or a level that runs past the end.
+ */
+export function parseKtx2(bytes) {
+    if (!isKtx2(bytes))
+        throw new Ktx2Error('not a KTX2 file (bad identifier)');
+    if (bytes.byteLength < HEADER_BYTES)
+        throw new Ktx2Error('truncated header');
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const u32 = (at) => dv.getUint32(at, true);
+    const u64 = (at) => {
+        const hi = dv.getUint32(at + 4, true);
+        if (hi !== 0)
+            throw new Ktx2Error(`offset at byte ${at} does not fit in 32 bits`);
+        return dv.getUint32(at, true);
+    };
+    const vkFormat = u32(12);
+    const typeSize = u32(16);
+    const width = u32(20);
+    const height = u32(24);
+    const depth = u32(28);
+    const layers = u32(32);
+    const faces = u32(36);
+    const levelCount = Math.max(1, u32(40));
+    const scheme = u32(44);
+    const supercompression = SCHEMES[scheme];
+    if (!supercompression)
+        throw new Ktx2Error(`supercompression scheme ${scheme} unknown`);
+    if (width === 0)
+        throw new Ktx2Error('pixelWidth is 0');
+    if (faces !== 1 && faces !== 6)
+        throw new Ktx2Error(`faceCount ${faces} must be 1 or 6`);
+    const dfdOffset = u32(48);
+    const dfdLength = u32(52);
+    if (HEADER_BYTES + levelCount * LEVEL_INDEX_BYTES > bytes.byteLength) {
+        throw new Ktx2Error('truncated level index');
+    }
+    let dataFormat = null;
+    // DFD: u32 total size, then the basic block: two u32 words, then the colour bytes.
+    if (dfdLength >= 16) {
+        if (dfdOffset + dfdLength > bytes.byteLength)
+            throw new Ktx2Error('data format runs past the end');
+        dataFormat = {
+            colorModel: bytes[dfdOffset + 12],
+            colorPrimaries: bytes[dfdOffset + 13],
+            transferFunction: bytes[dfdOffset + 14],
+            flags: bytes[dfdOffset + 15],
+        };
+    }
+    const levels = [];
+    if (supercompression === 'none') {
+        for (let i = 0; i < levelCount; i++) {
+            const at = HEADER_BYTES + i * LEVEL_INDEX_BYTES;
+            const off = u64(at);
+            const len = u64(at + 8);
+            if (off + len > bytes.byteLength)
+                throw new Ktx2Error(`level ${i} runs past the end`);
+            levels.push({
+                bytes: bytes.subarray(off, off + len),
+                width: Math.max(1, width >> i),
+                height: Math.max(1, height >> i),
+            });
+        }
+    }
+    return {
+        vkFormat,
+        typeSize,
+        width,
+        height,
+        depth,
+        layers,
+        faces,
+        levels,
+        levelCount,
+        dataFormat,
+        supercompression,
+    };
+}
+/** Uncompressed and packed `VkFormat`s with a WebGPU twin. */
+const PLAIN_FORMATS = {
+    9: 'r8unorm',
+    10: 'r8snorm',
+    13: 'r8uint',
+    14: 'r8sint',
+    16: 'rg8unorm',
+    17: 'rg8snorm',
+    20: 'rg8uint',
+    21: 'rg8sint',
+    37: 'rgba8unorm',
+    38: 'rgba8snorm',
+    41: 'rgba8uint',
+    42: 'rgba8sint',
+    43: 'rgba8unorm-srgb',
+    44: 'bgra8unorm',
+    50: 'bgra8unorm-srgb',
+    64: 'rgb10a2unorm',
+    74: 'r16uint',
+    75: 'r16sint',
+    76: 'r16float',
+    81: 'rg16uint',
+    82: 'rg16sint',
+    83: 'rg16float',
+    95: 'rgba16uint',
+    96: 'rgba16sint',
+    97: 'rgba16float',
+    98: 'r32uint',
+    99: 'r32sint',
+    100: 'r32float',
+    101: 'rg32uint',
+    102: 'rg32sint',
+    103: 'rg32float',
+    107: 'rgba32uint',
+    108: 'rgba32sint',
+    109: 'rgba32float',
+    122: 'rg11b10ufloat',
+    123: 'rgb9e5ufloat',
+    124: 'depth16unorm',
+    126: 'depth32float',
+};
+/** Block-compressed `VkFormat`s 131..156 (BC1..BC7, ETC2, EAC), in VkFormat order. */
+const BLOCK_FORMATS = [
+    'bc1-rgba-unorm', // 131 BC1_RGB_UNORM (WebGPU has the RGBA form only)
+    'bc1-rgba-unorm-srgb',
+    'bc1-rgba-unorm',
+    'bc1-rgba-unorm-srgb',
+    'bc2-rgba-unorm',
+    'bc2-rgba-unorm-srgb',
+    'bc3-rgba-unorm',
+    'bc3-rgba-unorm-srgb',
+    'bc4-r-unorm',
+    'bc4-r-snorm',
+    'bc5-rg-unorm',
+    'bc5-rg-snorm',
+    'bc6h-rgb-ufloat',
+    'bc6h-rgb-float',
+    'bc7-rgba-unorm',
+    'bc7-rgba-unorm-srgb',
+    'etc2-rgb8unorm',
+    'etc2-rgb8unorm-srgb',
+    'etc2-rgb8a1unorm',
+    'etc2-rgb8a1unorm-srgb',
+    'etc2-rgba8unorm',
+    'etc2-rgba8unorm-srgb',
+    'eac-r11unorm',
+    'eac-r11snorm',
+    'eac-rg11unorm',
+    'eac-rg11snorm', // 156
+];
+/** ASTC block sizes of `VkFormat` 157..184, each as (unorm, sRGB). */
+const ASTC_SIZES = [
+    '4x4',
+    '5x4',
+    '5x5',
+    '6x5',
+    '6x6',
+    '8x5',
+    '8x6',
+    '8x8',
+    '10x5',
+    '10x6',
+    '10x8',
+    '10x10',
+    '12x10',
+    '12x12',
+];
+/**
+ * The WebGPU texture format a `VkFormat` stores, or null when WebGPU has none (or the file
+ * holds a Basis payload, `vkFormat` 0, that must be transcoded first).
+ */
+export function ktx2ToWebGpuFormat(vkFormat) {
+    const plain = PLAIN_FORMATS[vkFormat];
+    if (plain)
+        return plain;
+    if (vkFormat >= 131 && vkFormat <= 156)
+        return BLOCK_FORMATS[vkFormat - 131];
+    if (vkFormat >= 157 && vkFormat <= 184) {
+        const i = vkFormat - 157;
+        const size = ASTC_SIZES[i >> 1];
+        return `astc-${size}-${i & 1 ? 'unorm-srgb' : 'unorm'}`;
+    }
+    return null;
+}

package/dist/assets/manifest.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A typed asset manifest: the keys a game loads by, each with a kind and the uri(s) the game's
+ * `read` resolves. `defineManifest` is an identity function that keeps the literal types, so
+ * `bundle.get('hero')` is typed by the entry's kind (`AssetOf`). Plain data: no GPU, no network.
+ */
+import type { LoadTextureArrayOptions, LoadTextureOptions, Texture } from '../render/texture.js';
+import type { AtlasLayout, AtlasOptions, AtlasRect } from './atlas.js';
+import type { GltfScene, LoadGltfOptions } from './gltf-load.js';
+/** One 2D `Texture` through `loadTexture` (the image decoded with `createImageBitmap`). */
+export interface TextureEntry {
+    kind: 'texture';
+    uri: string;
+    options?: LoadTextureOptions;
+}
+/** One `texture_2d_array` through `loadTextureArray`, a layer per uri, in order. */
+export interface TextureArrayEntry {
+    kind: 'texture-array';
+    uris: string[];
+    options?: LoadTextureArrayOptions;
+}
+/**
+ * A glTF scene: the uri is parsed with `parseGltf`, every `externalUris` entry is read through
+ * `resources` (the uri the file names → the uri to read; an unmapped uri is read as is) and the
+ * result goes through `loadGltf`.
+ */
+export interface GltfEntry {
+    kind: 'gltf';
+    uri: string;
+    resources?: Record<string, string>;
+    options?: LoadGltfOptions;
+}
+/** An `AudioBuffer`, decoded by the `audio` the bundle was given. */
+export interface AudioEntry {
+    kind: 'audio';
+    uri: string;
+}
+/** `JSON.parse` of the bytes as UTF-8. */
+export interface JsonEntry {
+    kind: 'json';
+    uri: string;
+}
+/** The bytes as a UTF-8 string. */
+export interface TextEntry {
+    kind: 'text';
+    uri: string;
+}
+/** The bytes themselves. */
+export interface BytesEntry {
+    kind: 'bytes';
+    uri: string;
+}
+/** An `ImageBitmap` (for a game that packs or inspects the pixels itself). */
+export interface ImageEntry {
+    kind: 'image';
+    uri: string;
+}
+/** Loose images packed into one texture with `packAtlas` and `createAtlasTexture`. */
+export interface AtlasEntry<N extends string = string> {
+    kind: 'atlas';
+    uris: Record<N, string>;
+    options?: AtlasOptions;
+}
+export type ManifestEntry = TextureEntry | TextureArrayEntry | GltfEntry | AudioEntry | JsonEntry | TextEntry | BytesEntry | ImageEntry | AtlasEntry;
+export type AssetKind = ManifestEntry['kind'];
+/** A manifest: asset keys to entries. */
+export type Manifest = Record<string, ManifestEntry>;
+/** What an `atlas` entry loads to: the texture, the uv rect per image name and the layout. */
+export interface AtlasAsset<N extends string = string> {
+    texture: Texture;
+    rects: Record<N, AtlasRect>;
+    layout: AtlasLayout;
+}
+/** The loaded value of a manifest entry, by its kind. */
+export type AssetOf<E extends ManifestEntry> = E extends TextureEntry ? Texture : E extends TextureArrayEntry ? Texture : E extends GltfEntry ? GltfScene : E extends AudioEntry ? AudioBuffer : E extends JsonEntry ? unknown : E extends TextEntry ? string : E extends BytesEntry ? ArrayBuffer : E extends ImageEntry ? ImageBitmap : E extends AtlasEntry<infer N> ? AtlasAsset<N> : never;
+/**
+ * Identity with types: `const manifest = defineManifest({ hero: { kind: 'texture', uri: 'hero.png' } })`
+ * keeps `hero` as a `TextureEntry`, so `createBundle(manifest).get('hero')` is a `Texture`.
+ */
+export declare function defineManifest<M extends Manifest>(entries: M): M;

package/dist/assets/manifest.js

@@ -0,0 +1,7 @@
+/**
+ * Identity with types: `const manifest = defineManifest({ hero: { kind: 'texture', uri: 'hero.png' } })`
+ * keeps `hero` as a `TextureEntry`, so `createBundle(manifest).get('hero')` is a `Texture`.
+ */
+export function defineManifest(entries) {
+    return entries;
+}

package/dist/assets/meshopt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A TypeScript port of the meshoptimizer decoders `EXT_meshopt_compression` needs (bitstream
+ * version 0 for vertices, versions 0 and 1 for indices): the vertex codec (`ATTRIBUTES`), the
+ * triangle index codec (`TRIANGLES`), the index sequence codec (`INDICES`) and the three
+ * filters (`OCTAHEDRAL`, `QUATERNION`, `EXPONENTIAL`) applied after the vertex codec. Sync, on
+ * `Uint8Array`s; the only allocation is the caller's target (one per buffer view). Malformed
+ * input throws `MeshoptError`. The reference is meshoptimizer's `vertexcodec.cpp`,
+ * `indexcodec.cpp` and `vertexfilter.cpp` (MIT, Arseny Kapoulkine); this port follows their
+ * scalar paths byte for byte.
+ */
+/** `EXT_meshopt_compression` `mode`. */
+export type MeshoptMode = 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES';
+/** `EXT_meshopt_compression` `filter` (`'NONE'` when absent). */
+export type MeshoptFilter = 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL';
+/** A meshopt stream that does not decode (bad header, truncated, trailing bytes, bad stride). */
+export declare class MeshoptError extends Error {
+    readonly name = "MeshoptError";
+}
+/**
+ * Decode one `EXT_meshopt_compression` buffer view into `target` (`count × stride` bytes, the
+ * view's `byteLength`), then apply `filter` in place. Throws `MeshoptError` on a bad stream.
+ */
+export declare function decodeMeshopt(target: Uint8Array, count: number, stride: number, source: Uint8Array, mode: MeshoptMode, filter?: MeshoptFilter): void;