@haiyue/extensions 0.1.0 → 0.2.0

package/dist/experimental-indexed-sprite.js

@@ -0,0 +1,482 @@
+import { I as IndexedSpriteWgsl } from './chunks/2d-ui-indexed-sprite.generated-DmKR0CC3.js';
+
+const DEFAULT_INDEXED_SPRITE_ATLAS_LIMITS = Object.freeze({
+    maxTextureDimension2D: 8_192,
+    maxAtlasPages: 64,
+    maxGpuBytes: 536_870_912,
+    maxPaletteGpuBytes: 16_777_216,
+    maxUploadBytesPerFrame: 16_777_216,
+    maxDrawCommandsPerFrame: 16_384,
+});
+
+function prepareIndexedSpriteAtlas(sprites, palettes, limits = DEFAULT_INDEXED_SPRITE_ATLAS_LIMITS) {
+    validateLimits(limits);
+    const sortedSprites = [...sprites].sort((left, right) => compare(left.id, right.id));
+    const sortedPalettes = [...palettes].sort((left, right) => compare(left.id, right.id));
+    assertUnique(sortedSprites.map(value => value.id), 'sprite');
+    assertUnique(sortedPalettes.map(value => value.id), 'palette');
+    const mutablePages = [];
+    const mutablePlacements = new Map();
+    for (const sprite of sortedSprites) {
+        validateSprite(sprite, limits);
+        const kind = sprite.format === 'indexed8' ? 'indexed' : 'color';
+        const sourceBytesPerPixel = sprite.format === 'indexed8' ? 1 : sprite.format === 'rgb8' ? 3 : 4;
+        let page = mutablePages.find(value => value.kind === kind && canPlace(value, sprite.width, sprite.height, limits.maxTextureDimension2D));
+        if (!page) {
+            if (mutablePages.length >= limits.maxAtlasPages)
+                throw new RangeError(`Indexed sprite atlas exceeds maxAtlasPages=${limits.maxAtlasPages}.`);
+            page = { kind, placements: [], x: 0, y: 0, shelfHeight: 0, usedWidth: 0, usedHeight: 0 };
+            mutablePages.push(page);
+        }
+        const point = place(page, sprite.width, sprite.height, limits.maxTextureDimension2D);
+        const placement = Object.freeze({ spriteId: sprite.id, pageIndex: mutablePages.indexOf(page), pageKind: kind, x: point.x, y: point.y, width: sprite.width, height: sprite.height });
+        page.placements.push({ ...placement, source: sprite.pixels.slice(), sourceBytesPerPixel });
+        mutablePlacements.set(sprite.id, placement);
+    }
+    const pages = mutablePages.map((page, index) => finalizePage(page, index));
+    const mutablePaletteRows = new Map();
+    const paletteHeight = Math.max(1, sortedPalettes.length);
+    const palettePixels = new Uint8Array(256 * paletteHeight * 4);
+    sortedPalettes.forEach((palette, row) => {
+        validatePalette(palette);
+        mutablePaletteRows.set(palette.id, row);
+        palettePixels.set(palette.rgba, row * 256 * 4);
+    });
+    if (palettePixels.byteLength > limits.maxPaletteGpuBytes)
+        throw new RangeError(`Indexed sprite palette bank exceeds maxPaletteGpuBytes=${limits.maxPaletteGpuBytes}.`);
+    const pageBytes = pages.reduce((total, page) => total + page.pixels.byteLength, 0);
+    const gpuBytes = pageBytes + palettePixels.byteLength;
+    if (gpuBytes > limits.maxGpuBytes)
+        throw new RangeError(`Indexed sprite atlas exceeds maxGpuBytes=${limits.maxGpuBytes}.`);
+    return Object.freeze({
+        pages: Object.freeze(pages),
+        placements: readonlyMap(mutablePlacements),
+        paletteRows: readonlyMap(mutablePaletteRows),
+        paletteWidth: 256, paletteHeight, palettePixels,
+        cpuBytes: gpuBytes, gpuBytes,
+    });
+}
+function readonlyMap(source) {
+    const view = {
+        get size() { return source.size; },
+        has: key => source.has(key),
+        get: key => source.get(key),
+        entries: () => source.entries(),
+        keys: () => source.keys(),
+        values: () => source.values(),
+        forEach: (callback, thisArg) => source.forEach((value, key) => callback.call(thisArg, value, key, view)),
+        [Symbol.iterator]: () => source[Symbol.iterator](),
+    };
+    return Object.freeze(view);
+}
+function validateSprite(sprite, limits) {
+    if (!sprite.id || !Number.isSafeInteger(sprite.width) || !Number.isSafeInteger(sprite.height) || sprite.width < 1 || sprite.height < 1 || sprite.width > limits.maxTextureDimension2D - 2 || sprite.height > limits.maxTextureDimension2D - 2)
+        throw new RangeError(`Sprite ${sprite.id || '<empty>'} dimensions are invalid or exceed the atlas limit.`);
+    const bytesPerPixel = sprite.format === 'indexed8' ? 1 : sprite.format === 'rgb8' ? 3 : sprite.format === 'rgba8' ? 4 : 0;
+    if (bytesPerPixel === 0 || sprite.pixels.byteLength !== sprite.width * sprite.height * bytesPerPixel)
+        throw new RangeError(`Sprite ${sprite.id} pixel byte length does not match its descriptor.`);
+}
+function validatePalette(palette) {
+    if (!palette.id || !Number.isSafeInteger(palette.colorCount) || palette.colorCount < 1 || palette.colorCount > 256 || palette.rgba.byteLength !== palette.colorCount * 4)
+        throw new RangeError(`Palette ${palette.id || '<empty>'} is invalid.`);
+}
+function validateLimits(limits) { for (const [key, value] of Object.entries(limits))
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError(`Indexed sprite limit ${key} must be a positive safe integer.`); }
+function assertUnique(values, label) { const seen = new Set(); for (const value of values) {
+    if (seen.has(value))
+        throw new RangeError(`Duplicate indexed sprite ${label} id: ${value}.`);
+    seen.add(value);
+} }
+function compare(left, right) { const count = Math.min(left.length, right.length); for (let i = 0; i < count; i++) {
+    const difference = left.charCodeAt(i) - right.charCodeAt(i);
+    if (difference !== 0)
+        return difference;
+} return left.length - right.length; }
+function canPlace(page, width, height, maximum) {
+    const paddedWidth = width + 2;
+    const paddedHeight = height + 2;
+    if (page.x + paddedWidth <= maximum && page.y + paddedHeight <= maximum)
+        return true;
+    return paddedWidth <= maximum && page.y + page.shelfHeight + paddedHeight <= maximum;
+}
+function place(page, width, height, maximum) {
+    const paddedWidth = width + 2;
+    const paddedHeight = height + 2;
+    if (page.x + paddedWidth > maximum) {
+        page.x = 0;
+        page.y += page.shelfHeight;
+        page.shelfHeight = 0;
+    }
+    const point = { x: page.x + 1, y: page.y + 1 };
+    page.x += paddedWidth;
+    page.shelfHeight = Math.max(page.shelfHeight, paddedHeight);
+    page.usedWidth = Math.max(page.usedWidth, page.x);
+    page.usedHeight = Math.max(page.usedHeight, page.y + page.shelfHeight);
+    return point;
+}
+function finalizePage(page, index) {
+    const bytesPerPixel = page.kind === 'indexed' ? 1 : 4;
+    const pixels = new Uint8Array(page.usedWidth * page.usedHeight * bytesPerPixel);
+    for (const placement of page.placements) {
+        for (let y = -1; y <= placement.height; y++) {
+            const sourceY = Math.max(0, Math.min(placement.height - 1, y));
+            for (let x = -1; x <= placement.width; x++) {
+                const sourceX = Math.max(0, Math.min(placement.width - 1, x));
+                const sourceOffset = (sourceY * placement.width + sourceX) * placement.sourceBytesPerPixel;
+                const targetOffset = ((placement.y + y) * page.usedWidth + placement.x + x) * bytesPerPixel;
+                if (bytesPerPixel === 1)
+                    pixels[targetOffset] = placement.source[sourceOffset];
+                else {
+                    pixels[targetOffset] = placement.source[sourceOffset];
+                    pixels[targetOffset + 1] = placement.source[sourceOffset + 1];
+                    pixels[targetOffset + 2] = placement.source[sourceOffset + 2];
+                    pixels[targetOffset + 3] = placement.sourceBytesPerPixel === 4 ? placement.source[sourceOffset + 3] : 255;
+                }
+            }
+        }
+    }
+    return Object.freeze({ index, kind: page.kind, width: page.usedWidth, height: page.usedHeight, bytesPerPixel: bytesPerPixel, pixels });
+}
+
+const INSTANCE_BYTES = 144;
+const INSTANCE_WORDS = INSTANCE_BYTES / 4;
+const WHITE = [1, 1, 1, 1];
+const IDENTITY_COLOR = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0];
+const compareCommands = (a, b) => (a.command.priority ?? 0) - (b.command.priority ?? 0) || a.sourceOrder - b.sourceOrder;
+class IndexedSpriteRenderer {
+    layout;
+    limits;
+    targetFormat;
+    label;
+    sampleCount;
+    #device;
+    #pipelines = new Map();
+    #pages = [];
+    #paletteTexture = null;
+    #dummyIndexTexture = null;
+    #dummyColorTexture = null;
+    #nearestSampler = null;
+    #linearSampler = null;
+    #frameBindGroup = null;
+    #viewportBuffer = null;
+    #instanceBuffer = null;
+    #uploadJobs = [];
+    #uploadedBytes = 0;
+    #drawCommands = 0;
+    #drawCalls = 0;
+    #batches = 0;
+    #generation = 0;
+    #disposed = false;
+    #prepared = [];
+    #commandPool = [];
+    #instanceData = new ArrayBuffer(0);
+    #instanceFloats = new Float32Array(this.#instanceData);
+    #instanceUints = new Uint32Array(this.#instanceData);
+    #viewportData = new Float32Array(4);
+    constructor(device, sprites, palettes, options) {
+        this.#device = device;
+        this.targetFormat = options.targetFormat;
+        this.limits = options.limits ?? DEFAULT_INDEXED_SPRITE_ATLAS_LIMITS;
+        this.label = options.label ?? 'IndexedSpriteRenderer';
+        this.sampleCount = options.sampleCount ?? 1;
+        this.layout = prepareIndexedSpriteAtlas(sprites, palettes, this.limits);
+        this.#createGpuResources();
+    }
+    get ready() { return !this.#disposed && this.#uploadJobs.length === 0; }
+    upload(maxBytes = this.limits.maxUploadBytesPerFrame) {
+        this.#assertAlive();
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > this.limits.maxUploadBytesPerFrame)
+            throw new RangeError(`Indexed sprite upload budget must be between 1 and ${this.limits.maxUploadBytesPerFrame}.`);
+        let remaining = maxBytes;
+        while (remaining > 0 && this.#uploadJobs.length > 0) {
+            const job = this.#uploadJobs[0];
+            const sourceBytesPerRow = job.width * job.bytesPerPixel;
+            const alignedBytesPerRow = align(sourceBytesPerRow, 256);
+            if (alignedBytesPerRow > maxBytes)
+                throw new RangeError(`One indexed sprite atlas row requires ${alignedBytesPerRow} upload bytes, exceeding maxUploadBytesPerFrame=${maxBytes}.`);
+            const rows = Math.min(job.height - job.nextRow, Math.floor(remaining / alignedBytesPerRow));
+            if (rows < 1)
+                break;
+            const upload = new Uint8Array(alignedBytesPerRow * rows);
+            for (let row = 0; row < rows; row++) {
+                const sourceOffset = (job.nextRow + row) * sourceBytesPerRow;
+                upload.set(job.pixels.subarray(sourceOffset, sourceOffset + sourceBytesPerRow), row * alignedBytesPerRow);
+            }
+            this.#device.queue.writeTexture({ texture: job.texture, origin: { x: 0, y: job.nextRow, z: 0 } }, upload, { offset: 0, bytesPerRow: alignedBytesPerRow, rowsPerImage: rows }, { width: job.width, height: rows, depthOrArrayLayers: 1 });
+            const sourceUploaded = sourceBytesPerRow * rows;
+            this.#uploadedBytes += sourceUploaded;
+            remaining -= alignedBytesPerRow * rows;
+            job.nextRow += rows;
+            if (job.nextRow === job.height)
+                this.#uploadJobs.shift();
+        }
+        return this.stats();
+    }
+    uploadAll() {
+        while (!this.ready)
+            this.upload(this.limits.maxUploadBytesPerFrame);
+        return this.stats();
+    }
+    render(pass, commands, viewportWidth, viewportHeight) {
+        this.#assertAlive();
+        if (!this.ready)
+            throw new Error('Indexed sprite renderer cannot draw until all bounded uploads are complete.');
+        if (!Number.isFinite(viewportWidth) || !Number.isFinite(viewportHeight) || viewportWidth <= 0 || viewportHeight <= 0)
+            throw new RangeError('Indexed sprite viewport must be finite and positive.');
+        if (commands.length > this.limits.maxDrawCommandsPerFrame)
+            throw new RangeError(`Indexed sprite draw command count exceeds ${this.limits.maxDrawCommandsPerFrame}.`);
+        const prepared = this.#prepared;
+        const bytes = commands.length * INSTANCE_BYTES;
+        if (bytes > this.#instanceData.byteLength) {
+            const capacity = Math.min(this.limits.maxDrawCommandsPerFrame, Math.max(64, 2 ** Math.ceil(Math.log2(commands.length))));
+            this.#instanceData = new ArrayBuffer(capacity * INSTANCE_BYTES);
+            this.#instanceFloats = new Float32Array(this.#instanceData);
+            this.#instanceUints = new Uint32Array(this.#instanceData);
+        }
+        try {
+            let ordered = true, previousPriority = -Infinity;
+            for (let i = 0; i < commands.length; i++) {
+                const value = this.#prepareCommand(commands[i], i);
+                prepared.push(value);
+                const priority = commands[i].priority ?? 0;
+                if (priority < previousPriority)
+                    ordered = false;
+                previousPriority = priority;
+            }
+            if (!ordered)
+                prepared.sort(compareCommands);
+            for (let i = 0; i < prepared.length; i++)
+                this.#writeInstance(prepared[i], i * INSTANCE_WORDS, this.#instanceFloats, this.#instanceUints);
+            // writeBuffer copies immediately; CPU scratch can be reused after this call.
+            if (bytes > 0)
+                this.#device.queue.writeBuffer(this.#instanceBuffer, 0, this.#instanceData, 0, bytes);
+            this.#viewportData[0] = viewportWidth;
+            this.#viewportData[1] = viewportHeight;
+            this.#device.queue.writeBuffer(this.#viewportBuffer, 0, this.#viewportData);
+            pass.setBindGroup(0, this.#frameBindGroup);
+            let batchStart = 0;
+            let drawCalls = 0;
+            while (batchStart < prepared.length) {
+                const first = prepared[batchStart];
+                let batchEnd = batchStart + 1;
+                while (batchEnd < prepared.length) {
+                    const next = prepared[batchEnd];
+                    if (next.pageIndex !== first.pageIndex || next.sampling !== first.sampling || next.blend !== first.blend)
+                        break;
+                    batchEnd++;
+                }
+                const page = this.#pages[first.pageIndex];
+                pass.setPipeline(this.#pipelines.get(first.blend));
+                pass.setBindGroup(1, first.sampling === 'linear' ? page.linearBindGroup : page.nearestBindGroup);
+                pass.draw(6, batchEnd - batchStart, 0, batchStart);
+                drawCalls++;
+                batchStart = batchEnd;
+            }
+            this.#drawCommands = prepared.length;
+            this.#drawCalls = drawCalls;
+            this.#batches = drawCalls;
+            return this.stats();
+        }
+        finally {
+            for (const value of prepared)
+                value.command = null;
+            prepared.length = 0;
+        }
+    }
+    recover(device) {
+        this.#assertAlive();
+        this.#destroyGpuResources();
+        this.#device = device;
+        this.#generation++;
+        this.#uploadedBytes = 0;
+        this.#createGpuResources();
+    }
+    stats() {
+        const pendingUploadBytes = Math.max(0, this.layout.gpuBytes - this.#uploadedBytes);
+        return Object.freeze({
+            pageCount: this.layout.pages.length,
+            indexedPageCount: this.layout.pages.filter(page => page.kind === 'indexed').length,
+            colorPageCount: this.layout.pages.filter(page => page.kind === 'color').length,
+            paletteCount: this.layout.paletteRows.size,
+            cpuBytes: this.layout.cpuBytes,
+            gpuBytes: this.layout.gpuBytes,
+            uploadedBytes: this.#uploadedBytes,
+            pendingUploadBytes,
+            textureCount: this.#disposed ? 0 : this.#pages.length + 3,
+            drawCommands: this.#drawCommands,
+            drawCalls: this.#drawCalls,
+            batches: this.#batches,
+            generation: this.#generation,
+            ready: this.ready,
+            disposed: this.#disposed,
+        });
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#destroyGpuResources();
+        this.#prepared.length = 0;
+        this.#commandPool.length = 0;
+        this.#instanceData = new ArrayBuffer(0);
+        this.#instanceFloats = new Float32Array(this.#instanceData);
+        this.#instanceUints = new Uint32Array(this.#instanceData);
+    }
+    #createGpuResources() {
+        const maximumDimension = this.#device.limits.maxTextureDimension2D;
+        for (const page of this.layout.pages)
+            if (page.width > maximumDimension || page.height > maximumDimension)
+                throw new RangeError(`Indexed sprite atlas page ${page.index} exceeds the device texture limit ${maximumDimension}.`);
+        if (this.layout.paletteWidth > maximumDimension || this.layout.paletteHeight > maximumDimension)
+            throw new RangeError('Indexed sprite palette bank exceeds the device texture limit.');
+        const module = this.#device.createShaderModule({ label: `${this.label}.shader`, code: IndexedSpriteWgsl });
+        const frameLayout = this.#device.createBindGroupLayout({
+            label: `${this.label}.frameLayout`,
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+            ],
+        });
+        const materialLayout = this.#device.createBindGroupLayout({
+            label: `${this.label}.materialLayout`,
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'uint' } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+                { binding: 3, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
+            ],
+        });
+        const pipelineLayout = this.#device.createPipelineLayout({ label: `${this.label}.pipelineLayout`, bindGroupLayouts: [frameLayout, materialLayout] });
+        for (const blend of ['alpha', 'additive', 'subtractive', 'opaque'])
+            this.#pipelines.set(blend, this.#device.createRenderPipeline({
+                label: `${this.label}.pipeline.${blend}`,
+                layout: pipelineLayout,
+                vertex: { module, entryPoint: 'vs_main' },
+                fragment: { module, entryPoint: 'fs_main', targets: [colorTarget(this.targetFormat, blend)] },
+                primitive: { topology: 'triangle-list', cullMode: 'none' },
+                multisample: { count: this.sampleCount },
+            }));
+        this.#viewportBuffer = this.#device.createBuffer({ label: `${this.label}.viewport`, size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#instanceBuffer = this.#device.createBuffer({ label: `${this.label}.instances`, size: this.limits.maxDrawCommandsPerFrame * INSTANCE_BYTES, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        this.#frameBindGroup = this.#device.createBindGroup({ label: `${this.label}.frame`, layout: frameLayout, entries: [{ binding: 0, resource: { buffer: this.#viewportBuffer } }, { binding: 1, resource: { buffer: this.#instanceBuffer } }] });
+        this.#nearestSampler = this.#device.createSampler({ label: `${this.label}.nearest`, magFilter: 'nearest', minFilter: 'nearest', mipmapFilter: 'nearest', addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge' });
+        this.#linearSampler = this.#device.createSampler({ label: `${this.label}.linear`, magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'nearest', addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge' });
+        this.#dummyIndexTexture = createTexture(this.#device, `${this.label}.dummyIndex`, 1, 1, 'r8uint');
+        this.#dummyColorTexture = createTexture(this.#device, `${this.label}.dummyColor`, 1, 1, 'rgba8unorm');
+        this.#paletteTexture = createTexture(this.#device, `${this.label}.palettes`, this.layout.paletteWidth, this.layout.paletteHeight, 'rgba8unorm');
+        this.#uploadJobs.push({ texture: this.#paletteTexture, width: this.layout.paletteWidth, height: this.layout.paletteHeight, bytesPerPixel: 4, pixels: this.layout.palettePixels, nextRow: 0 });
+        for (const page of this.layout.pages) {
+            const texture = createTexture(this.#device, `${this.label}.${page.kind}.${page.index}`, page.width, page.height, page.kind === 'indexed' ? 'r8uint' : 'rgba8unorm');
+            this.#uploadJobs.push({ texture, width: page.width, height: page.height, bytesPerPixel: page.bytesPerPixel, pixels: page.pixels, nextRow: 0 });
+            const entriesWithoutSampler = [
+                { binding: 0, resource: (page.kind === 'indexed' ? texture : this.#dummyIndexTexture).createView() },
+                { binding: 1, resource: (page.kind === 'color' ? texture : this.#dummyColorTexture).createView() },
+                { binding: 2, resource: this.#paletteTexture.createView() },
+            ];
+            const makeBindGroup = (sampling, sampler) => this.#device.createBindGroup({ label: `${this.label}.${page.index}.${sampling}`, layout: materialLayout, entries: [...entriesWithoutSampler, { binding: 3, resource: sampler }] });
+            this.#pages.push({ page, texture, nearestBindGroup: makeBindGroup('nearest', this.#nearestSampler), linearBindGroup: makeBindGroup('linear', this.#linearSampler) });
+        }
+    }
+    #prepareCommand(command, sourceOrder) {
+        const placement = this.layout.placements.get(command.spriteId);
+        if (!placement)
+            throw new RangeError(`Indexed sprite draw references unknown sprite ${command.spriteId}.`);
+        if (placement.pageKind === 'indexed' && (!command.paletteId || !this.layout.paletteRows.has(command.paletteId)))
+            throw new RangeError(`Indexed sprite ${command.spriteId} requires a known paletteId.`);
+        if (!Number.isFinite(command.x) || !Number.isFinite(command.y) || !Number.isFinite(command.axisX ?? 0) || !Number.isFinite(command.axisY ?? 0) || !Number.isFinite(command.scaleX ?? 1) || !Number.isFinite(command.scaleY ?? 1) || !Number.isFinite(command.rotationRadians ?? 0) || !Number.isFinite(command.opacity ?? 1) || !Number.isFinite(command.priority ?? 0) || !Number.isFinite(command.depth ?? 0.5))
+            throw new RangeError('Indexed sprite draw contains a non-finite number.');
+        const opacity = command.opacity ?? 1;
+        if (opacity < 0 || opacity > 1)
+            throw new RangeError('Indexed sprite opacity must be in [0,1].');
+        const value = this.#commandPool[sourceOrder] ??= { command: null, pageIndex: 0, pageKind: 'color', sampling: 'nearest', blend: 'alpha', sourceOrder };
+        value.command = command;
+        value.pageIndex = placement.pageIndex;
+        value.pageKind = placement.pageKind;
+        value.sampling = command.sampling ?? 'nearest';
+        value.blend = command.blend ?? 'alpha';
+        return value;
+    }
+    #writeInstance(prepared, offset, floats, uints) {
+        const command = prepared.command;
+        const placement = this.layout.placements.get(command.spriteId);
+        floats[offset] = command.x;
+        floats[offset + 1] = command.y;
+        floats[offset + 2] = command.scaleX ?? 1;
+        floats[offset + 3] = command.scaleY ?? 1;
+        floats[offset + 4] = placement.width;
+        floats[offset + 5] = placement.height;
+        floats[offset + 6] = command.axisX ?? 0;
+        floats[offset + 7] = command.axisY ?? 0;
+        floats[offset + 8] = placement.x;
+        floats[offset + 9] = placement.y;
+        floats[offset + 10] = placement.width;
+        floats[offset + 11] = placement.height;
+        floats[offset + 12] = command.rotationRadians ?? 0;
+        floats[offset + 13] = command.depth ?? 0.5;
+        floats[offset + 14] = command.opacity ?? 1;
+        floats[offset + 15] = 0;
+        uints[offset + 16] = prepared.pageKind === 'indexed' ? this.layout.paletteRows.get(command.paletteId) : 0;
+        uints[offset + 17] = (prepared.pageKind === 'indexed' ? 1 : 0) | (prepared.sampling === 'linear' ? 2 : 0) | (command.flipX ? 4 : 0) | (command.flipY ? 8 : 0);
+        uints[offset + 18] = 0;
+        uints[offset + 19] = 0;
+        const tint = command.tint ?? WHITE;
+        for (let index = 0; index < 4; index++) {
+            const value = tint[index];
+            if (!Number.isFinite(value))
+                throw new RangeError('Indexed sprite tint must be finite.');
+            floats[offset + 20 + index] = value;
+        }
+        const colorMatrix = command.colorMatrix ?? IDENTITY_COLOR;
+        if (colorMatrix.length !== 12)
+            throw new RangeError('Indexed sprite colorMatrix must contain twelve values.');
+        for (let index = 0; index < 12; index++) {
+            const value = colorMatrix[index];
+            if (!Number.isFinite(value))
+                throw new RangeError('Indexed sprite colorMatrix must be finite.');
+            floats[offset + 24 + index] = value;
+        }
+    }
+    #destroyGpuResources() {
+        for (const page of this.#pages)
+            page.texture.destroy();
+        this.#paletteTexture?.destroy();
+        this.#dummyIndexTexture?.destroy();
+        this.#dummyColorTexture?.destroy();
+        this.#viewportBuffer?.destroy();
+        this.#instanceBuffer?.destroy();
+        this.#pages = [];
+        this.#pipelines.clear();
+        this.#uploadJobs = [];
+        this.#paletteTexture = null;
+        this.#dummyIndexTexture = null;
+        this.#dummyColorTexture = null;
+        this.#nearestSampler = null;
+        this.#linearSampler = null;
+        this.#frameBindGroup = null;
+        this.#viewportBuffer = null;
+        this.#instanceBuffer = null;
+    }
+    #assertAlive() { if (this.#disposed)
+        throw new Error('Indexed sprite renderer is disposed.'); }
+}
+function createTexture(device, label, width, height, format) { return device.createTexture({ label, size: { width, height, depthOrArrayLayers: 1 }, format, usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST }); }
+function align(value, alignment) { return Math.ceil(value / alignment) * alignment; }
+function blendState(blend) {
+    if (blend === 'opaque')
+        return undefined;
+    if (blend === 'additive')
+        return { color: { operation: 'add', srcFactor: 'src-alpha', dstFactor: 'one' }, alpha: { operation: 'add', srcFactor: 'one', dstFactor: 'one' } };
+    if (blend === 'subtractive')
+        return { color: { operation: 'reverse-subtract', srcFactor: 'src-alpha', dstFactor: 'one' }, alpha: { operation: 'add', srcFactor: 'zero', dstFactor: 'one' } };
+    return { color: { operation: 'add', srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha' }, alpha: { operation: 'add', srcFactor: 'one', dstFactor: 'one-minus-src-alpha' } };
+}
+function colorTarget(format, blend) {
+    const state = blendState(blend);
+    return state
+        ? { format, blend: state, writeMask: GPUColorWrite.ALL }
+        : { format, writeMask: GPUColorWrite.ALL };
+}
+
+export { DEFAULT_INDEXED_SPRITE_ATLAS_LIMITS, IndexedSpriteRenderer, prepareIndexedSpriteAtlas };
+//# sourceMappingURL=experimental-indexed-sprite.js.map

package/dist/gltf-worker-runtime.js

@@ -5977,15 +5977,6 @@ mat4} = wgpuMatrixAPI(Float32Array, Float32Array, Float32Array, Float32Array, Fl
 wgpuMatrixAPI(Float64Array, Float64Array, Float64Array, Float64Array, Float64Array, Float64Array);
 wgpuMatrixAPI(ZeroArray, Array, Array, Array, Array, Array);
 
-function monotonicNow() {
-    return globalThis.performance?.now() ?? Date.now();
-}
-function createAbortError(message, cause) {
-    const error = new Error(message, { cause });
-    error.name = 'AbortError';
-    return error;
-}
-
 /** Asset semantics supported by the metallic-roughness pipeline. */
 const PBR_COMPATIBILITY_CONTRACT = Object.freeze({
     supportedUvSets: Object.freeze([0, 1]),
@@ -6012,6 +6003,15 @@ const PBR_COMPATIBILITY_CONTRACT = Object.freeze({
     }),
 });
 
+function monotonicNow() {
+    return globalThis.performance?.now() ?? Date.now();
+}
+function createAbortError(message, cause) {
+    const error = new Error(message, { cause });
+    error.name = 'AbortError';
+    return error;
+}
+
 /** Validates the untrusted JSON envelope before the loader follows references. */
 function isGltfAsset(value) {
     if (!isRecord(value))

package/dist/hya-state-machine.js

@@ -2,9 +2,10 @@ import { hyaStateMachineChannelCapability, HYA_STATE_MACHINE_EXTENSION_ID, parse
 export { HYA_STATE_MACHINE_CHANNEL_REGISTRY, hyaStateMachineChannelCapability } from '@haiyue/animation-spec';
 import { Component, System } from '@haiyue/engine';
 import { UniqueCheckType, ComponentLifecycleFlags } from '@haiyue/engine/ecs';
-import { r as runAnimationStateMachineControllerUpdateTransaction } from './chunks/AnimationStateMachineController-BIcAh-sT.js';
-import { A as Animation2DRuntime, c as createAnimation2DStateMachineController } from './chunks/Animation2DStateMachine-9IonguNa.js';
+import { r as runAnimationStateMachineControllerUpdateTransaction } from './chunks/AnimationStateMachineController-4sKaqh9E.js';
+import { A as Animation2DRuntime, c as createAnimation2DStateMachineController } from './chunks/Animation2DStateMachine-BHcA6Cu3.js';
 import '@haiyue/engine/geometry';
+import './chunks/AnimationVisual2D-8y3qp0_U.js';
 import '@haiyue/engine/components';
 
 class Animation2DStateMachineActionRuntimeHandle {

package/dist/index.js

@@ -1,4 +1,4 @@
-export { R as RenderSystem2DBase } from './chunks/RenderSystem2DBase-DDT61dAu.js';
+export { R as RenderSystem2DBase } from './chunks/RenderSystem2DBase-CF2s00vg.js';
 import '@haiyue/engine/extension-authoring';
 import '@haiyue/engine/components';
 import '@haiyue/engine/ecs';

package/dist/indexed-sprite/AtlasLayout.d.ts

@@ -0,0 +1,2 @@
+import { type IndexedSpriteAtlasLayout, type IndexedSpriteAtlasLimits, type IndexedSpritePaletteDescriptor, type IndexedSpritePlaneDescriptor } from './contracts';
+export declare function prepareIndexedSpriteAtlas(sprites: readonly IndexedSpritePlaneDescriptor[], palettes: readonly IndexedSpritePaletteDescriptor[], limits?: IndexedSpriteAtlasLimits): IndexedSpriteAtlasLayout;

package/dist/indexed-sprite/IndexedSpriteRenderer.d.ts

@@ -0,0 +1,23 @@
+import { type IndexedSpriteAtlasLayout, type IndexedSpriteAtlasLimits, type IndexedSpriteDrawCommand, type IndexedSpritePaletteDescriptor, type IndexedSpritePlaneDescriptor, type IndexedSpriteRendererStats } from './contracts';
+export interface IndexedSpriteRendererOptions {
+    readonly targetFormat: GPUTextureFormat;
+    readonly limits?: IndexedSpriteAtlasLimits;
+    readonly label?: string;
+    readonly sampleCount?: 1 | 4;
+}
+export declare class IndexedSpriteRenderer {
+    #private;
+    readonly layout: IndexedSpriteAtlasLayout;
+    readonly limits: IndexedSpriteAtlasLimits;
+    readonly targetFormat: GPUTextureFormat;
+    readonly label: string;
+    readonly sampleCount: 1 | 4;
+    constructor(device: GPUDevice, sprites: readonly IndexedSpritePlaneDescriptor[], palettes: readonly IndexedSpritePaletteDescriptor[], options: IndexedSpriteRendererOptions);
+    get ready(): boolean;
+    upload(maxBytes?: number): IndexedSpriteRendererStats;
+    uploadAll(): IndexedSpriteRendererStats;
+    render(pass: GPURenderPassEncoder, commands: readonly IndexedSpriteDrawCommand[], viewportWidth: number, viewportHeight: number): IndexedSpriteRendererStats;
+    recover(device: GPUDevice): void;
+    stats(): IndexedSpriteRendererStats;
+    dispose(): void;
+}

package/dist/indexed-sprite/contracts.d.ts

@@ -0,0 +1,89 @@
+export type IndexedSpritePlaneFormat = 'indexed8' | 'rgb8' | 'rgba8';
+export type IndexedSpriteSampling = 'nearest' | 'linear';
+export type IndexedSpriteBlend = 'alpha' | 'additive' | 'subtractive' | 'opaque';
+export interface IndexedSpritePlaneDescriptor {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    readonly format: IndexedSpritePlaneFormat;
+    readonly pixels: Uint8Array;
+}
+export interface IndexedSpritePaletteDescriptor {
+    readonly id: string;
+    readonly colorCount: number;
+    readonly rgba: Uint8Array;
+}
+export interface IndexedSpriteAtlasLimits {
+    readonly maxTextureDimension2D: number;
+    readonly maxAtlasPages: number;
+    readonly maxGpuBytes: number;
+    readonly maxPaletteGpuBytes: number;
+    readonly maxUploadBytesPerFrame: number;
+    readonly maxDrawCommandsPerFrame: number;
+}
+export declare const DEFAULT_INDEXED_SPRITE_ATLAS_LIMITS: IndexedSpriteAtlasLimits;
+export interface IndexedSpriteAtlasPlacement {
+    readonly spriteId: string;
+    readonly pageIndex: number;
+    readonly pageKind: 'indexed' | 'color';
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface IndexedSpriteAtlasPage {
+    readonly index: number;
+    readonly kind: 'indexed' | 'color';
+    readonly width: number;
+    readonly height: number;
+    readonly bytesPerPixel: 1 | 4;
+    readonly pixels: Uint8Array;
+}
+export interface IndexedSpriteAtlasLayout {
+    readonly pages: readonly IndexedSpriteAtlasPage[];
+    readonly placements: ReadonlyMap<string, IndexedSpriteAtlasPlacement>;
+    readonly paletteRows: ReadonlyMap<string, number>;
+    readonly paletteWidth: 256;
+    readonly paletteHeight: number;
+    readonly palettePixels: Uint8Array;
+    readonly cpuBytes: number;
+    readonly gpuBytes: number;
+}
+export interface IndexedSpriteDrawCommand {
+    readonly spriteId: string;
+    readonly paletteId?: string;
+    readonly x: number;
+    readonly y: number;
+    readonly axisX?: number;
+    readonly axisY?: number;
+    readonly scaleX?: number;
+    readonly scaleY?: number;
+    readonly rotationRadians?: number;
+    readonly opacity?: number;
+    readonly tint?: readonly [number, number, number, number];
+    /** Row-major RGB affine transform: three vec4 rows containing rgb coefficients and additive bias. */
+    readonly colorMatrix?: readonly [number, number, number, number, number, number, number, number, number, number, number, number];
+    readonly flipX?: boolean;
+    readonly flipY?: boolean;
+    readonly sampling?: IndexedSpriteSampling;
+    readonly blend?: IndexedSpriteBlend;
+    readonly priority?: number;
+    readonly depth?: number;
+}
+export interface IndexedSpriteRendererStats {
+    readonly pageCount: number;
+    readonly indexedPageCount: number;
+    readonly colorPageCount: number;
+    readonly paletteCount: number;
+    readonly cpuBytes: number;
+    readonly gpuBytes: number;
+    readonly uploadedBytes: number;
+    readonly pendingUploadBytes: number;
+    readonly textureCount: number;
+    readonly drawCommands: number;
+    readonly drawCalls: number;
+    readonly batches: number;
+    readonly generation: number;
+    readonly ready: boolean;
+    readonly disposed: boolean;
+}