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.

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