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 context.ts
* @brief Explicit application context replacing globalThis implicit coupling
*/
/**
* Surface the engine exposes to an attached editor host.
*
* `registerComponent` is called eagerly during `defineComponent` so the
* editor knows the full component catalogue. The `on*` callbacks are all
* optional — an editor that only needs the catalogue (no live inspector)
* can leave them unset and avoid any per-mutation overhead.
*
* All entity values are the engine's numeric Entity handle. Component
* identification is by the string name that was passed to
* `registerComponent` / `defineComponent`.
*/
export interface EditorBridge {
registerComponent(name: string, defaults: Record<string, unknown>, isTag: boolean): void;
/** Fired after an entity is created (optionally with a Name component). */
onEntitySpawned?(entity: number, name?: string): void;
/** Fired just before an entity is destroyed. Components are still attached. */
onEntityDespawned?(entity: number): void;
/** Fired when a component is first attached to an entity. */
onComponentAdded?(entity: number, component: string): void;
/** Fired when a component is detached from an entity. */
onComponentRemoved?(entity: number, component: string): void;
/** Fired when component data changes (insert with new data, set, or edit). */
onComponentChanged?(entity: number, component: string): void;
/** Fired when a parent link changes. `parent === null` means the entity was unparented. */
onParentChanged?(child: number, parent: number | null): void;
}
export interface PendingSystemEntry {
schedule: number;
system: unknown;
}
export type WasmErrorHandler = (error: unknown, context: string) => void;
export interface WasmErrorState {
handler: WasmErrorHandler | null;
lastReportTime: number;
suppressedCount: number;
}
export class AppContext {
readonly componentRegistry = new Map<string, any>();
readonly pendingSystems: PendingSystemEntry[] = [];
/** Plugins a project bundle installed at module level, drained with the
* systems: a bundle is imported before an App exists. */
readonly pendingPlugins: unknown[] = [];
editorBridge: EditorBridge | null = null;
readonly wasmError: WasmErrorState = { handler: null, lastReportTime: 0, suppressedCount: 0 };
/**
* Run mode. `editorMode` = an editor host is attached (vs a standalone
* runtime); `playMode` = within an editor, gameplay is running. Gameplay
* systems gate on these via {@link playModeOnly} (`env.ts`). Kept here so
* all app-scoped mutable state lives on one context (with componentRegistry
* / editorBridge / pendingSystems) rather than in a separate module global,
* so isolated Apps get isolated run modes.
*/
editorMode = false;
playMode = false;
/**
* How many times the queues have been taken or cleared. What was declared into them belongs to the App that took them, so a declaration
* made once for the context (a layer that is imported once) has to be queued again for the next App when this has moved.
*/
queueEpoch = 0;
/** @brief Drain all pending systems and clear the queue */
drainPendingSystems(): PendingSystemEntry[] {
const drained = this.pendingSystems.splice(0);
this.queueEpoch++;
return drained;
}
/** @brief Drain all pending plugins and clear the queue */
drainPendingPlugins(): unknown[] {
return this.pendingPlugins.splice(0);
}
/** @brief Reset all mutable state for a new session */
reset(): void {
this.queueEpoch++;
this.pendingSystems.length = 0;
this.pendingPlugins.length = 0;
this.componentRegistry.clear();
this.editorBridge = null;
this.wasmError.handler = null;
this.wasmError.lastReportTime = 0;
this.wasmError.suppressedCount = 0;
this.editorMode = false;
this.playMode = false;
}
}
/**
* Module-level default context.
*
* Multi-app note: this default is shared across all consumers that call
* `getDefaultContext()` without first installing their own context. If you
* run multiple isolated Apps in one process, each must call
* `setDefaultContext(new AppContext())` on its own entry path — the lazy
* singleton here will otherwise leak state (component registry, pending
* systems, wasm-error throttle) between them.
*/
let defaultContext_: AppContext | null = null;
export function getDefaultContext(): AppContext {
if (!defaultContext_) defaultContext_ = new AppContext();
return defaultContext_;
}
export function setDefaultContext(ctx: AppContext): void {
defaultContext_ = ctx;
}