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 system.ts
* @brief System definition and scheduling
*/
import { AnyComponentDef } from './component';
import { getDefaultContext } from './context';
import { QueryDescriptor, QueryInstance, QueryArg, RemovedQueryDescriptor, RemovedQueryInstance, type QueryCost } from './query';
import { ResDescriptor, ResMutDescriptor, ResMutInstance, ResourceStorage } from './resource';
import { CommandsDescriptor, CommandsInstance } from './commands';
import {
EventWriterDescriptor, EventReaderDescriptor,
EventWriterInstance, EventReaderInstance,
EventRegistry,
} from './event';
import type { Entity } from '../types';
import type { World } from './world';
import type { AotDispatcher, AotRuntime } from './aot/AotRuntime';
import type { AotTwin } from './aot/AotSystems';
// =============================================================================
// Schedule Phases
// =============================================================================
/**
* When in a frame a system runs, in the order listed; `Startup` runs once before
* the first frame. The `Fixed*` three are the simulation's cadence, running zero
* or more times per frame as `Time.fixedDelta` accumulates — where anything that
* must be deterministic belongs.
*
* @public
*/
export enum Schedule {
Startup = 0,
First = 1,
PreUpdate = 2,
Update = 3,
PostUpdate = 4,
Last = 5,
FixedPreUpdate = 10,
FixedUpdate = 11,
FixedPostUpdate = 12,
}
// =============================================================================
// World Access Descriptor
// =============================================================================
/**
* A request for the {@link World} itself, as {@link GetWorld} returns it — the
* escape hatch for work the declared parameters cannot express.
*
* @public
*/
export interface GetWorldDescriptor {
/** @internal */
readonly _type: 'get_world';
}
/**
* Ask a system for the {@link World} itself. The escape hatch: it declares no
* access, so the scheduler cannot see what the system touches and the query cache
* cannot serve it. Reach for `Query`/`Res`/`Commands` first.
*
* @public
*/
export function GetWorld(): GetWorldDescriptor {
return { _type: 'get_world' };
}
// =============================================================================
// System Parameter Types
// =============================================================================
/**
* Anything that may appear in a system's parameter list — what {@link Query},
* {@link Res}, {@link Commands} and their siblings return. Each is a request for
* access, resolved to a live value by {@link InferParams} when the system runs.
*
* @public
*/
export type SystemParam =
| QueryDescriptor<readonly QueryArg[]>
| ResDescriptor<unknown>
| ResMutDescriptor<unknown>
| CommandsDescriptor
| EventWriterDescriptor<unknown>
| EventReaderDescriptor<unknown>
| RemovedQueryDescriptor<AnyComponentDef>
| GetWorldDescriptor;
// =============================================================================
// Parameter Type Inference
// =============================================================================
/**
* One parameter's declaration resolved to the value a system body receives.
* {@link InferParams} maps this over a whole list; a request this does not
* recognise resolves to `never`, which is what makes a bad parameter a type
* error at the definition rather than a surprise at the call.
*
* @public
*/
export type InferParam<P> =
P extends QueryDescriptor<infer C> ? QueryInstance<C> :
P extends ResDescriptor<infer T> ? T :
P extends ResMutDescriptor<infer T> ? ResMutInstance<T> :
P extends CommandsDescriptor ? CommandsInstance :
P extends EventWriterDescriptor<infer T> ? EventWriterInstance<T> :
P extends EventReaderDescriptor<infer T> ? EventReaderInstance<T> :
P extends RemovedQueryDescriptor<infer _T> ? RemovedQueryInstance<_T> :
P extends GetWorldDescriptor ? World :
never;
/**
* The values a system body receives, derived from the parameters it declared —
* a `Query(...)` becomes a `QueryInstance`, a `Res(X)` becomes the resource
* value. Inferred, so a system body's arguments are typed without annotation.
*
* @public
*/
export type InferParams<P extends readonly SystemParam[]> = {
[K in keyof P]: InferParam<P[K]>;
};
// =============================================================================
// System Definition
// =============================================================================
/**
* Predicate evaluated per-frame; returning false skips the system for that tick.
* It is asked once per schedule run, so a set of nine systems gated on one pause
* flag reads it once and either all nine run or none do.
*
* @public
*/
export type RunCondition = () => boolean;
/**
* A declared system, as {@link defineSystem} returns it. Opaque: hand it to
* `addSystem`, a {@link SystemSet} or a schedule rather than reading it — every
* member is engine plumbing and may change.
*
* @public
*/
export interface SystemDef {
/** @internal */
readonly _id: symbol;
/** @internal */
readonly _params: readonly SystemParam[];
/** @internal */
readonly _fn: (...args: never[]) => void | Promise<void>;
/** @internal */
readonly _name: string;
/** @internal */
readonly _runBefore?: readonly string[];
/** @internal */
readonly _runAfter?: readonly string[];
/** @internal */
readonly _runWhenPaused?: boolean;
/** @internal */
readonly _touches?: SystemTouches | (() => SystemTouches);
}
let templateCounter_ = 0;
/**
* Scheduling policy a system carries with it. Names are matched against other
* systems' names and against {@link SystemSet} names, so a set can be ordered
* against without knowing which systems are in it.
*
* @public
*/
export interface SystemOptions {
/** Name other systems reference in their ordering edges. */
name?: string;
/** This system runs before each of these names (a system or a set). */
runBefore?: string[];
/** This system runs after each of these names (a system or a set). */
runAfter?: string[];
/** Opt into paused First/PreUpdate/Update/PostUpdate frames. Last already runs; fixed steps stay stopped. */
runWhenPaused?: boolean;
/**
* What the system reaches for through {@link GetWorld}. See {@link SystemTouches}.
*
* A function is re-read every time the access is, which is what lets a system
* running authored data (an FSM, a behaviour tree) answer from the data
* actually loaded rather than from everything it could ever be handed.
*/
touches?: SystemTouches | (() => SystemTouches);
}
/**
* What a system reaches for outside its declared parameters — a {@link GetWorld}
* user's claim about the escape hatch, without which the scheduler assumes it
* touches everything. By component NAME: the reason to reach through the World
* is usually a type registered later than the system.
*
* @public
*/
export interface SystemTouches {
reads?: readonly string[];
writes?: readonly string[];
/**
* Some of the reach genuinely cannot be named — a system running data a
* project authored, where one of the leaves does not say what it writes.
* Declared rather than left out: an omitted `touches` and a known-incomplete
* one are both "assume everything", but only this one says so on purpose.
*/
opaque?: boolean;
}
/**
* Declare a system: what it reads and writes, and the function to run.
*
* Ordering declared here travels with the definition, so it applies wherever
* the system is registered — including the top-level {@link addSystem}, which
* takes no options of its own. Edges given again at the registration site (or
* on the enclosing {@link SystemSet}) are added to these, not replaced.
*
* @public
*/
export function defineSystem<P extends readonly SystemParam[]>(
params: [...P],
fn: (...args: InferParams<P>) => void | Promise<void>,
options?: SystemOptions
): SystemDef {
const tid = ++templateCounter_;
return {
_id: Symbol(`SystemTemplate_${tid}`),
_params: params,
_fn: fn as (...args: never[]) => void,
_name: options?.name ?? '',
_runBefore: options?.runBefore,
_runAfter: options?.runAfter,
_runWhenPaused: options?.runWhenPaused,
_touches: options?.touches,
};
}
/**
* The same system under a scheduler-owned identity and name.
*
* Registration gives a template its own id so the same definition can be added
* twice, and copying the fields by hand at each site is how a field added to
* SystemDef silently stops travelling with it.
*/
export function rescopeSystem(system: SystemDef, name: string): SystemDef {
return {
...system,
_id: Symbol(`System_${name}`),
_name: name,
};
}
/** Union of ordering edges from two sources, preserving first-seen order. */
export function mergeOrderingEdges(
a: readonly string[] | undefined,
b: readonly string[] | undefined
): string[] | undefined {
if (!a?.length) return b?.length ? [...b] : undefined;
if (!b?.length) return [...a];
const out = [...a];
for (const name of b) {
if (!out.includes(name)) out.push(name);
}
return out;
}
// =============================================================================
// System Set — group of systems sharing a run condition and ordering edges
// =============================================================================
/**
* A named group of systems. When registered via `App.addSystemSet`, every
* member gets the set's `runIf` and its `runBefore` / `runAfter` edges — the
* group's ordering written once instead of per system. Other
* systems or sets may also reference the set's *name* in their own edges; the
* scheduler expands such a reference to every member of the set.
*
* Build one with {@link defineSystemSet}; the underscore-prefixed fields are
* the scheduler's, not an authoring surface.
*
* @public
*/
export interface SystemSet {
/** @internal */
readonly _kind: 'set';
/** @internal */
readonly _name: string;
/** @internal */
readonly _systems: readonly SystemDef[];
/** @internal */
readonly _runIf?: RunCondition;
/** @internal */
readonly _runBefore?: readonly string[];
/** @internal */
readonly _runAfter?: readonly string[];
}
/**
* What a {@link SystemSet} is built out of. `systems` keeps the order it is
* written in; `runIf` and the two edge lists apply to every member.
*
* @public
*/
export interface SystemSetOptions {
/** Systems contained in the set. */
systems: SystemDef[];
/** Predicate checked per-frame; false skips every member. */
runIf?: RunCondition;
/** Member systems run before each of these names (may reference a set). */
runBefore?: string[];
/** Member systems run after each of these names (may reference a set). */
runAfter?: string[];
}
/**
* Group systems under one name so ordering and run conditions are written once.
*
* ```ts
* const physics = defineSystemSet('physics', {
* systems: [applyForces, integrateVelocity],
* runBefore: ['render'],
* runIf: () => !paused,
* });
* app.addSystemSetToSchedule(Schedule.FixedUpdate, physics);
* ```
*
* Members keep the order they are listed in; anything constraining `'physics'`
* constrains all of them.
*
* @public
*/
export function defineSystemSet(name: string, options: SystemSetOptions): SystemSet {
if (!name) throw new Error('SystemSet requires a name');
return {
_kind: 'set',
_name: name,
_systems: options.systems,
_runIf: options.runIf,
_runBefore: options.runBefore,
_runAfter: options.runAfter,
};
}
// =============================================================================
// Global System Registration
// =============================================================================
function getPendingSystems(): Array<{ schedule: number; system: unknown }> {
return getDefaultContext().pendingSystems;
}
export function addSystem(system: SystemDef): void {
getPendingSystems().push({ schedule: Schedule.Update, system });
}
/**
* Register a system to run once, before the first frame — where a project spawns
* its world. Startup runs after the engine's own startup, so the components and
* resources a system asks for are there.
*
* @public
*/
export function addStartupSystem(system: SystemDef): void {
getPendingSystems().push({ schedule: Schedule.Startup, system });
}
/**
* Register a system in a {@link Schedule}. This is how a project bundle's
* systems reach the loop: the call records them, and the app drains what was
* recorded when it starts, so module-level registration works before an `App`
* exists.
*
* @public
*/
export function addSystemToSchedule(schedule: Schedule, system: SystemDef): void {
getPendingSystems().push({ schedule, system });
}
/**
* Register a {@link SystemSet} from a project bundle, the module-level twin of
* `App.addSystemSetToSchedule`. Without it a project can define a set — the run
* condition a pause is written as — and have no door to register it through.
*
* @public
*/
export function addSystemSetToSchedule(schedule: Schedule, set: SystemSet): void {
getPendingSystems().push({ schedule, system: set });
}
// =============================================================================
// System Runner
// =============================================================================
/** A component with no fields: a query filters on it and nothing reads it. */
function isTagDef(def: AnyComponentDef): boolean {
const shape = (def as { _default?: unknown })._default;
return typeof shape === 'object' && shape !== null && Object.keys(shape).length === 0;
}
export class SystemRunner {
private readonly world_: World;
private readonly resources_: ResourceStorage;
private readonly eventRegistry_: EventRegistry | null;
private readonly argsCache_ = new Map<symbol, unknown[]>();
private readonly systemTicks_ = new Map<symbol, number>();
private readonly systemChangeSequences_ = new Map<symbol, number>();
private readonly queryCache_ = new Map<symbol, QueryInstance<any>[]>();
private readonly removedCache_ = new Map<symbol, RemovedQueryInstance<any>[]>();
private currentLastRunTick_ = -1;
private timings_: Map<string, number> | null = null;
private queryCosts_: Map<string, QueryCost> | null = null;
/**
* Compiled twins, when a shipping build installed them. Absent in the editor
* and in dev, which is the whole of the mode policy — with nothing installed
* there is nothing to dispatch to.
*/
private aot_: AotRuntime | null = null;
/** The compiled half of this runner: everything a twin needs around its
* call, from whichever side of the contract can lay the rows out. */
private aotDispatch_: AotDispatcher | null = null;
constructor(world: World, resources: ResourceStorage, eventRegistry?: EventRegistry) {
this.world_ = world;
this.resources_ = resources;
this.eventRegistry_ = eventRegistry ?? null;
}
/** @internal Install the twins a build produced. */
useAot(runtime: AotRuntime | null): void {
this.aot_ = runtime;
this.aotDispatch_ = runtime ? runtime.dispatcherFor(this.world_) : null;
}
setTimingEnabled(enabled: boolean): void {
this.timings_ = enabled ? new Map() : null;
this.queryCosts_ = enabled ? new Map() : null;
this.world_.setQueryCostEnabled(enabled);
}
getTimings(): ReadonlyMap<string, number> | null {
return this.timings_;
}
/**
* Per-system query cost for the frame: what each system's queries walked, and
* how much of that a change filter then discarded. This is what turns "7ms"
* into "7ms over 18,400 entities, none of which had changed".
*/
getQueryCosts(): ReadonlyMap<string, QueryCost> | null {
return this.queryCosts_;
}
/** @brief Clear timing data for the current frame */
clearTimings(): void {
this.timings_?.clear();
this.queryCosts_?.clear();
}
/** @brief Remove cached state for a single system */
evict(systemId: symbol): void {
this.argsCache_.delete(systemId);
this.systemTicks_.delete(systemId);
this.systemChangeSequences_.delete(systemId);
this.queryCache_.delete(systemId);
// Dropping the reference is not releasing the claim: a reader nothing
// can reach still pins its component's removal history forever.
for (const removed of this.removedCache_.get(systemId) ?? []) removed.dispose();
this.removedCache_.delete(systemId);
}
/** @brief Clear all cached state */
reset(): void {
this.argsCache_.clear();
this.systemTicks_.clear();
this.systemChangeSequences_.clear();
this.queryCache_.clear();
for (const removeds of this.removedCache_.values()) {
for (const removed of removeds) removed.dispose();
}
this.removedCache_.clear();
}
run(system: SystemDef): void | Promise<void> {
const twin = this.aot_?.systems.get(system._name);
// Falls through when the dispatcher could not take it, which is the
// interpreter keeping the system rather than the system not running.
if (twin && this.runCompiled_(system, twin)) return;
let args = this.argsCache_.get(system._id);
if (!args) {
args = new Array(system._params.length);
this.argsCache_.set(system._id, args);
}
this.currentLastRunTick_ = this.systemTicks_.get(system._id) ?? -1;
const lastChangeSequence = this.systemChangeSequences_.get(system._id) ?? -1;
// Published only once every param resolved. Building a system's first set
// of query instances can throw — an unregistered component reaches
// resolveGetter, and that is exactly when it says so — and a cache
// published up front kept whatever had been built before the throw. The
// next frame then read `firstRun === false` against a SHORT array, found
// `undefined` where a later query belonged, and reported
// "cannot read properties of undefined (reading 'resetTick')" forever:
// the true error scrolls away and every frame after it names the runner.
// Commit at the end instead, so a failed setup is simply not cached and
// the following frame re-raises the real one.
const cachedQueries = this.queryCache_.get(system._id);
const firstRun = !cachedQueries;
const queries = cachedQueries ?? [];
const removeds = this.removedCache_.get(system._id) ?? [];
let qi = 0, ri = 0;
for (let i = 0; i < system._params.length; i++) {
const param = system._params[i];
if (param._type === 'query') {
if (firstRun) {
const inst = new QueryInstance(this.world_, param, this.currentLastRunTick_);
inst.resetChangeSequence(lastChangeSequence);
queries.push(inst);
args[i] = inst;
} else {
const inst = queries[qi];
inst.resetTick(this.currentLastRunTick_);
inst.resetChangeSequence(lastChangeSequence);
args[i] = inst;
}
qi++;
} else if (param._type === 'removed') {
if (firstRun) {
const desc = param as RemovedQueryDescriptor<AnyComponentDef>;
const inst = new RemovedQueryInstance(this.world_, desc._component, this.currentLastRunTick_);
removeds.push(inst);
args[i] = inst;
} else {
const inst = removeds[ri];
inst.resetTick(this.currentLastRunTick_);
args[i] = inst;
}
ri++;
} else {
args[i] = this.resolveParam(param);
}
}
if (firstRun) {
this.queryCache_.set(system._id, queries);
this.removedCache_.set(system._id, removeds);
// After the commit, never during: a param that threw halfway would
// otherwise leave a claim on history with no owner to release it.
for (const removed of removeds) removed.activateRetention();
}
const t0 = this.timings_ ? performance.now() : 0;
let result: void | Promise<void>;
try {
result = (system._fn as (...args: unknown[]) => void | Promise<void>)(...args);
} catch (e) {
this.flushSystem_(system, args, t0);
throw e;
}
if (result instanceof Promise) {
// Parked here, another system may run. The iteration guard belongs to
// the world, so this one's share of it is set aside until it resumes.
const suspended = this.world_.suspendIteration();
const resume = (): void => {
this.world_.resumeIteration(suspended);
this.flushSystem_(system, args, t0);
};
return result.then(resume, (e) => {
resume();
throw e;
});
}
this.flushSystem_(system, args, t0);
}
/**
* A compiled system's frame: the dispatcher does the contract, this keeps the
* scheduler's own books — what it cost, and when it last ran.
*/
private runCompiled_(system: SystemDef, twin: AotTwin): boolean {
const t0 = this.timings_ ? performance.now() : 0;
// A dispatcher that could not take this one has not failed: the system
// is interpreted this frame, which is the fallback the whole design
// rests on, arriving at the only layer that still has the closure.
if (!this.aotDispatch_!.run(twin)) return false;
if (this.timings_) {
const name = system._name;
this.timings_.set(name, (this.timings_.get(name) ?? 0) + (performance.now() - t0));
}
this.systemTicks_.set(system._id, this.world_.getWorldTick());
this.systemChangeSequences_.set(system._id, this.world_.getChangeSequence());
return true;
}
private flushSystem_(system: SystemDef, args: unknown[], t0: number): void {
// Kept Mut rows first: the edits a system made to rows it held past the
// loop belong to the entities as they stood, before its Commands despawn
// or restructure any of them.
for (let i = 0; i < args.length; i++) {
if (args[i] instanceof QueryInstance) (args[i] as QueryInstance<readonly QueryArg[]>).settleKeptRows();
}
for (let i = 0; i < args.length; i++) {
if (args[i] instanceof CommandsInstance) {
(args[i] as CommandsInstance).flush();
}
}
if (this.queryCosts_) {
this.harvestQueryCost_(system);
}
if (this.timings_) {
// Accumulated, not assigned: a fixed schedule runs as many times in one
// frame as the accumulator has steps for, and the frame cost of such a
// system is all of them. Assigning reported the last step alone.
const name = system._name;
this.timings_.set(name, (this.timings_.get(name) ?? 0) + (performance.now() - t0));
}
this.world_.resetIterationDepth();
// The window closes here, not where it opened: a system that awaited
// mid-body reads its rows after `resetTick`, so releasing there would let
// another reader prune what this one is still owed.
const ranAt = this.world_.getWorldTick();
for (const removed of this.removedCache_.get(system._id) ?? []) {
removed.releaseThrough(ranAt);
}
this.systemTicks_.set(system._id, ranAt);
// Closing at completion consumes this run's own writebacks too. Writes
// after completion remain distinct even within the same world tick.
this.systemChangeSequences_.set(system._id, this.world_.getChangeSequence());
}
private harvestQueryCost_(system: SystemDef): void {
const queries = this.queryCache_.get(system._id);
if (!queries || queries.length === 0) return;
const name = system._name;
const total = this.queryCosts_!.get(name) ?? { calls: 0, scanned: 0, filtered: 0 };
for (const q of queries) {
const cost = q.takeCost();
total.calls += cost.calls;
total.scanned += cost.scanned;
total.filtered += cost.filtered;
}
if (total.calls > 0) this.queryCosts_!.set(name, total);
}
private resolveParam(param: SystemParam): unknown {
switch (param._type) {
case 'res':
return this.resources_.get(param._resource);
case 'res_mut':
return this.resources_.getResMut(param._resource);
case 'commands':
return new CommandsInstance(this.world_, this.resources_);
case 'event_writer': {
const desc = param as EventWriterDescriptor<unknown>;
const bus = this.eventRegistry_
? this.eventRegistry_.getBus(desc._event)
: (() => { throw new Error('EventRegistry not available'); })();
return new EventWriterInstance(bus);
}
case 'event_reader': {
const desc = param as EventReaderDescriptor<unknown>;
const bus = this.eventRegistry_
? this.eventRegistry_.getBus(desc._event)
: (() => { throw new Error('EventRegistry not available'); })();
return new EventReaderInstance(bus);
}
case 'get_world':
return this.world_;
default:
throw new Error('Unknown system parameter type');
}
}
}