Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

10.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    spine-batch-storage.test.ts
 * @brief   The batch slots outlive the frame that fills them — and hand back
 *          exactly what the frame-scoped ones did.
 *
 * @details A frame poses the skeletons the last frame posed, so it writes the
 *          same vectors to the same sizes. Destroying them in between made every
 *          frame grow back into the capacity it had just freed. Keeping them is
 *          only safe if two things stay true, and neither is visible in a wall
 *          clock: a slot the last frame filled must not be readable as this
 *          one's, and a slot reopened must carry nothing of what it held.
 *
 *          So the geometry is held to a digest taken from a build that did not
 *          have them — a parity claim is worth what its witness is independent
 *          of — and the storage itself is read through `spine_probe_storage`,
 *          because "it stopped reallocating" is a statement about capacity and
 *          not about time.
 */
import { describe, it, expect, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { WASM_DIR, hasSideModule } from './helpers/loadWasm';
import { wrapSpineModule } from '../src/spine/SpineModuleLoader';
import { SpineModuleController } from '../src/spine/SpineController';
import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';
import { withScratch } from '../src/wasm/wasmScratch';

const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');
const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');
const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');

/**
 * `hash` is FNV-1a over every batch's vertex bytes, index bytes and state, in
 * order — recorded from the build before this change, at the pose below.
 */
const ASSETS = [
    {
        name: 'spineboy', skel: 'spineboy-38/spineboy-pro.skel', atlas: 'spineboy-38/spineboy.atlas',
        hash: '2046a073', batches: [{ vertices: 278, indices: 1023, texture: 1, blend: 0 }],
    },
    {
        name: 'raptor', skel: 'raptor-38/raptor-pro.skel', atlas: 'raptor-38/raptor.atlas',
        hash: 'a25dcd8b', batches: [{ vertices: 588, indices: 2085, texture: 1, blend: 0 }],
    },
    {
        name: 'coin', skel: 'coin-38/coin-pro.skel', atlas: 'coin-38/coin.atlas',
        hash: '034b3ea2',
        batches: [
            { vertices: 12, indices: 18, texture: 1, blend: 0 },
            { vertices: 38, indices: 96, texture: 1, blend: 1 },
        ],
    },
] as const;

const HAS_ASSETS = hasSideModule('spine38')
    && ASSETS.every((a) => existsSync(resolve(FIXTURES, a.skel)));

/** The four u32 counters `spine_probe_storage` writes, in order. */
const STORAGE = ['slots', 'active', 'vertexFloats', 'indices'] as const;
type Storage = Record<(typeof STORAGE)[number], number>;

/** Every slot of coin's but the additive one, so that batch lands in slot 0. */
const COIN_NORMAL_SLOTS = ['clipping', 'coin-side', 'coin-front-texture', 'coin-side-round', 'shine'];
const COIN_ADDITIVE_SLOT = 'coin-front-shine';

let raw: SpineWasmModule;
let api: SpineWrappedAPI;
/** The pool as it was before anything had ever extracted through it. */
let atRest: Storage;

beforeAll(async () => {
    if (!HAS_ASSETS) return;
    const factory = (await import(SPINE38_JS)).default as (opts: unknown) => Promise<SpineWasmModule>;
    const bytes = readFileSync(SPINE38_WASM);
    raw = await factory({
        instantiateWasm(imports: WebAssembly.Imports, cb: (i: WebAssembly.Instance, m: WebAssembly.Module) => void) {
            void WebAssembly.instantiate(bytes, imports).then((r) => cb(r.instance, r.module));
            return {};
        },
    });
    api = wrapSpineModule(raw);
    atRest = storage();
});

function storage(): Storage {
    return withScratch(raw, (alloc) => {
        const ptr = alloc(STORAGE.length * 4);
        api.probeStorage(ptr);
        const out = {} as Storage;
        STORAGE.forEach((name, i) => { out[name] = raw.HEAPU32[(ptr >> 2) + i]; });
        return out;
    });
}

/** A skeleton whose atlas page is bound to `texture`, and one instance of it. */
function posed(asset: { skel: string; atlas: string }, texture = 1): number {
    const skelData = new Uint8Array(readFileSync(resolve(FIXTURES, asset.skel)));
    const atlasText = readFileSync(resolve(FIXTURES, asset.atlas), 'utf-8');
    const skelHandle = new SpineModuleController(raw, api).loadSkeleton(skelData, atlasText, true);
    for (let i = 0, pages = api.getAtlasPageCount(skelHandle); i < pages; i++) {
        api.setAtlasPageTexture(skelHandle, i, texture, 1024, 1024);
    }
    const instanceId = api.createInstance(skelHandle);
    const [first] = JSON.parse(api.getAnimations(instanceId)) as string[];
    if (!api.playAnimation(instanceId, first, true, 0)) throw new Error(`no animation "${first}"`);
    api.update(instanceId, 0.35);
    return instanceId;
}

interface Batch { vertices: number; indices: number; texture: number; blend: number }

/** Every batch of one extraction: its state, its extent, and its bytes. */
function read(instanceId: number): { batches: Batch[]; hash: string } {
    const count = api.getMeshBatchCount(instanceId);
    const batches: Batch[] = [];
    let hash = 0x811c9dc5;
    for (let b = 0; b < count; b++) {
        const vertices = api.getMeshBatchVertexCount(instanceId, b);
        const indices = api.getMeshBatchIndexCount(instanceId, b);
        withScratch(raw, (alloc) => {
            const vp = alloc(vertices * 8 * 4 + 4);
            const ip = alloc(indices * 2 + 2);
            const tp = alloc(4);
            const bp = alloc(4);
            api.getMeshBatchData(instanceId, b, vp, ip, tp, bp);
            const texture = raw.HEAPU32[tp >> 2];
            const blend = raw.HEAPU32[bp >> 2] | 0;
            hash = fnv1a(hash, new Uint8Array(raw.HEAPU8.buffer, vp, vertices * 8 * 4));
            hash = fnv1a(hash, new Uint8Array(raw.HEAPU8.buffer, ip, indices * 2));
            hash = fnv1a(hash, new Uint8Array(new Uint32Array([vertices, indices, texture, blend]).buffer));
            batches.push({ vertices, indices, texture, blend });
        });
    }
    return { batches, hash: (hash >>> 0).toString(16).padStart(8, '0') };
}

function fnv1a(seed: number, bytes: Uint8Array): number {
    let hash = seed;
    for (let i = 0; i < bytes.length; i++) {
        hash = Math.imul(hash ^ bytes[i], 0x01000193) >>> 0;
    }
    return hash >>> 0;
}

describe.skipIf(!HAS_ASSETS)('spine batch storage outlives the frame', () => {
    it('a steady pose reallocates nothing after the first frame', () => {
        expect(atRest, 'the pool held storage before anything extracted through it')
            .toEqual({ slots: 0, active: 0, vertexFloats: 0, indices: 0 });

        // Warmed by the BIGGER skeleton on purpose: a pool sized to the frame it
        // is about to run reads the same whether it kept its storage or freed it
        // and grew back. Warmed above, rebuilding shows up as capacity dropping.
        const big = posed(ASSETS[1]);
        const steady = posed(ASSETS[0]);
        api.getMeshBatchCount(big);
        const warm = storage();
        expect(warm.vertexFloats, 'the warm-up frame did not size the pool')
            .toBeGreaterThanOrEqual(588 * 8);

        for (let frame = 1; frame <= 6; frame++) {
            api.getMeshBatchCount(steady);
            expect(storage(), `frame ${frame} rebuilt storage the pool already held`)
                .toEqual(warm);
        }
    });

    it('persistent slots hand back the geometry the frame-scoped ones did', () => {
        for (const asset of ASSETS) {
            const instanceId = posed(asset);
            const got = read(instanceId);
            expect(got.batches, `${asset.name}: the batches a frame reads changed`)
                .toEqual(asset.batches.map((b) => ({ ...b })));
            expect(got.hash, `${asset.name}: same batches, different bytes`).toBe(asset.hash);
        }
    });

    it('a frame with fewer batches does not show the ones it did not fill', () => {
        const coin = posed(ASSETS[2]);
        const spineboy = posed(ASSETS[0]);

        expect(api.getMeshBatchCount(coin)).toBe(2);
        expect(api.getMeshBatchCount(spineboy)).toBe(1);
        expect(storage().active, 'the slot coin filled is still counted as this frame\'s').toBe(1);
        // The slot coin's second batch left behind is still allocated; a reader
        // that went by the pool rather than by the frame would find it here.
        expect(api.getMeshBatchVertexCount(spineboy, 1)).toBe(0);
        expect(api.getMeshBatchIndexCount(spineboy, 1)).toBe(0);
    });

    it('a reopened slot keeps nothing of the batch it last held', () => {
        const coin = posed(ASSETS[2], 1);
        const before = read(coin);
        expect(before.hash).toBe(ASSETS[2].hash);

        // One additive batch, bound to another texture: slot 0 now holds every
        // field coin's own first batch must overwrite — state, extent and bytes.
        const shineOnly = posed(ASSETS[2], 9);
        for (const slot of COIN_NORMAL_SLOTS) api.setAttachment(shineOnly, slot, '');
        const shine = read(shineOnly);
        expect(shine.batches, 'the fixture no longer produces one additive batch in slot 0')
            .toEqual([{ vertices: 4, indices: 6, texture: 9, blend: 1 }]);

        expect(read(coin), 'coin read back what the slot held before it').toEqual(before);
        expect(api.setAttachment(shineOnly, COIN_ADDITIVE_SLOT, '')).toBe(1);
    });

    it('capacity is scoped to the module, not to the frame', () => {
        const raptor = posed(ASSETS[1]);
        const spineboy = posed(ASSETS[0]);

        api.getMeshBatchCount(raptor);
        const high = storage();
        expect(high.vertexFloats).toBeGreaterThanOrEqual(588 * 8);

        // The smaller frame keeps the larger one's storage rather than trimming
        // it: giving it back is the per-frame free this change removed.
        api.getMeshBatchCount(spineboy);
        expect(storage().vertexFloats).toBe(high.vertexFloats);
        expect(storage().indices).toBe(high.indices);
    });
});