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.

12.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    commands.ts
 * @brief   Deferred entity/component operations
 */

import { Entity } from '../types';
import { AnyComponentDef, ComponentDef, isBuiltinComponent, Name } from './component';
import type { World } from './world';
import { ResourceDef, ResourceStorage } from './resource';
import { log } from '../util/logger';

/** Key order is not a difference a replay should report, so sort it away. */
function stableText(value: unknown): string {
    if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';
    if (Array.isArray(value)) return `[${value.map(stableText).join(',')}]`;
    const rec = value as Record<string, unknown>;
    return `{${Object.keys(rec).sort().map((k) => `${k}:${stableText(rec[k])}`).join(',')}}`;
}

// =============================================================================
// Commands Descriptor (for system parameters)
// =============================================================================

/**
 * A request for a command queue in a system's parameter list, as
 * {@link Commands} returns it. Opaque — the system body receives a
 * `CommandsInstance`, which is the thing with methods.
 *
 * @public
 */
export interface CommandsDescriptor {
    /** @internal */
    readonly _type: 'commands';
}

/**
 * Ask a system for a command queue: spawning, despawning and adding or removing
 * components, recorded now and applied together.
 *
 * It flushes when the system returns — on a throw too, and after an async body's
 * await — so structural edits never land mid-iteration of that system's queries.
 *
 * @public
 */
export function Commands(): CommandsDescriptor {
    return { _type: 'commands' };
}

// =============================================================================
// Command Types
// =============================================================================

interface SpawnComponentEntry {
    component: AnyComponentDef;
    data: unknown;
}

interface DespawnCommand {
    type: 'despawn';
    entity: Entity;
}

interface InsertCommand {
    type: 'insert';
    entity: Entity;
    component: AnyComponentDef;
    data: unknown;
}

interface RemoveCommand {
    type: 'remove';
    entity: Entity;
    component: AnyComponentDef;
}

interface SetParentCommand {
    type: 'set_parent';
    entity: Entity;
    parent: Entity;
}

interface InsertResourceCommand {
    type: 'insert_resource';
    resource: ResourceDef<unknown>;
    value: unknown;
}

type Command =
    | DespawnCommand
    | InsertCommand
    | RemoveCommand
    | SetParentCommand
    | InsertResourceCommand;

// =============================================================================
// Entity Commands (Builder for spawning)
// =============================================================================

/**
 * One entity's share of a {@link CommandsInstance}: chain `insert`/`remove` and
 * let the queue apply them. Asking {@link EntityCommands.id} for a spawn's
 * entity materialises it early, because an id has to exist to be answered —
 * except inside a running query, where the id is reserved and the spawn still
 * lands at the flush.
 *
 * @public
 */
export class EntityCommands {
    private readonly commands_: CommandsInstance;
    private readonly entityRef_: { entity: Entity };
    private readonly components_: SpawnComponentEntry[] = [];
    private readonly spawnName_?: string;
    private isNew_: boolean;
    private parent_: Entity | null = null;

    constructor(commands: CommandsInstance, entity: Entity | null, name?: string) {
        this.commands_ = commands;

        if (entity === null) {
            this.entityRef_ = { entity: 0 as Entity };
            this.isNew_ = true;
            this.spawnName_ = name;
        } else {
            this.entityRef_ = { entity };
            this.isNew_ = false;
        }
    }

    /** @internal What this spawn or edit WOULD do, as text a second run can be
     *  compared against — a queued spawn has no entity yet, so identity cannot
     *  be part of the comparison and the composition is. */
    describe(): string {
        const parts = this.components_.map((c) => `${c.component._name}=${stableText(c.data)}`).sort();
        return `${this.isNew_ ? 'spawn' : `edit#${this.entityRef_.entity}`}`
            + `${this.spawnName_ ? `:${this.spawnName_}` : ''}`
            + `(${parts.join(',')})${this.parent_ === null ? '' : `<-${this.parent_}`}`;
    }

    insert<T extends object>(component: AnyComponentDef, data?: Partial<T>): this {
        let instance: unknown;

        if (isBuiltinComponent(component)) {
            instance = { ...component._default, ...(data as object) };
        } else {
            instance = (component as ComponentDef<T>).create(data);
        }

        if (this.isNew_) {
            this.components_.push({ component, data: instance });
        } else {
            this.commands_.queueInsert(this.entityRef_.entity, component, instance);
        }

        return this;
    }

    remove(component: AnyComponentDef): this {
        if (!this.isNew_) {
            this.commands_.queueRemove(this.entityRef_.entity, component);
        }
        return this;
    }

    /**
     * Attach this entity under `parent`. The engine keeps {@link Parent} and
     * {@link Children} in step from here — inserting `Parent` yourself writes
     * only one half of the link.
     */
    childOf(parent: Entity): this {
        if (this.isNew_) {
            this.parent_ = parent;
        } else {
            this.commands_.queueSetParent(this.entityRef_.entity, parent);
        }
        return this;
    }

    id(): Entity {
        if (this.isNew_ && this.entityRef_.entity === 0) {
            // Inside a running query the spawn cannot happen yet, but its identity
            // can: reserve it, and let the flush spawn into it. Outside one the
            // spawn lands now, as it always has.
            if (this.commands_.isWorldIterating()) this.entityRef_.entity = this.commands_.reserveEntity();
            else this.finalize();
        }
        return this.entityRef_.entity;
    }

    finalize(): void {
        if (this.isNew_) {
            this.commands_.spawnImmediate(this.components_, this.entityRef_, this.spawnName_, this.parent_);
            this.isNew_ = false;
            this.parent_ = null;
        }
    }
}

// =============================================================================
// Commands Instance (Runtime)
// =============================================================================

/**
 * The command queue a system declared with {@link Commands}. Records structural
 * work — spawn, despawn, add or remove a component, install a resource — and
 * applies it when the system returns, so nothing moves under a running query.
 *
 * @public
 */
export class CommandsInstance {
    private readonly world_: World;
    private readonly resources_: ResourceStorage;
    private pending_: Command[] = [];
    private spawned_: EntityCommands[] = [];

    constructor(world: World, resources: ResourceStorage) {
        this.world_ = world;
        this.resources_ = resources;
    }

    spawn(name?: string): EntityCommands {
        const ec = new EntityCommands(this, null, name);
        this.spawned_.push(ec);
        return ec;
    }

    entity(entity: Entity): EntityCommands {
        return new EntityCommands(this, entity);
    }

    despawn(entity: Entity): this {
        this.pending_.push({ type: 'despawn', entity });
        return this;
    }

    /**
     * A world-level service, for the work no component write can express.
     * Null where nothing installed it — an app assembled without that plugin
     * is a fact to report, not a crash. Here rather than on each context
     * because this is the one door every authored surface already holds.
     */
    resource<T>(def: ResourceDef<T>): T | null {
        return this.resources_.has(def) ? this.resources_.get(def) : null;
    }

    insertResource<T>(resource: ResourceDef<T>, value: T): this {
        this.pending_.push({
            type: 'insert_resource',
            resource: resource as ResourceDef<unknown>,
            value
        });
        return this;
    }

    queueInsert(entity: Entity, component: AnyComponentDef, data: unknown): void {
        this.pending_.push({ type: 'insert', entity, component, data });
    }

    queueRemove(entity: Entity, component: AnyComponentDef): void {
        this.pending_.push({ type: 'remove', entity, component });
    }

    queueSetParent(entity: Entity, parent: Entity): void {
        this.pending_.push({ type: 'set_parent', entity, parent });
    }

    /** @internal Whether the world is inside a query walk, where a spawn must wait. */
    isWorldIterating(): boolean {
        return this.world_.isIterating();
    }

    /** @internal An identity for a spawn that will be applied at flush. */
    reserveEntity(): Entity {
        return this.world_.reserveEntity();
    }

    /** @internal How EntityCommands applies a deferred spawn — `entityRef` is the
     *  handle it already gave the caller, filled in once the entity exists. */
    spawnImmediate(
        components: SpawnComponentEntry[],
        entityRef: { entity: Entity },
        name?: string,
        parent?: Entity | null,
    ): void {
        // A reserved id (see EntityCommands.id) is spawned into, not replaced.
        let entity = entityRef.entity;
        if (entity !== 0 && this.world_.valid(entity)) this.world_.commitReservedSpawn(entity, name);
        else entity = this.world_.spawn(name);
        entityRef.entity = entity;

        for (const entry of components) {
            this.world_.insert(entity, entry.component, entry.data as Record<string, unknown>);
        }

        if (parent !== null && parent !== undefined) {
            this.world_.setParent(entity, parent);
        }
    }

    /** @internal Everything queued and not yet applied, as comparable text. */
    describe(): string {
        const spawned = this.spawned_.map((ec) => ec.describe());
        const pending = this.pending_.map((c) => {
            const anyCmd = c as { type: string; entity?: Entity; component?: { _name: string }; data?: unknown };
            return `${anyCmd.type}#${anyCmd.entity ?? '-'}`
                + `${anyCmd.component ? `:${anyCmd.component._name}` : ''}`
                + `${anyCmd.data === undefined ? '' : `=${stableText(anyCmd.data)}`}`;
        });
        return [...spawned, ...pending].join('|');
    }

    flush(): void {
        for (const ec of this.spawned_) {
            ec.finalize();
        }
        this.spawned_.length = 0;

        for (const cmd of this.pending_) {
            try {
                this.executeCommand(cmd);
            } catch (e) {
                log.warn('commands', `Failed to execute command: ${cmd.type}`, e);
            }
        }
        this.pending_.length = 0;
    }

    private executeCommand(cmd: Command): void {
        switch (cmd.type) {
            case 'despawn':
                if (!this.world_.valid(cmd.entity)) {
                    log.warn('commands', `despawn skipped: entity ${cmd.entity} is already invalid`);
                    break;
                }
                this.world_.despawn(cmd.entity);
                break;

            case 'insert':
                if (!this.world_.valid(cmd.entity)) {
                    log.warn('commands', `insert skipped: entity ${cmd.entity} is invalid`);
                    break;
                }
                this.world_.insert(cmd.entity, cmd.component, cmd.data as Record<string, unknown>);
                break;

            case 'remove':
                if (!this.world_.valid(cmd.entity)) {
                    log.warn('commands', `remove skipped: entity ${cmd.entity} is invalid`);
                    break;
                }
                this.world_.remove(cmd.entity, cmd.component);
                break;

            case 'set_parent':
                if (!this.world_.valid(cmd.entity) || !this.world_.valid(cmd.parent)) {
                    log.warn('commands', `childOf skipped: entity ${cmd.entity} or parent ${cmd.parent} is invalid`);
                    break;
                }
                this.world_.setParent(cmd.entity, cmd.parent);
                break;

            case 'insert_resource':
                this.resources_.insert(cmd.resource, cmd.value);
                break;
        }
    }
}