TrackEvents interface ALPHA
Something that takes events: an engine's ring (engine.events).
export interface TrackEvents {
emit(type: string, a?: number, b?: number): unknown;
}
TRACK V0.27.0 ALPHA
@fzlt/core/trackBoard 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).
Measured on this build: minified and gzipped with everything it imports, the way npm run size checks the budget in CI.
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.
import { HOP, track } from "https://fizlet.com/dist/track.js";npm install @fzlt/core
import { HOP, track } from "@fzlt/core/track";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 spaceEvery 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 ALPHASomething that takes events: an engine's ring (engine.events).
export interface TrackEvents {
emit(type: string, a?: number, b?: number): unknown;
}
TrackFinish type ALPHAHow an open path ends when a move would go past the last space.
export type TrackFinish = "stop" | "exact" | "bounce";
TrackOptions interface ALPHAOptions 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 ALPHAHop kinds and flags (hops.kind, hops.flag).
{ /** 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 ALPHAA board path on o.points: place tokens, move them, then sample the hops over time.
track(o: TrackOptions): Track
Trackexport 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 ALPHAWhat track returns.
export type Track = ReturnType<typeof track>;