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 behavior.ts
* @brief defineBehavior — per-entity scripted behavior, compiled to one ECS system.
*
* The authoring sugar for the gameplay loop: a behavior is a `defineComponent`
* (its `state`, attachable + tunable per-entity in the editor Details panel) plus
* an auto-registered system that drives `start` / `update` / `destroy` for every
* entity carrying that component. There is no second runtime — it desugars
* entirely onto the existing ECS-system model (REARCH_GAMEPLAY.md §2.2).
*/
import type { Entity } from './types';
import {
defineComponent,
type AnyComponentDef,
type ComponentData,
type ComponentDef,
type ComponentMetadata,
} from './ecs/component';
import { Schedule, defineSystem, addSystemToSchedule, GetWorld, type SystemTouches } from './ecs/system';
import { Query, Mut } from './ecs/query';
import { Res, Time, type TimeData } from './ecs/resource';
import { Commands, type CommandsInstance } from './ecs/commands';
import { Input, type InputState } from './input/input';
import type { World } from './ecs/world';
/**
* The per-entity handle passed to a behavior's lifecycle hooks. `self` is the
* behavior's own component data — mutate it freely, the change persists. The
* object is REUSED across entities and frames (zero per-entity allocation): do
* not retain it past the hook call; copy what you need.
*/
export interface BehaviorContext<S extends object> {
/** The entity this behavior instance is attached to. */
readonly entity: Entity;
/** This behavior's own component data — mutate freely (persists). */
readonly self: S;
/** Frame timing (`delta` seconds, `elapsed`, …). */
readonly time: TimeData;
/** Runtime input (keyboard / mouse / touch). */
readonly input: InputState;
/** Deferred structural ops (spawn / despawn / insert) — safe mid-iteration. */
readonly commands: CommandsInstance;
/** The world, for cross-entity access. */
readonly world: World;
/**
* Read another component on THIS entity.
*
* For a script component this IS the stored object, so mutating it sticks.
* For an ENGINE component (Transform, Sprite, RigidBody2D — anything C++-backed)
* it is a copy decoded out of the wasm heap: mutating it changes nothing.
* Read it, change it, and hand it back through {@link set}.
*/
get<C extends AnyComponentDef>(component: C): ComponentData<C>;
/** Write another component on THIS entity — how an engine component is changed. */
set<C extends AnyComponentDef>(component: C, data: ComponentData<C>): void;
/** Whether THIS entity has `component`. */
has(component: AnyComponentDef): boolean;
}
export interface BehaviorDef<S extends object> {
/** Per-entity state → a `defineComponent`, editable in the Details panel. */
state?: S;
/** Schedule the lifecycle system runs in (default `Schedule.Update`). */
schedule?: Schedule;
/** Field-presentation metadata for `state` (ranges, enums, …), forwarded to the component. */
metadata?: ComponentMetadata;
/**
* The components this behaviour reaches for through `ctx.get`/`ctx.set`, by
* name — its own state component is already declared. Undeclared, the
* schedule assumes anything, and this conflicts with every other system.
*/
touches?: SystemTouches;
/** Run once, the frame the behavior's component first appears on an entity. */
start?(ctx: BehaviorContext<S>): void;
/** Run every frame for each entity carrying the behavior. `dt` == `ctx.time.delta`. */
update?(ctx: BehaviorContext<S>, dt: number): void;
/** Run once when the component is removed OR the entity is despawned. */
destroy?(ctx: BehaviorContext<S>): void;
}
/** Internal: the mutable backing of the reused {@link BehaviorContext}. */
interface MutableContext<S extends object> {
entity: Entity;
self: S;
time: TimeData;
input: InputState;
commands: CommandsInstance;
world: World;
get<C extends AnyComponentDef>(component: C): ComponentData<C>;
set<C extends AnyComponentDef>(component: C, data: ComponentData<C>): void;
has(component: AnyComponentDef): boolean;
}
/**
* Define a per-entity behavior. Returns the backing {@link ComponentDef} (so you
* can spawn/insert it from code), and registers the lifecycle system as a side
* effect.
*
* @example
* export const Patrol = defineBehavior('Patrol', {
* state: { speed: 60 },
* update(ctx, dt) {
* const t = ctx.get(Transform); // a copy — Transform is C++-backed
* t.position.x += ctx.self.speed * dt;
* ctx.set(Transform, t); // …so hand it back
* },
* });
*/
export function defineBehavior<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S> {
const Comp = defineComponent<S>(name, (def.state ?? ({} as S)), def.metadata);
const schedule = def.schedule ?? Schedule.Update;
// Lifecycle is presence-diffed against the live query, NOT tick-based removed
// detection: a behavior system that runs before whoever despawns would miss a
// same-tick removal. Instead `destroy` fires the frame an entity drops out of
// the query (component removed OR entity despawned) — order-independent.
// `started` is per-system-instance state, rebuilt fresh on hot-reload, so a
// reload re-runs `start` (matching the fast-restart semantics).
const started = new Set<Entity>();
const seen = new Set<Entity>();
const lastData = def.destroy ? new Map<Entity, S>() : null;
const gone: Entity[] = [];
// One reused context; methods close over `ctx` (not `this`) so they survive
// destructuring (`const { get } = ctx`).
const ctx: MutableContext<S> = {
entity: 0 as Entity,
self: null as unknown as S,
time: null as unknown as TimeData,
input: null as unknown as InputState,
commands: null as unknown as CommandsInstance,
world: null as unknown as World,
get(component) { return ctx.world.get(ctx.entity, component); },
set(component, data) { ctx.world.set(ctx.entity, component, data); },
has(component) { return ctx.world.has(ctx.entity, component); },
};
const { start, update, destroy } = def;
const system = defineSystem(
[Query(Mut(Comp)), Res(Time), Res(Input), Commands(), GetWorld()],
(q, time, input, commands, world) => {
ctx.time = time;
ctx.input = input;
ctx.commands = commands;
ctx.world = world;
seen.clear();
for (const [entity, data] of q) {
const self = data as unknown as S;
seen.add(entity);
ctx.entity = entity;
ctx.self = self;
if (!started.has(entity)) {
started.add(entity);
start?.(ctx);
}
update?.(ctx, time.delta);
lastData?.set(entity, self);
}
if (destroy) {
gone.length = 0;
for (const e of started) if (!seen.has(e)) gone.push(e);
for (const e of gone) {
started.delete(e);
ctx.entity = e;
ctx.self = (lastData?.get(e) ?? ({} as S));
destroy(ctx);
lastData?.delete(e);
}
}
},
{
name: `Behavior:${name}`,
// Undeclared is opaque ON PURPOSE, and said rather than left out: the
// body is a project's code, and the schedule must not assume that
// silence means it touches nothing.
touches: def.touches ?? { opaque: true },
},
);
addSystemToSchedule(schedule, system);
return Comp;
}