DOM ENGINEV0.27.0FIZLET
Start

TRACK V0.27.0 ALPHA

@fzlt/core/track

Board paths for roll-and-move games. Spaces along a closed loop or an open path, straight between the points you give or on a smooth curve through them, in board coordinates [x, z] (diorama's floor plane; y is up). Jumps (chutes, ladders, shortcuts) take a token from one space to another; several tokens on one space spread around it, then stack upward. - move(token, steps) works out the whole move at once: the hops (a step per space, then any jumps), with a flag on each for passing the start ("go"), bouncing back, the finish and the landing; an open path ends by stopping at the end, needing the exact count, or bouncing back. - The hops are data with times: sample(t, out) gives the moving token's [x, y, z] (an arc per step, a slide or climb for a jump), apply(ob, t) writes it into a diorama object's pos. - Events, if you pass an event ring (engine.events), as move works the move out: track:pass, track:jump, track:finish, track:land and track:stay (an exact finish overshot), each with the token and the space. No randomness (the dice decide) and no allocation per move or sample (typed arrays, fixed capacity). Lengths use steer's exact hypot (the builtin boxes its arguments).

@fzlt/core/track · GZIP2,055 B2.0 KB of a 2.1 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, for the Tabletop roll-and-move games; its API may still change before a game ships on it.

SINCE
v0.22.0
SHIPPED IN
no released game or page yet
MODULES · hosted on this site
import { HOP, track } from "https://fizlet.com/dist/track.js";
NPM · @fzlt/core
npm install @fzlt/core
import { HOP, track } from "@fzlt/core/track";
IN SHORT
const t = track({ points: corners, closed: true, smooth: true, spaces: 40, jumps: [[4, 14], [31, 9]], events: e.events });
t.place(0, 0);
t.move(0, dc.total); // steps, then a ladder or chute; track:pass, track:land on the ring
t.apply(token, time); // each frame: an arc per step, a slide per jump, side by side on a shared space

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.

TrackEvents interface ALPHA

Something that takes events: an engine's ring (engine.events).

export interface TrackEvents {
    emit(type: string, a?: number, b?: number): unknown;
}

TrackFinish type ALPHA

How an open path ends when a move would go past the last space.

export type TrackFinish = "stop" | "exact" | "bounce";

TrackOptions interface ALPHA

Options for track(): the path, its spaces, jumps, sharing, the end rule and the hop's look.

export interface TrackOptions {
    /** The path's points, [x0, z0, x1, z1, …], in board units. */
    points: ArrayLike<number>;
    /** A loop: the last space leads to the first (default false: an open path, start to finish). */
    closed?: boolean;
    /** Lay this many spaces at even distances along the path (default: one space per point). */
    spaces?: number;
    /** A smooth curve through the points (Catmull-Rom) instead of straight lines; needs `spaces`. */
    smooth?: boolean;
    /** Jumps as [from, to] space pairs: a ladder up, a chute down, a shortcut. */
    jumps?: ArrayLike<ArrayLike<number>>;
    /** Tokens side by side on a space before the next ones stack on top (one number, or one per space; default 4). */
    cap?: number | ArrayLike<number>;
    /** How far apart tokens that share a space stand from its centre (default 0.3). */
    spacing?: number;
    /** The height of one stacked level (default 0.3). */
    level?: number;
    /** The most tokens (default 8). */
    tokens?: number;
    /** An open path's end: "stop" at the last space (default), "exact" (a move past it does not move)
     *  or "bounce" (count back from it). */
    finish?: TrackFinish;
    /** The space a token passes on a loop to "pass go" (default 0). */
    start?: number;
    /** The arc's height over a step (default 0.6). */
    hop?: number;
    /** Seconds per step (default 0.22). */
    hopTime?: number;
    /** Board units per second along a jump (default 6; at least 1.5 steps long). */
    jumpSpeed?: number;
    /** The most hops in one move (default 64). */
    maxHops?: number;
    /** An event ring for `track:pass`, `track:jump`, `track:finish`, `track:land`. */
    events?: TrackEvents;
}

HOP const ALPHA

Hop kinds and flags (hops.kind, hops.flag).

Type
{ /** A step to the next (or previous) space. */ readonly step: 0; /** A jump from a space to its target. */ readonly jump: 1; /** Flag: this hop enters the start space going forward on a loop (pass go). */ readonly pass: 1; /** Flag: a step backward after the end (bounce). */ readonly back: 2; /** Flag: the move ends on the last space of an open path. */ readonly finish: 4; /** Flag: the last hop of the move. */ readonly land: 8; }
export declare const HOP: {
    /** A step to the next (or previous) space. */
    readonly step: 0;
    /** A jump from a space to its target. */
    readonly jump: 1;
    /** Flag: this hop enters the start space going forward on a loop (pass go). */
    readonly pass: 1;
    /** Flag: a step backward after the end (bounce). */
    readonly back: 2;
    /** Flag: the move ends on the last space of an open path. */
    readonly finish: 4;
    /** Flag: the last hop of the move. */
    readonly land: 8;
};

track function ALPHA

A board path on o.points: place tokens, move them, then sample the hops over time.

track(o: TrackOptions): Track
Returns
Track
Declaration
export declare function track(o: TrackOptions): {
    /** Spaces. */
    n: number;
    closed: boolean;
    /** Space centres. */
    x: Float64Array<ArrayBuffer>;
    z: Float64Array<ArrayBuffer>;
    /** Each space's heading: diorama's rot[1] that turns +x along the path. */
    a: Float64Array<ArrayBuffer>;
    /** Each space's jump target, or −1. */
    jump: Int32Array<ArrayBuffer>;
    /** Each token's space, or −1 off the board. */
    at: Int32Array<ArrayBuffer>;
    /** The last move's hops (`HOP` kinds and flags; `A`, `B`: each hop's ends, [x, y, z] × n). */
    hops: {
        /** Hops in the last move. */
        n: number;
        kind: Uint8Array<ArrayBuffer>;
        flag: Uint8Array<ArrayBuffer>;
        from: Int32Array<ArrayBuffer>;
        to: Int32Array<ArrayBuffer>;
        t0: Float64Array<ArrayBuffer>;
        t1: Float64Array<ArrayBuffer>;
        A: Float64Array<ArrayBuffer>;
        B: Float64Array<ArrayBuffer>;
    };
    /** The token the last move moved, or −1. */
    readonly token: number;
    /** Seconds the last move takes. */
    duration: number;
    /** Put token k on space s (−1 takes it off), with no hops. */
    place(k: number, s: number): void;
    /** Tokens on space s. */
    count(s: number): number;
    /** Move token k by `steps` (negative: back) and any jumps where it lands. Fills `hops` and
     *  returns its count (0: it did not move, e.g. an exact finish it overshot). */
    move(k: number, steps: number): number;
    slot: (k: number, out: {
        [i: number]: number;
    }, s?: number) => {
        [i: number]: number;
    };
    spot: (s: number, r: number, m: number, out: {
        [i: number]: number;
    }) => {
        [i: number]: number;
    };
    /** Where the moving token is at t seconds into the last move: out = [x, y, z] (y over the board's
     *  top). False once the move is over (out is then its landing place). */
    sample(t: number, out: {
        [i: number]: number;
    }): boolean;
    /** Write `sample(t)` into a diorama object's `pos` (plus `y0` up); true while it moves. */
    apply(ob: {
        pos: {
            [i: number]: number;
        };
    }, t: number, y0?: number): boolean;
};

Track type ALPHA

What track returns.

export type Track = ReturnType<typeof track>;