Skip to content

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.

28.7 KB
Raw Blame
// 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,
        };
    }
}