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.

14.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    entityEvents.ts
 * @brief   EntityEventQueue — the entity-scoped, string-named event channel.
 *
 * The engine has two event channels and they answer different questions.
 * `event.ts` is the GLOBAL, statically-typed bus: `defineEvent<T>()` gives a
 * symbol-keyed, double-buffered stream that systems read as a batch ("all
 * damage events this frame"). This file is the per-ENTITY one: an open string
 * key ("click", "trigger_enter") dispatched synchronously to handlers
 * subscribed for that entity, with bubbling to ancestors. It is what "this
 * button was clicked" means, and it is the channel {@link EventBinding} wires
 * authored data onto.
 *
 * It grew up inside `ui/` (as UIEventQueue) because widgets were its first
 * producer, but nothing in it is UI-specific — the type strings are open and
 * the queue never looks at a component. It lives here so non-UI producers and
 * the core binding layer can speak it without importing `ui/`. The `ui/core/
 * events.ts` names remain as aliases of these very objects.
 */
import { defineResource } from './resource';
import type { Entity } from '../types';
import type { App } from '../app/app';
import { log } from '../util/logger';

export interface EntityEvent<TData = unknown> {
    /** Event type string (e.g. `'click'`, `'change'`). */
    readonly type: string;
    /** The entity where the event originated. */
    readonly target: Entity;
    /** The entity currently handling the event (differs from target during bubbling). */
    readonly currentTarget: Entity;
    /** User-provided payload (shape depends on `type`). */
    readonly data: TData;
    /** True if any handler called `stopPropagation()`. */
    propagationStopped: boolean;
    /** True if any handler called `preventDefault()`. */
    defaultPrevented: boolean;
    /** Stop the event from bubbling further up the parent chain. */
    stopPropagation(): void;
    /** Signal that the default action (if any) should be skipped. */
    preventDefault(): void;
}

/** Immutable dispatch facts for debugger observers; no payload or mutation methods. */
export interface EntityEventObservation {
    readonly eventId: number;
    readonly type: string;
    readonly target: Entity;
    readonly currentTarget: Entity;
    readonly propagationStopped: boolean;
    readonly defaultPrevented: boolean;
}

export type EntityEventHandler<TData = unknown> = (event: EntityEvent<TData>) => void;
export type Unsubscribe = () => void;

/**
 * The event objects handed to handlers.
 *
 * A class rather than an object literal because the literal's two methods were
 * fresh closures on every emit. Under a JIT that costs nothing; on the
 * interpreter a device runs, a busy frame (physics republishes every contact to
 * both participants) allocated them by the tens of thousands and threw them
 * straight away. On the prototype they are allocated once.
 */
class EmittedEvent<TData> implements EntityEvent<TData> {
    propagationStopped = false;
    defaultPrevented = false;

    constructor(
        readonly type: string,
        readonly target: Entity,
        readonly currentTarget: Entity,
        readonly data: TData,
    ) {}

    stopPropagation(): void {
        this.propagationStopped = true;
    }

    preventDefault(): void {
        this.defaultPrevented = true;
    }
}

/**
 * A bubbled copy, which shares its propagation state with the event that
 * started the walk — stopping it stops the root, so the caller's walk halts.
 */
class BubbledEvent<TData> extends EmittedEvent<TData> {
    constructor(type: string, target: Entity, currentTarget: Entity, data: TData,
                private readonly root_: EntityEvent) {
        super(type, target, currentTarget, data);
        this.defaultPrevented = root_.defaultPrevented;
    }

    override stopPropagation(): void {
        this.propagationStopped = true;
        this.root_.propagationStopped = true;
    }

    override preventDefault(): void {
        this.defaultPrevented = true;
        this.root_.defaultPrevented = true;
    }
}

/**
 * Entity event queue: pub/sub with bubbling support.
 *
 * @example
 * ```ts
 * const events = new EntityEventQueue();
 * world.onDespawn(e => events.removeAll(e));   // one-time wiring
 *
 * events.on(buttonEntity, 'click', e => console.log('clicked'));
 * events.emit(buttonEntity, 'click');
 * ```
 */
export class EntityEventQueue {
    private readonly entityHandlers_ = new Map<
        Entity,
        Map<string, Set<EntityEventHandler>>
    >();
    private readonly globalHandlers_ = new Map<string, Set<EntityEventHandler>>();
    // How many handlers exist per type, entity-specific and global together. Kept as a
    // count rather than derived on demand so {@link hasListenersFor} is O(1): a producer
    // that has to WATCH for its events (visibility, proximity — anything not already
    // computed) asks every frame, and should cost nothing while nobody is listening.
    private readonly typeCounts_ = new Map<string, number>();
    private pending_: EntityEvent[] = [];
    private readonly activeKeys_ = new Set<string>();

    private readonly observers_ = new Set<(event: EntityEventObservation) => void>();
    private readonly eventIds_ = new WeakMap<EntityEvent, number>();
    private nextEventId_ = 0;

    /** Observe actual dispatch after handlers, without subscribing as a game listener.
     * Observers cannot stop propagation, prevent defaults or change the payload. */
    observe(handler: (event: EntityEventObservation) => void): Unsubscribe {
        this.observers_.add(handler);
        return () => { this.observers_.delete(handler); };
    }

    /**
     * Subscribe to an entity-specific event.
     * Returns an unsubscribe function.
     */
    on(entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe;
    /**
     * Subscribe to all events of a type, from any entity.
     */
    on(type: string, handler: EntityEventHandler): Unsubscribe;
    on(
        arg1: Entity | string,
        arg2: string | EntityEventHandler,
        arg3?: EntityEventHandler,
    ): Unsubscribe {
        // Entity-specific: on(entity, type, handler)
        if (typeof arg1 === 'number' && typeof arg2 === 'string' && typeof arg3 === 'function') {
            const entity = arg1 as Entity;
            const type = arg2;
            const handler = arg3;

            let typeMap = this.entityHandlers_.get(entity);
            if (!typeMap) {
                typeMap = new Map();
                this.entityHandlers_.set(entity, typeMap);
            }
            let set = typeMap.get(type);
            if (!set) {
                set = new Set();
                typeMap.set(type, set);
            }
            if (!set.has(handler)) this.countType_(type, 1);
            set.add(handler);

            return () => {
                const tm = this.entityHandlers_.get(entity);
                const s = tm?.get(type);
                if (s?.delete(handler)) {
                    this.countType_(type, -1);
                    if (s.size === 0) tm!.delete(type);
                    if (tm && tm.size === 0) this.entityHandlers_.delete(entity);
                }
            };
        }

        // Global: on(type, handler)
        const type = arg1 as string;
        const handler = arg2 as EntityEventHandler;

        let set = this.globalHandlers_.get(type);
        if (!set) {
            set = new Set();
            this.globalHandlers_.set(type, set);
        }
        if (!set.has(handler)) this.countType_(type, 1);
        set.add(handler);

        return () => {
            const s = this.globalHandlers_.get(type);
            if (s?.delete(handler)) {
                this.countType_(type, -1);
                if (s.size === 0) this.globalHandlers_.delete(type);
            }
        };
    }

    private countType_(type: string, delta: number): void {
        const next = (this.typeCounts_.get(type) ?? 0) + delta;
        if (next > 0) this.typeCounts_.set(type, next);
        else this.typeCounts_.delete(type);
    }

    /**
     * Is anyone subscribed to this event type, for any entity?
     *
     * For producers that must LOOK for their events rather than being handed them: a
     * visibility watcher walks the UI tree, a proximity watcher measures distances, and
     * neither should do that work into an empty room. Emitting is unaffected — an event
     * with no handlers still queues for `drain()`.
     */
    hasListenersFor(type: string): boolean {
        return this.typeCounts_.has(type);
    }

    /**
     * Remove all entity-specific handlers for `entity`.
     * Wire this to `world.onDespawn` for automatic cleanup.
     */
    removeAll(entity: Entity): void {
        const typeMap = this.entityHandlers_.get(entity);
        if (!typeMap) return;
        for (const [type, set] of typeMap) this.countType_(type, -set.size);
        this.entityHandlers_.delete(entity);
    }

    /**
     * Emit an event for `entity`. Synchronously dispatches to registered
     * handlers and queues the event for `drain()` / `query()`. Returns the
     * event so callers can inspect propagationStopped / defaultPrevented
     * (e.g. to drive bubbling to parents).
     */
    emit<TData = unknown>(
        entity: Entity,
        type: string,
        data?: TData,
    ): EntityEvent<TData> {
        const event = new EmittedEvent<TData>(type, entity, entity, data as TData);
        if (this.observers_.size) this.eventIds_.set(event, ++this.nextEventId_);
        this.pending_.push(event);
        this.dispatch_(entity, event);
        return event;
    }

    /**
     * Emit a bubbled event to an ancestor. Shares propagation state with
     * the root event: calling stopPropagation on the bubbled event marks
     * the root as stopped so callers can halt the bubbling walk.
     *
     * Callers are responsible for walking the parent chain; this queue
     * does not know about hierarchy.
     */
    emitBubbled(ancestor: Entity, rootEvent: EntityEvent): EntityEvent {
        if (rootEvent.propagationStopped) return rootEvent;

        const bubbled = new BubbledEvent(
            rootEvent.type, rootEvent.target, ancestor, rootEvent.data, rootEvent);
        if (this.observers_.size) {
            const id = this.eventIds_.get(rootEvent) ?? ++this.nextEventId_;
            this.eventIds_.set(rootEvent, id);
            this.eventIds_.set(bubbled, id);
        }
        this.pending_.push(bubbled);
        this.dispatch_(ancestor, bubbled);
        return bubbled;
    }

    /**
     * Return all events queued since the last drain and clear the queue.
     * Typically called once per frame by a UI system.
     */
    drain(): readonly EntityEvent[] {
        const events = this.pending_;
        this.pending_ = [];
        return events;
    }

    /** Non-destructively inspect currently-pending events of a type. */
    query(type: string): readonly EntityEvent[] {
        return this.pending_.filter((e) => e.type === type);
    }

    /** Restore an already-dispatched event for frame consumers without calling handlers again. @internal */
    requeue(event: EntityEvent): void {
        if (!this.pending_.includes(event)) this.pending_.push(event);
    }

    /** Remove all handlers and pending events. */
    clear(): void {
        this.entityHandlers_.clear();
        this.globalHandlers_.clear();
        this.pending_ = [];
        this.activeKeys_.clear();
        this.observers_.clear();
    }

    private dispatch_(entity: Entity, event: EntityEvent): void {
        // Re-entry guard: a handler that emits the same event on the same
        // entity would recurse forever. Block recursion for (entity, type).
        const key = `${entity as number}:${event.type}`;
        if (this.activeKeys_.has(key)) return;
        this.activeKeys_.add(key);

        try {
            const typeMap = this.entityHandlers_.get(entity);
            if (typeMap) {
                const set = typeMap.get(event.type);
                if (set) {
                    // Snapshot so handler-side unsubscribe doesn't skip peers
                    for (const h of Array.from(set)) {
                        try {
                            h(event);
                        } catch (err) {
                            log.error(
                                'ui',
                                `EntityEventQueue handler error [${event.type}]`,
                                err,
                            );
                        }
                    }
                }
            }

            const global = this.globalHandlers_.get(event.type);
            if (global) {
                for (const h of Array.from(global)) {
                    try {
                        h(event);
                    } catch (err) {
                        log.error(
                            'ui',
                            `EntityEventQueue handler error [${event.type}]`,
                            err,
                        );
                    }
                }
            }
        } finally {
            this.activeKeys_.delete(key);
            if (this.observers_.size) {
                const eventId = this.eventIds_.get(event) ?? ++this.nextEventId_;
                this.eventIds_.set(event, eventId);
                const observation = Object.freeze({ eventId, type: event.type, target: event.target,
                    currentTarget: event.currentTarget, propagationStopped: event.propagationStopped,
                    defaultPrevented: event.defaultPrevented });
                for (const observer of [...this.observers_]) {
                    try { observer(observation); } catch (err) { log.error('ui', 'Entity event observer error', err); }
                }
            }
        }
    }
}

/**
 * Shared EntityEventQueue resource. A plugin inserts the authoritative
 * instance on startup; systems access it via `Res(EntityEvents)`.
 *
 * The default value exists only so the resource is well-typed before
 * the owning plugin constructs the real queue. Consumers should never
 * see the placeholder at runtime — UIInteractionPlugin inserts its
 * queue during `build()`.
 */
export const EntityEvents = defineResource<EntityEventQueue>(new EntityEventQueue(), 'EntityEvents');

/**
 * The app's queue, creating it on first ask. Every producer and consumer — the
 * UI hit-test, the physics bridge, the binding dispatcher — goes through here
 * instead of inserting its own, so plugin build order cannot decide who wins and
 * a late plugin can never replace the queue earlier subscribers captured.
 * Despawn cleanup is wired once, with the queue.
 */
export function ensureEntityEvents(app: App): EntityEventQueue {
    if (!app.hasResource(EntityEvents)) {
        const queue = new EntityEventQueue();
        app.insertResource(EntityEvents, queue);
        app.world.onDespawn((entity: Entity) => queue.removeAll(entity));
    }
    return app.getResource(EntityEvents) as EntityEventQueue;
}