DOM ENGINEV0.27.0FIZLET
Start

ACTOR V0.27.0 ALPHA

@fzlt/core/actor

Units, bots, turrets and shots as data. One fixed-capacity table of typed arrays, one row per actor: alive, side, kind, tag bits, health (hp of max) and a body (x, y, heading a, velocity vx, vy, radius r). Nothing allocates after actors(): spawn takes a free row, kill marks it dead, and sweep() (once per step, after your loops) gives dead rows back. A game's own fields are its own typed arrays of length cap, indexed by row (cooldowns, orders, timers). Iterate the dense list, which keeps spawn order, so a seeded run replays: for (let k = 0; k < A.n; k++) { const i = A.list[k]!; if (!A.alive[i]) continue; ... } A row is reused once swept, so hold on to an actor across steps by its handle (ref(i)), not its row: get(handle) is -1 once that actor is gone, even if its row lives again. Share the body with @fzlt/core/steer by passing its arrays (actors({ cap, x: m.x, y: m.y, a: m.a })). With events (engine.events) it rings actor:spawn, actor:hurt and actor:kill (a: row, b: side, x, y: where, in whole pixels, v: damage, or health on spawn) for sound, effects and the HUD. Whole pixels because small integers never box: a double passed to the ring can cost a heap number.

@fzlt/core/actor · GZIP908 B0.9 KB of a 1.2 KB budget

Measured on this build: minified and gzipped with everything it imports, the way npm run size checks the budget in CI.

STATUS · what the flags meanALPHA

In the package to try; no promise yet. New (E11): no game moves its units on it yet; DOM Battlefield is first in line (src/ACTORS.md).

SINCE
v0.28.0
SHIPPED IN
no released game or page yet
MODULES · hosted on this site
import { actors } from "https://fizlet.com/dist/actor.js";
NPM · @fzlt/core
npm install @fzlt/core
import { actors } from "@fzlt/core/actor";
IN SHORT
const A = actors({ cap: 64, sides: 2, events: e.events });
const i = A.spawn(0, 5); A.x[i] = 120; A.y[i] = 80; // side 0, 5 hp
const foe = A.nearest(i, 300, 1 << 1);  // closest side-1 actor in range
if (foe >= 0 && A.hurt(foe, 1)) score++; // true: that killed it
A.sweep(); // once per step: dead rows come back

API

Every export with its signature, parameters, return type, doc comment and status flag, generated at build time from the published type declarations of v0.27.0 by the TypeScript compiler. For AI agents: the whole API as plain text.

ActorOptions interface ALPHA

Options for actors(): capacity, sides, optional shared body arrays and the event ring.

export interface ActorOptions {
    /** Rows (fixed: the arrays never grow; spawn returns -1 when full). */
    cap: number;
    /** Sides counted by `count(side)` (default 8, at most 32: `nearest` takes them as bits). */
    sides?: number;
    /** Bring your own body arrays (length ≥ cap), e.g. a steer's, so both move the same numbers. */
    x?: Float64Array;
    y?: Float64Array;
    a?: Float64Array;
    /** engine.events: actor:spawn, actor:hurt, actor:kill. */
    events?: EventRing;
}

actors function ALPHA

A fixed-capacity actor table: typed-array rows with spawn, kill, hurt, heal, sweep, handles, side counts, tags and nearest.

actors(o: ActorOptions): Actors
Returns
Actors
Declaration
export declare function actors(o: ActorOptions): {
    cap: number;
    x: Float64Array<ArrayBufferLike>;
    y: Float64Array<ArrayBufferLike>;
    a: Float64Array<ArrayBufferLike>;
    vx: Float64Array<ArrayBuffer>;
    vy: Float64Array<ArrayBuffer>;
    r: Float64Array<ArrayBuffer>;
    hp: Float64Array<ArrayBuffer>;
    max: Float64Array<ArrayBuffer>;
    alive: Uint8Array<ArrayBuffer>;
    side: Uint8Array<ArrayBuffer>;
    kind: Uint8Array<ArrayBuffer>;
    tags: Uint32Array<ArrayBuffer>;
    gen: Uint32Array<ArrayBuffer>;
    /** The dense list: rows list[0..n), in spawn order (dead ones stay until `sweep()`). */
    list: Int32Array<ArrayBuffer>;
    readonly n: number;
    /** Actors alive right now. */
    readonly live: number;
    /** A new actor on `side` with `health` (its max too); its body is zeroed. -1 when full. */
    spawn(s: number, health: number, k?: number, t?: number): number;
    /** Dead now (alive = 0, out of `count`); its row comes back at `sweep()`. False if already dead. */
    kill: (i: number) => boolean;
    /** Take `damage`; true when that killed it. */
    hurt(i: number, damage: number): boolean;
    /** Back up by `amount`, never over max. */
    heal(i: number, amount: number): void;
    /** Give dead rows back (keeps the list's order). Once per step, after the loops that kill. */
    sweep(): void;
    /** Live actors on side s. */
    count(s: number): number;
    /** A handle that outlives the row: `get(ref(i))` is i while that actor lives, -1 after. */
    ref(i: number): number;
    get(h: number): number;
    /** Every bit of `bits` set? / set or clear them. */
    has(i: number, bits: number): boolean;
    tag(i: number, bits: number, on?: boolean): void;
    /** The nearest live actor to i (not i) within `range`, on a side in the `sides` bits (1 << side)
     *  and carrying every `need` tag bit; -1 if none. Ties go to the earlier spawn. */
    nearest(i: number, range?: number, sides?: number, need?: number): number;
    /** Everything dead and every row free (a new match). Handles from before stay stale. */
    clear: () => void;
};

Actors type ALPHA

The table actors() returns.

export type Actors = ReturnType<typeof actors>;