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, vi, beforeEach } from 'vitest';
import { App } from '../src/app/app';
import { defineSystem, Schedule, SystemRunner } from '../src/ecs/system';
import { defineResource, Res, ResMut, ResourceStorage } from '../src/ecs/resource';
import { Commands, CommandsInstance } from '../src/ecs/commands';
import type { World } from '../src/ecs/world';
import type { Entity } from '../src/types';
// =============================================================================
// Mock World
// =============================================================================
function createMockWorld() {
let nextId = 1;
const entities = new Set<Entity>();
const worldTick = { value: 0 };
const world = {
spawn: vi.fn(() => {
const e = nextId++ as Entity;
entities.add(e);
return e;
}),
despawn: vi.fn((e: Entity) => entities.delete(e)),
insert: vi.fn(),
remove: vi.fn(),
get: vi.fn(),
set: vi.fn(),
valid: vi.fn((e: Entity) => entities.has(e)),
getEntitiesWithComponents: vi.fn(() => [] as Entity[]),
// What QueryInstance actually calls: the precomputed-key path.
queryEntities: vi.fn(() => [] as Entity[]),
beginIteration: vi.fn(),
endIteration: vi.fn(),
resetIterationDepth: vi.fn(),
// A system parked at an await hands its share of the world's iteration
// guard back, so whoever runs next is not refused for it.
suspendIteration: vi.fn(() => 0),
resumeIteration: vi.fn(),
getWorldTick: vi.fn(() => worldTick.value),
getChangeSequence: vi.fn(() => 0),
isAddedSince: vi.fn(() => false),
isChangedSince: vi.fn(() => false),
getRemovedEntitiesSince: vi.fn(() => []),
enableChangeTracking: vi.fn(),
resolveGetter: vi.fn(() => null),
};
return { world: world as unknown as World, entities, worldTick };
}
// =============================================================================
// SystemRunner async tests
// =============================================================================
/** Drain the microtask queue and one macrotask turn — scheduling, not wall clock. */
const flush = (): Promise<void> => new Promise((resolve) => { setImmediate(resolve); });
describe('SystemRunner async', () => {
let mockWorld: ReturnType<typeof createMockWorld>;
let world: World;
let resources: ResourceStorage;
let runner: SystemRunner;
beforeEach(() => {
mockWorld = createMockWorld();
world = mockWorld.world;
resources = new ResourceStorage();
runner = new SystemRunner(world, resources);
});
it('should run async system and return a Promise', async () => {
const fn = vi.fn(async () => {});
const sys = defineSystem([], fn);
const result = runner.run(sys);
expect(result).toBeInstanceOf(Promise);
await result;
expect(fn).toHaveBeenCalledOnce();
});
it('should flush Commands after async system resolves', async () => {
let flushed = false;
const originalFlush = CommandsInstance.prototype.flush;
CommandsInstance.prototype.flush = function () {
flushed = true;
return originalFlush.call(this);
};
const sys = defineSystem([Commands()], async (cmds) => {
await Promise.resolve();
cmds.spawn();
});
await runner.run(sys);
expect(flushed).toBe(true);
CommandsInstance.prototype.flush = originalFlush;
});
it('should call resetIterationDepth after async system resolves', async () => {
const sys = defineSystem([], async () => {
await Promise.resolve();
});
await runner.run(sys);
expect((world as any).resetIterationDepth).toHaveBeenCalled();
});
it('should call resetIterationDepth even if async system rejects', async () => {
const sys = defineSystem([], async () => {
await Promise.resolve();
throw new Error('async boom');
});
await expect(runner.run(sys)).rejects.toThrow('async boom');
expect((world as any).resetIterationDepth).toHaveBeenCalled();
});
it('should still work synchronously for non-async systems', () => {
const fn = vi.fn();
const sys = defineSystem([], fn);
const result = runner.run(sys);
expect(result).toBeUndefined();
expect(fn).toHaveBeenCalledOnce();
});
it('should update system tick after async system completes', async () => {
mockWorld.worldTick.value = 5;
const sys = defineSystem([], async () => {
await Promise.resolve();
});
await runner.run(sys);
expect((world as any).getWorldTick).toHaveBeenCalled();
});
});
// =============================================================================
// App-level async system tests
// =============================================================================
describe('App async systems', () => {
it('should await async startup system before frame loop', async () => {
const app = App.new();
const order: string[] = [];
app.addSystemToSchedule(Schedule.Startup, defineSystem(
[], async () => {
await new Promise(r => setTimeout(r, 10));
order.push('startup-done');
}, { name: 'AsyncStartup' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { order.push('update'); }, { name: 'SyncUpdate' }
));
await app.tick(1 / 60);
expect(order).toEqual(['startup-done', 'update']);
});
it('should await async Update system', async () => {
const app = App.new();
const order: string[] = [];
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
order.push('async-start');
await Promise.resolve();
order.push('async-end');
}, { name: 'AsyncUpdate' }
));
app.addSystemToSchedule(Schedule.PostUpdate, defineSystem(
[], () => { order.push('post-update'); }, { name: 'SyncPostUpdate' }
));
await app.tick(1 / 60);
expect(order).toEqual(['async-start', 'async-end', 'post-update']);
});
// Systems that declare nothing they touch declare nothing about their order
// either, so their waits may overlap and the shorter one lands first.
// Ordering is something you say — see the next test.
it('lets unordered async systems overlap, and finish in their own order', async () => {
const app = App.new();
const started: string[] = [];
const order: string[] = [];
// Gates, not durations: the claim needs BOTH systems to reach their wait
// before either finishes, which a serial scheduler could not do. Racing
// two setTimeouts said that only by implication, and lost the race.
let releaseA!: () => void;
let releaseB!: () => void;
const gateA = new Promise<void>((r) => { releaseA = r; });
const gateB = new Promise<void>((r) => { releaseB = r; });
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
started.push('A');
await gateA;
order.push('A');
}, { name: 'AsyncA' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
started.push('B');
await gateB;
order.push('B');
}, { name: 'AsyncB' }
));
const ticking = app.tick(1 / 60);
await flush();
// The overlap itself: B began without waiting for A to finish.
expect(started).toEqual(['A', 'B']);
expect(order).toEqual([]);
releaseB();
await flush();
releaseA();
await ticking;
expect(order).toEqual(['B', 'A']);
});
it('keeps async systems in order when the order was declared', async () => {
const app = App.new();
const order: string[] = [];
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
await new Promise(r => setTimeout(r, 10));
order.push('A');
}, { name: 'AsyncA' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
await new Promise(r => setTimeout(r, 5));
order.push('B');
}, { name: 'AsyncB' }
), { runAfter: ['AsyncA'] });
await app.tick(1 / 60);
expect(order).toEqual(['A', 'B']);
});
// The point of overlapping: a synchronous system no longer queues behind an
// await it has nothing to do with. `sync-2` runs while `async` is parked, and
// every one of them still runs before the tick returns.
it('should handle mix of sync and async systems', async () => {
const app = App.new();
const order: string[] = [];
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { order.push('sync-1'); }, { name: 'Sync1' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
await Promise.resolve();
order.push('async');
}, { name: 'Async' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { order.push('sync-2'); }, { name: 'Sync2' }
));
await app.tick(1 / 60);
expect(order).toEqual(['sync-1', 'sync-2', 'async']);
});
it('should handle async system with resource access', async () => {
const app = App.new();
const MyData = defineResource<{ loaded: boolean }>({ loaded: false }, 'MyData');
app.insertResource(MyData, { loaded: false });
app.addSystemToSchedule(Schedule.Startup, defineSystem(
[ResMut(MyData)],
async (data) => {
await Promise.resolve();
data.get().loaded = true;
},
{ name: 'AsyncLoader' }
));
await app.tick(1 / 60);
expect(app.getResource(MyData).loaded).toBe(true);
});
it('should not run async startup system twice when tick is called concurrently', async () => {
const app = App.new();
let runCount = 0;
app.addSystemToSchedule(Schedule.Startup, defineSystem(
[], async () => {
runCount++;
await new Promise(r => setTimeout(r, 50));
}, { name: 'AsyncStartupOnce' }
));
const tick1 = app.tick(1 / 60);
const tick2 = app.tick(1 / 60);
await Promise.all([tick1, tick2]);
expect(runCount).toBe(1);
});
it('should handle error in async system gracefully', async () => {
const app = App.new();
const errors: string[] = [];
app.onSystemError((err) => {
errors.push(err.message);
return 'continue';
});
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], async () => {
await Promise.resolve();
throw new Error('async failure');
}, { name: 'FailingAsync' }
));
await app.tick(1 / 60);
expect(errors).toContain('async failure');
});
});