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
import { describe, it, expect, beforeEach } from 'vitest';
import {
defineComponent,
defineBuiltin,
defineTag,
getComponent,
getComponentFieldMeta,
getUserComponent,
getUserComponents,
getComponentRegistry,
getComponentDefaults,
clearUserComponents,
unregisterComponent,
enumOptions,
Camera,
ProjectionType,
} from '../src/ecs/component';
import { AppContext, getDefaultContext, setDefaultContext } from '../src/ecs/context';
describe('Component Registry', () => {
beforeEach(() => {
clearUserComponents();
});
describe('defineComponent', () => {
it('should create a component with defaults', () => {
const TestComponent = defineComponent('TestComponent', {
value: 0,
name: 'test',
});
expect(TestComponent._name).toBe('TestComponent');
expect(TestComponent._default).toEqual({ value: 0, name: 'test' });
});
it('should create a component without defaults', () => {
const SimpleTag = defineComponent('SimpleTag', {});
expect(SimpleTag._name).toBe('SimpleTag');
expect(SimpleTag._default).toEqual({});
});
it('should register component in user registry', () => {
const Custom = defineComponent('Custom', { x: 1 });
const retrieved = getUserComponent('Custom');
expect(retrieved).toBe(Custom);
});
it('reuses the definition when a name is declared twice with the same fields', () => {
const comp1 = defineComponent('Duplicate', { a: 1 });
const comp2 = defineComponent('Duplicate', { a: 1 });
expect(comp1).toBe(comp2);
});
it('refuses a second component that claims a taken name with other fields', () => {
defineComponent('Contested', { a: 1 });
expect(() => defineComponent('Contested', { b: 2 }))
.toThrow(/Component name collision: "Contested"/);
});
});
describe('defineTag', () => {
it('should create a tag component with empty defaults', () => {
const TestTag = defineTag('TestTag');
expect(TestTag._name).toBe('TestTag');
expect(TestTag._default).toEqual({});
});
it('should register tag in user registry', () => {
const MyTag = defineTag('MyTag');
const retrieved = getUserComponent('MyTag');
expect(retrieved).toBe(MyTag);
});
});
describe('getComponent', () => {
it('should retrieve user-defined components', () => {
const Custom = defineComponent('Custom', { x: 1 });
const retrieved = getComponent('Custom');
expect(retrieved).toBe(Custom);
});
it('should return undefined for unknown components', () => {
const result = getComponent('NonExistent');
expect(result).toBeUndefined();
});
it('should prioritize user components over builtins', () => {
const Custom = defineComponent('CustomOverride', { custom: true });
const retrieved = getComponent('CustomOverride');
expect(retrieved).toBe(Custom);
});
});
describe('getUserComponent', () => {
it('should retrieve only user-defined components', () => {
const Custom = defineComponent('Custom', { x: 1 });
const retrieved = getUserComponent('Custom');
expect(retrieved).toBe(Custom);
});
it('should return undefined for builtins', () => {
const result = getUserComponent('Transform');
expect(result).toBeUndefined();
});
it('should return undefined for unknown components', () => {
const result = getUserComponent('NonExistent');
expect(result).toBeUndefined();
});
});
describe('getComponentDefaults', () => {
it('should return defaults for user components', () => {
defineComponent('WithDefaults', { x: 10, y: 20 });
const defaults = getComponentDefaults('WithDefaults');
expect(defaults).toEqual({ x: 10, y: 20 });
});
it('should return empty object for tags', () => {
defineTag('EmptyTag');
const defaults = getComponentDefaults('EmptyTag');
expect(defaults).toEqual({});
});
it('should return null for unknown components', () => {
const defaults = getComponentDefaults('Unknown');
expect(defaults).toBeNull();
});
});
describe('component reuse', () => {
it('should reuse component on duplicate names', () => {
const comp1 = defineComponent('Reusable', { x: 1 });
const comp2 = defineComponent('Reusable', { x: 1 });
expect(comp1).toBe(comp2);
});
});
describe('clearUserComponents', () => {
it('should clear all user-defined components', () => {
defineComponent('Comp1', { x: 1 });
defineComponent('Comp2', { y: 2 });
defineTag('Tag1');
clearUserComponents();
expect(getUserComponent('Comp1')).toBeUndefined();
expect(getUserComponent('Comp2')).toBeUndefined();
expect(getUserComponent('Tag1')).toBeUndefined();
});
it('should allow re-registration after clear', () => {
defineComponent('Reusable', { v: 1 });
clearUserComponents();
const NewReusable = defineComponent('Reusable', { v: 2 });
const retrieved = getUserComponent('Reusable');
expect(retrieved).toBe(NewReusable);
expect(retrieved?._default).toEqual({ v: 2 });
});
});
describe('component defaults cloning', () => {
it('should return cloned defaults each time', () => {
const Comp = defineComponent('Shared', { items: [] as number[] });
const defaults1 = getComponentDefaults('Shared');
const defaults2 = getComponentDefaults('Shared');
expect(defaults1).not.toBe(defaults2);
expect(defaults1).toEqual(defaults2);
});
});
describe('name collision detection', () => {
it('should throw when defineComponent collides with a builtin', () => {
expect(() => defineComponent('Transform', { x: 0 })).toThrow(
/Component name collision.*"Transform".*builtin/
);
});
it('should throw when defineTag collides with a builtin', () => {
expect(() => defineTag('Sprite')).toThrow(
/Component name collision.*"Sprite".*builtin/
);
});
it('should throw when defineBuiltin collides with a user component', () => {
defineComponent('MyCustom', { v: 1 });
try {
expect(() => defineBuiltin('MyCustom', { v: 2 })).toThrow(
/Component name collision.*"MyCustom".*user/
);
} finally {
unregisterComponent('MyCustom');
}
});
it('should allow idempotent re-registration of the same builtin', () => {
const first = defineBuiltin('TestBuiltin', { a: 1 });
const second = defineBuiltin('TestBuiltin', { a: 1 });
expect(first).toBe(second);
unregisterComponent('TestBuiltin');
});
});
describe('complex scenarios', () => {
it('should handle many components', () => {
for (let i = 0; i < 100; i++) {
defineComponent(`Comp${i}`, { index: i });
}
const comp50 = getComponent('Comp50');
expect(comp50?._default).toEqual({ index: 50 });
});
it('should handle mixed tags and components', () => {
const Tag1 = defineTag('Tag1');
const Comp1 = defineComponent('Comp1', { x: 1 });
const Tag2 = defineTag('Tag2');
const Comp2 = defineComponent('Comp2', { y: 2 });
expect(getUserComponent('Tag1')).toBe(Tag1);
expect(getUserComponent('Comp1')).toBe(Comp1);
expect(getUserComponent('Tag2')).toBe(Tag2);
expect(getUserComponent('Comp2')).toBe(Comp2);
});
});
});
// Two-tier registry invariants: builtins are GLOBAL (one module-level registry),
// user components are PER-CONTEXT (AppContext) and must not leak across contexts.
describe('Component registry tiers (builtins global, user per-context)', () => {
beforeEach(() => clearUserComponents());
it('getComponentRegistry merges builtins + the current context user components', () => {
const Builtin = defineBuiltin('TierBuiltin', { v: 0 });
const User = defineComponent('TierUser', { v: 0 });
const all = getComponentRegistry();
expect(all.get('TierBuiltin')).toBe(Builtin);
expect(all.get('TierUser')).toBe(User);
// getComponentRegistry is an alias of the complete view.
expect(getComponentRegistry().get('TierBuiltin')).toBe(Builtin);
// getComponent resolves both tiers.
expect(getComponent('TierBuiltin')).toBe(Builtin);
expect(getComponent('TierUser')).toBe(User);
});
it('getUserComponents excludes builtins', () => {
defineBuiltin('TierBuiltin2', { v: 0 });
const User = defineComponent('TierUser2', { v: 0 });
const users = getUserComponents();
expect(users.get('TierUser2')).toBe(User);
expect(users.has('TierBuiltin2')).toBe(false);
});
it('user components do NOT leak across contexts; builtins stay global', () => {
const Builtin = defineBuiltin('TierBuiltinGlobal', { v: 0 });
defineComponent('TierUserA', { v: 0 });
expect(getComponentRegistry().has('TierUserA')).toBe(true);
const original = getDefaultContext();
setDefaultContext(new AppContext());
try {
// Fresh context: the user component is isolated (no leak)…
expect(getComponentRegistry().has('TierUserA')).toBe(false);
expect(getUserComponents().has('TierUserA')).toBe(false);
// …but the builtin is still globally visible.
expect(getComponent('TierBuiltinGlobal')).toBe(Builtin);
expect(getComponentRegistry().has('TierBuiltinGlobal')).toBe(true);
} finally {
setDefaultContext(original);
}
// Restored context still has the original user component.
expect(getComponentRegistry().has('TierUserA')).toBe(true);
});
});
describe('Field metadata (editor presentation policy)', () => {
beforeEach(() => {
clearUserComponents();
});
it('enumOptions derives label→value pairs from a const, dropping value aliases', () => {
const opts = enumOptions(ProjectionType);
expect(opts).toEqual(
expect.arrayContaining([{ label: 'Perspective', value: 0 }, { label: 'Orthographic', value: 1 }]),
);
// Alias members sharing a value collapse to the first label.
const aliased = enumOptions({ A: 0, B: 1, BAlias: 1 });
expect(aliased).toEqual([{ label: 'A', value: 0 }, { label: 'B', value: 1 }]);
// A TS numeric enum's reverse (value→name) entries are not options.
expect(enumOptions({ Normal: 0, '0': 'Normal' } as Record<string, unknown>)).toEqual([
{ label: 'Normal', value: 0 },
]);
});
it('a builtin exposes enum + numeric field metadata; the runtime never reads it', () => {
const meta = getComponentFieldMeta('Camera');
expect(meta.projectionType?.enum).toEqual(enumOptions(ProjectionType));
expect(Camera.fieldMeta.projectionType?.enum).toBe(meta.projectionType?.enum);
// Numeric range/unit policy rides the same channel.
expect(meta.fov).toMatchObject({ min: 1, max: 179, unit: '°' });
expect(meta.orthoSize).toMatchObject({ min: 0 });
// Tooltips (UE ToolTip) ride the same metadata channel as range/unit.
expect(typeof meta.orthoSize?.tooltip).toBe('string');
// An unannotated field carries no metadata at all.
expect(meta.isActive).toBeUndefined();
});
it('a user component declares its own field metadata', () => {
const Mover = defineComponent('Mover', { mode: 0 }, {
fields: { mode: { enum: [{ label: 'Walk', value: 0 }, { label: 'Run', value: 1 }] } },
});
expect(Mover.fieldMeta.mode?.enum?.map((o) => o.label)).toEqual(['Walk', 'Run']);
expect(getComponentFieldMeta('Mover').mode?.enum?.[1]).toEqual({ label: 'Run', value: 1 });
});
it('a component without metadata returns an empty map', () => {
defineComponent('Plain', { hp: 100 });
expect(getComponentFieldMeta('Plain')).toEqual({});
expect(getComponentFieldMeta('Nonexistent')).toEqual({});
});
});
/**
* A project's declarations are BUNDLED, not type-checked, on the path the editor
* extracts schemas through — so a call TypeScript would have refused reaches
* runtime intact. `defineComponent({ name: 'Piece', fields: {...} })` is the
* shape the API reads like, and it used to store that whole object as the
* component's NAME. Nothing noticed until the extractor sorted by it, a stack
* away, as "e.name.localeCompare is not a function" — naming neither the
* component nor the call. One dogfood run lost twenty minutes to it and came out
* believing the system scheduler was broken.
*/
describe('defineComponent refuses a call TypeScript would have caught', () => {
it('names the signature when handed the options-object form', () => {
expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(
{ name: 'Piece', fields: { hp: 'number' } },
)).toThrow(/takes the NAME first/);
// And says which keys it actually got, so the caller sees their own object.
expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(
{ name: 'Piece', fields: { hp: 'number' } },
)).toThrow(/name, fields/);
});
it('says the defaults are values, not a description of them', () => {
expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(
{ name: 'Piece' },
)).toThrow(/real values/);
});
it('refuses an empty or non-string name', () => {
expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)('', {}))
.toThrow(/takes the NAME first/);
expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)(42, {}))
.toThrow(/number 42/);
});
it('refuses a missing or non-object defaults, naming the component', () => {
expect(() => (defineComponent as unknown as (a: unknown, b?: unknown) => unknown)('Piece'))
.toThrow(/Component "Piece".*was given nothing/s);
});
it('still accepts the real call', () => {
const def = defineComponent('GuardOk', { speed: 100 });
expect(def._name).toBe('GuardOk');
expect(def._default).toEqual({ speed: 100 });
});
});