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.

15.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// The optional subsystems on a device. On the web they are fetched wasm side
// modules; in a native app the same C is compiled into the host binary and its entry
// points sit on the JS global object. What must hold is that NOTHING downstream can
// tell the difference: the SDK's `PhysicsWasmModule` shape is satisfied by the host
// globals plus the heap, so the runtime's own gating installs physics either way.
//
// Driven against a mock host scope — the marshalling is what these check, not Box2D.
import { describe, it, expect, vi } from 'vitest';
import {
    createNativeSideModules, NATIVE_SIDE_MODULE_PROBES, NATIVE_PREFIX_ALIASES,
} from '../src/ecs/bridge/nativeSideModules';
import { HEAP_BINDINGS } from '../src/ecs/bridge/nativeHeap';
import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
import { wrapDragonBonesModule } from '../src/dragonbones/DragonBonesModuleLoader';
import type { DragonBonesWasmModule } from '../src/dragonbones/DragonBonesModuleLoader';

/** A host that compiled physics in: the heap plus a few es_physics_* globals. */
function mockNativeHost(options: {
    physics?: boolean; heap?: boolean; spine?: number | number[]; dragonbones?: boolean;
} = {}) {
    const { physics = true, heap = true, spine, dragonbones = false } = options;
    const buffer = new ArrayBuffer(4096);
    let next = 8;
    const calls: { name: string; args: unknown[] }[] = [];
    const scope: Record<string, unknown> = {};
    if (heap) {
        scope[HEAP_BINDINGS.heap] = () => buffer;
        scope[HEAP_BINDINGS.malloc] = (bytes: number) => {
            const at = next; next += Math.ceil(bytes / 8) * 8; return at;
        };
        scope[HEAP_BINDINGS.free] = () => {};
    }
    if (physics) {
        const record = (name: string) => (...args: unknown[]) => { calls.push({ name, args }); return 0; };
        for (const name of ['init', 'step', 'createBody', 'destroyBody', 'setGravity',
                            'getDynamicBodyCount', 'collectEvents', 'addPolygonShape']) {
            scope[`es_physics_${name}`] = record(name);
        }
        // The readback getters answer an OFFSET into the heap (the wrapper published
        // the module's bytes there), exactly like a wasm pointer.
        scope['es_physics_getDynamicBodyTransforms'] = () => 64;
    }
    // A host carries every Spine release it was built with, each under its own
    // prefix (es_spine38_*, es_spine42_*): the tag says which ones this mock has.
    for (const tag of spine === undefined ? [] : [spine].flat()) {
        const record = (name: string) => (...args: unknown[]) => { calls.push({ name: `${tag}:${name}`, args }); return 1; };
        scope[`es_spine${tag}_loadSkeleton`] = record('loadSkeleton');
        scope[`es_spine${tag}_playAnimation`] = record('playAnimation');
        // A C string crosses as a JS string, in and out — the generated wrapper reads
        // and writes them, so nothing here needs the heap.
        scope[`es_spine${tag}_getAnimations`] = () => `idle,walk,run@${tag}`;
    }
    if (dragonbones) {
        // One runtime, no version to declare: the format is frozen, so unlike Spine
        // there is nothing for the host to disagree with the content about.
        scope['es_db_loadSkeleton'] = (...args: unknown[]) => { calls.push({ name: 'loadSkeleton', args }); return 1; };
        scope['es_db_createInstance'] = (...args: unknown[]) => { calls.push({ name: 'createInstance', args }); return 0; };
        scope['es_db_getArmatures'] = () => '["Dragon"]';
    }
    return { scope, buffer, calls };
}

describe('createNativeSideModules', () => {
    it('answers physics when the host compiled it in', async () => {
        const { scope } = mockNativeHost();
        const mod = await createNativeSideModules(scope).acquire('physics');
        expect(mod).not.toBeNull();
    });

    // iOS runs the game's JS on QuickJS, which has no WebAssembly global. The host's modules
    // are linked in C++, so that must not matter: the release boot of every iOS template
    // found physics, Spine and DragonBones all turned off by a check meant for the web.
    it('answers physics on a host with no WebAssembly global', async () => {
        const { scope } = mockNativeHost();
        const saved = globalThis.WebAssembly;
        try {
            delete (globalThis as { WebAssembly?: unknown }).WebAssembly;
            expect(await createNativeSideModules(scope).acquire('physics')).not.toBeNull();
        } finally {
            globalThis.WebAssembly = saved;
        }
    });

    it('answers null when the host did not — not an object that throws on first call', async () => {
        const { scope } = mockNativeHost({ physics: false });
        expect(await createNativeSideModules(scope).acquire('physics')).toBeNull();
    });

    it('answers null when the host bound no heap to marshal through', async () => {
        const { scope } = mockNativeHost({ heap: false });
        expect(await createNativeSideModules(scope).acquire('physics')).toBeNull();
    });

    it('answers null for a subsystem this host did not compile in', async () => {
        // The KTX2 transcoder is the one no native host needs a module for — it
        // transcodes in C++ behind the texture path (host/media/ktx2_decode.cpp).
        const { scope } = mockNativeHost();
        expect(await createNativeSideModules(scope).acquire('basis')).toBeNull();
        expect(NATIVE_SIDE_MODULE_PROBES.basis).toBeUndefined();
    });

    // The DragonBones module was linked into the Android host and unreachable from
    // it for exactly one missing probe entry, which is the shape of failure this
    // pins: the acquirer answering null while the binary carries the runtime.
    it('answers DragonBones when the host compiled it in', async () => {
        const { scope } = mockNativeHost({ dragonbones: true });
        const mod = await createNativeSideModules(scope).acquire('dragonbones');
        expect(mod).not.toBeNull();
        // Through the SAME cwrap the web loader uses, so the controller cannot tell
        // a compiled-in runtime from a fetched one.
        const wrapped = wrapDragonBonesModule(mod as unknown as DragonBonesWasmModule);
        expect(wrapped.getArmatures(1)).toBe('["Dragon"]');
    });

    it('answers null for DragonBones when the host did not compile it in', async () => {
        const { scope } = mockNativeHost();
        expect(await createNativeSideModules(scope).acquire('dragonbones')).toBeNull();
    });

    it('caches, so two consumers share one view', async () => {
        const host = createNativeSideModules(mockNativeHost().scope);
        expect(await host.acquire('physics')).toBe(await host.acquire('physics'));
    });
});

describe('the native physics module satisfies the SDK’s shape', () => {
    it('resolves an emscripten C export name to the host global', async () => {
        const { scope, calls } = mockNativeHost();
        const mod = (await createNativeSideModules(scope).acquire('physics')) as unknown as PhysicsWasmModule;
        mod._physics_init(0, -9.81, 1 / 60, 4, 120, 10, 10);
        mod._physics_step(1 / 60);
        expect(calls.map((c) => c.name)).toEqual(['init', 'step']);
        expect(calls[0]!.args).toEqual([0, -9.81, 1 / 60, 4, 120, 10, 10]);
    });

    it('carries the heap, so a caller writes its buffer and passes an offset', async () => {
        const { scope, buffer, calls } = mockNativeHost();
        const mod = (await createNativeSideModules(scope).acquire('physics')) as unknown as PhysicsWasmModule;
        // What PhysicsSystem does for a polygon collider.
        const verts = new Float32Array([0, 0, 1, 0, 1, 1]);
        const ptr = mod._malloc(verts.byteLength);
        mod.HEAPF32.set(verts, ptr / 4);
        mod._physics_addPolygonShape(1, ptr, 3, 0, 1, 0.3, 0, 0, 1, 0xffff);
        mod._free(ptr);
        // The bytes really landed in the host's arena, which is what the C side reads.
        expect(Array.from(new Float32Array(buffer, ptr, 6))).toEqual([0, 0, 1, 0, 1, 1]);
        expect(calls.at(-1)!.args[1]).toBe(ptr);
    });

    it('reads a readback getter as an offset into that same heap', async () => {
        const { scope, buffer } = mockNativeHost();
        const mod = (await createNativeSideModules(scope).acquire('physics')) as unknown as PhysicsWasmModule;
        // The host published a body transform at offset 64: [entity, x, y, angle].
        new Uint32Array(buffer, 64, 1)[0] = 7;
        new Float32Array(buffer, 68, 3).set([12.5, -3, 1.5]);
        const base = mod._physics_getDynamicBodyTransforms() >> 2;
        expect(mod.HEAPU32[base]).toBe(7);
        expect(Array.from(mod.HEAPF32.subarray(base + 1, base + 4))).toEqual([12.5, -3, 1.5]);
    });

    it('is honest about an entry point the host never bound', async () => {
        const { scope } = mockNativeHost();
        const mod = (await createNativeSideModules(scope).acquire('physics')) as unknown as
            Record<string, unknown>;
        expect(mod._physics_neverBound).toBeUndefined();
        expect('_physics_step' in mod).toBe(true);
        expect('_physics_neverBound' in mod).toBe(false);
    });

    it('does not invent a name that is not a C export', async () => {
        const { scope } = mockNativeHost();
        const mod = (await createNativeSideModules(scope).acquire('physics')) as unknown as
            Record<string, unknown>;
        // No leading underscore: not the export convention, so not forwarded.
        expect(mod.physics_step).toBeUndefined();
    });
});

describe('the runtime installs physics from a native host', () => {
    it('goes through the same acquirer the web realms use', async () => {
        const { scope } = mockNativeHost();
        const host = createNativeSideModules(scope);
        const acquire = vi.spyOn(host, 'acquire');
        await host.acquire('physics');
        expect(acquire).toHaveBeenCalledWith('physics');
    });
});

describe('spine on a native host', () => {
    it('answers each version the host carries', async () => {
        const host = createNativeSideModules(mockNativeHost({ spine: [38, 42] }).scope);
        expect(await host.acquire('spine:4.2')).not.toBeNull();
        expect(await host.acquire('spine:3.8')).not.toBeNull();
    });

    // #115: one binary, several runtimes, and the call reaches the one the skeleton
    // was exported from — never another release's decoder.
    it('routes each version to its own runtime', async () => {
        const { scope, calls } = mockNativeHost({ spine: [38, 42] });
        const host = createNativeSideModules(scope);
        type Mod = { _spine_loadSkeleton(...a: unknown[]): number; cwrap(i: string, r: string, a: string[]): (...a: unknown[]) => unknown };
        const v38 = (await host.acquire('spine:3.8')) as unknown as Mod;
        const v42 = (await host.acquire('spine:4.2')) as unknown as Mod;
        v38._spine_loadSkeleton('a');
        v42._spine_loadSkeleton('b');
        expect(calls.map((c) => c.name)).toEqual(['38:loadSkeleton', '42:loadSkeleton']);
        expect(v38.cwrap('spine_getAnimations', 'string', ['number'])(1)).toBe('idle,walk,run@38');
    });

    it('refuses a version the app does not carry, rather than mis-decoding a skeleton', async () => {
        const host = createNativeSideModules(mockNativeHost({ spine: 42 }).scope);
        expect(await host.acquire('spine:3.8')).toBeNull();
        expect(await host.acquire('spine:4.1')).toBeNull();
    });

    it('answers nothing when no spine runtime is linked at all', async () => {
        const host = createNativeSideModules(mockNativeHost().scope);
        expect(await host.acquire('spine:4.2')).toBeNull();
    });

    it('cwrap is a passthrough — the wrapper already speaks JS strings', async () => {
        const { scope, calls } = mockNativeHost({ spine: 42 });
        const mod = (await createNativeSideModules(scope).acquire('spine:4.2')) as unknown as {
            cwrap(ident: string, ret: string | null, args: string[]): (...a: unknown[]) => unknown;
        };
        const play = mod.cwrap('spine_playAnimation', 'number', ['number', 'string', 'number', 'number']);
        expect(play(1, 'walk', 1, 0)).toBe(1);
        expect(calls.at(-1)).toEqual({ name: '42:playAnimation', args: [1, 'walk', 1, 0] });

        const list = mod.cwrap('spine_getAnimations', 'string', ['number']);
        expect(list(1)).toBe('idle,walk,run@42');
    });

    it('reads and writes heap strings the way emscripten states them', async () => {
        const { scope } = mockNativeHost({ spine: 42 });
        const mod = (await createNativeSideModules(scope).acquire('spine:4.2')) as unknown as {
            UTF8ToString(ptr: number): string;
            stringToNewUTF8(str: string): number;
            _free(ptr: number): void;
        };
        const ptr = mod.stringToNewUTF8('走る');
        expect(ptr).toBeGreaterThan(0);
        expect(mod.UTF8ToString(ptr)).toBe('走る');
        expect(mod.UTF8ToString(0)).toBe('');   // what UTF8ToString(0) answers on the web
        mod._free(ptr);
    });
});

describe('3D physics on a native host: Jolt and PhysX side by side', () => {
    /** A host with Jolt's es_physics3d_* globals and, optionally, PhysX's renamed copy. */
    function physics3dHost(physx: boolean) {
        const { scope } = mockNativeHost({ physics: false });
        const calls: string[] = [];
        for (const prefix of physx ? ['physics3d', 'physx3d'] : ['physics3d']) {
            for (const name of ['init', 'step', 'addBox']) {
                scope[`es_${prefix}_${name}`] = () => { calls.push(`${prefix}_${name}`); return 7; };
            }
        }
        return { scope, calls };
    }

    it('answers the PhysX project with the physx3d_* copy, under the names the SDK calls', async () => {
        const { scope, calls } = physics3dHost(true);
        const mod = (await createNativeSideModules(scope).acquire('physics3d:physx')) as unknown as {
            _physics3d_init(...a: number[]): void; _physics3d_addBox(...a: number[]): number;
            cwrap(ident: string): (...a: unknown[]) => unknown;
        };
        mod._physics3d_init(0, -9.81, 0, 1024);
        expect(mod._physics3d_addBox(1)).toBe(7);
        (mod.cwrap('physics3d_step') as (...a: unknown[]) => unknown)(1 / 60, 1);
        expect(calls).toEqual(['physx3d_init', 'physx3d_addBox', 'physx3d_step']);
        expect(NATIVE_PREFIX_ALIASES['physics3d:physx']).toEqual(['physics3d_', 'physx3d_']);
    });

    it('answers the Jolt project with Jolt in the same binary', async () => {
        const { scope, calls } = physics3dHost(true);
        const mod = (await createNativeSideModules(scope).acquire('physics3d')) as unknown as {
            _physics3d_init(...a: number[]): void;
        };
        mod._physics3d_init(0, -9.81, 0, 1024);
        expect(calls).toEqual(['physics3d_init']);
    });

    it('runs a PhysX project on Jolt, and says so, on a host built without PhysX', async () => {
        const { scope, calls } = physics3dHost(false);
        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
        try {
            const mod = (await createNativeSideModules(scope).acquire('physics3d:physx')) as unknown as {
                _physics3d_init(...a: number[]): void;
            };
            expect(mod).not.toBeNull();
            mod._physics3d_init(0, -9.81, 0, 1024);
            expect(calls).toEqual(['physics3d_init']);
        } finally {
            warn.mockRestore();
        }
    });
});