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 The render system's frame order: the world's transforms resolve BEFORE
* the cameras are read.
*
* A camera's view matrix is built from its Transform's worldPosition, and the
* transform pass is what writes it. With the pass behind the read (its old home,
* inside submitScene) every camera was placed at the PREVIOUS frame's position
* while the sprites drew at this frame's — so a camera moved in Update trailed
* the world by exactly one frame, and the two only agreed while nothing moved.
*/
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { bootMockApp } from './helpers/mockApp';
import { setPlatform } from '../src/platform/base';
import type { PlatformAdapter } from '../src/platform/types';
import { cameraPlugin, renderCameraFrame } from '../src/camera/CameraPlugin';
import { RenderPipeline } from '../src/render/renderPipeline';
import { setRendererBackend, type RendererBackend } from '../src/render/renderer';
import { defineSystem, Schedule } from '../src/ecs/system';
import { Camera, Transform, ProjectionType } from '../src/ecs/component';
import { Query, Mut } from '../src/ecs/query';
import type { Entity } from '../src/types';
import type { CppRegistry } from '../src/wasm';
import { ScreenScaling } from '../src/camera/ScreenScaling';
import { Time } from '../src/ecs/resource';
import { setAppHostPaused } from '../src/app/app';
import { setViewTarget, BlendCurve, shakeCamera } from '../src/camera/CameraDirector';
/** Where a world point lands in clip space under a view-projection. */
const ndcX = (vp: Float32Array, x: number, y: number): number =>
vp[0] * x + vp[4] * y + vp[12];
describe('render order: transforms resolve before cameras are read', () => {
const calls: string[] = [];
let lastViewProjection: Float32Array | null = null;
let beginFrames = 0;
let wallTime = 0;
const drawnTimes: number[] = [];
/**
* Stands in for the C++ renderer: `beginFrame` clears the transform pass's
* once-per-frame memo (EngineState.transforms_updated) and the pass itself
* does what TransformSystem does to a root — world TRS := local TRS.
*/
function fakeBackend(registry: CppRegistry, roots: Entity[]): RendererBackend {
let transformsUpdated = false;
return {
init: () => {}, resize: () => {},
beginFrame: elapsed => { transformsUpdated = false; beginFrames++; drawnTimes.push(elapsed); calls.push('beginFrame'); },
updateTransforms: () => {
calls.push('updateTransforms');
if (transformsUpdated) return;
transformsUpdated = true;
for (const e of roots) {
const t = registry.getTransform(e) as unknown as
{ position: { x: number; y: number; z: number } } | undefined;
if (!t) continue;
(registry as unknown as { addTransform(e: Entity, d: unknown): void })
.addTransform(e, { ...t, worldPosition: { ...t.position } });
}
},
begin: (viewProjection) => { calls.push('begin'); lastViewProjection = viewProjection; },
submitAll: () => { calls.push('submitAll'); },
flush: () => {}, end: () => {}, endFrame: () => { calls.push('endFrame'); },
// No overlay from this fake: what it records is the ORDER a frame
// drives its cameras in, and a screen pass is not one of them.
hasScreenOverlay: () => false,
beginScreenOverlay: () => {}, submitScreenOverlay: () => {}, endScreenOverlay: () => {},
setStage: () => {}, setViewport: () => {},
setYSortLayers: () => {}, setDepthLayers: () => {}, setTreeSortLayers: () => {}, setCullingMask: () => {},
setViewId: () => {},
lodInspect: () => null, setLodPreview: () => {}, setViewShading: () => {}, setMeshEdgeBuffers: () => {}, setViewSkinWeights: () => {}, lightStatus: () => null, shadowStatus: () => null,
getStats: () => ({ drawCalls: 0, gpuDraws: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 }),
};
}
beforeEach(() => {
calls.length = 0; drawnTimes.length = 0; lastViewProjection = null; beginFrames = 0; wallTime = 0;
setPlatform({ now: () => wallTime, devicePixelRatio: () => 1 } as unknown as PlatformAdapter);
});
afterEach(() => { setRendererBackend(null); });
it.each([
{ dimension: '2D', projection: ProjectionType.Orthographic, owner: 'user' },
{ dimension: '3D', projection: ProjectionType.Perspective, owner: 'user' },
{ dimension: '2D', projection: ProjectionType.Orthographic, owner: 'host' },
{ dimension: '3D', projection: ProjectionType.Perspective, owner: 'host' },
] as const)('$dimension rendering shares scaled time through $owner pause, stepping and resume', async ({ projection, owner }) => {
const { app, module } = bootMockApp();
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
const cam = app.world.spawn('camera');
app.world.insert(cam, Transform, { position: { x: 0, y: 0, z: 5 } });
app.world.insert(cam, Camera, { isActive: true, projectionType: projection, orthoSize: 300 });
registry.getCameraEntities = () => [cam];
registry.getCanvasEntities = () => [];
const pipeline = new RenderPipeline();
app.setPipeline(pipeline);
setRendererBackend(fakeBackend(registry, [cam]));
app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
const host = {};
const pause = (on: boolean) => owner === 'host' ? setAppHostPaused(app, host, on) : app.setPaused(on);
wallTime = 10_000;
await app.tick(0.1);
expect(pipeline.frameElapsed).toBeCloseTo(0.1);
app.getResource(Time).scale = 0.5;
wallTime += 5000;
await app.tick(0.2);
expect(pipeline.frameElapsed).toBeCloseTo(0.2);
pause(true);
wallTime += 60_000;
await app.tick(0.2);
expect(pipeline.frameElapsed).toBeCloseTo(0.2);
expect(beginFrames).toBe(3);
await app.stepFrames(1, 0.1);
expect(pipeline.frameElapsed).toBeCloseTo(0.25);
expect(app.isPaused()).toBe(true);
expect(renderCameraFrame(app, 800, 600)).toBe(true);
expect(pipeline.frameElapsed).toBeCloseTo(0.25);
pause(false);
app.getResource(Time).scale = 0;
wallTime += 5000;
await app.tick(0.2);
expect(pipeline.frameElapsed).toBeCloseTo(0.25);
app.getResource(Time).scale = 1;
await app.tick(0.1);
expect(pipeline.frameElapsed).toBeCloseTo(0.35);
expect(drawnTimes).toHaveLength(7);
for (const [i, expected] of [0.1, 0.2, 0.2, 0.25, 0.25, 0.25, 0.35].entries()) {
expect(drawnTimes[i]).toBeCloseTo(expected);
}
app.quit();
});
it('camera blends and shakes freeze at the same frame as material time', async () => {
const { app, module } = bootMockApp();
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
const cameras = [app.world.spawn('from'), app.world.spawn('to')];
for (const [i, cam] of cameras.entries()) {
app.world.insert(cam, Transform, { position: { x: i * 100, y: 0, z: 0 } });
app.world.insert(cam, Camera, { isActive: i === 0, orthoSize: 300 });
}
registry.getCameraEntities = () => cameras;
registry.getCanvasEntities = () => [];
const pipeline = new RenderPipeline();
app.setPipeline(pipeline);
setRendererBackend(fakeBackend(registry, cameras));
app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
await app.tick(0.1);
setViewTarget(app, cameras[1], { time: 0.8, curve: BlendCurve.Linear });
shakeCamera(app, { amplitude: 4, frequency: 3, duration: 1 });
await app.tick(0.1);
await app.tick(0.2);
const held = Array.from(lastViewProjection!);
app.setPaused(true);
wallTime = 60_000;
await app.tick(0.2);
expect(Array.from(lastViewProjection!)).toEqual(held);
expect(pipeline.frameElapsed).toBeCloseTo(0.4);
await app.stepFrames(1, 0.2);
expect(Array.from(lastViewProjection!)).not.toEqual(held);
expect(pipeline.frameElapsed).toBeCloseTo(0.6);
app.quit();
});
it('previews an inactive camera at its latest placement without running Update', async () => {
const { app, module } = bootMockApp();
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
const cam = app.world.spawn('camera') as Entity;
app.world.insert(cam, Transform, { position: { x: 0, y: 0, z: 0 } });
app.world.insert(cam, Camera, { isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 300 });
registry.getCameraEntities = () => [cam];
registry.getCanvasEntities = () => [];
app.setPipeline(new RenderPipeline());
setRendererBackend(fakeBackend(registry, [cam]));
app.addPlugin(cameraPlugin(() => ({ width: 320, height: 180 })));
let updates = 0;
app.addSystem(defineSystem([], () => { updates++; }, { name: 'PreviewUpdate' }));
await app.tick(1 / 60);
app.world.insert(cam, Transform, { position: { x: 100, y: 0, z: 0 } });
app.world.insert(cam, Camera, { isActive: false, projectionType: ProjectionType.Orthographic, orthoSize: 180 });
calls.length = 0;
expect(renderCameraFrame(app, 320, 180, cam)).toBe(true);
expect(calls.indexOf('beginFrame')).toBeLessThan(calls.indexOf('updateTransforms'));
expect(ndcX(lastViewProjection!, 100, 0)).toBeCloseTo(0, 5);
expect(updates).toBe(1);
expect(app.world.get(cam, Camera).isActive).toBe(false);
expect(calls.at(-1)).toBe('endFrame');
expect(renderCameraFrame(app, 320, 180, 9999)).toBe(false);
expect(calls.at(-1)).toBe('endFrame');
});
it('a selected camera preview uses the project fit just as a game frame does', async () => {
const { app, module } = bootMockApp();
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
const cam = app.world.spawn('camera') as Entity;
app.world.insert(cam, Transform, {});
app.world.insert(cam, Camera, { isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 180 });
registry.getCameraEntities = () => [cam];
registry.getCanvasEntities = () => [];
app.setPipeline(new RenderPipeline());
setRendererBackend(fakeBackend(registry, [cam]));
app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
// FixedWidth on a wider design than the screen: the fit changes what the
// camera shows, so a preview that skipped it would not match the game.
app.insertResource(ScreenScaling, { designWidth: 1000, designHeight: 600, scaleMode: 0, matchWidthOrHeight: 0.5 });
await app.tick(1 / 60);
const gameProjection = Array.from(lastViewProjection!);
// The raw camera would put x = 400 (orthoSize 300 at 4:3) on the edge.
expect(Math.abs(ndcX(lastViewProjection!, 400, 0) - 1)).toBeGreaterThan(0.05);
app.world.update(cam, Camera, data => { data.isActive = false; });
expect(renderCameraFrame(app, 800, 600, cam)).toBe(true);
expect(Array.from(lastViewProjection!)).toEqual(gameProjection);
});
it('keeps updates alive without drawing a covered surface and resumes rendering', async () => {
const { app, module } = bootMockApp();
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
registry.getCameraEntities = () => [];
registry.getCanvasEntities = () => [];
const pipeline = new RenderPipeline();
app.setPipeline(pipeline);
setRendererBackend(fakeBackend(registry, []));
app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
let updates = 0;
app.addSystem(defineSystem([], () => { updates++; }, { name: 'LiveUpdate' }));
pipeline.setRenderingEnabled(false);
await app.tick(1 / 60);
expect(updates).toBe(1);
expect(beginFrames).toBe(0);
expect(calls).not.toContain('submitAll');
pipeline.setRenderingEnabled(true);
await app.tick(1 / 60);
expect(updates).toBe(2);
expect(beginFrames).toBe(1);
expect(calls).toContain('submitAll');
});
it('a camera moved in Update is looked through at THIS frame’s position', async () => {
const { app, module } = bootMockApp();
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
const cam = app.world.spawn('camera') as Entity;
app.world.insert(cam, Transform, { position: { x: 0, y: 0, z: 0 } });
app.world.insert(cam, Camera, {
isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 300,
});
// The mock registry answers scene queries the C++ registry owns.
registry.getCameraEntities = () => [cam];
registry.getCanvasEntities = () => [];
app.setPipeline(new RenderPipeline());
setRendererBackend(fakeBackend(registry, [cam]));
app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
// The user's cameraMoveSystem, in the shape the report came in.
const SPEED = 300;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Query(Mut(Transform), Camera)],
(query) => { query.forEach((_e, t) => { t.position.x += SPEED * (1 / 60); }); },
{ name: 'cameraMove' },
));
await app.tick(1 / 60);
// The order itself: the pass that writes worldPosition leads the read.
expect(calls.indexOf('updateTransforms')).toBeGreaterThanOrEqual(0);
expect(calls.indexOf('updateTransforms')).toBeLessThan(calls.indexOf('begin'));
// And it is opened exactly once — a second beginFrame ages the target pool twice.
expect(beginFrames).toBe(1);
// What it buys: the camera's own position maps to the centre of the view.
// A frame-late camera would put x = 0 there instead.
const moved = SPEED / 60;
expect(app.world.get(cam, Transform).position.x).toBeCloseTo(moved);
expect(lastViewProjection).not.toBeNull();
expect(ndcX(lastViewProjection!, moved, 0)).toBeCloseTo(0, 5);
expect(Math.abs(ndcX(lastViewProjection!, 0, 0))).toBeGreaterThan(1e-3); // not still at the origin
});
});