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.

12.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, vi, beforeEach } from 'vitest';
import type { Entity } from '../src/types';
import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
import type { TransformData, ParentData } from '../src/ecs/component';
import { Transform, Parent } from '../src/ecs/component';
import { applyPhysics2DTransforms } from '../src/physics/PhysicsSystem';
import { createMockModule } from './mocks/wasm';
import { World } from '../src/ecs/world';

// Publish the module's pose buffer to Transforms. The lerp itself lives in the
// physics module (see PhysicsModuleEntry.cpp / physics_interpolation doctests);
// what these tests cover is the SDK half — routing that buffer to the engine.
function sync(
    app: any,
    physMod: PhysicsWasmModule,
    ppu: number,
    parented: Set<Entity>,
): void {
    applyPhysics2DTransforms(app, ppu, parented, physMod, 1);
}

// =============================================================================
// Helpers
// =============================================================================

function buildPhysicsBuffer(bodies: Array<{ entity: number; x: number; y: number; angle: number }>): {
    buffer: ArrayBuffer;
    HEAPF32: Float32Array;
    HEAPU32: Uint32Array;
    ptr: number;
    count: number;
} {
    const count = bodies.length;
    const byteLength = count * 4 * 4;
    const ptr = 256;
    const totalBytes = ptr + byteLength;
    const buffer = new ArrayBuffer(totalBytes);
    const f32 = new Float32Array(buffer);
    const u32 = new Uint32Array(buffer);

    for (let i = 0; i < count; i++) {
        const base = (ptr >> 2) + i * 4;
        u32[base] = bodies[i].entity;
        f32[base + 1] = bodies[i].x;
        f32[base + 2] = bodies[i].y;
        f32[base + 3] = bodies[i].angle;
    }

    return { buffer, HEAPF32: f32, HEAPU32: u32, ptr, count };
}

/**
 * Stands in for the module's interpolation: the real one lerps its own snapshot
 * pair and hands back the result, so a mock that returns a prepared buffer is the
 * same contract with the arithmetic already settled.
 */
function createMockPhysicsModule(buf: ReturnType<typeof buildPhysicsBuffer>): PhysicsWasmModule {
    return {
        _physics_getDynamicBodyCount: () => buf.count,
        _physics_getDynamicBodyTransforms: () => buf.ptr,
        _physics_capturePoses: vi.fn(),
        _physics_getInterpolatedCount: () => buf.count,
        _physics_getInterpolatedTransforms: () => buf.ptr,
        HEAPF32: buf.HEAPF32,
        HEAPU32: buf.HEAPU32,
        HEAPU8: new Uint8Array(buf.buffer),
        _malloc: vi.fn(),
        _free: vi.fn(),
    } as unknown as PhysicsWasmModule;
}

function defaultTransform(): TransformData {
    return {
        position: { x: 0, y: 0, z: 0 },
        rotation: { w: 1, x: 0, y: 0, z: 0 },
        scale: { x: 1, y: 1, z: 1 },
        worldPosition: { x: 0, y: 0, z: 0 },
        worldRotation: { w: 1, x: 0, y: 0, z: 0 },
        worldScale: { x: 1, y: 1, z: 1 },
    } as TransformData;
}

function createTestApp() {
    const mod = createMockModule();
    const world = new World();
    world.connectCpp(mod.getRegistry(), mod);
    return {
        world,
        wasmModule: mod,
        get physicsModule() { return null; },
    } as any;
}

// =============================================================================
// Tests
// =============================================================================

describe('syncDynamicTransforms', () => {
    const PPU = 100;

    it('should update position from physics coordinates (× PPU)', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());

        const buf = buildPhysicsBuffer([
            { entity: e1 as number, x: 3.5, y: 7.2, angle: 0 },
        ]);
        const physMod = createMockPhysicsModule(buf);
        const parentedBodies = new Set<Entity>();

        sync(app, physMod, PPU, parentedBodies);

        const t = app.world.get(e1, Transform) as TransformData;
        expect(t.position.x).toBeCloseTo(350);
        expect(t.position.y).toBeCloseTo(720);
    });

    it('should update rotation quaternion from physics angle', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());

        const angle = Math.PI / 4;
        const buf = buildPhysicsBuffer([
            { entity: e1 as number, x: 0, y: 0, angle },
        ]);
        const physMod = createMockPhysicsModule(buf);

        sync(app, physMod, PPU, new Set());

        const t = app.world.get(e1, Transform) as TransformData;
        const half = angle * 0.5;
        expect(t.rotation.w).toBeCloseTo(Math.cos(half));
        expect(t.rotation.x).toBeCloseTo(0);
        expect(t.rotation.y).toBeCloseTo(0);
        expect(t.rotation.z).toBeCloseTo(Math.sin(half));
    });

    it('should handle multiple bodies in one call', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        const e2 = app.world.spawn();
        const e3 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());
        app.world.insert(e2, Transform, defaultTransform());
        app.world.insert(e3, Transform, defaultTransform());

        const buf = buildPhysicsBuffer([
            { entity: e1 as number, x: 1, y: 2, angle: 0 },
            { entity: e2 as number, x: 3, y: 4, angle: 0 },
            { entity: e3 as number, x: 5, y: 6, angle: 0 },
        ]);
        const physMod = createMockPhysicsModule(buf);

        sync(app, physMod, PPU, new Set());

        expect((app.world.get(e1, Transform) as TransformData).position.x).toBeCloseTo(100);
        expect((app.world.get(e2, Transform) as TransformData).position.x).toBeCloseTo(300);
        expect((app.world.get(e3, Transform) as TransformData).position.x).toBeCloseTo(500);
    });

    it('should skip invalid entities', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());

        const buf = buildPhysicsBuffer([
            { entity: 9999, x: 1, y: 2, angle: 0 },
            { entity: e1 as number, x: 5, y: 6, angle: 0 },
        ]);
        const physMod = createMockPhysicsModule(buf);

        sync(app, physMod, PPU, new Set());

        const t = app.world.get(e1, Transform) as TransformData;
        expect(t.position.x).toBeCloseTo(500);
        expect(t.position.y).toBeCloseTo(600);
    });

    it('should do nothing when count is zero', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, { ...defaultTransform(), position: { x: 42, y: 99, z: 0 } });

        const buf = buildPhysicsBuffer([]);
        const physMod = createMockPhysicsModule(buf);

        sync(app, physMod, PPU, new Set());

        const t = app.world.get(e1, Transform) as TransformData;
        expect(t.position.x).toBeCloseTo(42);
        expect(t.position.y).toBeCloseTo(99);
    });

    it('should handle large body count (benchmark-like)', () => {
        const app = createTestApp();
        const BODY_COUNT = 500;
        const entities: Entity[] = [];

        for (let i = 0; i < BODY_COUNT; i++) {
            const e = app.world.spawn();
            app.world.insert(e, Transform, defaultTransform());
            entities.push(e);
        }

        const bodies = entities.map((e, i) => ({
            entity: e as number,
            x: i * 0.5,
            y: i * 0.3,
            angle: i * 0.01,
        }));
        const buf = buildPhysicsBuffer(bodies);
        const physMod = createMockPhysicsModule(buf);

        sync(app, physMod, PPU, new Set());

        const t0 = app.world.get(entities[0], Transform) as TransformData;
        expect(t0.position.x).toBeCloseTo(0);
        expect(t0.position.y).toBeCloseTo(0);

        const tLast = app.world.get(entities[BODY_COUNT - 1], Transform) as TransformData;
        expect(tLast.position.x).toBeCloseTo((BODY_COUNT - 1) * 0.5 * PPU);
        expect(tLast.position.y).toBeCloseTo((BODY_COUNT - 1) * 0.3 * PPU);
    });
});

describe('syncDynamicTransforms — fast path', () => {
    const PPU = 100;

    it('should produce correct results via fast path (no parentedBodies)', () => {
        const app = createTestApp();

        const bodies = [
            { x: 1.5, y: 2.5, angle: 0.3 },
            { x: -0.7, y: 4.1, angle: -1.2 },
            { x: 10, y: 0, angle: Math.PI },
        ];

        const entities: Entity[] = [];
        for (const b of bodies) {
            const e = app.world.spawn();
            app.world.insert(e, Transform, defaultTransform());
            entities.push(e);
        }

        const buf = buildPhysicsBuffer(bodies.map((b, i) => ({ entity: entities[i] as number, ...b })));
        sync(app, createMockPhysicsModule(buf), PPU, new Set());

        for (let i = 0; i < bodies.length; i++) {
            const t = app.world.get(entities[i], Transform) as TransformData;
            expect(t.position.x).toBeCloseTo(bodies[i].x * PPU, 3);
            expect(t.position.y).toBeCloseTo(bodies[i].y * PPU, 3);

            const half = bodies[i].angle * 0.5;
            expect(t.rotation.w).toBeCloseTo(Math.cos(half), 3);
            expect(t.rotation.z).toBeCloseTo(Math.sin(half), 3);
        }
    });

    it('should fall back to slow path when parentedBodies is non-empty', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());

        const buf = buildPhysicsBuffer([
            { entity: e1 as number, x: 2, y: 3, angle: 0.5 },
        ]);
        const physMod = createMockPhysicsModule(buf);
        const parentedBodies = new Set<Entity>([e1]);

        sync(app, physMod, PPU, parentedBodies);

        const t = app.world.get(e1, Transform) as TransformData;
        expect(t.position.x).toBeCloseTo(200);
        expect(t.position.y).toBeCloseTo(300);
    });
});

// The lerp itself is the module's (physics_getInterpolatedTransforms); its
// semantics — midpoint, first-frame seeding, ±π short arc — are covered by the
// physics_interpolation doctests. What the SDK owes is asking at the right alpha
// and getting the answer to the engine without a per-body detour.
describe('interpolation hand-off', () => {
    const PPU = 100;

    it('asks the module for the pose at this frame\'s alpha', () => {
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());

        const mod = createMockPhysicsModule(buildPhysicsBuffer([
            { entity: e1 as number, x: 2, y: 4, angle: 0 },
        ]));
        const spy = vi.spyOn(mod, '_physics_getInterpolatedTransforms');

        applyPhysics2DTransforms(app, PPU, new Set(), mod, 0.5);

        expect(spy).toHaveBeenCalledWith(0.5);
        const t = app.world.get(e1, Transform) as TransformData;
        expect(t.position.x).toBeCloseTo(2 * PPU);
        expect(t.position.y).toBeCloseTo(4 * PPU);
    });

    it('publishes nothing when the module reports no bodies', () => {
        const app = createTestApp();
        const mod = createMockPhysicsModule(buildPhysicsBuffer([]));
        expect(() => applyPhysics2DTransforms(app, PPU, new Set(), mod, 1)).not.toThrow();
    });

    it('passes a shared heap straight through instead of re-marshalling it', () => {
        // A native host compiles physics into the engine's own binary: one heap, so
        // the module's pointer is already an engine pointer. Copying it there would
        // be pure waste, and allocating for the copy doubly so.
        const app = createTestApp();
        const e1 = app.world.spawn();
        app.world.insert(e1, Transform, defaultTransform());

        const buf = buildPhysicsBuffer([{ entity: e1 as number, x: 1, y: 1, angle: 0 }]);
        const sharedHeap = new Uint8Array(buf.buffer);
        const mod = createMockPhysicsModule(buf);
        (mod as any).HEAPU8 = sharedHeap;

        const batchSync = vi.fn();
        const malloc = vi.fn();
        const engine = app.wasmModule as any;
        engine.registry_batchSyncPhysicsTransforms = batchSync;
        engine.HEAPU8 = sharedHeap;
        engine._malloc = malloc;

        applyPhysics2DTransforms(app, PPU, new Set(), mod, 1);

        expect(batchSync).toHaveBeenCalledWith(expect.anything(), buf.ptr, 1, PPU);
        expect(malloc).not.toHaveBeenCalled();
    });
});