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 type { PowerPolicy } from './power';
/** A bound on a hand-edited file, well past the effects that exist: one lower quietly left the effects past it running. */
const MAX_SKIPPED_EFFECTS = 1024;
export type QualityLevel = 'low' | 'medium' | 'high';
export type QualityMode = 'off' | 'auto' | QualityLevel;
export interface DeviceQualityInfo {
model?: string;
gpu?: string;
memoryGB?: number;
cores?: number;
}
/** The size of the set a body of water's waves are taken from (water/waves.ts: WAVE_SET_SIZE). */
export const MOST_WATER_WAVES = 8;
export interface QualityProfile {
renderScale: number;
minRenderScale: number;
msaaSamples: 1 | 2 | 4 | 8;
/**
* How the edges of the picture are smoothed. `msaa` is the multisampling above (plus an FXAA pass where the scene has one). `temporal` draws
* at one sample and lets the `taa` pass do it from the frames before: it costs a tenth of a millisecond at 1080p where four samples cost three
* and two cost over one, and in return the picture is somewhat softer, a cut-out leaf has no coverage dither and a surface that moves by itself
* without a motion vector (water) smears a little while the camera moves. The level takes the `taa` pass whether or not the scene's volume
* lists it, and leaves `fxaa` out; it needs a post-process volume on the camera.
*/
antialiasing: 'msaa' | 'temporal';
shadowAtlasSize: number;
shadowCellSize: number;
/**
* The cascades a perspective sun's shadow is split into, and how far (in world units, 0 for as far as the scene reaches) they reach. Both act only on
* a sun whose `shadowExtent` is 0: one with an extent draws a single map of that size and uses neither. Each cascade draws the casters again.
*/
shadowCascades: number;
shadowDistance: number;
/**
* How much of its distances a level lets a plant keep, 0.25 to 1: a kind that changes to its cheaper mesh at 60 m and is not drawn past
* 150 m does so at 30 m and 75 m with 0.5. The far version (a tree's cards) is the same cost at any distance, so it takes over sooner.
*/
detailScale: number;
particleLimit: number;
planarReflectionScale: number;
planarReflectionMaxSize: number;
/** Zero means every frame; this never caps the main scene. */
planarReflectionUpdatesPerSecond: number;
/**
* Whether the opaque scene is drawn twice, depth alone first, so each pixel is shaded for the surface in front of it and not for every one drawn
* there on the way. It pays where surfaces overlap (a wood, a crowd of foliage) on a GPU that shades what it rasterises; on one that defers
* shading to the end of a tile it is geometry paid for twice, so the weakest level leaves it off.
*/
depthPrepass: boolean;
postProcess: boolean;
ssao: boolean;
/** How many of a body of water's waves are summed, longest first: in the geometry, the shading and what the surface answers for code. 1 to the size of the water's set. */
waterWaves: number;
/** The most cells along a side of the ripple grid a body of water keeps; the body's own `ripples` is held to it. 0 keeps none. */
waterRippleCells: number;
/** Whether the waves lift the water's geometry. Off is the lite water: a flat surface whose waves are in the shading only, and which code reads as flat. */
waterDisplacement: boolean;
/** Whether the surface seen from below mirrors the world under it (a screen-space march per pixel). */
waterMirror: boolean;
/** Whether the sun's web of light is drawn on what is under the water, and through the surface as shafts. */
waterCaustics: boolean;
/**
* Post-process effects this level leaves out, each named by its effect type (`ssr`, `taa`, `depthOfField`,
* `lightShafts`, `autoExposure` …), compared without regard to case. An effect is all of its passes: a
* multi-pass effect is skipped whole, however its passes are named. The expensive ones are the ones a weak
* device has no use for — they are measured per effect (`fx-cost` in the editor checks) — so what a level
* skips follows from what a frame on that device can afford.
*/
skipEffects: readonly string[];
/**
* The most texels a side the 2D rain's shelter mask has: the largest a `rain2d` effect is let draw its own `maskSize` at. The mask is painted every frame, so
* a weak device spends less on a smaller one and gets rain whose dry edges are softer.
*/
shelterMaskSize: number;
/**
* How many samples across a light source a soft 2D shadow is drawn with, 1 to 32: a light's `shadowSoftness` is a source with width, and its penumbra
* is that many silhouettes added up. Fewer is cheaper and shows the edge as bands; sixteen is where the bands stop reading as separate shadows.
*/
shadowSoftSamples: number;
lighting: 'full' | 'direct';
/**
* Whether the dynamic GI runs its cheaper way: one pixel in four asks the probes and the rest take the light of the four round them, a
* probe traces a quarter of its rays a frame instead of half, the cards are relit over eight frames instead of four, and there are two
* thirds of the rows of probes. On a Snapdragon 8 Elite at 2530 x 1200 the effect costs 4.5 ms this way and 7.3 the full way. What it
* gives up: light runs a pixel or two across an edge two surfaces share, and light that changes takes about twice as long to settle.
* It acts on a volume that lists `dynamicGI`, at a level that runs it, and never makes a volume's own settings dearer.
*/
dynamicGIReduced: boolean;
/**
* The most draws a frame at this level should ask of the GPU, every pass counted (shadows, prepass, reflections and post-processing with the
* scene). Nothing is held back to meet it: the profiler and the stats overlay show a frame over it, and the frame debugger says where the draws
* went. Draw calls cost the CPU and the driver more than the GPU, and on a phone or in a mini game they are what a 3D scene runs out of first.
*/
drawCallBudget: number;
/**
* Hold each texture only meshes draw at the size its views need (see `textureStreamingPlugin`): a texture far away takes a
* fraction of its memory, and grows back as the camera comes close. A web build ships a small copy beside each such texture, so its
* file is downloaded only once a view needs more than the copy holds.
*/
textureStreaming: boolean;
/** The megabytes the streamed textures may take together; past it they are held a level softer. 0 is no cap. */
textureStreamingBudget: number;
}
export interface DeviceQualityRule {
level: QualityLevel;
modelIncludes?: string;
gpuIncludes?: string;
maxMemoryGB?: number;
maxCores?: number;
}
/** @experimental */
export interface QualityConfig {
mode?: QualityMode;
targetFps?: number;
dynamicResolution?: boolean;
/**
* A frame never waits for a shader the browser is still compiling: what needs it is left out until it is ready, and several compile at once. Off
* (the default) the first draw to need a shader waits for it, which keeps every frame complete and can stop one for seconds on a first visit
* (a heavy lit shader on a driver that compiles slowly). Turn it on for a game that would rather open fast and fill in.
*/
asyncShaderCompile?: boolean;
/**
* With `asyncShaderCompile`: draw the first scene's frames out of sight, behind the loading screen, until its shaders have compiled, and show it
* complete instead of filling in (see `warmShaders`). The wait is bounded by `prewarmTimeoutMs`.
*/
prewarmShaders?: boolean;
/**
* Draw only the frames that can look different (see `RenderDemand`): a still screen costs the game's logic and nothing else. Off unless a game
* turns it on, because what the engine cannot see change (a script setting a colour, an animation) has to be said with `request` or `hold`.
*/
renderOnDemand?: boolean;
/** Frames still drawn after the last reason to draw. Default 30. */
renderOnDemandTail?: number;
/** The longest the loading screen waits for the shaders. Default 30000. */
prewarmTimeoutMs?: number;
profiles?: Partial<Record<QualityLevel, Partial<QualityProfile>>>;
deviceRules?: DeviceQualityRule[];
/**
* Draw less when the device is short of battery or running hot: a frame cap and a ceiling on the level while it is, both taken off when it recovers.
* Absent, the device is not watched and nothing changes. See {@link PowerPolicy}.
*/
power?: PowerPolicy;
}
const LEVELS: readonly QualityLevel[] = ['low', 'medium', 'high'];
const PROFILES: Record<QualityLevel, QualityProfile> = {
low: {
renderScale: 0.75, minRenderScale: 0.5, msaaSamples: 1, antialiasing: 'msaa',
shadowAtlasSize: 1024, shadowCellSize: 256, shadowCascades: 2,
planarReflectionScale: 0.25, planarReflectionMaxSize: 512, planarReflectionUpdatesPerSecond: 0, depthPrepass: false,
shadowDistance: 0, detailScale: 0.5, particleLimit: 1000, postProcess: true, ssao: false,
waterWaves: 3, waterRippleCells: 32, waterDisplacement: false, waterMirror: false, waterCaustics: false,
skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts', 'motionBlur', 'lensFlare', 'gtao', 'subsurface', 'voxelGI', 'dynamicGI'],
shelterMaskSize: 256, shadowSoftSamples: 8, lighting: 'direct', dynamicGIReduced: true, drawCallBudget: 150, textureStreaming: true, textureStreamingBudget: 128,
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',
shadowAtlasSize: 2048, shadowCellSize: 512, shadowCascades: 3,
planarReflectionScale: 0.5, planarReflectionMaxSize: 1024, planarReflectionUpdatesPerSecond: 0, depthPrepass: true,
shadowDistance: 0, detailScale: 0.8, particleLimit: 5000, postProcess: true, ssao: true,
waterWaves: 5, waterRippleCells: 64, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: ['ssr', 'depthOfField'],
shelterMaskSize: 512, shadowSoftSamples: 12, lighting: 'direct', dynamicGIReduced: true, drawCallBudget: 400, textureStreaming: true, textureStreamingBudget: 256,
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',
// A face is millimetres of relief: at 512 texels a cascade, a skin-hugging card (a brow, a hairline) falls inside one texel of the skin and the
// shadow speckles it with dirt. 1024 is the cell that clears it for a character at arm's length.
shadowAtlasSize: 4096, shadowCellSize: 1024, shadowCascades: 4,
planarReflectionScale: 1, planarReflectionMaxSize: 2048, planarReflectionUpdatesPerSecond: 0, depthPrepass: true,
shadowDistance: 0, detailScale: 1, particleLimit: 20000, postProcess: true, ssao: true,
waterWaves: 8, waterRippleCells: 128, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: [],
shelterMaskSize: 1024, shadowSoftSamples: 16, lighting: 'full', dynamicGIReduced: false, drawCallBudget: 1500, textureStreaming: false, textureStreamingBudget: 0,
},
};
function record(value: unknown): Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value)
? value as Record<string, unknown> : {};
}
function finite(value: unknown, fallback: number, min: number, max: number): number {
return typeof value === 'number' && Number.isFinite(value)
? Math.min(max, Math.max(min, value)) : fallback;
}
/**
* The level a project gets that names none. A phone or tablet takes medium: all of a level's picture at a fraction of the cost (a full-screen sea on a
* Snapdragon 8 Elite is 25.7 ms a frame as authored and 9.0 at medium, mostly by leaving four samples behind). Elsewhere nothing is managed. Naming a
* level, `off` among them, always wins.
*/
export function defaultQualityMode(handheld: boolean): QualityMode {
return handheld ? 'medium' : 'off';
}
/** @experimental */
export function parseQualityConfig(value: unknown): QualityConfig {
const raw = record(value);
const mode = raw.mode === 'auto' || LEVELS.includes(raw.mode as QualityLevel)
? raw.mode as QualityMode : 'off';
const config: QualityConfig = {
mode, targetFps: finite(raw.targetFps, 60, 15, 120),
dynamicResolution: raw.dynamicResolution === true,
asyncShaderCompile: raw.asyncShaderCompile === true,
prewarmShaders: raw.prewarmShaders === true,
renderOnDemand: raw.renderOnDemand === true,
renderOnDemandTail: finite(raw.renderOnDemandTail, 30, 1, 600),
prewarmTimeoutMs: finite(raw.prewarmTimeoutMs, 30000, 1000, 600000),
};
if (raw.power !== undefined && raw.power !== false) config.power = parsePowerPolicy(raw.power);
if (raw.profiles) {
config.profiles = {};
for (const level of LEVELS) {
if (!record(raw.profiles)[level]) continue;
config.profiles[level] = resolveProfile(level, record(raw.profiles)[level]);
}
}
if (Array.isArray(raw.deviceRules)) {
config.deviceRules = raw.deviceRules.slice(0, 64).flatMap(value => {
const r = record(value);
if (!LEVELS.includes(r.level as QualityLevel)) return [];
const rule: DeviceQualityRule = { level: r.level as QualityLevel };
for (const key of ['modelIncludes', 'gpuIncludes'] as const) {
if (typeof r[key] === 'string' && r[key].trim()) rule[key] = r[key].trim();
}
for (const key of ['maxMemoryGB', 'maxCores'] as const) {
if (typeof r[key] === 'number' && Number.isFinite(r[key]) && r[key] > 0) {
rule[key] = r[key];
}
}
return Object.keys(rule).length > 1 ? [rule] : [];
});
}
return config;
}
/** A power policy from a project's settings: what is not a usable number or name keeps its default, and `true` is every default. */
export function parsePowerPolicy(value: unknown): PowerPolicy {
const r = record(value);
const policy: PowerPolicy = {};
if (typeof r.lowBattery === 'number' && Number.isFinite(r.lowBattery)) policy.lowBattery = Math.min(Math.max(r.lowBattery, 0), 1);
if (r.thermal === 'serious' || r.thermal === 'critical' || r.thermal === 'never') policy.thermal = r.thermal;
if (typeof r.fps === 'number' && Number.isFinite(r.fps)) policy.fps = Math.min(Math.max(Math.round(r.fps), 10), 120);
if (r.ceiling === 'low' || r.ceiling === 'medium' || r.ceiling === 'high') policy.ceiling = r.ceiling;
if (r.severe === 'critical' || r.severe === 'never') policy.severe = r.severe;
return policy;
}
function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
const base = PROFILES[level];
const r = record(value);
const renderScale = finite(r.renderScale, base.renderScale, 0.25, 1);
const atlas = [512, 1024, 2048, 4096].includes(r.shadowAtlasSize as number)
? r.shadowAtlasSize as number : base.shadowAtlasSize;
const cell = [128, 256, 512, 1024].includes(r.shadowCellSize as number)
? r.shadowCellSize as number : base.shadowCellSize;
return {
renderScale,
minRenderScale: finite(r.minRenderScale, Math.min(base.minRenderScale, renderScale),
0.25, renderScale),
msaaSamples: [1, 2, 4, 8].includes(r.msaaSamples as number)
? r.msaaSamples as QualityProfile['msaaSamples'] : base.msaaSamples,
antialiasing: r.antialiasing === 'msaa' || r.antialiasing === 'temporal' ? r.antialiasing : base.antialiasing,
shadowAtlasSize: atlas,
shadowCellSize: Math.min(cell, atlas / 2),
shadowCascades: Math.round(finite(r.shadowCascades, base.shadowCascades, 1, 4)),
shadowDistance: finite(r.shadowDistance, base.shadowDistance, 0, 10000000),
detailScale: finite(r.detailScale, base.detailScale, 0.25, 1),
particleLimit: Math.round(finite(r.particleLimit, base.particleLimit, 0, 1000000)),
planarReflectionScale: finite(r.planarReflectionScale, base.planarReflectionScale, 0.125, 1),
planarReflectionMaxSize: Math.round(finite(r.planarReflectionMaxSize, base.planarReflectionMaxSize, 64, 4096)),
planarReflectionUpdatesPerSecond: finite(r.planarReflectionUpdatesPerSecond, base.planarReflectionUpdatesPerSecond, 0, 120),
depthPrepass: typeof r.depthPrepass === 'boolean' ? r.depthPrepass : base.depthPrepass,
postProcess: typeof r.postProcess === 'boolean' ? r.postProcess : base.postProcess,
ssao: typeof r.ssao === 'boolean' ? r.ssao : base.ssao,
dynamicGIReduced: typeof r.dynamicGIReduced === 'boolean' ? r.dynamicGIReduced : base.dynamicGIReduced,
waterWaves: Math.round(finite(r.waterWaves, base.waterWaves, 1, MOST_WATER_WAVES)),
waterRippleCells: Math.round(finite(r.waterRippleCells, base.waterRippleCells, 0, 256)),
waterDisplacement: typeof r.waterDisplacement === 'boolean' ? r.waterDisplacement : base.waterDisplacement,
waterMirror: typeof r.waterMirror === 'boolean' ? r.waterMirror : base.waterMirror,
waterCaustics: typeof r.waterCaustics === 'boolean' ? r.waterCaustics : base.waterCaustics,
skipEffects: Array.isArray(r.skipEffects)
? r.skipEffects.filter((e): e is string => typeof e === 'string' && e.trim() !== '')
.map((e) => e.trim()).slice(0, MAX_SKIPPED_EFFECTS)
: base.skipEffects,
shelterMaskSize: Math.round(finite(r.shelterMaskSize, base.shelterMaskSize, 64, 2048)),
shadowSoftSamples: Math.round(finite(r.shadowSoftSamples, base.shadowSoftSamples, 1, 32)),
lighting: r.lighting === 'full' || r.lighting === 'direct' ? r.lighting : base.lighting,
drawCallBudget: Math.round(finite(r.drawCallBudget, base.drawCallBudget, 1, 100000)),
textureStreaming: typeof r.textureStreaming === 'boolean' ? r.textureStreaming : base.textureStreaming,
textureStreamingBudget: Math.round(finite(r.textureStreamingBudget, base.textureStreamingBudget, 0, 65536)),
};
}
/** A level's profile as the engine will use it: the level's own defaults with a project's overrides on top. */
export function resolveQualityProfile(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile {
return resolveProfile(level, overrides);
}
/** What a level is before a project says anything about it. */
export function defaultQualityProfile(level: QualityLevel): QualityProfile {
return PROFILES[level];
}
function matches(rule: DeviceQualityRule, info: DeviceQualityInfo): boolean {
const includes = (text: string | undefined, part: string): boolean =>
text?.toLowerCase().includes(part.toLowerCase()) ?? false;
return (!rule.modelIncludes || includes(info.model, rule.modelIncludes))
&& (!rule.gpuIncludes || includes(info.gpu, rule.gpuIncludes))
&& (rule.maxMemoryGB === undefined
|| (info.memoryGB !== undefined && info.memoryGB <= rule.maxMemoryGB))
&& (rule.maxCores === undefined
|| (info.cores !== undefined && info.cores <= rule.maxCores));
}
export interface QualityReport {
mode: QualityMode;
level: QualityLevel;
renderScale: number;
targetFps: number;
/** Smoothed frame interval. */
frameMs: number;
/** Smoothed time the frame's own run took, and the GPU's time for it; -1 where the host does not say. */
busyMs: number;
gpuMs: number;
reason: string;
limitations: string[];
/** The level's draw call budget (see `QualityProfile.drawCallBudget`). */
drawCallBudget: number;
}
/**
* @experimental One frame's clock readings, as dynamic resolution takes them. `frameMs` is the interval since the last
* frame; `busyMs` how long the frame's own run took (`FrameTiming.busyMs`); `gpuMs` the GPU's time for the frame. The
* last two are optional, and a value that is not a positive number counts as not given.
*/
export interface QualitySample {
frameMs: number;
busyMs?: number;
gpuMs?: number;
}
/** @experimental What a stretch of frames says about the render resolution. */
export type FrameVerdict = 'gpu-pressure' | 'frame-pressure' | 'headroom' | 'steady';
const PRESSURE = 1.1;
const HEADROOM = 0.8;
/**
* @experimental Whether resolution should go down, may come back up, or stay, from smoothed readings (-1 = not known)
* and the frame budget. Pure.
*
* A GPU reading over the budget is pressure on its own word. A small one is not headroom on its own word: a timer
* can cover less than the frame (a tile renderer has not drawn when the pass is stamped), so what a low reading may
* do is decided with the frame itself. A frame that came late although its own run fitted the budget waited on the
* GPU or the display, and resolution is the lever for that; one whose run did not fit is the CPU's, and resolution
* would buy nothing.
*/
export function judgeFrames(avg: Readonly<Required<QualitySample>>, budgetMs: number): FrameVerdict {
const gpuKnown = avg.gpuMs > 0;
const busyKnown = avg.busyMs > 0;
if (gpuKnown && avg.gpuMs > budgetMs * PRESSURE) return 'gpu-pressure';
const gpuFree = gpuKnown && avg.gpuMs < budgetMs * HEADROOM;
if (avg.frameMs > budgetMs * PRESSURE) {
if (busyKnown ? avg.busyMs <= budgetMs : !gpuKnown) return 'frame-pressure';
return gpuFree ? 'headroom' : 'steady';
}
return (gpuKnown ? gpuFree : avg.frameMs < budgetMs * HEADROOM) ? 'headroom' : 'steady';
}
/** Pressure for this long lowers the scale a step; headroom for `RECOVER_MS` and up raises it one. */
const PRESSURE_MS = 500;
const RECOVER_MS = 2000;
const RECOVER_MAX_MS = 32000;
/** A step up that is taken back within this long was a mistake, not a change of scene. */
const BOUNCE_MS = 5000;
const known = (ms: number | undefined): ms is number => ms !== undefined && Number.isFinite(ms) && ms > 0;
/** @experimental Per-app policy; authored scene components remain unchanged. */
export class QualityController {
private config_: QualityConfig;
private level_: QualityLevel = 'high';
/** The level the mode asks for, before a ceiling lowers it. */
private modeLevel_: QualityLevel = 'high';
private ceiling_: QualityLevel | null = null;
private profile_: QualityProfile = PROFILES.high;
private scale_ = 1;
private average_: Required<QualitySample> = { frameMs: 0, busyMs: -1, gpuMs: -1 };
private pressureMs_ = 0;
private recoveryMs_ = 0;
/** Sampled time, the clock the two below are read on. */
private clockMs_ = 0;
private raisedAt_ = -1;
/** How long headroom must last before a step up; grows while steps up keep being taken back. */
private recoverAfterMs_ = RECOVER_MS;
private reason_ = 'disabled';
private modeReason_ = 'disabled';
private limitations_ = new Set<string>();
constructor(config: QualityConfig, private readonly device_: DeviceQualityInfo = {}) {
this.config_ = parseQualityConfig(config);
this.setMode(this.config_.mode ?? 'off');
}
get enabled(): boolean { return this.config_.mode !== 'off'; }
get profile(): Readonly<QualityProfile> { return this.profile_; }
get renderScale(): number { return this.enabled ? this.scale_ : 1; }
setMode(mode: QualityMode): void {
this.config_.mode = mode;
const rule = this.config_.deviceRules?.find(r => matches(r, this.device_));
const low = (this.device_.memoryGB !== undefined && this.device_.memoryGB <= 2)
|| (this.device_.cores !== undefined && this.device_.cores <= 2);
this.modeLevel_ = mode === 'off' ? 'high' : mode === 'auto'
? rule?.level ?? (low ? 'low' : 'medium') : mode;
this.level_ = this.ceilingOf_(this.modeLevel_);
this.profile_ = resolveProfile(this.level_, this.config_.profiles?.[this.level_]);
this.scale_ = mode === 'off' ? 1 : this.profile_.renderScale;
this.resetSampling_(true);
this.reason_ = mode === 'off' ? 'disabled' : mode !== 'auto' ? 'manual'
: rule ? 'device-rule' : low ? 'device-capacity' : 'device-unknown';
this.modeReason_ = this.reason_;
}
private ceilingOf_(level: QualityLevel): QualityLevel {
return this.ceiling_ !== null && LEVELS.indexOf(this.ceiling_) < LEVELS.indexOf(level) ? this.ceiling_ : level;
}
/**
* No level above `level` while it is set; null takes it off. Only lowers: a mode already at or under the ceiling is left as it is. Used by the power
* policy, which holds the level down while the device is short of battery or hot.
*/
setCeiling(level: QualityLevel | null): void {
if (this.ceiling_ === level) return;
this.ceiling_ = level;
const next = this.ceilingOf_(this.modeLevel_);
this.setLimitation('power-saver', next !== this.modeLevel_);
if (next === this.level_) return;
this.level_ = next;
this.profile_ = resolveProfile(next, this.config_.profiles?.[next]);
this.scale_ = this.enabled ? this.profile_.renderScale : 1;
this.resetSampling_(true);
this.reason_ = next !== this.modeLevel_ ? 'power-saver' : this.modeReason_;
}
setLimitation(reason: string, active: boolean): void {
if (active) this.limitations_.add(reason);
else this.limitations_.delete(reason);
}
/** Forget the running averages; `all` also forgets what was learned about stepping back up. */
private resetSampling_(all: boolean): void {
this.average_ = { frameMs: 0, busyMs: -1, gpuMs: -1 };
this.pressureMs_ = this.recoveryMs_ = 0;
if (all) { this.clockMs_ = 0; this.raisedAt_ = -1; this.recoverAfterMs_ = RECOVER_MS; }
}
/**
* Take one frame's readings. Sustained pressure lowers the render scale a step towards the level's floor;
* sustained headroom raises it back a step. See {@link judgeFrames} for what counts as which.
*/
sample(sample: Readonly<QualitySample>): void {
if (!this.enabled || !this.config_.dynamicResolution) return;
const { frameMs } = sample;
if (!Number.isFinite(frameMs) || frameMs <= 0 || frameMs > 250) {
this.resetSampling_(false);
return;
}
const first = this.average_.frameMs === 0;
const weight = 1 - Math.exp(-frameMs / 250);
const blend = (avg: number, ms: number | undefined): number =>
!known(ms) ? -1 : first || avg < 0 ? ms : avg + weight * (ms - avg);
this.average_ = {
frameMs: blend(this.average_.frameMs, frameMs),
busyMs: blend(this.average_.busyMs, sample.busyMs),
gpuMs: blend(this.average_.gpuMs, sample.gpuMs),
};
this.clockMs_ += frameMs;
const verdict = judgeFrames(this.average_, 1000 / (this.config_.targetFps ?? 60));
const pressed = verdict === 'gpu-pressure' || verdict === 'frame-pressure';
this.pressureMs_ = pressed ? this.pressureMs_ + frameMs : 0;
this.recoveryMs_ = verdict === 'headroom' ? this.recoveryMs_ + frameMs : 0;
if (this.pressureMs_ >= PRESSURE_MS) {
// A step up that had to be taken straight back: whatever called that headroom cannot be trusted on this
// device, so the next one waits twice as long instead of flickering between two scales.
if (this.raisedAt_ >= 0 && this.clockMs_ - this.raisedAt_ <= BOUNCE_MS) {
this.recoverAfterMs_ = Math.min(RECOVER_MAX_MS, this.recoverAfterMs_ * 2);
}
this.raisedAt_ = -1;
this.scale_ = Math.max(this.profile_.minRenderScale,
Math.round((this.scale_ - 0.05) * 100) / 100);
this.reason_ = this.scale_ === this.profile_.minRenderScale ? 'resolution-floor' : verdict;
this.pressureMs_ = this.recoveryMs_ = 0;
} else if (this.recoveryMs_ >= this.recoverAfterMs_) {
// The last step up held, so the wait eases back towards its start.
if (this.raisedAt_ >= 0) this.recoverAfterMs_ = Math.max(RECOVER_MS, this.recoverAfterMs_ / 2);
this.raisedAt_ = this.scale_ < this.profile_.renderScale ? this.clockMs_ : -1;
this.scale_ = Math.min(this.profile_.renderScale,
Math.round((this.scale_ + 0.05) * 100) / 100);
this.reason_ = this.scale_ === this.profile_.renderScale ? this.modeReason_ : 'recovery';
this.pressureMs_ = this.recoveryMs_ = 0;
}
}
report(): QualityReport {
return {
mode: this.config_.mode ?? 'off', level: this.level_,
renderScale: this.renderScale, targetFps: this.config_.targetFps ?? 60,
frameMs: this.average_.frameMs, busyMs: this.average_.busyMs, gpuMs: this.average_.gpuMs,
reason: this.reason_, limitations: [...this.limitations_],
drawCallBudget: this.profile_.drawCallBudget,
};
}
}