@aethervtt/shard-dice 0.0.0-stage → 0.2.0

package/dist/table.d.ts

@@ -0,0 +1,227 @@
+import { type AssetRef, type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import { type TrackClient, type TrackWorkerLike } from '@aethervtt/shard-physics/worker';
+import type { DieKind } from './builtins.js';
+import { type DiceEffectRecipeValue } from './effects.js';
+import { type FaceLayoutValue } from './layout.js';
+import { DiceResources } from './resources.js';
+import { type DiceRoll } from './roll.js';
+import { type DiceTray } from './settle.js';
+import { DiceSoundBank } from './sound.js';
+export type DicePhase = 'idle' | 'simulating' | 'tumble' | 'entrance' | 'accent' | 'rest';
+export type DiceOutcome = 'finished' | 'dismissed' | 'cancelled' | 'failed';
+export interface DicePlayOptions {
+    /** Aborting it, in any phase, cancels the roll: `'cancelled'`. */
+    signal?: AbortSignal;
+    /** Dismiss a roll that's playing instead of rejecting with `dice/busy`. */
+    replace?: boolean;
+}
+export interface DiceTableOptions {
+    restMs: number;
+    maxDice: number;
+    /** Wall clock, ms: rests and releases run on it (tests pass their own). */
+    now: () => number;
+    kinds: Readonly<Record<DieKind, readonly string[]>>;
+    worker: (() => TrackWorkerLike) | 'inline';
+    /** The dice camera's vertical field of view, degrees. */
+    fovY: number;
+    /** How long a roll waits for an entrance's assets and warm-up past the physics (0065). */
+    entranceWaitMs: number;
+}
+/** The frame demand a presentation holds while it moves. */
+export declare const PRESENTATION_DEMAND = "dice/presentation";
+/** Held while dice of an animated family (at the display's rate) are shown. */
+export declare const ANIMATED_DEMAND = "dice/animated";
+/** Held while an entrance's scene is alive (0065). */
+export declare const ENTRANCE_DEMAND = "dice/entrance";
+/** How long a roll waits for an entrance's assets past the physics being ready, by default. */
+export declare const ENTRANCE_WAIT_MS = 1500;
+/** A fixed tray and seed for skin pickers. */
+export declare const PREVIEW_TRAY: DiceTray;
+export declare class DiceTableState {
+    /** The last failure's error (`'failed'` outcomes). */
+    lastError: ShardError | undefined;
+    /** Recordings sent to the track worker (reduced motion sends none). */
+    recordings: number;
+    readonly resources: DiceResources;
+    readonly sounds: DiceSoundBank;
+    readonly options: DiceTableOptions;
+    camera: Entity;
+    light: Entity;
+    floor: Entity;
+    /** Where shadows fall on the floor (x, z), from the key light: blobs lean that way. */
+    shadowDir: [number, number];
+    /** The tray material and quad, for the floor and contact blobs. */
+    trayMaterial: AssetRef<'Material'> | undefined;
+    quad: AssetRef<'Mesh'> | undefined;
+    private readonly world;
+    private client;
+    private current;
+    private nextId;
+    private disposed;
+    private fitted;
+    private warned;
+    /** Warm-ups waiting for the next frame (0065). */
+    private frameWaiters;
+    constructor(world: World, options: DiceTableOptions);
+    /** Where the presentation is: `'idle'` with none. */
+    get phase(): DicePhase;
+    /** The track client, started on first use; call early to have the worker warm. */
+    tracks(): TrackClient;
+    /**
+     * Presents a roll the host decided. Resolves once it's over: `'finished'` after the rest,
+     * `'dismissed'`, `'cancelled'` (the signal aborted), or `'failed'` (with the error in
+     * `lastError`; never a half-played roll). Rejects with `dice/busy` while another plays, unless
+     * `replace`.
+     */
+    play(roll: DiceRoll, options?: DicePlayOptions): Promise<DiceOutcome>;
+    /** Plays a roll on a fixed seed and tray, for skin pickers. Replaces what's playing. */
+    preview(roll: DiceRoll, options?: Omit<DicePlayOptions, 'replace'>): Promise<DiceOutcome>;
+    /** Ends the presentation now: `'dismissed'`. False when nothing plays. */
+    dismiss(): boolean;
+    /** Shortens the rest to at most `ms` from now (or from when the dice land, if they haven't). */
+    shortenRest(ms: number): void;
+    /** Everything that can fail before anything plays: the roll's values, its skins and layouts. */
+    private check;
+    /**
+     * Loads what the roll's skins reference (layouts, recipes, the layouts' fonts), then checks the
+     * skins: an unknown family, a layout that can't show a value, a recipe over its bounds.
+     */
+    private loadSkins;
+    layout(ref: AssetRef): FaceLayoutValue | undefined;
+    recipe(ref: AssetRef): DiceEffectRecipeValue | undefined;
+    /** Loads what the roll's layouts need (fonts), makes the dice's resources, then records or places. */
+    private prepare;
+    private prepareAudio;
+    private eventSound;
+    private loadFonts;
+    private acquire;
+    private screenUp;
+    /**
+     * The track is in (or there's none: every die enters): which dice land, where the rest go, each
+     * die's correction, and where entrance dice will land (0065).
+     */
+    private land;
+    /**
+     * Rest poses for entrance dice: free spots near what each entrance wants (the tray's center by
+     * default), clear of where the physical dice ended, target up with the readable twist.
+     */
+    private placeEntrances;
+    /** Reduced motion: no physics. Each die rests in its lane, target up and upright, fading in. */
+    private placeReduced;
+    private geometryOf;
+    /** Spawns the dice (and contact blobs) at their first pose. */
+    private spawnDice;
+    private spawnBlob;
+    private blobRadius;
+    /** How far a blob sits from under its die, toward the shadows: more as the die rises. */
+    private blobLean;
+    private blobStrength;
+    /** A die's pose at `time`, with its correction: rotation · C. Allocates nothing. */
+    private samplePose;
+    /** One frame of the table: the systems call it in Update. */
+    frame(): void;
+    private tumble;
+    /**
+     * Impact sounds up to the current step, as the track recorded them: at most one per die every
+     * 45 ms, and the strongest four in a frame. Allocates nothing without audio.
+     */
+    private contacts;
+    /**
+     * One impact: a variation of its strength layer, louder faster than strength (light touches stay
+     * light), at a pitch and level picked around the contact's (0035's ranges).
+     */
+    private impact;
+    /** The tumble ended: results light up, large pools get their shadow, effects or the rest begin. */
+    private landed;
+    /** Every die is down: the accent if anything plays in it, else the rest. */
+    private afterLanding;
+    /** The result ramp, over 350 ms from landing. */
+    private settleLook;
+    /**
+     * A large pool's landing, t from 0 to 1: the tray's shadow in, the opaque dice's blobs out
+     * (despawned at 1). Allocates nothing.
+     */
+    private crossfadeShadows;
+    /** Reduced motion's fade in, over 150 ms. */
+    private fade;
+    private rest;
+    /**
+     * The roll's recipes, once each, and which dice carry each one (their skin names it): a
+     * recipe's conditions read the whole roll, but its effects play on its own skin's dice.
+     */
+    private recipesOf;
+    private centroid;
+    /**
+     * The roll's recipes, matched once (the conditions read only the roll), and the entrance dice they
+     * choose (0065): at most 2, in the full tier, with effects on and full motion.
+     */
+    private chooseEntrances;
+    /** Budgets for one burst of effects: one light, one cue, 32 particles. */
+    private static budget;
+    /** Starts a matched recipe's effects on `anchors`. Returns how long the longest runs, ms. */
+    private playRecipe;
+    /** Starts the accent phase if anything plays in it. */
+    private startAccent;
+    /** An accent cue, a little above the hardest impact at full gain. */
+    private accentSound;
+    private startRun;
+    private accent;
+    private attach;
+    /**
+     * What a scene on a die can reach and do (attachments, and entrances, 0065): the die, the camera,
+     * its screen point, lens fields and screen effects on it, sound at the roll's gain.
+     */
+    private sceneContext;
+    private attachmentsFrame;
+    /**
+     * Lands every entrance still to come or playing, now: each die snaps to its rest pose, and scenes
+     * get 400 ms to wind down (`ctx.skipped`). False when no entrance is left to skip.
+     */
+    skip(): boolean;
+    private entranceUnavailable;
+    /** While the physics records: the entrance's assets, then its scene drawn once. */
+    private readyEntrance;
+    /**
+     * Draws an entrance's scene once, away from everything, to an offscreen target on the app's
+     * device (as thumbnails are), so its uploads are done and its pipelines compiled before it plays.
+     * The warm copy's lens fields, screen effects and sounds go nowhere.
+     */
+    private warmEntrance;
+    /**
+     * Resolves at the table's next frame (an idle app is woken for it); code after the `await` runs
+     * once that frame has rendered, with its stats in.
+     */
+    private nextFrame;
+    /** An entrance's context: live on its die, or (warming up) on a stand-in, going nowhere. */
+    private entranceContext;
+    /** Starts the next entrance whose turn it is; with every die down, the accent (or the rest). */
+    private nextEntrance;
+    private startEntrance;
+    /** Each frame while an entrance is alive: scenes, the die's landing, its result ramp. */
+    private entrancesFrame;
+    /** The placed drop, t from 0 to 1: from above its spot down onto it, easing in. */
+    private dropPose;
+    /**
+     * The die lands: its rest pose, shown, its result from now (its own material), its impact, and
+     * the effects of the recipe that chose it, on it. Then the next entrance's turn.
+     */
+    private landEntrance;
+    /** The skin's impact as the die lands, as hard as the entrance says (default 0.8). */
+    private entranceImpact;
+    private endEntrance;
+    private fail;
+    /** Ends a presentation: despawns what it spawned, lets go of frames, sounds and resources. */
+    private finish;
+    private warnOnce;
+    /** The dice view's aspect: its camera's target, or the window. */
+    aspect(): number;
+    /** The tray the camera frames: the roll's, or the viewport's while idle. */
+    private fitCamera;
+    private fovY;
+    /** The GPU device was lost: a playing roll fails (it would show nothing), fields cleared. */
+    deviceLost(message: string): void;
+    dispose(): void;
+    describe(): Record<string, unknown>;
+}
+/** The dice table: `world.resource(DiceTable).play(roll)`. */
+export declare const DiceTable: import("@aethervtt/shard-core").ResourceDef<DiceTableState>;