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 } from 'vitest';
import { App } from '../src/app/app';
import { Schedule, defineSystem } from '../src/ecs/system';
import { Time } from '../src/ecs/resource';
import { defineResource, Res } from '../src/ecs/resource';
import { setPlatform } from '../src/platform/base';
import type { PlatformAdapter } from '../src/platform/types';
describe('App.tick()', () => {
it('should lazily initialize runner and Time resource', async () => {
const app = App.new();
expect(app.hasResource(Time)).toBe(false);
await app.tick(1 / 60);
expect(app.hasResource(Time)).toBe(true);
const time = app.getResource(Time);
expect(time.frameCount).toBe(1);
expect(time.delta).toBeCloseTo(1 / 60);
});
it('scales delta and stops the fixed steps at scale 0', async () => {
const app = App.new();
let fixedSteps = 0;
app.addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], () => { fixedSteps++; }));
await app.tick(1 / 30);
expect(fixedSteps).toBeGreaterThan(0);
const before = fixedSteps;
app.getResource(Time).scale = 0;
for (let i = 0; i < 10; i++) await app.tick(1 / 30);
const time = app.getResource(Time);
expect(time.delta).toBe(0);
// Real time keeps flowing — whatever must move while the world does not
// has something to move by.
expect(time.unscaledDelta).toBeCloseTo(1 / 30);
// The whole point: physics is a fixed step, and a paused world takes none.
expect(fixedSteps).toBe(before);
});
it('should run Startup schedule only once', async () => {
const app = App.new();
let startupCount = 0;
app.addSystemToSchedule(Schedule.Startup, defineSystem(
[], () => { startupCount++; }, { name: 'TestStartup' }
));
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', async () => {
const app = App.new();
const order: string[] = [];
app.addSystemToSchedule(Schedule.First, defineSystem(
[], () => { order.push('First'); }, { name: 'S_First' }
));
app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(
[], () => { order.push('PreUpdate'); }, { name: 'S_PreUpdate' }
));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { order.push('Update'); }, { name: 'S_Update' }
));
app.addSystemToSchedule(Schedule.PostUpdate, defineSystem(
[], () => { order.push('PostUpdate'); }, { name: 'S_PostUpdate' }
));
app.addSystemToSchedule(Schedule.Last, defineSystem(
[], () => { order.push('Last'); }, { name: 'S_Last' }
));
await app.tick(1 / 60);
expect(order).toEqual(['First', 'PreUpdate', 'Update', 'PostUpdate', 'Last']);
});
it('should skip Fixed schedules when accumulator below timestep', async () => {
const app = App.new();
let fixedRan = false;
app.addSystemToSchedule(Schedule.FixedUpdate, defineSystem(
[], () => { fixedRan = true; }, { name: 'S_FixedUpdate' }
));
// Default fixedTimestep is 1/60; pass a smaller dt so accumulator stays below threshold
await app.tick(1 / 120);
expect(fixedRan).toBe(false);
});
it('should accumulate elapsed time across ticks', async () => {
const app = App.new();
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);
expect(time.frameCount).toBe(3);
expect(time.delta).toBeCloseTo(0.05);
});
it('should pass resources to systems via Res()', async () => {
const app = App.new();
const MyRes = defineResource({ value: 42 }, 'MyRes');
app.insertResource(MyRes, { value: 42 });
let capturedValue = 0;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(MyRes)],
(res: { value: number }) => { capturedValue = res.value; },
{ name: 'S_ReadRes' }
));
await app.tick(1 / 60);
expect(capturedValue).toBe(42);
});
});
describe('App.stepFrames()', () => {
it('counts explicitly stepped frames separately from the normal clock', async () => {
const app = App.new();
await app.tick(1 / 60);
expect(app.getSteppedFrameCount()).toBe(0);
await app.stepFrames(5);
expect(app.getSteppedFrameCount()).toBe(5);
expect(app.getResource(Time).frameCount).toBe(6);
await app.tick(1 / 60);
expect(app.getSteppedFrameCount()).toBe(5);
const release = app.holdExecution();
await app.stepFrames(2);
expect(app.getSteppedFrameCount()).toBe(5);
release();
});
it('waits for an in-flight frame and resumes only one loop', async () => {
const realRaf = globalThis.requestAnimationFrame;
const realCancel = globalThis.cancelAnimationFrame;
const pending = new Map<number, FrameRequestCallback>();
let nextId = 0;
globalThis.requestAnimationFrame = callback => { pending.set(++nextId, callback); return nextId; };
globalThis.cancelAnimationFrame = id => { pending.delete(id); };
setPlatform({ now: () => 1000 } as unknown as PlatformAdapter);
let release!: () => void;
const blocked = new Promise<void>(resolve => { release = resolve; });
const app = App.new();
let frames = 0;
app.addSystem(defineSystem([], async () => { if (++frames === 1) await blocked; }, { name: 'AsyncFrame' }));
const settle = async () => { for (let i = 0; i < 50; i++) await Promise.resolve(); };
try {
await app.run(); await settle();
const stepping = app.stepFrames(2);
await settle();
expect(frames).toBe(1);
release(); await stepping; await settle();
expect(frames).toBe(3);
expect(pending.size).toBe(1);
} finally {
release(); app.quit();
globalThis.requestAnimationFrame = realRaf;
globalThis.cancelAnimationFrame = realCancel;
}
});
it('replaces the pending loop when stepping and ignores a stale callback', async () => {
const realRaf = globalThis.requestAnimationFrame;
const realCancel = globalThis.cancelAnimationFrame;
const pending = new Map<number, FrameRequestCallback>();
let nextId = 0;
globalThis.requestAnimationFrame = callback => { pending.set(++nextId, callback); return nextId; };
globalThis.cancelAnimationFrame = id => { pending.delete(id); };
setPlatform({ now: () => 1000 } as unknown as PlatformAdapter);
const app = App.new();
let frames = 0;
app.addSystem(defineSystem([], () => { frames++; }, { name: 'CountLoopFrames' }));
const settle = async () => { for (let i = 0; i < 50; i++) await Promise.resolve(); };
try {
await app.run(); await settle();
expect(pending.size).toBe(1);
const stale = [...pending.values()][0];
for (let i = 0; i < 5; i++) await app.stepFrames(2);
expect(pending.size).toBe(1);
const before = frames;
await stale(1016.67); await settle();
expect(frames).toBe(before);
expect(pending.size).toBe(1);
const [id, callback] = [...pending.entries()][0];
pending.delete(id);
await callback(1033.33); await settle();
expect(frames).toBe(before + 1);
expect(pending.size).toBe(1);
app.quit();
expect(pending.size).toBe(0);
} finally {
app.quit();
globalThis.requestAnimationFrame = realRaf;
globalThis.cancelAnimationFrame = realCancel;
}
});
// The rAF loop is wall-clock and the browser throttles it in a background tab
// to about a frame a second, so "wait and look again" cannot observe a game.
// This is the door that advances one on purpose; before it existed the only
// way through was App's private runFrame_, which a dogfood run duly found.
it('runs exactly the frames asked for, at exactly the delta asked for', async () => {
const app = App.new();
let frames = 0;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { frames++; }, { name: 'Count' },
));
await app.stepFrames(30, 1 / 60);
expect(frames).toBe(30);
const time = app.getResource(Time);
expect(time.frameCount).toBe(30);
expect(time.delta).toBeCloseTo(1 / 60);
expect(time.elapsed).toBeCloseTo(0.5);
});
it('steps a PAUSED app — that is what stepping a paused game means — and leaves it paused', async () => {
const app = App.new();
let frames = 0;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { frames++; }, { name: 'Count' },
));
app.setPaused(true);
await app.stepFrames(3);
expect(frames).toBe(3);
expect(app.isPaused()).toBe(true);
});
// Measuring delta at callback entry folds the scheduling jitter in twice —
// added to one frame, subtracted from the next — turning a steady 60 Hz into
// unequal `speed * delta` steps. The rAF timestamp is the vsync itself.
it('takes the frame clock from the animation-frame timestamp, not the callback entry time', async () => {
const realRaf = globalThis.requestAnimationFrame;
let pending: ((ts: number) => void) | null = null;
globalThis.requestAnimationFrame = ((fn: FrameRequestCallback) => {
pending = fn as unknown as (ts: number) => void;
return 1;
}) as unknown as typeof globalThis.requestAnimationFrame;
// The wall clock as the callback sees it: vsync plus however long the host
// took to get round to us this frame.
let entryNow = 1000;
setPlatform({ now: () => entryNow } as unknown as PlatformAdapter);
const app = App.new();
const deltasMs: number[] = [];
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time)], (time: { delta: number }) => { deltasMs.push(time.delta * 1000); },
{ name: 'RecordDelta' },
));
const settle = async (): Promise<void> => {
for (let i = 0; i < 30; i++) await Promise.resolve();
};
try {
await app.run(); // seeds the clock and runs one frame off platformNow()
await settle();
deltasMs.length = 0;
app.setPlaySpeed(2);
const VSYNC = 1000 / 60;
const startDelay = [0.2, 4.1, 0.9, 6.3, 1.7, 3.0];
for (let i = 1; i <= startDelay.length; i++) {
const vsync = 1000 + i * VSYNC;
entryNow = vsync + startDelay[i - 1];
const fire = pending!;
pending = null;
await fire(vsync);
await settle();
}
expect(deltasMs).toHaveLength(startDelay.length);
for (const d of deltasMs) expect(d).toBeCloseTo(VSYNC * 2, 6);
expect(app.getFrameTiming()?.frameMs).toBeCloseTo(VSYNC, 6);
} finally {
app.quit();
globalThis.requestAnimationFrame = realRaf;
}
});
it('hands the cap to a native host, which paces its own display-driven loop', () => {
const host = globalThis as { es_setTargetFrameRate?: (fps: number) => void };
const seen: number[] = [];
host.es_setTargetFrameRate = (fps) => { seen.push(fps); };
try {
const app = App.new();
app.setTargetFrameRate(45);
app.setTargetFrameRate(0);
expect(seen).toEqual([45, 0]);
} finally {
delete host.es_setTargetFrameRate;
}
});
it.each([30, 48])('a %i fps cap on a 60 Hz display runs at the cap, whatever the jitter', async (cap) => {
const realRaf = globalThis.requestAnimationFrame;
let pending: ((ts: number) => void) | null = null;
globalThis.requestAnimationFrame = ((fn: FrameRequestCallback) => {
pending = fn as unknown as (ts: number) => void;
return 1;
}) as unknown as typeof globalThis.requestAnimationFrame;
setPlatform({ now: () => 1000 } as unknown as PlatformAdapter);
const app = App.new();
let frames = 0;
app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { frames++; }, { name: 'CountFrames' }));
const settle = async (): Promise<void> => { for (let i = 0; i < 30; i++) await Promise.resolve(); };
try {
app.setTargetFrameRate(cap);
await app.run();
await settle();
frames = 0;
// A 60 Hz display: vsyncs every 16.67 ms, each a fraction of a ms off.
const VSYNC = 1000 / 60;
for (let i = 1; i <= 120; i++) {
const fire = pending!;
pending = null;
await fire(1000 + i * VSYNC + (i % 2 ? -0.3 : 0.3));
await settle();
}
// Two seconds of vsyncs: never faster than the cap, and not a frame short of it.
expect(frames).toBeGreaterThanOrEqual(cap * 2 - 1);
expect(frames).toBeLessThanOrEqual(cap * 2 + 1);
} finally {
app.quit();
globalThis.requestAnimationFrame = realRaf;
}
});
it('keeps running on a host whose requestAnimationFrame refuses an async handler', async () => {
// vivo's quick-game runtime: "requestAnimationFrame handler is not a function"
// for anything whose tag is not [object Function] — and an async function's is not.
const realRaf = globalThis.requestAnimationFrame;
let pending: ((ts: number) => void) | null = null;
globalThis.requestAnimationFrame = ((fn: FrameRequestCallback) => {
if (Object.prototype.toString.call(fn) !== '[object Function]') return 0;
pending = fn as unknown as (ts: number) => void;
return 1;
}) as unknown as typeof globalThis.requestAnimationFrame;
setPlatform({ now: () => 1000 } as unknown as PlatformAdapter);
const app = App.new();
let frames = 0;
app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { frames++; }, { name: 'CountFrames' }));
const settle = async (): Promise<void> => { for (let i = 0; i < 30; i++) await Promise.resolve(); };
try {
await app.run();
await settle();
for (let i = 1; i <= 5; i++) {
const fire = pending as ((ts: number) => void) | null;
if (!fire) break;
pending = null;
fire(1000 + i * 16.7);
await settle();
}
expect(frames).toBeGreaterThanOrEqual(6);
} finally {
app.quit();
globalThis.requestAnimationFrame = realRaf;
}
});
it('defaults to one frame', async () => {
const app = App.new();
await app.stepFrames();
expect(app.getResource(Time).frameCount).toBe(1);
});
// A driver injects an input edge the moment this returns; a frame started
// inside the call would clear it at its Last before anything sampled it.
it('leaves the resumed loop to the next animation frame, so the caller keeps the boundary', async () => {
// The loop reads the clock through the platform, which only a real entry
// point installs.
setPlatform({ now: () => performance.now() } as unknown as PlatformAdapter);
const app = App.new();
let frames = 0;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[], () => { frames++; }, { name: 'Count' },
));
await app.run();
for (let i = 0; i < 20; i++) await Promise.resolve(); // the loop's first frame finishes
const before = frames;
await app.stepFrames(2);
expect(frames).toBe(before + 2);
for (let i = 0; i < 20; i++) await Promise.resolve();
expect(frames).toBe(before + 2);
app.quit();
});
});