minimojs 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/minimo-dice.d.ts

@@ -0,0 +1,206 @@
+import { DrawSprite, Game } from "./minimo.js";
+/** The kinds of die a {@link Dice} set makes: a d4, d6, d8, d10, d12, or d20. */
+export type DieSides = 4 | 6 | 8 | 10 | 12 | 20;
+/**
+ * How a die turns, in degrees per second about the screen's three axes.
+ * The sign is the direction and the size is the speed.
+ *
+ * - `x`: positive turns the die's top toward the player.
+ * - `y`: positive turns the die's front to the right.
+ * - `z`: positive turns the die clockwise, as `Sprite.rotation` does.
+ */
+export interface DieSpin {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+/**
+ * The look of a die. A {@link Dice} set holds one for all its dice, and each
+ * die can override any field.
+ */
+export interface DieLook {
+    /** Color of the die's body. Default `"#f4f1ea"`. */
+    color?: string;
+    /** Color of the die's edges. Default `"rgba(0, 0, 0, 0.35)"`. */
+    edgeColor?: string;
+    /** Color of the pips and numbers. Default `"#1b1f1d"`. */
+    markColor?: string;
+    /**
+     * How faces are marked: `"pips"` or `"numbers"`. Pips exist only on a d6,
+     * and are its default; every other die shows numbers. On a die with
+     * numbers, `6` and `9` are underlined, as on real dice.
+     */
+    marks?: "pips" | "numbers";
+    /**
+     * CSS font family of the numbers, such as `'"Lilita One"'`. Use a web font
+     * the page declares and the game registers with `game.requireFont`, so the
+     * numbers look the same on every device. Default: the engine's default
+     * font, `monospace`. Pips are shapes and need no font.
+     */
+    font?: string;
+    /** Font weight of the numbers. Default `"700"`. */
+    fontWeight?: string;
+    /** Body color of single faces, by value, over {@link DieLook.color}. */
+    faceColors?: Record<number, string>;
+    /**
+     * An image key for single faces, by value, drawn in place of that face's
+     * pips or number. On a d6 the image fills the face. On a d4, whose result is
+     * read at its top corner, it is drawn at the corner of that value on each
+     * face.
+     */
+    faces?: Record<number, string>;
+}
+/** Where a new die is, how big, and how it looks. */
+export interface DieOptions extends DieLook {
+    /** X position in world space (center), in pixels. Default `0`. */
+    x?: number;
+    /** Y position in world space (center), in pixels. Default `0`. */
+    y?: number;
+    /**
+     * About how wide the die is at rest, in pixels. Default `64`. It is also the
+     * die's collision body; its drawing surface is larger, to hold the die at
+     * every angle.
+     */
+    size?: number;
+    /** The face shown at first. Default `1`. */
+    value?: number;
+}
+/** How {@link Die.roll} throws a die. */
+export interface DieRollOptions {
+    /**
+     * The turning at the throw, which slows down to a stop. Default: the die's
+     * current spin while it turns, otherwise `{ x: 600, y: 420, z: 90 }`.
+     */
+    spin?: DieSpin;
+    /** How long the roll takes, in milliseconds. Default `1000`. */
+    ms?: number;
+}
+/**
+ * A set of dice that share a look. It makes each die and advances all of them
+ * with one {@link Dice.update} call per frame.
+ *
+ * The set never decides a result: the game chooses each value, and the dice
+ * turn and land on it. The same value, spin, and duration turn a die the same
+ * way on every device, so a multiplayer room can put them in its shared state
+ * and every player sees the same roll.
+ *
+ * @example
+ * ```ts
+ * const dice = new Dice(game, { color: "#f4f1ea", font: '"Lilita One"' });
+ * const d20 = dice.create(20, { x: 200, y: 300, size: 72 });
+ * game.onUpdate = (dt) => dice.update(dt);
+ *
+ * const value = 1 + Math.floor(game.random() * 20);
+ * await d20.roll(value, { spin: { x: 540, y: -360, z: 90 }, ms: 1200 });
+ * ```
+ *
+ * ## In a design
+ *
+ * A design can place dice, so the creator moves them in the design editor. A
+ * die is a `module` object of a version 3 design whose `kind` is `"d4"`,
+ * `"d6"`, `"d8"`, `"d10"`, `"d12"`, or `"d20"`, and a design sets only its
+ * `x` and `y`. Its look and size are the set's, as for {@link Dice.create}
+ * without options, and it shows its 1 until the game rolls it.
+ *
+ * ```json
+ * { "id": "9a2c4e6f-1b3d-4f5a-8c7e-0d2f4b6a8c1e", "name": "d20", "type": "module", "module": "dice", "kind": "d20", "x": 360, "y": 640 }
+ * ```
+ *
+ * Create the set in the scene's `onCreate()` before the design's objects,
+ * then find the die by its name:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.dice = new Dice(game, { color: "#f4f1ea" });
+ *   this.d20 = game.createObjectList(board.objects).findByName("d20");
+ * }
+ * ```
+ */
+export declare class Dice {
+    /** The game the dice are added to. */
+    readonly game: Game;
+    /** The look every die of the set starts from. */
+    readonly look: DieLook;
+    constructor(game: Game, look?: DieLook);
+    /** The dice of this set, in the order they were made. */
+    get dice(): readonly Die[];
+    /**
+     * Makes a die, adds it to the game, and returns it. The die is a sprite: the
+     * game can move it, give it gravity, and test its collisions while it turns.
+     * @param sides - `4`, `6`, `8`, `10`, `12`, or `20`.
+     * @param options - Position, size, first face, and any look over the set's.
+     */
+    create(sides: DieSides, options?: DieOptions): Die;
+    /** Removes a die from the game and from this set. */
+    remove(die: Die): void;
+    /**
+     * Advances every die of the set. Call it once per frame from `onUpdate`.
+     * A die the game destroyed, such as by `game.reset()`, leaves the set.
+     */
+    update(dt: number): void;
+}
+/**
+ * One die, drawn in simulated 3D: a real solid, turned, shaded, and projected
+ * onto the 2D canvas. It is a `DrawSprite`, so it has everything a sprite has.
+ * The module turns it in place; moving it is the game's, with the same
+ * physics as any other sprite.
+ *
+ * Make dice with {@link Dice.create}, which also advances them. A die made
+ * with `new Die` must be added with `game.add` and advanced with
+ * {@link Die.update} by the game.
+ */
+export declare class Die extends DrawSprite {
+    /** The kind of die: `4`, `6`, `8`, `10`, `12`, or `20`. */
+    readonly sides: DieSides;
+    /** About how wide the die is at rest, in pixels. */
+    readonly size: number;
+    /** Called with the value whenever the die comes to rest after turning. */
+    onLand: ((value: number) => void) | null;
+    /**
+     * @param sides - `4`, `6`, `8`, `10`, `12`, or `20`.
+     * @param options - Position, size, first face, and look.
+     */
+    constructor(sides: DieSides, options?: DieOptions);
+    /** The look of this die. Change it with {@link Die.setLook}. */
+    get look(): Readonly<DieLook>;
+    /** Changes some of the die's look, keeping the rest. */
+    setLook(look: DieLook): void;
+    /**
+     * The value facing the player: the result once the die is at rest, and
+     * whatever face is in front while it turns. A d4 is read at its top corner,
+     * as a real one is: its value is the corner pointing up.
+     */
+    get value(): number;
+    /** `true` while the die turns, from a spin or a roll until it lands. */
+    get rolling(): boolean;
+    /**
+     * Starts the die turning, or changes how it turns, and keeps it turning
+     * until {@link Die.land} or {@link Die.show}. A landing in progress stops,
+     * and the die turns freely again.
+     */
+    spin(spin: DieSpin): void;
+    /**
+     * Slows the die down and settles it on `value`, upright, in `ms`. The die
+     * keeps the direction and speed it was turning at, and slows to a stop
+     * exactly on its face.
+     * @returns A promise that resolves with the value when the die is at rest.
+     */
+    land(value: number, ms?: number): Promise<number>;
+    /**
+     * Throws the die: it starts turning with `spin` and lands on `value` after
+     * `ms`, slowing down all the way. This is the call most games need.
+     * @returns A promise that resolves with the value when the die is at rest.
+     */
+    roll(value: number, options?: DieRollOptions): Promise<number>;
+    /**
+     * Turns the die to `value` at once, with no animation, such as when a game
+     * restores its state. A die that was turning stops.
+     */
+    show(value: number): void;
+    /**
+     * Advances the die's turning. {@link Dice.update} calls it for every die of
+     * its set; call it yourself only for a die made with `new Die`.
+     */
+    update(dt: number): void;
+    redraw(ctx: CanvasRenderingContext2D): void;
+}