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 skeletal/enableSync.ts
* @brief Making a skeletal component's `enabled` field mean what it says.
*
* @details Every other renderable is drawn straight from its component, so
* clearing `enabled` stops it: the renderer walks the World and the flag
* is right there. A skeleton is not. Its instance lives in a side
* module's heap, keyed by entity in a manager the renderer knows nothing
* about, and the manager submits from ITS table — so the World's copy of
* the flag was read by nobody. The editor's eye toggle, the inspector's
* checkbox and a gameplay `world.set(e, SpineAnimation, {enabled:false})`
* all wrote a value that changed nothing.
*
* This is the one place that closes the loop, and it closes it for both
* runtimes: once a frame, each bound entity's flag is carried from the
* World into the manager that draws it.
*
* EDGE-TRIGGERED, deliberately. A flag has two writers — the component
* (authoring, editor visibility, gameplay writes) and the manager's own
* `setEnabled` (the imperative API) — and a mirror that pushed every
* frame would make the second one useless, undoing it on the next tick.
* Pushing only when the component's value actually MOVES leaves both
* honest: writing the field wins at the moment it is written, and
* between writes the imperative switch is free to override. It also
* means an entity whose binding lands after the field was written still
* picks it up (the first sync it appears in has nothing memoised for it),
* so no writer of the field needs to know when a skeleton finished
* loading.
*/
import type { Entity } from '../types';
import type { AnyComponentDef, ComponentData } from '../ecs/component';
/** The slice of the World this reads: one component's data, or null if absent. */
export interface SkeletalEnableWorld {
tryGet<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C> | null;
}
/** A skeletal runtime's manager, seen as "which entities it holds, and the switch". */
export interface SkeletalEnableTarget {
/** The entities this manager currently has an instance for. */
boundEntities(): Iterable<Entity>;
/** Take an entity out of / put it back into the frame. */
setEnabled(entity: Entity, enabled: boolean): void;
}
/**
* Carries `<component>.enabled` from the World into one skeletal manager, on the
* edges of that field. Hold one per manager (the memo of what it last pushed is
* what makes it edge-triggered) and call {@link sync} once per frame, before the
* manager advances and submits.
*/
export class SkeletalEnableMirror {
/** entity → the flag value this mirror last pushed for it. */
private readonly mirrored_ = new Map<Entity, boolean>();
constructor(private readonly component_: AnyComponentDef) {}
sync(world: SkeletalEnableWorld, target: SkeletalEnableTarget, isActive?: (entity: Entity) => boolean): void {
let bound = 0;
for (const entity of target.boundEntities()) {
bound++;
// Read new bindings once; inactive ones catch up before they resume.
if (this.mirrored_.has(entity) && isActive && !isActive(entity)) continue;
const data = world.tryGet(entity, this.component_) as { enabled?: boolean } | null;
// No component (an entity bound by something other than a scene —
// a test, a tool) has no flag to obey, so it is left alone.
if (!data) continue;
const enabled = data.enabled !== false;
if (this.mirrored_.get(entity) === enabled) continue;
this.mirrored_.set(entity, enabled);
target.setEnabled(entity, enabled);
}
// Entities have unbound (a despawn, a scene reload) — drop their memos, or
// a long editor session accumulates one entry per skeleton it ever showed.
if (this.mirrored_.size > bound) this.prune_(target);
}
private prune_(target: SkeletalEnableTarget): void {
const live = new Set(target.boundEntities());
for (const entity of this.mirrored_.keys()) {
if (!live.has(entity)) this.mirrored_.delete(entity);
}
}
}