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, expect, it } from 'vitest';
import { judgeFrames, parseQualityConfig, QualityController } from '../src/render/quality';
describe('quality selection', () => {
it('keeps unconfigured projects at their authored resolution', () => {
const q = new QualityController({});
for (let i = 0; i < 100; i++) q.sample({ frameMs: 40 });
expect(q.enabled).toBe(false);
expect(q.renderScale).toBe(1);
});
it('requires all rule conditions and takes the first matching device rule', () => {
const config = { mode: 'auto' as const, deviceRules: [
{ level: 'high' as const, gpuIncludes: 'RTX', maxMemoryGB: 16 },
{ level: 'low' as const, modelIncludes: 'phone', maxCores: 4 },
] };
expect(new QualityController(config, { gpu: 'rtx 4060', memoryGB: 8 })
.report().level).toBe('high');
expect(new QualityController(config, { gpu: 'RTX 4060' }).report().level).toBe('medium');
expect(new QualityController(config, { model: 'Phone 1', cores: 4 })
.report().level).toBe('low');
});
it('keeps profile overrides when switching tiers at runtime', () => {
const q = new QualityController({ mode: 'low', profiles: {
high: { renderScale: 0.9 }, low: { renderScale: 0.6, minRenderScale: 0.4 },
} });
q.setMode('high');
expect(q.renderScale).toBe(0.9);
q.setMode('off');
expect(q.renderScale).toBe(1);
q.setMode('low');
expect(q.renderScale).toBe(0.6);
});
it('normalizes malformed manifests and bounds allocation sizes', () => {
const config = parseQualityConfig({ mode: 'invalid', targetFps: NaN, profiles: {
low: { renderScale: 0, minRenderScale: 2, shadowAtlasSize: 1024,
shadowCellSize: 1024, particleLimit: Infinity, shadowCascades: 500, shadowDistance: -100 },
}, deviceRules: [null, { level: 'high' }, { level: 'low', maxCores: NaN }] });
const q = new QualityController({ ...config, mode: 'low' });
expect(config.mode).toBe('off');
expect(config.targetFps).toBe(60);
expect(config.deviceRules).toEqual([]);
expect(q.profile.renderScale).toBe(0.25);
expect(q.profile.minRenderScale).toBe(0.25);
expect(q.profile.shadowCellSize).toBe(512);
expect(q.profile.shadowCascades).toBe(4);
expect(q.profile.shadowDistance).toBe(0);
expect(q.profile.particleLimit).toBe(1000);
});
});
describe('dynamic resolution', () => {
const make = () => new QualityController({ mode: 'high', dynamicResolution: true });
const sample = (q: QualityController, frames: number, frameMs: number, gpuMs = -1, busyMs = -1) => {
for (let i = 0; i < frames; i++) q.sample({ frameMs, gpuMs, busyMs });
};
it('ignores a transient spike, then reduces resolution under sustained pressure', () => {
const q = make();
q.sample({ frameMs: 40, gpuMs: 40 });
expect(q.renderScale).toBe(1);
sample(q, 20, 40, 40);
expect(q.renderScale).toBeLessThan(1);
expect(q.report().reason).toBe('gpu-pressure');
});
it('does not lower resolution for CPU pressure when the GPU has headroom', () => {
const q = make();
sample(q, 200, 40, 5);
expect(q.renderScale).toBe(1);
expect(q.report().reason).toBe('manual');
});
it('bounds the floor and slowly recovers without oscillating near the budget', () => {
const q = make();
sample(q, 200, 40, 40);
expect(q.renderScale).toBe(0.75);
expect(q.report().reason).toBe('resolution-floor');
sample(q, 100, 16.67, 16.67);
expect(q.renderScale).toBe(0.75);
sample(q, 200, 10, 10);
expect(q.renderScale).toBe(0.75);
sample(q, 400, 10, 10);
expect(q.renderScale).toBeGreaterThan(0.75);
expect(q.renderScale).toBeLessThanOrEqual(1);
});
// A phone whose GPU timer reads half a millisecond while the frame takes 27: the frame's own run fits the budget,
// so the wait is the GPU's, whatever its timer says (#120).
it('lowers resolution when the frame is late and its own run was not, however little the GPU timer reads', () => {
const q = make();
sample(q, 30, 27, 0.5, 15);
expect(q.renderScale).toBeLessThan(1);
expect(q.report().reason).toBe('frame-pressure');
sample(q, 300, 27, 0.5, 15);
expect(q.renderScale).toBe(0.75);
expect(q.report()).toMatchObject({ reason: 'resolution-floor', gpuMs: 0.5, busyMs: 15 });
expect(q.report().frameMs).toBeCloseTo(27);
});
it('leaves resolution alone when the frame is late because its own run is long', () => {
const withTimer = make();
sample(withTimer, 200, 40, 0.5, 38);
expect(withTimer.renderScale).toBe(1);
// No GPU timer at all: the run still says whose frame it is.
const without = make();
sample(without, 200, 40, -1, 38);
expect(without.renderScale).toBe(1);
// And with neither, a late frame is all there is to go on.
const blind = make();
sample(blind, 200, 40);
expect(blind.renderScale).toBe(0.75);
});
it('stops stepping back up when every step up has to be taken back', () => {
// The same phone: on budget at 0.8 and under, late above it, and a GPU timer that always claims headroom.
const q = make();
let changes = 0;
const run = (ms: number) => {
for (let t = 0; t < ms;) {
const frameMs = q.renderScale > 0.8 ? 27 : 16.7;
const before = q.renderScale;
q.sample({ frameMs, gpuMs: 0.5, busyMs: 10 });
if (q.renderScale !== before) changes++;
t += frameMs;
}
};
run(10_000);
expect(q.renderScale).toBeLessThanOrEqual(0.85);
changes = 0;
run(120_000);
// A fixed two-second wait would trade the two scales about fifty times in two minutes.
expect(changes).toBeLessThanOrEqual(14);
expect(q.renderScale).toBeGreaterThanOrEqual(0.8);
});
it('takes a step up again once the scene is lighter', () => {
const q = make();
sample(q, 300, 27, 0.5, 15);
expect(q.renderScale).toBe(0.75);
sample(q, 1500, 16.7, 0.5, 8);
expect(q.renderScale).toBe(1);
expect(q.report().reason).toBe('manual');
});
it('says which post-process effects each level leaves out, and takes an override', () => {
const levels = (config: object, level: 'low' | 'medium' | 'high') => {
const q = new QualityController({ mode: level, ...config });
return q.profile.skipEffects;
};
// The expensive effects are left to the devices that can afford them.
expect(levels({}, 'low')).toContain('ssr');
expect(levels({}, 'medium')).toContain('ssr');
expect(levels({}, 'high')).toEqual([]);
// A project's own list replaces the level's, and what is not a name is dropped.
expect(levels({ profiles: { low: { skipEffects: ['Bloom', 7, ' ', null, 'ssr'] } } }, 'low'))
.toEqual(['Bloom', 'ssr']);
});
it('does not react to background gaps, invalid clocks or a static tier', () => {
const q = make();
for (const ms of [NaN, Infinity, 0, -5, 30000]) q.sample({ frameMs: ms });
expect(q.renderScale).toBe(1);
expect(q.report().frameMs).toBe(0);
const staticQ = new QualityController({ mode: 'low' });
sample(staticQ, 100, 40);
expect(staticQ.renderScale).toBe(0.75);
});
});
describe('judgeFrames', () => {
const budget = 1000 / 60;
const judge = (frameMs: number, gpuMs = -1, busyMs = -1) => judgeFrames({ frameMs, gpuMs, busyMs }, budget);
it('takes a GPU reading over the budget at its word', () => {
expect(judge(40, 40)).toBe('gpu-pressure');
expect(judge(40, 40, 38)).toBe('gpu-pressure');
expect(judge(16.7, 20, 5)).toBe('gpu-pressure');
});
it('asks the frame before believing a small one', () => {
expect(judge(27, 0.5, 15)).toBe('frame-pressure');
expect(judge(27, 0.5, 26)).toBe('headroom'); // the CPU's frame, and the GPU is idle: resolution is free
expect(judge(27, 15, 26)).toBe('steady');
expect(judge(16.7, 0.5, 8)).toBe('headroom');
expect(judge(16.7, 15, 8)).toBe('steady');
});
it('falls back to what it is given', () => {
expect(judge(40, 5)).toBe('headroom'); // no run time: the GPU reading stands, as it always did
expect(judge(40)).toBe('frame-pressure');
expect(judge(40, -1, 38)).toBe('steady');
expect(judge(10)).toBe('headroom');
expect(judge(16.7)).toBe('steady');
});
});
describe('what a quality level lets the chain run', () => {
it('honours a list of every effect there is, however many that has become', () => {
const all = Array.from({ length: 64 }, (_, i) => `effect${i}`);
const q = new QualityController({ mode: 'low', profiles: { low: { skipEffects: all } } });
expect(q.profile.skipEffects).toHaveLength(64);
});
const level = (skipEffects: string[], extra: object = {}) => new QualityController({
mode: 'low', profiles: { low: { skipEffects, ...extra } },
}).profile;
it('removes every pass of a multi-pass effect, however its passes are named', async () => {
const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
const profile = level(['autoExposure', 'ssao']);
for (const pass of ['ae_measure', 'ae_adapt', 'ae_apply', 'ssao_ao', 'ssao_blur_x', 'ssao_composite']) {
expect(qualityPassAllowed(profile, pass), pass).toBe(false);
}
expect(qualityPassAllowed(profile, 'bloom'), 'bloom').toBe(true);
expect(qualityPassAllowed(profile, 'ssr'), 'ssr').toBe(true);
});
it('leaves the dynamic GI out of the low level and in the other two', async () => {
const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
const { effectPassNames } = await import('../src/postprocess/effects');
const passes = effectPassNames('dynamicGI');
expect(passes.length).toBeGreaterThan(0);
for (const mode of ['low', 'medium', 'high'] as const) {
const profile = new QualityController({ mode }).profile;
for (const pass of passes) expect(qualityPassAllowed(profile, pass), `${mode} ${pass}`).toBe(mode !== 'low');
}
});
it('runs the dynamic GI its cheaper way at the medium level and the full way at the high one', () => {
expect(new QualityController({ mode: 'medium' }).profile.dynamicGIReduced).toBe(true);
expect(new QualityController({ mode: 'high' }).profile.dynamicGIReduced).toBe(false);
expect(new QualityController({ mode: 'high', profiles: { high: { dynamicGIReduced: true } } }).profile.dynamicGIReduced).toBe(true);
});
it('keeps the old prefix reading for a name no effect answers to, and the ssao and post-process switches', async () => {
const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
expect(qualityPassAllowed(level(['custom']), 'custom_pass')).toBe(false);
expect(qualityPassAllowed(level([], { ssao: false }), 'ssao_blur_y')).toBe(false);
expect(qualityPassAllowed(level([], { postProcess: false }), 'bloom')).toBe(false);
expect(qualityPassAllowed(null, 'anything')).toBe(true);
});
it('names the effects a level leaves out by type, ignoring case', async () => {
const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
// Depth of field is three passes now, and a level that leaves it out leaves out all of them.
for (const pass of ['dof_focus', 'dof_coc', 'dof_gather']) {
expect(qualityPassAllowed(level(['DepthOfField']), pass), pass).toBe(false);
}
});
});
describe('temporal anti-aliasing as the smoothing of a level', () => {
const temporal = (level: 'low' | 'medium' | 'high') => new QualityController({
mode: level, profiles: { [level]: { antialiasing: 'temporal' } },
}).profile;
it('is the smoothing of medium and a choice elsewhere, and parses only the two names', () => {
expect(new QualityController({ mode: 'medium' }).profile.antialiasing).toBe('temporal');
for (const level of ['low', 'high'] as const) {
expect(new QualityController({ mode: level }).profile.antialiasing, level).toBe('msaa');
}
const odd = new QualityController({ mode: 'high', profiles: { high: { antialiasing: 'fxaa' as never } } }).profile;
expect(odd.antialiasing).toBe('msaa');
expect(temporal('medium').antialiasing).toBe('temporal');
});
it('runs the taa pass even where the level skips it, and leaves fxaa out', async () => {
const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
// Low skips `taa` for the cost of everything that needs it: a project that asks for temporal smoothing there has said it wants it.
expect(qualityPassAllowed(new QualityController({ mode: 'low' }).profile, 'taa')).toBe(false);
expect(qualityPassAllowed(temporal('low'), 'taa')).toBe(true);
expect(qualityPassAllowed(temporal('medium'), 'fxaa')).toBe(false);
expect(qualityPassAllowed(new QualityController({ mode: 'medium', profiles: { medium: { antialiasing: 'msaa' } } }).profile, 'fxaa')).toBe(true);
// Nothing else changes.
expect(qualityPassAllowed(temporal('medium'), 'bloom_extract')).toBe(true);
});
});
describe('how far plants keep their detail', () => {
it('is a share of a plant\'s distances that falls with the level, and a project may set it', () => {
const share = (mode: 'low' | 'medium' | 'high', detailScale?: unknown) =>
new QualityController(parseQualityConfig({ mode, profiles: detailScale === undefined ? undefined : { [mode]: { detailScale } } })).profile.detailScale;
expect([share('low'), share('medium'), share('high')]).toEqual([0.5, 0.8, 1]);
expect(share('low', 0.3)).toBe(0.3);
expect(share('low', 0)).toBe(0.25);
expect(share('low', 7)).toBe(1);
});
});