@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/entity.d.ts

@@ -0,0 +1,409 @@
+import { type Cost, type EffectDef, type ResourceKind, type UnitTypeDef } from './defs';
+import { type Component } from './components';
+import type { Rect, Vec2 } from './math';
+import type { StatsCache } from './stats';
+import type { OrderParams } from './registry';
+/** @beta */
+export type EntityId = number;
+/** @beta */
+export type PlayerId = number;
+/**
+ * An order a unit carries out or has queued. `State` is what its behaviour keeps in it (`OrderBehavior<State>`): empty
+ * as the order is given, so every field of it is one that may not be there yet
+ *
+ * @beta
+ */
+export interface Order<State extends object = Record<string, any>, Init extends object = OrderParams> {
+    id: number;
+    type: string;
+    /** What it was given, as its type takes it (`OrderInits`): plain data, saved with the order */
+    init: Init;
+    /** Shared by every unit that received the order from the same command */
+    groupId: number;
+    started: boolean;
+    /** Scratch space owned by the order behavior: plain data, saved with the order */
+    state: State;
+}
+/** @beta */
+export interface AbilityState {
+    id: string;
+    /** 0 for an ability a hero has not learned yet */
+    level: number;
+    /** Seconds until it can be used again */
+    cooldown: number;
+    /**
+     * Uses left, of an ability with charges (`AbilityDef.charges`): all it holds when left out, and `chargesLeft` says
+     * how many that is. Set while it holds fewer
+     */
+    charges?: number;
+    /** Seconds until the next use is back, while it holds fewer than it can */
+    refill?: number;
+    autocast: boolean;
+    /** Where it was last aimed */
+    point?: Vec2;
+}
+/** @beta */
+export interface BuffInstance {
+    id: string;
+    /** Level of the ability it came from */
+    level: number;
+    /** Seconds left. Infinity for buffs that stay */
+    remaining: number;
+    elapsed: number;
+    /** Entity that put it there */
+    source: EntityId;
+    /** What is left of the shield it gives */
+    shield?: number;
+    /** How many of it there are, for buffs that pile up */
+    stacks?: number;
+    /** The ability it came from, for buffs that do something when their time is up */
+    ability?: string;
+    /**
+     * Kept up by an ability of its source's for as long as it holds (a passive's buff, an aura's): put on again every
+     * round for a moment, with no time of its own to show (`EntityState.buffTimes` says -1)
+     */
+    kept?: boolean;
+    /** State of the game's own about this one buff: a counter, what it has done so far. Plain data: it is saved */
+    data?: Record<string, unknown>;
+}
+/**
+ * An item someone carries
+ *
+ * @beta
+ */
+export interface ItemInstance {
+    id: number;
+    item: string;
+    /** Uses left, for items that run out */
+    charges: number;
+    /** Cooldown of the ability the item gives */
+    state?: AbilityState;
+    /** State of the game's own about this one item: kills it has seen, what it has stored. Plain data: it is saved */
+    data?: Record<string, unknown>;
+}
+/**
+ * What a shop has of one of its wares (`shopStock`, a component of the entity's)
+ *
+ * @beta
+ */
+export interface StockState {
+    item: string;
+    count: number;
+    /** Seconds until the next one arrives */
+    restock: number;
+}
+/** @beta */
+export type MoveStatus = 'idle' | 'moving' | 'arrived' | 'failed';
+/** @beta */
+export interface MovementState {
+    speed: number;
+    /** The fastest it goes for now, whatever its speed: a group's slowest, as it moves together (`OrderParams.together`) */
+    cap?: number;
+    status: MoveStatus;
+    goal: Vec2;
+    /** When set the goal follows this entity */
+    goalEntity: EntityId;
+    /** Arrive once this close to the goal (edge distance for entity goals) */
+    range: number;
+    groupId: number;
+    /** Last destination handed to the navigation */
+    navGoal: Vec2;
+    navVersion: number;
+    /** Corner of the path the unit is heading for. Progress is measured towards it, so a long way round is not mistaken for standing still */
+    corner: Vec2;
+    /** Closest the unit has been to its corner, used to detect that it stopped making progress */
+    bestDistance: number;
+    stalledTime: number;
+    /**
+     * Seconds it has gone well under its speed on its way, held up by others (not counting getting going, or slowing
+     * to arrive): what has those in its way asked to step aside (see `GameRules.movement.lookAhead`)
+     */
+    slowTime?: number;
+    /**
+     * The point it goes round standing units by, on its way to the next corner of its path, when that is not much
+     * longer (`GameRules.movement.goesAround`, the `detour` hook): none while it goes straight
+     */
+    detour?: Vec2;
+    /** Where it heads on from `detour`: the corner of its path it went round the knot towards */
+    detourAim?: Vec2;
+    /** On a step aside for another (`MoveOptions.aside`): it goes round nobody and asks nobody to make way */
+    aside?: boolean;
+    /** Whether it was sent on past `detour`, towards its path, as it neared it */
+    detourPast?: boolean;
+    /** Whether the last move failed by getting stuck on the way (in a crowd, say), not for there being no way there */
+    stuck?: boolean;
+    anchored: boolean;
+    ghost: boolean;
+    /** Direction the unit turns to while it stands still. Null when it may face wherever it ended up */
+    finalFacing: number | null;
+    /**
+     * The route its side planned to the goal, corner by corner, with what the side knows (`GameModule.paths: 'seen'`):
+     * walked a stretch at a time. None where routes know everything, or there is no route
+     */
+    route?: Vec2[];
+    /** The corner of `route` it heads past next */
+    routeAt?: number;
+    /** What its side knew when the route was planned (`SidePaths.version`): it is planned again once that changes */
+    routeVersion?: number;
+    /** Where along `route` the navigation was last sent it: a stretch no longer than it can see */
+    stretch?: Vec2;
+}
+/**
+ * What moves of an entity: where it goes, how fast, how it is doing (`MovementState`). Units that walk, swim or fly
+ * have it from their type's speed; a building, a tree, or a unit an upgrade stopped has none. Filed (`index`), for the
+ * movement system to go through
+ *
+ * @beta
+ */
+export declare const moving: Component<MovementState, MovementState>;
+/** @beta */
+export interface CombatState {
+    /** Seconds until the next attack may start */
+    cooldown: number;
+    /** Seconds until the running swing lands. 0 when not swinging */
+    swing: number;
+    swingTarget: EntityId;
+    /**
+     * Which of its attacks the running swing, or the last, is of, by place (`UnitTypeDef.attacks`): the first when left
+     * out, as for every unit with one. It swings one at a time, and waits out the cooldown of the one that hit
+     */
+    weapon?: number;
+    /** Target picked by the unit itself rather than by an order */
+    autoTarget: EntityId;
+    lastAttacker: EntityId;
+    /** Where an idle unit returns to after chasing */
+    guard: Vec2 | null;
+    /** Does not pick fights of its own accord until it gets an order (set by a game's rules; `stop` no longer sets it) */
+    passive: boolean;
+    /** What it is fighting or closing in on, whoever picked it: 0 for nothing (see `engagement.ts`) */
+    engaged?: EntityId;
+    /** The spot it holds around that, as an angle seen from it. Null when it has none: it flies, it hits a building */
+    slot?: number | null;
+    /** Targets it left alone because it could not get at them, and until when, in world time */
+    shunned?: [EntityId, number][];
+}
+/**
+ * How an entity fights (`CombatState`): its cooldown, its swing, what it is engaged with. What attacks has it from its
+ * type's attack; an upgrade that takes the attack away takes it. Filed (`index`), for the combat system to go through
+ *
+ * @beta
+ */
+export declare const fighting: Component<CombatState, CombatState>;
+/** @beta */
+export interface HarvesterState {
+    carrying: number;
+    /** What it is that the worker carries, or last gathered. Null for one that has not gathered anything yet */
+    kind: ResourceKind | null;
+    /** Last resource this worker gathered from */
+    resource: EntityId;
+}
+/** @beta */
+export interface ResourceState {
+    amount: number;
+    occupants: number;
+    /** The building that stands on it (`UnitTypeDef.builtOn`), by id: none when nothing does */
+    under?: EntityId;
+}
+/**
+ * What is left of what can be gathered from an entity, and who is at it (`ResourceState`): a mine's gold, a tree's
+ * lumber. What its type gives (`UnitTypeDef.resource`) as it is made. Filed (`index`), for what looks for the nearest
+ *
+ * @beta
+ */
+export declare const deposit: Component<ResourceState, ResourceState>;
+/** @beta */
+export interface ConstructionState {
+    /** 0..1 */
+    progress: number;
+    buildTime: number;
+    /** Builders that worked on it during the current tick */
+    builders: number;
+    /** What was paid for it, when that is not what its type costs. A cancelled site gives part of this back */
+    paid?: Cost;
+}
+/** @beta */
+export interface ProductionItem {
+    kind: 'unit' | 'upgrade' | 'revive' | 'morph';
+    /** Unit type, upgrade id, the id of the hero to bring back, or the type the building turns into */
+    id: string;
+    /** What was paid, when that does not follow from the id */
+    paid?: Cost;
+    /** Seconds of work done */
+    progress: number;
+    duration: number;
+}
+/**
+ * Seconds an entity stays in sight of other teams, by team, for having attacked them: seen where it stands, in the fog
+ * and in a bush. Filed (`index`), for the fog to light those that have it
+ *
+ * @beta
+ */
+export declare const exposure: Component<Map<number, number>, Map<number, number>>;
+/**
+ * Seconds the teams that found an invisible entity with something that reveals it can go on seeing it, by team. Filed
+ * (`index`), for the fog to light those that have it
+ *
+ * @beta
+ */
+export declare const detection: Component<Map<number, number>, Map<number, number>>;
+/**
+ * A rush to a spot: nothing stops it, and what it does happens where it ends
+ *
+ * @beta
+ */
+export interface Dash {
+    x: number;
+    z: number;
+    /** Where it started */
+    from: Vec2;
+    /** Units per second */
+    speed: number;
+    ability: string;
+    level: number;
+    effects: EffectDef[];
+    /** How high it rises on the way: a leap, over whatever is in between */
+    height?: number;
+    /** A buff it carries for as long as the rush lasts */
+    buff?: string;
+}
+/** @beta */
+export interface RallyPoint {
+    point: Vec2;
+    target: EntityId;
+}
+/** @beta */
+export interface ProductionState {
+    queue: ProductionItem[];
+    rally: RallyPoint | null;
+}
+/**
+ * Anything in the world: a unit, a building, a tree.
+ *
+ * Fields marked `readonly` are kept in step with things elsewhere (the navigation, the spatial index, the lookups
+ * of the world), so they are changed through the world's functions only: `World.setOwner`, `World.setHidden`,
+ * `World.setLifetime`, `World.place`, `startDash`, `morph` (each through the entity's own internal writes: `moveTo`,
+ * `retype`, `changeOwner`…). The rest, like health, mana or cooldowns, a game
+ * module may change as it likes: nothing is worked out from them that would not notice.
+ *
+ * @beta
+ */
+export declare class Entity {
+    readonly id: EntityId;
+    /** Changes when a building is upgraded into another type */
+    readonly def: UnitTypeDef;
+    readonly owner: PlayerId;
+    readonly alive: boolean;
+    /** Hidden entities are inside something (a gold mine) and do not take part in the world */
+    readonly hidden: boolean;
+    /**
+     * Only stands there, like a tree: left out of the systems that run every tick, see `isScenery`.
+     * Becomes false for good once something gives it anything to do (`World.wake`)
+     */
+    readonly scenery: boolean;
+    readonly pos: Readonly<Vec2>;
+    readonly prevPos: Vec2;
+    facing: number;
+    prevFacing: number;
+    /** How big it is drawn, for the look of a map. Nothing in the rules goes by it */
+    scale: number;
+    /** Which of the models of its type it is drawn with, for the look of a map. Nothing in the rules goes by it either */
+    look?: string;
+    /** Velocity of the last tick */
+    readonly velocity: Vec2;
+    hp: number;
+    /** Teams that have seen this entity at least once, one bit per team as `FogOfWar.teamBit` hands them out. Ask `World.hasSeen` */
+    seenBy: number;
+    /** When it was last hurt, in seconds of the game. Long ago for what never was */
+    hurtAt: number;
+    /** Seconds until it is gone by itself, for what does not last */
+    readonly expires: number | null;
+    /** Seconds it was given to last, for what does not */
+    lifetime: number;
+    /** Seconds until enemies cannot see it any more, for what is invisible. 0 once they cannot */
+    unseenIn: number | null;
+    /**
+     * What it was told to do, the first what it does now and the rest in turn: read here, given and ended through the
+     * orders' functions (`giveOrder`, `clearOrders`, `completeOrder`), which write it with the entity's own `addOrder`,
+     * `keepOrders` and `removeOrder`
+     */
+    readonly orders: readonly Order[];
+    /** Invisible to enemies right now, unless they have found it */
+    get unseen(): boolean;
+    maxHp: number;
+    mana: number;
+    maxMana: number;
+    /** Does nothing by itself until something wakes it, and is drawn sleeping: creeps at night */
+    asleep: boolean;
+    /** A fallen hero that is on its way back */
+    reviving: boolean;
+    /**
+     * What it can cast, with their levels and cooldowns: each state is the game's to change (`cooldown`, `autocast`),
+     * the list the engine's (a type's own, what a hero learns), written with the entity's own internal methods
+     */
+    readonly abilities: readonly AbilityState[];
+    /** What is on it: each instance the game's to change, the list put on and taken off by `applyBuff`, `removeBuff` */
+    readonly buffs: readonly BuffInstance[];
+    /** The resource it stands on (`UnitTypeDef.builtOn`), by id: none for what stands on the ground */
+    on?: EntityId;
+    /** Min corner of the footprint in grid cells, for buildings and resources */
+    cell?: {
+        x: number;
+        z: number;
+    };
+    /** Bookkeeping of the spatial index: the last query that found it. Not game state */
+    spatialStamp: number;
+    /** Stats as last worked out, see `statsOf`. Derived from the rest, never saved or sent */
+    statsCache: StatsCache | null;
+    /** The index of the world it is in, told when it gets or loses a component. Not game state */
+    index: {
+        componentChanged(entity: Entity, id: string, has: boolean): void;
+    } | null;
+    constructor(id: EntityId, 
+    /** Changes when a building is upgraded into another type */
+    def: UnitTypeDef, owner: PlayerId, position: Vec2);
+    /** A component of a game module or a mod, see `defineComponent` */
+    get<T>(key: Component<T, unknown>): T | undefined;
+    has(key: Component<unknown>): boolean;
+    /** Gives it the component, or a new value of it. `undefined` takes it away (`remove`) */
+    set<T>(key: Component<T, unknown>, value: T): void;
+    remove(key: Component<unknown>): void;
+    /** Its components, in the order it was given them: each one's value is `get(component)` */
+    heldComponents(): readonly Component<unknown, unknown>[];
+    /**
+     * Its components' values by id, in the order it was given them: made each time it is asked, for what reads them
+     * by id now and then (a save, the inspector). What does it often goes through `heldComponents`
+     */
+    get components(): Readonly<Record<string, unknown>>;
+    get isBuilding(): boolean;
+    get isUnit(): boolean;
+    get isResource(): boolean;
+    /** Up in the air, where the ground and what stands on it are not in the way */
+    get flying(): boolean;
+    get isStructure(): boolean;
+    /** Completed and able to do its job */
+    get operational(): boolean;
+    get currentOrder(): Order | undefined;
+    /** Ground area covered by a structure */
+    get rect(): Rect;
+}
+/**
+ * Anything with a place and a size: an entity, or what a client knows of one
+ *
+ * @beta
+ */
+export interface Placed {
+    pos: Vec2;
+    def: UnitTypeDef;
+}
+/**
+ * Distance from a point to the edge of an entity
+ *
+ * @beta
+ */
+export declare function distanceToEdge(point: Vec2, target: Placed): number;
+/**
+ * Distance between the edges of two entities
+ *
+ * @beta
+ */
+export declare function edgeDistance(a: Placed, b: Placed): number;

package/dist/entityIndex.d.ts

@@ -0,0 +1,50 @@
+import type { Component } from './components';
+import type { Entity, PlayerId } from './entity';
+/**
+ * Entities filed by what they are asked for by: whose they are, which have a component (and, for a component that
+ * asks, whose they are too: `Component.index`). Answers questions like "the heroes of player 2"
+ * or "every shop" without going through every entity of the world, most of which are trees. Kept up to date by the
+ * world as entities come and go, and by the entities as they get or lose a component.
+ *
+ * Every set keeps entities in the order of their ids, the order they came into the world and the one a walk through
+ * `World.entities` gives, however and whenever each was filed: one that changed owner or type, or was given a component
+ * late, takes its place among the others, as it has in a world loaded from a save. Code that picks the first of equals
+ * gets the same one either way. A set an entity is filed into out of its place is made again: a walk through it under
+ * way goes on through the one it had
+ */
+export declare class EntityIndex {
+    private readonly componentOf;
+    /** `componentOf`: a component of the world's game by its id, an error for one it does not list (`registry.used`) */
+    constructor(componentOf: (id: string) => Component<unknown, unknown> | undefined);
+    private readonly owned;
+    private readonly components;
+    /** By component id, then by owner: for the components that ask (`index: 'owner'`) */
+    private readonly byOwner;
+    /** By component id, what has it in the order of the entities' ids (`ordered`): made again once it changes */
+    private readonly inOrder;
+    /** Everything the player owns, dead heroes waiting to be brought back included */
+    ownedBy(player: PlayerId): ReadonlySet<Entity>;
+    /**
+     * Everything that has the component; with a player, what the player owns of it, for a component filed by owner
+     * (`Component.index: 'owner'`; throws for one that is not)
+     */
+    with(key: Component<unknown, unknown>, owner?: PlayerId): ReadonlySet<Entity>;
+    /**
+     * Everything that has the component, in the order of the entities' ids: the order a walk through `World.actors`
+     * meets them in. What a system that runs over a component goes through (`System.over`), so a game plays the same
+     * as one that looks at every actor. A list of its own, kept until what has the component changes: what is given it
+     * or loses it while the list is gone through is in the next one
+     */
+    ordered(key: Component<unknown, unknown>): readonly Entity[];
+    add(entity: Entity): void;
+    remove(entity: Entity): void;
+    /** An entity in the index was given a component, or had it taken away. Told by the entity */
+    /** Whether the component with this id asks to be filed by owner */
+    private byOwnerOf;
+    componentChanged(entity: Entity, id: string, has: boolean): void;
+    private fileComponent;
+    private dropComponent;
+    /** Throws when the index does not say what the entities are. See `debugChecks` */
+    check(entities: Iterable<Entity>): void;
+    clear(): void;
+}

package/dist/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * What becomes of a part of a game that throws: a hook's handler, a listener, a system, a timer, a unit's order, a
+ * player's command. The game says (`GameModule.onError`), or whoever runs it (a server, a page); a world that is told
+ * nothing throws, as it always did, so that a test sees every error.
+ */
+import type { EntityId, PlayerId } from './entity';
+import type { World } from './world';
+/**
+ * - `throw`: the error goes on to whoever stepped the world. Nothing is hidden: for tests and development
+ * - `end`: the game ends there, with the reason kept (`world.failure`) and told to the players. The world is not
+ *   stepped again. What a server and a launched game do when nothing is said: one game ends, and nothing else does
+ * - `disable`: the part that threw is switched off and the game goes on without it: the handler, the listener, the
+ *   system or the timer no longer runs; the order is taken off its unit, the command refused. Never done unasked: a
+ *   rule that is quietly gone is a game that goes quietly wrong
+ *
+ * @beta
+ */
+export type ErrorAnswer = 'throw' | 'end' | 'disable';
+/**
+ * The part of the game that threw
+ *
+ * @beta
+ */
+export interface ErrorSite {
+    kind: 'hook' | 'listener' | 'system' | 'timer' | 'order' | 'command';
+    /** Its id: the handler's, the listener's, the system's name, the timer's, the order's or the command's type */
+    id: string;
+    /** The hook a handler is on */
+    hook?: string;
+    /** The unit whose order it was */
+    entity?: EntityId;
+    /** The player whose command it was */
+    player?: PlayerId;
+    /** The mod that added the part or changed it last, for a game with mods (`composeGame`) */
+    mod?: string;
+}
+/**
+ * What to do about an error: the same for all of them, or decided for each
+ *
+ * @beta
+ */
+export type ErrorPolicy = ErrorAnswer | ((error: unknown, where: ErrorSite, world: World) => ErrorAnswer);
+/**
+ * Why a game ended on an error (`world.failure`): plain data, for a log, a save's notes, a player's screen
+ *
+ * @beta
+ */
+export interface WorldFailure {
+    /** What is said to whoever played: no more than that it stopped, and in what */
+    message: string;
+    where: ErrorSite;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    tick: number;
+}
+/** Thrown to leave the tick a game ends in (`end`): caught by `World.step`, and never seen outside it */
+export declare class GameEnded extends Error {
+    readonly failure: WorldFailure;
+    constructor(failure: WorldFailure);
+}
+/**
+ * Why a command was turned away (`commandRejected`): a type the game has not got, fields not as its definition says, a
+ * player not in the game, a unit not theirs, one there is not, more than a tick takes, or a director's command sent
+ * with no cinematic playing on the sender's screen (`withDirector`)
+ *
+ * @beta
+ */
+export type RejectedKind = 'unknownType' | 'badFields' | 'noSuchPlayer' | 'notTheirs' | 'noSuchUnit' | 'tooMany' | 'notDirecting';
+/** What a part switched off is kept as (`world.disabled`, a save): its kind, id, hook and mod, nothing of the moment it threw */
+export declare const siteOf: (where: ErrorSite) => ErrorSite;
+/**
+ * A part in words: `the handler "thorns" of the hook "damage"`
+ *
+ * @beta
+ */
+export declare function siteWords(where: ErrorSite): string;
+/** Kept by `composeGame` for the game it makes: who changed what, to say whose a part that throws is */
+export declare function notePartOwners(game: object, owners: ReadonlyMap<string, string>): void;
+/** The parts' owners as noted for a game: none for one without mods */
+export declare const partOwners: (game: object) => ReadonlyMap<string, string>;
+/** The mod a part is of, when a mod added it or changed it: nothing for a part of the game itself */
+export declare const modOfPart: (game: object | null | undefined, where: ErrorSite) => string | undefined;

package/dist/events.d.ts

@@ -0,0 +1,97 @@
+import type { SessionView } from './replication';
+import type { World } from './world';
+type Handler<T> = (payload: T) => void;
+/**
+ * Who of the players gets an event of a game's own on their screen (see `defineEvent`): everyone, or those a
+ * function picks, from what the event says and what the seat may know (`SessionView`: its player, `knows`, `sees`)
+ *
+ * @beta
+ */
+export type EventAudience<T> = 'everyone' | ((payload: T, view: SessionView) => boolean);
+/**
+ * A typed key for an event of a game's own, made with `defineEvent`
+ *
+ * @beta
+ */
+export interface EventKey<T> {
+    readonly id: string;
+    /** Sent to the screens of these players, in their snapshots. Only to whoever listens in the world when left out */
+    readonly replicate?: EventAudience<T>;
+    /** Only there for the type of the payload */
+    readonly payload?: T;
+}
+/**
+ * An event of a game's own: `const through = defineEvent<{ unit: string }>('td.invaderThrough', { replicate: 'everyone' })`.
+ * Emitted on `world.events` like the engine's (`world.events.emit(through, { unit })`), held to the end of the tick
+ * like them, and listened to with `defineListener`. Ids are shared by every game: give them a prefix of the game's.
+ *
+ * A replicated event goes to the players' screens, where `GameView.on` and the renderers get it: what it says has
+ * to be plain data then (numbers, text, lists, plain objects), with entities by id, as it may cross a network
+ *
+ * @beta
+ */
+export declare function defineEvent<T>(id: string, options?: {
+    replicate?: EventAudience<T>;
+}): EventKey<T>;
+/** Whether an event is one of a game's own, rather than one of the engine's */
+export declare const isGameEvent: (id: PropertyKey) => boolean;
+/**
+ * How a game reacts to an event: the engine's (`'entityDied'`, `'enteredArea'`) or one of its own. Listeners are
+ * given in `GameModule.listeners`, and the world subscribes them when it is made, in their order: a new game, a
+ * loaded save and every player's machine get the same ones. They run at the end of the tick, once everything in it
+ * is settled, and may change the world: what happens then is part of that tick. One with the id of another takes
+ * its place, in a mod
+ *
+ * @beta
+ */
+export interface ListenerDef {
+    id: string;
+    event: EventKey<any>;
+    run(world: World, payload: any): void;
+}
+/**
+ * Typed help for writing a listener: `defineListener({ event: enteredArea, id: 'td.gate', run(world, { area, entity }) { ... } })`
+ *
+ * @beta
+ */
+export declare function defineListener<T>(def: {
+    id: string;
+    event: EventKey<T>;
+    run(world: World, payload: T): void;
+}): ListenerDef;
+/**
+ * Minimal typed event emitter: each event by its key (`EventKey`), which types what it says.
+ *
+ * While held (`hold`), what is emitted waits in a queue and goes out on `release`, in the order it happened.
+ * The world holds its events for the length of a tick, so that whoever listens sees how things stand once
+ * the tick is over, and cannot change anything halfway through it.
+ */
+export declare class Emitter {
+    private handlers;
+    private held;
+    private queue;
+    /** True while what was held back goes out (`release`) */
+    releasing: boolean;
+    private readonly taps;
+    private readonly watchers;
+    /**
+     * Calls back for every event as it goes out, before whoever listens to it: the event log of the debug tools, a
+     * logger. Any number of them. Returns what stops it
+     */
+    tap(listener: (type: PropertyKey, payload: unknown) => void): () => void;
+    /**
+     * Calls back for every event as it goes out, whatever it is, after whoever listens to it by name: for what cannot
+     * know ahead which events there will be, as a player's seat that passes on a game's own. Returns what stops it
+     */
+    watch(watcher: (type: PropertyKey, payload: unknown) => void): () => void;
+    /** Listens to an event, the engine's (`engineEvents.ts`) or a game's own. Returns what stops it */
+    on<T>(key: EventKey<T>, handler: Handler<T>): () => void;
+    emit<T>(key: EventKey<T>, payload: T): void;
+    /** Holds back what is emitted from now on, until `release` */
+    hold(): void;
+    /** Sends out everything held back, and stops holding */
+    release(): void;
+    private deliver;
+    clear(): void;
+}
+export {};