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
feat: add async system support for all schedule phases
esengine52f10af5090e
diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex c4caa0bcc..84139df11 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -356,7 +356,7 @@ export class App {// Run// =========================================================================- tick(delta: number): void {+ async tick(delta: number): Promise<void> {if (!this.runner_) {this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);if (this.statsEnabled_) {@@ -368,7 +368,7 @@ export class App {this.finishPlugins_();}- this.flushStartupSystems_();+ await this.flushStartupSystems_();this.eventRegistry_.swapAll();this.world_.advanceTick();@@ -377,27 +377,27 @@ export class App {this.frame_paused_ = false;if (this.user_paused_ && !this.step_pending_) {- this.runSchedule(Schedule.Last);+ await this.runSchedule(Schedule.Last);} else {- this.runSchedule(Schedule.First);+ await this.runSchedule(Schedule.First);this.fixedAccumulator_ += delta;let fixedSteps = 0;while (this.fixedAccumulator_ >= this.fixedTimestep_ && fixedSteps < this.maxFixedSteps_) {this.fixedAccumulator_ -= this.fixedTimestep_;- this.runSchedule(Schedule.FixedPreUpdate);- this.runSchedule(Schedule.FixedUpdate);- this.runSchedule(Schedule.FixedPostUpdate);+ await this.runSchedule(Schedule.FixedPreUpdate);+ await this.runSchedule(Schedule.FixedUpdate);+ await this.runSchedule(Schedule.FixedPostUpdate);fixedSteps++;}if (fixedSteps >= this.maxFixedSteps_) {this.fixedAccumulator_ = this.fixedTimestep_;}- this.runSchedule(Schedule.PreUpdate);- this.runSchedule(Schedule.Update);- this.runSchedule(Schedule.PostUpdate);- this.runSchedule(Schedule.Last);+ await this.runSchedule(Schedule.PreUpdate);+ await this.runSchedule(Schedule.Update);+ await this.runSchedule(Schedule.PostUpdate);+ await this.runSchedule(Schedule.Last);if (this.step_pending_) {this.step_pending_ = false;@@ -408,7 +408,7 @@ export class App {this.world_.cleanRemovedBuffer(this.world_.getWorldTick() - REMOVED_BUFFER_RETENTION);}- run(): void {+ async run(): Promise<void> {if (this.running_) {return;}@@ -422,13 +422,13 @@ export class App {this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0 });this.finishPlugins_();- this.flushStartupSystems_();+ await this.flushStartupSystems_();this.lastTime_ = platformNow();this.mainLoop();}- private mainLoop = (): void => {+ private mainLoop = async (): Promise<void> => {if (!this.running_) {return;}@@ -440,7 +440,7 @@ export class App {const rawDelta = Math.min(deltaMs / 1000, this.maxDeltaTime_);const delta = rawDelta * this.play_speed_;- this.flushStartupSystems_();+ await this.flushStartupSystems_();this.eventRegistry_.swapAll();this.world_.advanceTick();@@ -449,27 +449,27 @@ export class App {this.frame_paused_ = false;if (this.user_paused_ && !this.step_pending_) {- this.runSchedule(Schedule.Last);+ await this.runSchedule(Schedule.Last);} else {- this.runSchedule(Schedule.First);+ await this.runSchedule(Schedule.First);this.fixedAccumulator_ += delta;let fixedSteps = 0;while (this.fixedAccumulator_ >= this.fixedTimestep_ && fixedSteps < this.maxFixedSteps_) {this.fixedAccumulator_ -= this.fixedTimestep_;- this.runSchedule(Schedule.FixedPreUpdate);- this.runSchedule(Schedule.FixedUpdate);- this.runSchedule(Schedule.FixedPostUpdate);+ await this.runSchedule(Schedule.FixedPreUpdate);+ await this.runSchedule(Schedule.FixedUpdate);+ await this.runSchedule(Schedule.FixedPostUpdate);fixedSteps++;}if (fixedSteps >= this.maxFixedSteps_) {this.fixedAccumulator_ = this.fixedTimestep_;}- this.runSchedule(Schedule.PreUpdate);- this.runSchedule(Schedule.Update);- this.runSchedule(Schedule.PostUpdate);- this.runSchedule(Schedule.Last);+ await this.runSchedule(Schedule.PreUpdate);+ await this.runSchedule(Schedule.Update);+ await this.runSchedule(Schedule.PostUpdate);+ await this.runSchedule(Schedule.Last);if (this.step_pending_) {this.step_pending_ = false;@@ -595,16 +595,16 @@ export class App {return sorted;}- private flushStartupSystems_(): void {+ private async flushStartupSystems_(): Promise<void> {const startup = this.systems_.get(Schedule.Startup)!;if (startup.length === 0) return;this.sortedSystemsCache_.delete(Schedule.Startup);- this.runSchedule(Schedule.Startup);+ await this.runSchedule(Schedule.Startup);startup.length = 0;this.sortedSystemsCache_.delete(Schedule.Startup);}- private runSchedule(schedule: Schedule): void {+ private async runSchedule(schedule: Schedule): Promise<void> {const rawSystems = this.systems_.get(schedule);if (!rawSystems || !this.runner_ || this.frame_paused_) {return;@@ -624,7 +624,10 @@ export class App {for (const entry of systems) {try {- this.runner_.run(entry.system);+ const result = this.runner_.run(entry.system);+ if (result instanceof Promise) {+ await result;+ }} catch (e) {const name = entry.system._name;console.error(`[ESEngine] System "${name}" threw an error:`, e);diff --git a/sdk/src/system.ts b/sdk/src/system.tsindex 3f8c15fcb..83ee661c1 100644--- a/sdk/src/system.ts+++ b/sdk/src/system.ts@@ -84,7 +84,7 @@ export type InferParams<P extends readonly SystemParam[]> = {export interface SystemDef {readonly _id: symbol;readonly _params: readonly SystemParam[];- readonly _fn: (...args: never[]) => void;+ readonly _fn: (...args: never[]) => void | Promise<void>;readonly _name: string;}@@ -98,7 +98,7 @@ export interface SystemOptions {export function defineSystem<P extends readonly SystemParam[]>(params: [...P],- fn: (...args: InferParams<P>) => void,+ fn: (...args: InferParams<P>) => void | Promise<void>,options?: SystemOptions): SystemDef {const id = ++systemCounter;@@ -161,7 +161,7 @@ export class SystemRunner {return this.timings_;}- run(system: SystemDef): void {+ run(system: SystemDef): void | Promise<void> {let args = this.argsCache_.get(system._id);if (!args) {args = new Array(system._params.length);@@ -213,21 +213,37 @@ export class SystemRunner {}const t0 = this.timings_ ? performance.now() : 0;+ let result: void | Promise<void>;try {- (system._fn as (...args: unknown[]) => void)(...args);+ result = (system._fn as (...args: unknown[]) => void | Promise<void>)(...args);+ } catch (e) {+ this.flushSystem_(system, args, t0);+ throw e;+ }- for (let i = 0; i < args.length; i++) {- if (args[i] instanceof CommandsInstance) {- (args[i] as CommandsInstance).flush();- }- }- } finally {- if (this.timings_) {- this.timings_.set(system._name, performance.now() - t0);+ if (result instanceof Promise) {+ return result.then(() => {+ this.flushSystem_(system, args, t0);+ }, (e) => {+ this.flushSystem_(system, args, t0);+ throw e;+ });+ }++ this.flushSystem_(system, args, t0);+ }++ private flushSystem_(system: SystemDef, args: unknown[], t0: number): void {+ for (let i = 0; i < args.length; i++) {+ if (args[i] instanceof CommandsInstance) {+ (args[i] as CommandsInstance).flush();}- this.world_.resetIterationDepth();- this.systemTicks_.set(system._id, this.world_.getWorldTick());}+ if (this.timings_) {+ this.timings_.set(system._name, performance.now() - t0);+ }+ this.world_.resetIterationDepth();+ this.systemTicks_.set(system._id, this.world_.getWorldTick());}private resolveParam(param: SystemParam): unknown {diff --git a/sdk/tests/app-tick.test.ts b/sdk/tests/app-tick.test.tsindex 952b04c74..957928af9 100644--- a/sdk/tests/app-tick.test.ts+++ b/sdk/tests/app-tick.test.ts@@ -5,11 +5,11 @@ import { Time } from '../src/resource';import { defineResource, Res } from '../src/resource';describe('App.tick()', () => {- it('should lazily initialize runner and Time resource', () => {+ it('should lazily initialize runner and Time resource', async () => {const app = App.new();expect(app.hasResource(Time)).toBe(false);- app.tick(1 / 60);+ await app.tick(1 / 60);expect(app.hasResource(Time)).toBe(true);const time = app.getResource(Time);@@ -17,7 +17,7 @@ describe('App.tick()', () => {expect(time.delta).toBeCloseTo(1 / 60);});- it('should run Startup schedule only once', () => {+ it('should run Startup schedule only once', async () => {const app = App.new();let startupCount = 0;@@ -25,14 +25,14 @@ describe('App.tick()', () => {[], () => { startupCount++; }, { name: 'TestStartup' }));- app.tick(1 / 60);- app.tick(1 / 60);- app.tick(1 / 60);+ await app.tick(1 / 60);+ await app.tick(1 / 60);+ await app.tick(1 / 60);expect(startupCount).toBe(1);});- it('should execute schedules in correct order', () => {+ it('should execute schedules in correct order', async () => {const app = App.new();const order: string[] = [];@@ -52,12 +52,12 @@ describe('App.tick()', () => {[], () => { order.push('Last'); }, { name: 'S_Last' }));- app.tick(1 / 60);+ await app.tick(1 / 60);expect(order).toEqual(['First', 'PreUpdate', 'Update', 'PostUpdate', 'Last']);});- it('should skip Fixed schedules when accumulator below timestep', () => {+ it('should skip Fixed schedules when accumulator below timestep', async () => {const app = App.new();let fixedRan = false;@@ -66,17 +66,17 @@ describe('App.tick()', () => {));// Default fixedTimestep is 1/60; pass a smaller dt so accumulator stays below threshold- app.tick(1 / 120);+ await app.tick(1 / 120);expect(fixedRan).toBe(false);});- it('should accumulate elapsed time across ticks', () => {+ it('should accumulate elapsed time across ticks', async () => {const app = App.new();- app.tick(0.1);- app.tick(0.2);- app.tick(0.05);+ await app.tick(0.1);+ await app.tick(0.2);+ await app.tick(0.05);const time = app.getResource(Time);expect(time.elapsed).toBeCloseTo(0.35);@@ -84,7 +84,7 @@ describe('App.tick()', () => {expect(time.delta).toBeCloseTo(0.05);});- it('should pass resources to systems via Res()', () => {+ it('should pass resources to systems via Res()', async () => {const app = App.new();const MyRes = defineResource({ value: 42 }, 'MyRes');app.insertResource(MyRes, { value: 42 });@@ -96,7 +96,7 @@ describe('App.tick()', () => {{ name: 'S_ReadRes' }));- app.tick(1 / 60);+ await app.tick(1 / 60);expect(capturedValue).toBe(42);});diff --git a/sdk/tests/async-system.test.ts b/sdk/tests/async-system.test.tsnew file mode 100644index 000000000..a696b8e6b--- /dev/null+++ b/sdk/tests/async-system.test.ts@@ -0,0 +1,257 @@+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { App } from '../src/app';+import { defineSystem, Schedule, SystemRunner } from '../src/system';+import { defineResource, Res, ResMut, ResourceStorage } from '../src/resource';+import { Commands, CommandsInstance } from '../src/commands';+import type { World } from '../src/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[]),+ beginIteration: vi.fn(),+ endIteration: vi.fn(),+ resetIterationDepth: vi.fn(),+ getWorldTick: vi.fn(() => worldTick.value),+ 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+// =============================================================================++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']);+ });++ it('should await async systems in sequence within same schedule', 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' }+ ));++ await app.tick(1 / 60);++ expect(order).toEqual(['A', 'B']);+ });++ 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', 'async', 'sync-2']);+ });++ 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 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');+ });+});diff --git a/sdk/tests/system-ordering.test.ts b/sdk/tests/system-ordering.test.tsindex 150334eca..376c0c55f 100644--- a/sdk/tests/system-ordering.test.ts+++ b/sdk/tests/system-ordering.test.ts@@ -12,7 +12,7 @@ describe('System Dependency Ordering', () => {});describe('runAfter', () => {- it('should run systems in dependency order', () => {+ it('should run systems in dependency order', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -25,12 +25,12 @@ describe('System Dependency Ordering', () => {app.addSystemToSchedule(Schedule.Update, systemA);(app as any).runner_ = { run: (sys: any) => sys._fn() };- (app as any).runSchedule(Schedule.Update);+ await (app as any).runSchedule(Schedule.Update);expect(executionOrder).toEqual(['A', 'B']);});- it('should handle multiple runAfter dependencies', () => {+ it('should handle multiple runAfter dependencies', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -48,7 +48,7 @@ describe('System Dependency Ordering', () => {app.addSystemToSchedule(Schedule.Update, systemA);(app as any).runner_ = { run: (sys: any) => sys._fn() };- (app as any).runSchedule(Schedule.Update);+ await (app as any).runSchedule(Schedule.Update);const aIndex = executionOrder.indexOf('A');const bIndex = executionOrder.indexOf('B');@@ -60,7 +60,7 @@ describe('System Dependency Ordering', () => {});describe('runBefore', () => {- it('should run system before specified target', () => {+ it('should run system before specified target', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -73,14 +73,14 @@ describe('System Dependency Ordering', () => {app.addSystemToSchedule(Schedule.Update, systemA, { runBefore: ['SystemB'] });(app as any).runner_ = { run: (sys: any) => sys._fn() };- (app as any).runSchedule(Schedule.Update);+ await (app as any).runSchedule(Schedule.Update);expect(executionOrder).toEqual(['A', 'B']);});});describe('mixed dependencies', () => {- it('should handle runBefore and runAfter together', () => {+ it('should handle runBefore and runAfter together', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -98,7 +98,7 @@ describe('System Dependency Ordering', () => {app.addSystemToSchedule(Schedule.Update, systemA);(app as any).runner_ = { run: (sys: any) => sys._fn() };- (app as any).runSchedule(Schedule.Update);+ await (app as any).runSchedule(Schedule.Update);const aIndex = executionOrder.indexOf('A');const bIndex = executionOrder.indexOf('B');@@ -110,7 +110,7 @@ describe('System Dependency Ordering', () => {});describe('circular dependency detection', () => {- it('should throw on circular dependencies', () => {+ it('should throw on circular dependencies', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -124,14 +124,12 @@ describe('System Dependency Ordering', () => {(app as any).runner_ = { run: (sys: any) => sys._fn() };- expect(() => {- (app as any).runSchedule(Schedule.Update);- }).toThrow('Circular dependency');+ await expect((app as any).runSchedule(Schedule.Update)).rejects.toThrow('Circular dependency');});});describe('systems without dependencies', () => {- it('should run in registration order when no dependencies specified', () => {+ it('should run in registration order when no dependencies specified', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -149,14 +147,14 @@ describe('System Dependency Ordering', () => {app.addSystemToSchedule(Schedule.Update, systemC);(app as any).runner_ = { run: (sys: any) => sys._fn() };- (app as any).runSchedule(Schedule.Update);+ await (app as any).runSchedule(Schedule.Update);expect(executionOrder).toEqual(['A', 'B', 'C']);});});describe('timeline system ordering in PostUpdate', () => {- it('should run TimelineSystem after UILayoutLateSystem and before UITransformFinalSystem', () => {+ it('should run TimelineSystem after UILayoutLateSystem and before UITransformFinalSystem', async () => {const uiLayoutLate = defineSystem([], () => {executionOrder.push('UILayoutLateSystem');}, { name: 'UILayoutLateSystem' });@@ -180,7 +178,7 @@ describe('System Dependency Ordering', () => {});(app as any).runner_ = { run: (sys: any) => sys._fn() };- (app as any).runSchedule(Schedule.PostUpdate);+ await (app as any).runSchedule(Schedule.PostUpdate);const layoutIdx = executionOrder.indexOf('UILayoutLateSystem');const timelineIdx = executionOrder.indexOf('TimelineSystem');@@ -192,7 +190,7 @@ describe('System Dependency Ordering', () => {});describe('non-existent dependencies', () => {- it('should ignore dependencies on non-existent systems', () => {+ it('should ignore dependencies on non-existent systems', async () => {const systemA = defineSystem([], () => {executionOrder.push('A');}, { name: 'SystemA' });@@ -201,9 +199,7 @@ describe('System Dependency Ordering', () => {(app as any).runner_ = { run: (sys: any) => sys._fn() };- expect(() => {- (app as any).runSchedule(Schedule.Update);- }).not.toThrow();+ await expect((app as any).runSchedule(Schedule.Update)).resolves.not.toThrow();expect(executionOrder).toEqual(['A']);});