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 { Entity } from '../types';
import type { ShaderHandle } from '../render/material';
import type { EngineApi } from '../ecs/bridge/engineApi';
import { defineResource } from '../ecs/resource';
import { handleWasmError } from '../wasm/wasmError';
import { WasmBridge } from '../wasm/WasmBridge';
import { PostProcessStack, PostProcessState } from './PostProcessStack';
import type { QualityProfile } from '../render/quality';
import { qualityPassAllowed } from './qualityFilter';
import { effectPassNames } from './effects';
/**
* The post-process entry points as a core that HAS them answers them. Named, not
* re-declared: the signatures come from the generated engine surface, so this
* cannot drift from the C++ (PostProcessBindings.hpp) that produced it.
*/
type PostProcessCore = Required<Pick<NonNullable<EngineApi>,
'postprocess_init' | 'postprocess_shutdown' | 'postprocess_resize'
| 'postprocess_isInitialized' | 'postprocess_begin' | 'postprocess_end'
| 'postprocess_clearPasses' | 'postprocess_addPass' | 'postprocess_setPassScale'
| 'postprocess_setPassContinuesEffect'
| 'postprocess_setPassTexture'
| 'postprocess_setUniformFloat' | 'postprocess_setUniformVec4'
| 'postprocess_setBypass' | 'postprocess_setOutputTransform' | 'postprocess_setMsaaSamples'
| 'postprocess_setPresentRequired'
| 'postprocess_setOutputViewport'
| 'postprocess_beginScreenCapture' | 'postprocess_endScreenCapture'
| 'postprocess_executeScreenPasses' | 'postprocess_addScreenPass'
| 'postprocess_clearScreenPasses' | 'postprocess_setScreenUniformFloat'
| 'postprocess_setScreenUniformVec4'>>
// A core without a compute stage (or built before there was one) does not answer this one.
& Pick<NonNullable<EngineApi>, 'postprocess_addComputePass' | 'postprocess_supportsCompute' | 'postprocess_addNativePass' | 'postprocess_setDisplayLut'>;
/** Guarded view of the core: after a wasm abort a call throws instead of reaching
* a dead module; a native host's bindings never abort. */
class PostProcessBridge extends WasmBridge<NonNullable<EngineApi>> {
protected readonly label = 'postprocess';
}
const bridge = new PostProcessBridge();
let module: PostProcessCore | null = null;
/** Four floats the committed format decision is read back through. */
let hdrPtr = 0;
/**
* The format one frame committed its intermediates to. @experimental
*
* `fellBack` is `requested !== effective`, stated so a reader does not have to
* compare two strings to learn whether anything gave way — and `linear` is what
* separates a granted ask from no ask at all, which the pair alone cannot say.
*/
export interface HdrFormat {
requested: string;
effective: string;
/** Why they differ; `none` when they do not. */
reason: string;
/** Whether the project asked for a linear pipeline this frame. */
linear: boolean;
fellBack: boolean;
}
/**
* @internal Wired by the engine plugins — not part of the public API.
* Takes whichever core is present (see ecs/engineApi.ts). A core built without
* ES_ENABLE_POSTPROCESS answers none of these entry points; the plugin checks that
* before calling, which is what makes the narrowing here sound.
*/
/** Whether the last App shut the pipeline down under a renderer that may have outlived it. */
let restartOwed = false;
export function initPostProcessAPI(engine: NonNullable<EngineApi>): void {
bridge.connect(engine);
module = bridge.module as PostProcessCore;
const heap = engine as unknown as { _malloc?(n: number): number };
if (!hdrPtr && typeof heap._malloc === 'function') hdrPtr = heap._malloc(4 * 4);
// The renderer outlives an App on a warm restart, and the last App shut this down. A linear frame is encoded here,
// so waiting for a camera with effects to bring it back left every scene without one showing raw linear values.
// Only then: on a first boot the renderer starts its own, and starting one before it exists would make a second.
const core = module as PostProcessCore;
if (restartOwed && hasPostProcessCore(core) && !core.postprocess_isInitialized()) core.postprocess_init(1, 1);
restartOwed = false;
}
/** A core built without ES_ENABLE_POSTPROCESS (the lite mini-game engine) has none of these entry points: no chain, nothing to ask. */
function hasPostProcessCore(core: PostProcessCore): boolean {
return typeof core.postprocess_isInitialized === 'function';
}
/** @internal Wired by the engine plugins — not part of the public API. */
export function shutdownPostProcessAPI(): void {
// Per-App state dies with its App; here we only tear down the shared module.
if (module) {
try {
if (hasPostProcessCore(module) && module.postprocess_isInitialized()) {
module.postprocess_shutdown();
restartOwed = true;
}
} catch (e) {
handleWasmError(e, 'PostProcess.shutdown');
}
}
if (hdrPtr && module) {
(module as unknown as { _free?(p: number): void })._free?.(hdrPtr);
hdrPtr = 0;
}
bridge.disconnect();
module = null;
}
/**
* Whether the device the chain runs on has a compute stage (WebGPU). False before the chain is up, and on WebGL2.
* An effect that has a compute version and a fragment one asks which to build.
*/
export function deviceHasCompute(): boolean {
try {
return getModule().postprocess_supportsCompute?.() === true;
} catch {
return false;
}
}
function getModule(): PostProcessCore {
if (!module) {
throw new Error('PostProcess API not initialized. Call initPostProcessAPI() first.');
}
return module;
}
/**
* Push a stack's enabled passes to the engine. `force` re-pushes a stack that has
* not been edited — needed because the engine's pass list is torn down after every
* camera (see {@link PostProcessAPI._resetAfterCamera}), so "not dirty" says the
* stack is unchanged, NOT that the engine still holds it.
*/
export function syncStackToWasm(stack: PostProcessStack, force = false,
allow: (name: string) => boolean = () => true): void {
if (!force && !stack.isDirty) return;
const m = getModule();
try {
m.postprocess_clearPasses();
} catch (e) {
handleWasmError(e, 'PostProcess._applyForCamera:clearPasses');
return;
}
for (const pass of stack.passes) {
if (!pass.enabled || !allow(pass.name)) continue;
try {
if (pass.native) {
if (!m.postprocess_addNativePass) continue;
m.postprocess_addNativePass(pass.name, pass.native);
} else if (pass.compute) {
// No compute on this core (WebGL2): the pass is left out and the picture goes through as it was.
if (!m.postprocess_addComputePass) continue;
m.postprocess_addComputePass(pass.name, pass.compute.source, pass.compute.params.join(','),
pass.compute.workgroupSize[0], pass.compute.workgroupSize[1]);
} else {
m.postprocess_addPass(pass.name, pass.shader);
}
// Only when it is not 1: every pass that predates fractional sizing
// means full size, and saying so is the same answer.
if (pass.scale !== 1) m.postprocess_setPassScale(pass.name, pass.scale);
if (pass.continuesEffect) m.postprocess_setPassContinuesEffect(pass.name);
} catch (e) {
handleWasmError(e, `PostProcess._applyForCamera:addPass("${pass.name}")`);
continue;
}
for (const [name, value] of pass.floatUniforms) {
try {
m.postprocess_setUniformFloat(pass.name, name, value);
} catch (e) {
handleWasmError(e, `PostProcess._applyForCamera:setUniform("${pass.name}", "${name}")`);
}
}
for (const [name, value] of pass.vec4Uniforms) {
try {
m.postprocess_setUniformVec4(pass.name, name, value.x, value.y, value.z, value.w);
} catch (e) {
handleWasmError(e, `PostProcess._applyForCamera:setUniformVec4("${pass.name}", "${name}")`);
}
}
for (const [name, handle] of pass.textureUniforms) {
try {
m.postprocess_setPassTexture(pass.name, name, handle);
} catch (e) {
handleWasmError(e, `PostProcess._applyForCamera:setPassTexture("${pass.name}", "${name}")`);
}
}
}
// The display look rides the stack as the passes do, and goes with them (clearPasses above): said again for every camera that has one.
if (stack.displayLut.amount > 0) {
try {
m.postprocess_setDisplayLut?.(stack.displayLut.texture, stack.displayLut.amount);
} catch (e) {
handleWasmError(e, 'PostProcess._applyForCamera:setDisplayLut');
}
}
stack.clearDirty();
}
/**
* Per-App post-process API. Owns this App's `state` (stacks, camera bindings,
* screen stack) and drives the shared C++ post-process pipeline via the module.
* The wasm-call methods are shared on the prototype; only `state` is per-App.
*
* B2b-3a: a single default instance is exported to keep call sites unchanged;
* B2b-3b flips this to a per-App `defineResource` injected into the pipeline.
*/
/**
* The curve a frame applies on its way to the display — the pipeline's, not an
* effect a stack happens to hold, so it runs once and last. `none` leaves values
* alone, which is the exact round trip flat content wants; `aces` maps radiance
* above 1 down a filmic shoulder, which is what a lit 3D scene needs; `neutral`
* (Khronos PBR Neutral) rolls highlights off while keeping hue and saturation, so a
* sunlit red stays red where `aces` walks it toward cream.
*
* @experimental
*/
export type OutputTransform = 'none' | 'aces' | 'neutral';
/**
* The curve's number at the wasm boundary. Here and not at each call: the
* translation was written twice, and a third curve would have reached one of
* them and been silently read as `none` by the other.
*/
export function outputTransformCode(transform: OutputTransform | undefined): number {
return transform === 'aces' ? 1 : transform === 'neutral' ? 2 : 0;
}
export class PostProcessAPI {
readonly state = new PostProcessState();
/** Volume-system bookkeeping (per-App): camera → the stack it created, and shared effect shaders. */
readonly volumeStacks = new Map<Entity, PostProcessStack>();
readonly volumeShaders = new Map<string, ShaderHandle>();
/**
* Which stack the engine's pass list currently holds, or null when it holds
* none. Distinct from the stack's own dirty flag, which only tracks edits:
* every camera ends by clearing the engine's passes, so a stack that was
* pushed last frame and never edited must still be pushed again this frame.
*/
private engineStack_: PostProcessStack | null = null;
private qualityFilter_: Readonly<QualityProfile> | null = null;
setQualityFilter(profile: Readonly<QualityProfile> | null): void {
if (this.qualityFilter_ === profile) return;
this.qualityFilter_ = profile;
this.engineStack_ = null;
}
/** How the quality level in force smooths edges: the volume system adds the temporal pass where it says `temporal`. */
get antialiasing(): 'msaa' | 'temporal' {
return this.qualityFilter_?.antialiasing ?? 'msaa';
}
/** Whether the quality level in force has the dynamic GI run its cheaper way: the volume system sets the effect's switches from it. */
get dynamicGIReduced(): boolean {
return this.qualityFilter_?.dynamicGIReduced ?? false;
}
/**
* Whether the quality level in force runs an effect, by its type. For a system that prepares something for an effect off the GPU (the dynamic GI
* builds a distance field, a second of a phone's CPU): it asks before it does.
*/
effectAllowed(type: string): boolean {
const passes = effectPassNames(type);
return (passes.length > 0 ? passes : [type]).every((name) => qualityPassAllowed(this.qualityFilter_, name));
}
private allowQualityPass_ = (name: string): boolean => {
return qualityPassAllowed(this.qualityFilter_, name);
};
// -- per-App state (stacks / bindings / screen stack) --------------------
get screenStack(): PostProcessStack | null {
return this.state.screenStack;
}
setScreenStack(stack: PostProcessStack | null): void {
this.state.screenStack = stack;
}
createStack(): PostProcessStack {
return this.state.createStack();
}
bind(camera: Entity, stack: PostProcessStack): void {
if (stack.isDestroyed) {
throw new Error('Cannot bind a destroyed PostProcessStack');
}
this.state.cameraBindings.set(camera, stack);
}
unbind(camera: Entity): void {
this.state.cameraBindings.delete(camera);
}
getStack(camera: Entity): PostProcessStack | null {
return this.state.cameraBindings.get(camera) ?? null;
}
// -- shared C++ pipeline commands ----------------------------------------
init(width: number, height: number): boolean {
try {
return getModule().postprocess_init(width, height);
} catch (e) {
handleWasmError(e, `PostProcess.init(${width}x${height})`);
return false;
}
}
shutdown(): void {
try {
getModule().postprocess_shutdown();
} catch (e) {
handleWasmError(e, 'PostProcess.shutdown');
}
}
resize(width: number, height: number): void {
try {
getModule().postprocess_resize(width, height);
} catch (e) {
handleWasmError(e, `PostProcess.resize(${width}x${height})`);
}
}
isInitialized(): boolean {
if (!module || !hasPostProcessCore(module)) return false;
try {
return module.postprocess_isInitialized();
} catch (e) {
handleWasmError(e, 'PostProcess.isInitialized');
return false;
}
}
setBypass(bypass: boolean): void {
try {
getModule().postprocess_setBypass(bypass);
} catch (e) {
handleWasmError(e, 'PostProcess.setBypass');
}
}
/**
* The curve the frame applies on its way to the display.
*
* Applied to whatever the chain produced, so it also engages the capture: a
* project that asks for a curve gets one with an empty stack. See
* {@link OutputTransform} for which to want.
*/
setOutputTransform(transform: OutputTransform): void {
try {
getModule().postprocess_setOutputTransform(outputTransformCode(transform));
} catch (e) {
handleWasmError(e, 'PostProcess.setOutputTransform');
}
}
/**
* Multisampling the scene target should rasterise with; 1 turns it off. The
* device clamps it, so this is the project's ASK, not what it gets — a
* backend with no MSAA answers 1 whatever is set here.
*/
setMsaaSamples(samples: number): void {
try {
getModule().postprocess_setMsaaSamples(samples >>> 0);
} catch (e) {
handleWasmError(e, 'PostProcess.setMsaaSamples');
}
}
/**
* What the scene target is ACTUALLY multisampled at, and the most this
* device can do. @experimental
*
* Two numbers because a request and a capability are different facts: asking
* for 8 where the backend allows 1 is not a typo, and only saying both tells
* those apart. `0` means nothing here can answer.
*/
msaaCapability(): { effective: number; max: number } {
try {
// Off the module rather than through PostProcessCore, a Required<> of
// what a chain cannot run WITHOUT: these two only report on it, and a
// host binding neither still has a working chain.
const m = getModule() as unknown as {
postprocess_effectiveMsaaSamples?(): number;
postprocess_maxMsaaSamples?(): number;
};
return {
effective: m.postprocess_effectiveMsaaSamples?.() ?? 0,
max: m.postprocess_maxMsaaSamples?.() ?? 0,
};
} catch (e) {
handleWasmError(e, 'PostProcess.msaaCapability');
return { effective: 0, max: 0 };
}
}
/**
* The format decision the last frame COMMITTED to. @experimental
*
* The frame's own answer, not the device asked again. `linear` false is a
* project that never asked for HDR, which is not a fallback. The names come
* from the engine — a second spelling of the enum's order is drift.
*/
hdrFormat(): HdrFormat | null {
try {
const m = getModule() as unknown as {
postprocess_hdrFormat?(p: number): number;
postprocess_hdrFormatNames?(): string;
};
if (!m.postprocess_hdrFormat || !m.postprocess_hdrFormatNames || !hdrPtr) return null;
if (!m.postprocess_hdrFormat(hdrPtr)) return null;
const heap = (bridge.module as unknown as { HEAPF32?: Float32Array }).HEAPF32;
if (!heap) return null;
const f = heap.subarray(hdrPtr >> 2, (hdrPtr >> 2) + 4);
const [requested, effective, reason] = m.postprocess_hdrFormatNames().split('|');
return {
requested: requested ?? '', effective: effective ?? '',
reason: reason ?? 'none', linear: f[3] === 1,
fellBack: (requested ?? '') !== (effective ?? ''),
};
} catch (e) {
handleWasmError(e, 'PostProcess.hdrFormat');
return null;
}
}
begin(): void {
try {
getModule().postprocess_begin();
} catch (e) {
handleWasmError(e, 'PostProcess.begin');
}
}
end(): void {
try {
getModule().postprocess_end();
} catch (e) {
handleWasmError(e, 'PostProcess.end');
}
}
/** Say the frame needs a present when the rects alone cannot: a 1x letterbox
* and a split-screen viewport are the same geometry and differ only in intent. */
setPresentRequired(required: boolean): void {
try {
getModule().postprocess_setPresentRequired?.(required);
} catch (e) {
handleWasmError(e, 'PostProcess.setPresentRequired');
}
}
setOutputViewport(x: number, y: number, w: number, h: number): void {
try {
getModule().postprocess_setOutputViewport(x, y, w, h);
} catch (e) {
handleWasmError(e, 'PostProcess.setOutputViewport');
}
}
// -- per-camera / screen orchestration (state + commands) ----------------
_applyForCamera(camera: Entity): void {
const stack = this.state.cameraBindings.get(camera);
if (!stack || stack.isDestroyed || stack.enabledPassCount === 0) {
this.setBypass(true);
return;
}
if (!this.isInitialized()) {
this.init(1, 1);
}
this.setBypass(false);
syncStackToWasm(stack, this.engineStack_ !== stack, this.allowQualityPass_);
this.engineStack_ = stack;
}
_resetAfterCamera(): void {
try {
getModule().postprocess_clearPasses();
getModule().postprocess_setBypass(true);
this.engineStack_ = null;
} catch (e) {
handleWasmError(e, 'PostProcess._resetAfterCamera');
}
}
_beginScreenCapture(): void {
try {
getModule().postprocess_beginScreenCapture();
} catch (e) {
handleWasmError(e, 'PostProcess._beginScreenCapture');
}
}
_endScreenCapture(): void {
try {
getModule().postprocess_endScreenCapture();
} catch (e) {
handleWasmError(e, 'PostProcess._endScreenCapture');
}
}
_applyScreenStack(): void {
const stack = this.state.screenStack;
if (!stack || stack.isDestroyed || stack.enabledPassCount === 0) return;
const m = getModule();
try {
m.postprocess_clearScreenPasses();
} catch (e) {
handleWasmError(e, 'PostProcess._applyScreenStack:clearScreenPasses');
return;
}
for (const pass of stack.passes) {
if (!pass.enabled || !this.allowQualityPass_(pass.name)) continue;
try {
m.postprocess_addScreenPass(pass.name, pass.shader);
} catch (e) {
handleWasmError(e, `PostProcess._applyScreenStack:addScreenPass("${pass.name}")`);
continue;
}
for (const [name, value] of pass.floatUniforms) {
try {
m.postprocess_setScreenUniformFloat(pass.name, name, value);
} catch (e) {
handleWasmError(e, `PostProcess._applyScreenStack:setScreenUniform("${pass.name}", "${name}")`);
}
}
for (const [name, value] of pass.vec4Uniforms) {
try {
m.postprocess_setScreenUniformVec4(pass.name, name, value.x, value.y, value.z, value.w);
} catch (e) {
handleWasmError(e, `PostProcess._applyScreenStack:setScreenUniformVec4("${pass.name}", "${name}")`);
}
}
}
}
_executeScreenPasses(): void {
try {
getModule().postprocess_executeScreenPasses();
} catch (e) {
handleWasmError(e, 'PostProcess._executeScreenPasses');
}
}
}
/**
* Per-App post-process resource. Published + injected into the render pipeline
* by `PostProcessPlugin`; read as `app.getResource(PostProcess)`.
*/
export const PostProcess = defineResource<PostProcessAPI>(null!, 'PostProcess');