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.

5.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    pool-layout.test.ts
 * @brief   The engine's rows and the compiler's offsets are one layout.
 *
 * @details A compiled system loads a script component's field at the offset this
 *          compiler emitted. The engine writes it at the offset `ScriptPool`
 *          chose. Those are two authors for one number, and the way that ends is
 *          a read of a different field — the same failure EHT's table exists to
 *          prevent for engine components.
 *
 *          So this holds them together over a real `defineComponent` shape. It
 *          is the script-side counterpart of the `offsetof` checks in
 *          tests/aot/test_aot_host.cpp.
 */
import { describe, it, expect } from 'vitest';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

import { lowerProgram } from '../src/frontend';
import { builtinShapes } from '../src/builtins';
import { packLayout } from '../src/abi';
import { encBytes } from '../src/eir';
import { ScriptPool, poolShape, POOL_SLOT_BYTES } from '../../sdk/src/ecs/ScriptPool';
import * as sdkAbi from '../../sdk/src/ecs/aot/AotContext';
import { RESOURCE_NAMES, resourceFields } from '../../sdk/src/ecs/resourceShapes';
import { CMD_DESPAWN, CMD_REMOVE, CMD_WORDS, QUERYROWS_WORDS, SYSCTX_WORDS } from '../src/abi';

const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));

/** The literal `defineComponent` passes, as the SDK holds it in `_default`. */
const DRIFT_DEFAULTS = { rate: 40, wrap: 100, enabled: true };

const { module } = lowerProgram([FIXTURE], builtinShapes());
const layout = packLayout(module.comps);

describe('a script component has one layout, not two', () => {
    it('the compiler and the pool agree field by field', () => {
        const shape = layout.comps.get('FixtureDrift');
        expect(shape, 'the fixture stopped declaring FixtureDrift').toBeDefined();
        const pool = new ScriptPool(poolShape(DRIFT_DEFAULTS)!);

        expect(pool.stride).toBe(shape!.stride);
        pool.fields.forEach((f, i) => {
            const leaf = shape!.leaves.get(f.name);
            expect(leaf, `the compiler has no field '${f.name}'`).toBeDefined();
            expect(leaf!.byteOffset, `'${f.name}' sits in two places`).toBe(i * POOL_SLOT_BYTES);
            // A host record is f64 throughout, which is what makes one slot per
            // field the whole story.
            expect(encBytes(leaf!.enc)).toBe(POOL_SLOT_BYTES);
        });
    });

    it('and on the field ORDER, which is what a slot index means', () => {
        // Declaration order is the only thing tying slot 1 to `wrap`. If the two
        // sides ever sort differently, every field still exists and every one is
        // the wrong one.
        expect(new ScriptPool(poolShape(DRIFT_DEFAULTS)!).fields.map((f) => f.name))
            .toEqual([...layout.comps.get('FixtureDrift')!.leaves.keys()]);
    });

    it('a shape the pool refuses is a shape the compiler refuses', () => {
        // Both sides admit exactly the all-scalar shapes, and they have to: a
        // component the compiler lowers but the engine cannot lay out flat is a
        // system that compiles and then has nowhere to read from.
        expect(poolShape({ label: 'hi' })).toBeNull();
        expect(module.comps.get('FixtureDrift')!.storage).toBe('host');
        for (const [, spec] of module.comps.get('FixtureDrift')!.fields) {
            expect(spec.enc).toBe('f64');
            expect(spec.offset, 'a host record is laid out by the ABI, not by EHT').toBeNull();
        }
    });
});

/**
 * The SDK cannot import a build tool, so it keeps its own copy of the three
 * struct sizes — and a contract with two authors is a contract with none. This
 * is the seam that keeps them one number each.
 */
describe('the SDK and the compiler count the same words', () => {
    it('SysCtx, QueryRows and Cmd', () => {
        expect(sdkAbi.SYSCTX_WORDS).toBe(SYSCTX_WORDS);
        expect(sdkAbi.QUERYROWS_WORDS).toBe(QUERYROWS_WORDS);
        expect(sdkAbi.CMD_WORDS).toBe(CMD_WORDS);
    });

    it('and the command kinds, which are what a flush switches on', () => {
        expect(sdkAbi.CMD_DESPAWN).toBe(CMD_DESPAWN);
        expect(sdkAbi.CMD_REMOVE).toBe(CMD_REMOVE);
    });
});

/**
 * A resource is laid out from the SAME declaration on both sides: the compiler
 * derives its shape from it, and the SDK mirrors its values into that layout.
 */
describe('a resource has one layout too', () => {
    it('the compiler knows exactly the resources the SDK declares', () => {
        expect([...layout.resources.keys()].sort()).toEqual([...RESOURCE_NAMES].sort());
    });

    it('and lays their fields out in the order the SDK declares', () => {
        for (const name of RESOURCE_NAMES) {
            const fields = resourceFields(name)!;
            const shape = layout.resources.get(name)!;
            expect([...shape.leaves.keys()], `${name} field order`).toEqual([...fields]);
            fields.forEach((field, i) => {
                // The mirror writes field i at slot i; anything else and a system
                // reading `delta` would get `elapsed`.
                expect(shape.leaves.get(field)!.byteOffset, `${name}.${field}`)
                    .toBe(i * POOL_SLOT_BYTES);
            });
        }
    });
});