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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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);
});
}
});
});