@haiyue/extensions 0.1.0 → 0.2.0

package/dist/deformable-animation.js

@@ -0,0 +1,316 @@
+import { DEFORMABLE_MESH_2D_EXTENSION_ID, decodeDeformableMesh2DData } from '@haiyue/animation-spec/deformable2d';
+import { AnimationFormatError } from '@haiyue/animation-spec';
+import { Entity, Transform2D, Geometry2D } from '@haiyue/engine';
+import { A as AnimationVisual2D } from './chunks/AnimationVisual2D-8y3qp0_U.js';
+import '@haiyue/engine/ecs';
+
+function sampleDeformableMesh2DDrawable(times, drawable, time, targetRuntimePositions) {
+    if (targetRuntimePositions.length !== drawable.vertexCount * 2)
+        throw new RangeError('Deformable sample target does not match drawable vertex count.');
+    const frame = findFrame(times, time);
+    const nextFrame = Math.min(frame + 1, times.length - 1);
+    const startTime = times[frame];
+    const endTime = times[nextFrame];
+    const progress = nextFrame === frame || endTime <= startTime ? 0 : clamp((time - startTime) / (endTime - startTime), 0, 1);
+    const stride = drawable.vertexCount * 2;
+    const startOffset = frame * stride;
+    const nextOffset = nextFrame * stride;
+    for (let index = 0; index < stride; index += 2) {
+        targetRuntimePositions[index] = mix(drawable.positions[startOffset + index], drawable.positions[nextOffset + index], progress);
+        // HYA stores screen-y-down coordinates; Animation2D geometry uses local y-up.
+        targetRuntimePositions[index + 1] = -mix(drawable.positions[startOffset + index + 1], drawable.positions[nextOffset + index + 1], progress);
+    }
+    return Object.freeze({
+        opacity: mix(drawable.opacities[frame], drawable.opacities[nextFrame], progress),
+        renderOrder: drawable.renderOrders[frame],
+        frame,
+        nextFrame,
+        progress,
+    });
+}
+/** Samples optional HYDM 1.2 RGBA tracks into caller-owned pose storage without allocating. */
+function sampleDeformableMesh2DDrawableColors(drawable, sample, targetMultiplyColors, targetScreenColors, targetOffset = 0) {
+    if (!Number.isSafeInteger(targetOffset) || targetOffset < 0 || targetOffset + 4 > targetMultiplyColors.length || targetOffset + 4 > targetScreenColors.length) {
+        throw new RangeError('Deformable color sample target requires four writable values.');
+    }
+    sampleColorTrack(drawable.multiplyColors, sample, targetMultiplyColors, targetOffset, [1, 1, 1, 1]);
+    sampleColorTrack(drawable.screenColors, sample, targetScreenColors, targetOffset, [0, 0, 0, 0]);
+}
+function sampleColorTrack(track, sample, target, targetOffset, fallback) {
+    const startOffset = sample.frame * 4;
+    const nextOffset = sample.nextFrame * 4;
+    for (let index = 0; index < 4; index++) {
+        const start = track?.[startOffset + index] ?? fallback[index];
+        const next = track?.[nextOffset + index] ?? fallback[index];
+        target[targetOffset + index] = mix(start, next, sample.progress);
+    }
+}
+function findFrame(times, time) {
+    if (time <= times[0])
+        return 0;
+    if (time >= times[times.length - 1])
+        return times.length - 1;
+    let low = 0;
+    let high = times.length - 1;
+    while (low + 1 < high) {
+        const middle = (low + high) >>> 1;
+        if (times[middle] <= time)
+            low = middle;
+        else
+            high = middle;
+    }
+    return low;
+}
+function mix(a, b, progress) { return a + (b - a) * progress; }
+function clamp(value, minimum, maximum) { return Math.max(minimum, Math.min(maximum, value)); }
+
+function createDeformableMesh2DRuntimeExtension(options = {}) {
+    return {
+        id: DEFORMABLE_MESH_2D_EXTENSION_ID,
+        create(context) {
+            return new DeformableMesh2DRuntimeInstance(context, options);
+        },
+    };
+}
+class DeformableMesh2DRuntimeInstance {
+    context;
+    options;
+    // Keep an explicit transform at the extension boundary. TransformStore marks
+    // transform-less entities as non-transform parents, so two consecutive
+    // transform-less runtime nodes would otherwise drop the owning HYA model's
+    // world transform before it reaches the drawable entities.
+    root = new Entity('HYA deformable mesh runtime').addComponent(new Transform2D());
+    controller = new AbortController();
+    assetHandles = [];
+    drawables = [];
+    onOwnerAbort = () => this.destroy();
+    state = 'loading';
+    lastTime = 0;
+    lastOpacity = 1;
+    destroyed = false;
+    constructor(context, options) {
+        this.context = context;
+        this.options = options;
+        context.parent.addChild(this.root);
+        context.signal.addEventListener('abort', this.onOwnerAbort, { once: true });
+        this.emitStatus();
+        if (context.signal.aborted) {
+            this.destroy();
+            return;
+        }
+        void this.load();
+    }
+    apply(timeSeconds, opacity) {
+        this.lastTime = timeSeconds;
+        this.lastOpacity = opacity;
+        if (this.state !== 'ready')
+            return;
+        for (const item of this.drawables) {
+            const sample = sampleDeformableMesh2DDrawable(this.data.times, item.source, timeSeconds, item.positions);
+            sampleDeformableMesh2DDrawableColors(item.source, sample, item.multiplyColor, item.screenColor);
+            item.geometry.markDirty();
+            for (const visual of item.visuals) {
+                // Cubism's setup-mask pass samples the source mesh texture alpha but
+                // deliberately ignores drawable/model opacity. Keep the main visual's
+                // sampled opacity while mask-only clones remain fully contributing.
+                visual.color[3] = visual.sourceOnly ? 1 : sample.opacity * opacity;
+                visual.setDrawableColors(item.multiplyColor, item.screenColor);
+                visual.setOrder(sample.renderOrder);
+                visual.revision++;
+            }
+        }
+    }
+    setOpacity(opacity) {
+        this.apply(this.lastTime, opacity);
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.state = 'destroyed';
+        this.controller.abort('deformable-runtime-destroyed');
+        this.context.signal.removeEventListener('abort', this.onOwnerAbort);
+        for (const handle of this.assetHandles.splice(0))
+            handle.release();
+        this.drawables.length = 0;
+        this.root.destroy();
+        this.emitStatus();
+    }
+    data = null;
+    async load() {
+        try {
+            const manager = this.context.assetManager;
+            if (!manager)
+                throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Deformable mesh runtime requires an AssetManager.', '$runtime.assetManager');
+            const component = this.context.component;
+            const dataResource = this.context.animation.resources.find(resource => resource.id === component.dataResource);
+            if (!dataResource || dataResource.type !== 'binary')
+                throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', `Deformable data resource "${component.dataResource}" is missing or not binary.`, '$.resources');
+            const textureResources = component.textures.map((id, index) => {
+                const resource = this.context.animation.resources.find(candidate => candidate.id === id);
+                if (!resource || resource.type !== 'image')
+                    throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', `Texture resource "${id}" is missing or not an image.`, `$.nodes[].components[].textures[${index}]`);
+                return resource;
+            });
+            const dataHandle = await manager.load(`deformable2d:${dataResource.integrity ?? dataResource.uri}`, async (signal) => {
+                const response = await fetch(dataResource.uri, signal ? { signal } : {});
+                if (!response.ok)
+                    throw new Error(`Deformable sidecar request failed with HTTP ${response.status}.`);
+                return response.arrayBuffer();
+            }, () => { }, { signal: this.controller.signal });
+            if (this.destroyed) {
+                dataHandle.release();
+                return;
+            }
+            this.assetHandles.push(dataHandle);
+            const data = decodeDeformableMesh2DData(dataHandle.value);
+            if (Math.abs(data.canvasWidth - this.context.animation.canvas.width) > 1e-6
+                || Math.abs(data.canvasHeight - this.context.animation.canvas.height) > 1e-6
+                || Math.abs(data.duration - this.context.animation.duration) > 1e-6) {
+                throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Deformable sidecar canvas/duration does not match HYA.', '$.resources');
+            }
+            for (let index = 0; index < data.drawables.length; index++) {
+                if (data.drawables[index].textureIndex >= textureResources.length)
+                    throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Drawable texture index exceeds component texture resources.', `$.drawables[${index}].textureIndex`);
+            }
+            const textureHandles = [];
+            for (let index = 0; index < textureResources.length; index++) {
+                const resource = textureResources[index];
+                try {
+                    textureHandles.push(await manager.loadTexture(resource.uri, {
+                        label: `DeformableMesh2D:${resource.id}`,
+                        // AnimationVisual2D currently composites display-encoded 2D colors
+                        // into an rgba8unorm canvas. An sRGB texture view would decode the
+                        // authored bytes to linear values and make the result visibly dark.
+                        // Preserve the source bytes here to match Canvas/WebGL Live2D output.
+                        format: 'rgba8unorm',
+                        // Cubism 5.2-and-earlier blend factors and linear texture filtering
+                        // both operate on premultiplied texels.
+                        premultipliedAlpha: true,
+                        cacheKey: resource.integrity ?? resource.uri,
+                        signal: this.controller.signal,
+                    }));
+                }
+                catch (error) {
+                    for (const handle of textureHandles)
+                        handle.release();
+                    throw new Error(`Texture ${index} failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (this.destroyed) {
+                for (const handle of textureHandles)
+                    handle.release();
+                return;
+            }
+            this.assetHandles.push(...textureHandles);
+            this.data = data;
+            this.createVisuals(data, textureHandles);
+            this.state = 'ready';
+            this.apply(this.lastTime, this.lastOpacity);
+            this.emitStatus();
+        }
+        catch (error) {
+            if (this.controller.signal.aborted || this.destroyed)
+                return;
+            for (const handle of this.assetHandles.splice(0))
+                handle.release();
+            this.data = null;
+            this.drawables.length = 0;
+            this.root.destroy();
+            this.state = 'error';
+            this.emitStatus(error instanceof Error ? error.message : String(error));
+        }
+    }
+    createVisuals(data, textures) {
+        const maskGroups = createRuntimeMaskGroups(data.drawables);
+        const groupByKey = new Map(maskGroups.map(group => [maskGroupKey(group.sources), group]));
+        const runtimeById = new Map();
+        const compositeFor = (drawable) => {
+            if (drawable.masks.length === 0)
+                return undefined;
+            const group = groupByKey.get(maskGroupKey(drawable.masks));
+            if (!group)
+                throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Drawable mask group could not be resolved.', `$.drawables[id=${JSON.stringify(drawable.id)}].masks`);
+            return {
+                layers: [{
+                        kind: 'mask',
+                        source: group.id,
+                        mode: drawable.maskMode,
+                        operation: 'add',
+                    }],
+            };
+        };
+        const createVisual = (drawable, geometry, sourceOnly, nodeId) => {
+            // A Cubism drawable used as a mask source is rendered directly into the
+            // clipping buffer. Its own clipping context must not recursively affect
+            // that setup-mask pass.
+            const composite = sourceOnly ? undefined : compositeFor(drawable);
+            return new AnimationVisual2D({
+                geometry,
+                uvs: drawable.uvs,
+                color: [1, 1, 1, 1],
+                instanceId: this.context.instanceId,
+                nodeId,
+                order: drawable.renderOrders[0],
+                blendMode: drawable.blendMode,
+                textureAlphaMode: 'premultiplied',
+                culling: drawable.culling,
+                sourceOnly,
+                ...(composite ? { composite } : {}),
+                textureHandle: textures[drawable.textureIndex],
+                requiresTexture: true,
+            });
+        };
+        for (const drawable of data.drawables) {
+            const positions = new Float32Array(drawable.vertexCount * 2);
+            sampleDeformableMesh2DDrawable(data.times, drawable, this.lastTime, positions);
+            const geometry = new Geometry2D(positions, drawable.indices);
+            const visible = createVisual(drawable, geometry, false, `draw:${drawable.id}`);
+            this.root.addChild(new Entity(`Drawable ${drawable.id}`).addComponent(visible));
+            const runtime = {
+                source: drawable,
+                geometry,
+                positions,
+                multiplyColor: new Float32Array(4),
+                screenColor: new Float32Array(4),
+                visuals: [visible],
+            };
+            runtimeById.set(drawable.id, runtime);
+            this.drawables.push(runtime);
+        }
+        for (const group of maskGroups) {
+            for (const sourceId of group.sources) {
+                const runtime = runtimeById.get(sourceId);
+                if (!runtime)
+                    throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Mask group references a missing drawable.', `$.drawables[id=${JSON.stringify(sourceId)}]`);
+                const mask = createVisual(runtime.source, runtime.geometry, true, group.id);
+                this.root.addChild(new Entity(`Mask group ${group.id} source ${sourceId}`).addComponent(mask));
+                runtime.visuals.push(mask);
+            }
+        }
+    }
+    emitStatus(error) {
+        this.options.onStatus?.(Object.freeze({ state: this.state, drawableCount: this.drawables.length, ...(error ? { error } : {}) }));
+    }
+}
+function createRuntimeMaskGroups(drawables) {
+    const groups = new Map();
+    for (const drawable of drawables) {
+        if (drawable.masks.length === 0)
+            continue;
+        const sources = Object.freeze([...drawable.masks].sort((left, right) => left.localeCompare(right)));
+        const key = maskGroupKey(sources);
+        if (!groups.has(key))
+            groups.set(key, Object.freeze({ id: `mask-group:${key}`, sources }));
+    }
+    return Object.freeze([...groups.values()]);
+}
+function maskGroupKey(sources) {
+    return [...sources]
+        .sort((left, right) => left.localeCompare(right))
+        .map(source => `${source.length}:${source}`)
+        .join('|');
+}
+
+export { createDeformableMesh2DRuntimeExtension, sampleDeformableMesh2DDrawable };
+//# sourceMappingURL=deformable-animation.js.map

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

@@ -0,0 +1,5 @@
+export { prepareIndexedSpriteAtlas } from './indexed-sprite/AtlasLayout';
+export { IndexedSpriteRenderer } from './indexed-sprite/IndexedSpriteRenderer';
+export type { IndexedSpriteRendererOptions } from './indexed-sprite/IndexedSpriteRenderer';
+export { DEFAULT_INDEXED_SPRITE_ATLAS_LIMITS } from './indexed-sprite/contracts';
+export type { IndexedSpriteAtlasLayout, IndexedSpriteAtlasLimits, IndexedSpriteAtlasPage, IndexedSpriteAtlasPlacement, IndexedSpriteBlend, IndexedSpriteDrawCommand, IndexedSpritePaletteDescriptor, IndexedSpritePlaneDescriptor, IndexedSpritePlaneFormat, IndexedSpriteRendererStats, IndexedSpriteSampling, } from './indexed-sprite/contracts';