minimojs 1.0.0-alpha.37 → 1.0.0-alpha.38

package/dist/minimo-dice.d.ts

@@ -0,0 +1,181 @@
+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 });
+ * ```
+ */
+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`. */
+    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;
+}

package/dist/minimo-dice.js

@@ -0,0 +1,665 @@
+import { DrawSprite } from "./minimo.js";
+const DEFAULT_SPIN = { x: 600, y: 420, z: 90 };
+const DEFAULT_LOOK = {
+    color: "#f4f1ea",
+    edgeColor: "rgba(0, 0, 0, 0.35)",
+    markColor: "#1b1f1d",
+    font: "monospace",
+    fontWeight: "700",
+};
+// The player looks at a die slightly from above and from the left, so a die
+// at rest shows some of its sides and reads as a solid rather than a flat
+// shape. The face that counts is the one facing the player before this tilt.
+const VIEW = qMul(qAxisAngle([1, 0, 0], 0.28), qAxisAngle([0, 1, 0], 0.18));
+const LIGHT = normalize([-0.45, 0.6, 0.75]);
+const HIGHLIGHT = normalize(add(LIGHT, [0, 0, 1]));
+/**
+ * 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 });
+ * ```
+ */
+export class Dice {
+    constructor(game, look = {}) {
+        /** @internal */
+        this._dice = [];
+        this.game = game;
+        this.look = { ...look };
+    }
+    /** The dice of this set, in the order they were made. */
+    get dice() {
+        return this._dice;
+    }
+    /**
+     * 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, options = {}) {
+        const die = new Die(sides, { ...this.look, ...options });
+        this._dice.push(die);
+        this.game.add(die);
+        return die;
+    }
+    /** Removes a die from the game and from this set. */
+    remove(die) {
+        const index = this._dice.indexOf(die);
+        if (index >= 0)
+            this._dice.splice(index, 1);
+        this.game.destroySprite(die);
+    }
+    /** Advances every die of the set. Call it once per frame from `onUpdate`. */
+    update(dt) {
+        for (const die of this._dice)
+            die.update(dt);
+    }
+}
+/**
+ * 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 class Die extends DrawSprite {
+    /**
+     * @param sides - `4`, `6`, `8`, `10`, `12`, or `20`.
+     * @param options - Position, size, first face, and look.
+     */
+    constructor(sides, options = {}) {
+        const solid = solidFor(sides);
+        const size = Math.max(4, finiteOr(options.size, 64));
+        const scale = size / solid.restExtent;
+        const surface = Math.ceil(2 * solid.radius * scale + size * 0.06 + 4);
+        super(surface, surface, finiteOr(options.x, 0), finiteOr(options.y, 0));
+        /** Called with the value whenever the die comes to rest after turning. */
+        this.onLand = null;
+        /** @internal Radians per second, in world axes. */
+        this._spin = [0, 0, 0];
+        /** @internal */
+        this._turning = false;
+        /** @internal */
+        this._landing = null;
+        /** @internal */
+        this._waiting = [];
+        this.sides = sides;
+        this.size = size;
+        this.bodyWidth = size;
+        this.bodyHeight = size;
+        this._solid = solid;
+        this._scale = scale;
+        const { x: _x, y: _y, size: _size, value: _value, ...look } = options;
+        this._look = look;
+        this._orientation = restOrientation(solid, this._checkValue(options.value ?? 1));
+    }
+    /** The look of this die. Change it with {@link Die.setLook}. */
+    get look() {
+        return this._look;
+    }
+    /** Changes some of the die's look, keeping the rest. */
+    setLook(look) {
+        this._look = { ...this._look, ...look };
+        this.frozen = false;
+    }
+    /**
+     * 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() {
+        return valueFacing(this._solid, this._orientation);
+    }
+    /** `true` while the die turns, from a spin or a roll until it lands. */
+    get rolling() {
+        return this._turning;
+    }
+    /**
+     * 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) {
+        this._spin = spinVector(spin);
+        this._landing = null;
+        this._turning = true;
+        this.frozen = false;
+    }
+    /**
+     * 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, ms = 800) {
+        const result = this._checkValue(value);
+        const promise = this._wait();
+        const seconds = Math.max(0, finiteOr(ms, 800)) / 1000;
+        if (seconds === 0) {
+            this.show(result);
+            return promise;
+        }
+        const speed = length(this._spin);
+        const axis = speed > 0 ? scaleVec(this._spin, 1 / speed) : [0, 0, 1];
+        // The spin decays to zero over the landing, turning the die by half what
+        // it would have turned at full speed. A correction spread over the same
+        // time takes it from there to the chosen face.
+        const spunTo = qMul(qAxisAngle(axis, (speed * seconds) / 2), this._orientation);
+        const correction = qMul(restOrientation(this._solid, result), qConjugate(spunTo));
+        const [angle, correctionAxis] = qToAxisAngle(correction);
+        this._landing = {
+            from: this._orientation,
+            axis,
+            speed,
+            seconds,
+            elapsed: 0,
+            correctionAxis,
+            correctionAngle: angle,
+            value: result,
+        };
+        this._turning = true;
+        this.frozen = false;
+        return promise;
+    }
+    /**
+     * 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, options = {}) {
+        const result = this._checkValue(value);
+        if (options.spin)
+            this._spin = spinVector(options.spin);
+        else if (!this._turning || length(this._spin) === 0)
+            this._spin = spinVector(DEFAULT_SPIN);
+        return this.land(result, finiteOr(options.ms, 1000));
+    }
+    /**
+     * 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) {
+        const result = this._checkValue(value);
+        this._orientation = restOrientation(this._solid, result);
+        this._spin = [0, 0, 0];
+        this._landing = null;
+        this._turning = false;
+        this.frozen = false;
+        this._settle(result, false);
+    }
+    /**
+     * 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) {
+        const seconds = Math.max(0, finiteOr(dt, 0));
+        if (!this._turning || seconds === 0)
+            return;
+        const landing = this._landing;
+        if (!landing) {
+            const speed = length(this._spin);
+            if (speed > 0) {
+                const step = qAxisAngle(scaleVec(this._spin, 1 / speed), speed * seconds);
+                this._orientation = qNormalize(qMul(step, this._orientation));
+            }
+            return;
+        }
+        landing.elapsed = Math.min(landing.seconds, landing.elapsed + seconds);
+        const t = landing.elapsed;
+        const T = landing.seconds;
+        if (t >= T) {
+            this._orientation = restOrientation(this._solid, landing.value);
+            this._spin = [0, 0, 0];
+            this._landing = null;
+            this._turning = false;
+            this._settle(landing.value, true);
+            return;
+        }
+        const spun = qMul(qAxisAngle(landing.axis, landing.speed * (t - (t * t) / (2 * T))), landing.from);
+        const u = t / T;
+        const eased = u * u * (3 - 2 * u);
+        this._orientation = qNormalize(qMul(qAxisAngle(landing.correctionAxis, landing.correctionAngle * eased), spun));
+        this._spin = scaleVec(landing.axis, landing.speed * (1 - u));
+    }
+    redraw(ctx) {
+        const solid = this._solid;
+        const look = this._look;
+        const s = this._scale;
+        const c = this.width / 2;
+        const toView = qMul(VIEW, this._orientation);
+        const points = solid.vertices.map((v) => qRotate(toView, v));
+        const project = (v) => [c + v[0] * s, c - v[1] * s];
+        const edgeWidth = Math.max(1, this.size * 0.025);
+        for (const face of solid.faces) {
+            const normal = qRotate(toView, face.normal);
+            if (normal[2] <= 1e-4)
+                continue;
+            const corners = face.verts.map((i) => project(points[i]));
+            ctx.save();
+            polygon(ctx, corners);
+            ctx.fillStyle = (face.value && look.faceColors?.[face.value]) || look.color || DEFAULT_LOOK.color;
+            ctx.fill();
+            ctx.clip();
+            this._drawMarks(ctx, face, toView, project);
+            const lit = Math.max(0, dot(normal, LIGHT));
+            polygon(ctx, corners);
+            ctx.fillStyle = `rgba(0, 0, 0, ${((1 - lit) * 0.5).toFixed(3)})`;
+            ctx.fill();
+            const shine = Math.pow(Math.max(0, dot(normal, HIGHLIGHT)), 24) * 0.35;
+            if (shine > 0.005) {
+                ctx.fillStyle = `rgba(255, 255, 255, ${shine.toFixed(3)})`;
+                ctx.fill();
+            }
+            ctx.restore();
+            polygon(ctx, corners);
+            ctx.lineJoin = "round";
+            ctx.lineWidth = edgeWidth;
+            ctx.strokeStyle = look.edgeColor || DEFAULT_LOOK.edgeColor;
+            ctx.stroke();
+        }
+        this.frozen = !this._turning;
+    }
+    /** @internal Draws one face's pips, numbers, or image, in the face's own plane. */
+    _drawMarks(ctx, face, toView, project) {
+        const solid = this._solid;
+        if (solid.sides === 4) {
+            // A d4 is read at its corners: each face shows, near each corner, the
+            // value of that corner, upright toward it.
+            for (const index of face.verts) {
+                const corner = solid.vertices[index];
+                const toCorner = sub(corner, face.center);
+                const origin = add(face.center, scaleVec(toCorner, 0.55));
+                const up = normalize(toCorner);
+                this._inFrame(ctx, origin, up, face, toView, project, () => {
+                    this._drawValue(ctx, index + 1, solid.markScale * 0.62, false);
+                });
+            }
+            return;
+        }
+        this._inFrame(ctx, face.center, face.up, face, toView, project, () => {
+            const pips = solid.sides === 6 && (this._look.marks ?? "pips") === "pips";
+            this._drawValue(ctx, face.value, solid.markScale, pips);
+        });
+    }
+    /**
+     * @internal Runs `draw` in a frame on the face's plane: the origin at
+     * `origin`, `up` reading upright, and 100 units for the face's inradius.
+     */
+    _inFrame(ctx, origin, up, face, toView, project, draw) {
+        const right = cross(up, face.normal);
+        const unit = face.inradius / 100;
+        const o = project(qRotate(toView, origin));
+        const r = qRotate(toView, right);
+        const u = qRotate(toView, up);
+        const s = this._scale * unit;
+        ctx.save();
+        // Local x runs along the face's right, local y down the face, as on a canvas.
+        ctx.transform(r[0] * s, -r[1] * s, -u[0] * s, u[1] * s, o[0], o[1]);
+        draw();
+        ctx.restore();
+    }
+    /** @internal Draws a value's image, pips, or number, centered, in face units. */
+    _drawValue(ctx, value, markScale, pips) {
+        const look = this._look;
+        const imageKey = look.faces?.[value];
+        const image = imageKey ? this.game?.getImage(imageKey) : undefined;
+        if (image) {
+            const half = this.sides === 6 ? 100 : this.sides === 4 ? 70 : 110;
+            ctx.drawImage(image, -half, -half, half * 2, half * 2);
+            return;
+        }
+        ctx.fillStyle = look.markColor || DEFAULT_LOOK.markColor;
+        if (pips) {
+            for (const [px, py] of PIPS[value] ?? []) {
+                ctx.beginPath();
+                ctx.arc(px * 52, py * 52, 17, 0, Math.PI * 2);
+                ctx.fill();
+            }
+            return;
+        }
+        const fontSize = Math.round(100 * markScale);
+        const label = String(value);
+        ctx.font = `${look.fontWeight || DEFAULT_LOOK.fontWeight} ${fontSize}px ${look.font || DEFAULT_LOOK.font}`;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "middle";
+        ctx.fillText(label, 0, 0);
+        if (value === 6 || value === 9) {
+            const width = ctx.measureText(label).width;
+            ctx.fillRect(-width / 2, fontSize * 0.42, width, Math.max(2, fontSize * 0.08));
+        }
+    }
+    /** @internal */
+    _checkValue(value) {
+        if (!Number.isInteger(value) || value < 1 || value > this.sides) {
+            throw new Error(`MinimoJS: A d${this.sides} has no face ${String(value)}; its values are 1 to ${this.sides}.`);
+        }
+        return value;
+    }
+    /** @internal */
+    _wait() {
+        return new Promise((resolve) => this._waiting.push(resolve));
+    }
+    /** @internal */
+    _settle(value, landed) {
+        const waiting = this._waiting;
+        this._waiting = [];
+        for (const resolve of waiting)
+            resolve(value);
+        if (landed)
+            this.onLand?.(value);
+    }
+}
+// Pip positions on a d6, in halves of the face's inradius.
+const PIPS = {
+    1: [[0, 0]],
+    2: [[-1, -1], [1, 1]],
+    3: [[-1, -1], [0, 0], [1, 1]],
+    4: [[-1, -1], [1, -1], [-1, 1], [1, 1]],
+    5: [[-1, -1], [1, -1], [0, 0], [-1, 1], [1, 1]],
+    6: [[-1, -1], [1, -1], [-1, 0], [1, 0], [-1, 1], [1, 1]],
+};
+// ---------------------------------------------------------------------------
+// The solids
+// ---------------------------------------------------------------------------
+const solids = new Map();
+/** The solid of each kind of die, built once. */
+function solidFor(sides) {
+    let solid = solids.get(sides);
+    if (!solid) {
+        solid = buildSolid(sides);
+        solids.set(sides, solid);
+    }
+    return solid;
+}
+function buildSolid(sides) {
+    const phi = (1 + Math.sqrt(5)) / 2;
+    let vertices;
+    let normals;
+    let markScale;
+    switch (sides) {
+        case 4:
+            vertices = [[1, 1, 1], [1, -1, -1], [-1, 1, -1], [-1, -1, 1]];
+            normals = vertices.map((v) => scaleVec(v, -1));
+            markScale = 1.6;
+            break;
+        case 6:
+            vertices = signs([1, 1, 1]);
+            normals = [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]];
+            markScale = 1.2;
+            break;
+        case 8:
+            vertices = [[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]];
+            normals = signs([1, 1, 1]);
+            markScale = 1.15;
+            break;
+        case 10: {
+            // A pentagonal trapezohedron: two apexes and a zigzag ring. Its kites
+            // are flat only when the apex height matches the ring's zigzag.
+            const zig = 0.105;
+            const cos36 = Math.cos(Math.PI / 5);
+            const apex = (zig * (1 + cos36)) / (1 - cos36);
+            vertices = [[0, 0, apex], [0, 0, -apex]];
+            for (let i = 0; i < 10; i++) {
+                const angle = (i * Math.PI) / 5;
+                vertices.push([Math.cos(angle), Math.sin(angle), i % 2 === 0 ? zig : -zig]);
+            }
+            const ring = (i) => 2 + (i % 10);
+            normals = [];
+            for (let k = 0; k < 5; k++) {
+                normals.push(planeNormal(vertices[0], vertices[ring(2 * k)], vertices[ring(2 * k + 1)]));
+                normals.push(planeNormal(vertices[1], vertices[ring(2 * k + 1)], vertices[ring(2 * k + 2)]));
+            }
+            markScale = 1.35;
+            break;
+        }
+        case 12:
+            vertices = [
+                ...signs([1, 1, 1]),
+                ...signs([0, 1 / phi, phi]),
+                ...signs([1 / phi, phi, 0]),
+                ...signs([phi, 0, 1 / phi]),
+            ];
+            normals = [...signs([0, phi, 1]), ...signs([1, 0, phi]), ...signs([phi, 1, 0])];
+            markScale = 1.0;
+            break;
+        case 20:
+            vertices = [...signs([0, 1, phi]), ...signs([1, phi, 0]), ...signs([phi, 0, 1])];
+            normals = [
+                ...signs([1, 1, 1]),
+                ...signs([0, phi, 1 / phi]),
+                ...signs([1 / phi, 0, phi]),
+                ...signs([phi, 1 / phi, 0]),
+            ];
+            markScale = 1.05;
+            break;
+        default:
+            throw new Error(`MinimoJS: There is no d${String(sides)}; a die has 4, 6, 8, 10, 12, or 20 sides.`);
+    }
+    const radius = Math.max(...vertices.map(length));
+    const faces = normals.map((n) => buildFace(vertices, normalize(n), sides));
+    if (sides !== 4)
+        assignValues(faces, sides);
+    const solid = { sides, vertices, faces, markScale, restExtent: 1, radius };
+    const rest = restOrientation(solid, 1);
+    const seen = vertices.map((v) => qRotate(qMul(VIEW, rest), v));
+    const xs = seen.map((v) => v[0]);
+    const ys = seen.map((v) => v[1]);
+    solid.restExtent = Math.max(Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
+    return solid;
+}
+/** Every sign combination of a vertex's non-zero coordinates. */
+function signs([x, y, z]) {
+    const out = [];
+    for (const sx of x === 0 ? [1] : [1, -1]) {
+        for (const sy of y === 0 ? [1] : [1, -1]) {
+            for (const sz of z === 0 ? [1] : [1, -1])
+                out.push([x * sx, y * sy, z * sz]);
+        }
+    }
+    return out;
+}
+function planeNormal(a, b, c) {
+    const n = normalize(cross(sub(b, a), sub(c, a)));
+    // Outward: away from the solid's center at the origin.
+    return dot(n, a) < 0 ? scaleVec(n, -1) : n;
+}
+/** The face of a convex solid on the plane with outward normal `n`. */
+function buildFace(vertices, n, sides) {
+    const reach = Math.max(...vertices.map((v) => dot(v, n)));
+    const on = vertices.map((v, i) => [v, i]).filter(([v]) => dot(v, n) > reach - 1e-6);
+    const center = scaleVec(on.reduce((sum, [v]) => add(sum, v), [0, 0, 0]), 1 / on.length);
+    const e1 = normalize(sub(on[0][0], center));
+    const e2 = cross(n, e1);
+    const verts = on
+        .map(([v, i]) => ({ i, angle: Math.atan2(dot(sub(v, center), e2), dot(sub(v, center), e1)) }))
+        .sort((a, b) => a.angle - b.angle)
+        .map(({ i }) => i);
+    let inradius = Infinity;
+    for (let k = 0; k < verts.length; k++) {
+        const a = vertices[verts[k]];
+        const b = vertices[verts[(k + 1) % verts.length]];
+        const edge = normalize(sub(b, a));
+        const toCenter = sub(center, a);
+        inradius = Math.min(inradius, length(sub(toCenter, scaleVec(edge, dot(toCenter, edge)))));
+    }
+    let up;
+    if (sides === 6) {
+        // A square reads upright toward an edge.
+        up = normalize(sub(scaleVec(add(vertices[verts[0]], vertices[verts[1]]), 0.5), center));
+    }
+    else {
+        // A triangle, kite, or pentagon reads upright toward a corner: on a d10,
+        // the corner at the apex, the farthest from the face's center.
+        let far = verts[0];
+        for (const i of verts)
+            if (length(sub(vertices[i], center)) > length(sub(vertices[far], center)) + 1e-9)
+                far = i;
+        up = normalize(sub(vertices[far], center));
+    }
+    return { verts, normal: n, center, up, inradius, value: 0 };
+}
+/** Numbers the faces so opposite faces add up to `sides + 1`, as on real dice. */
+function assignValues(faces, sides) {
+    let next = 1;
+    for (const face of faces) {
+        if (face.value)
+            continue;
+        const opposite = faces.find((other) => other !== face && dot(other.normal, face.normal) < -1 + 1e-6);
+        face.value = next;
+        if (opposite)
+            opposite.value = sides + 1 - next;
+        next++;
+    }
+}
+/** The orientation that shows `value` facing the player, upright. */
+function restOrientation(solid, value) {
+    let n;
+    let up;
+    if (solid.sides === 4) {
+        // A face toward the player with the value's corner at its top: the face
+        // opposite the next corner, which is one of the three that touch it.
+        const face = solid.faces[value % 4];
+        n = face.normal;
+        up = normalize(sub(solid.vertices[value - 1], face.center));
+    }
+    else {
+        const face = solid.faces.find((f) => f.value === value);
+        n = face.normal;
+        up = face.up;
+    }
+    const right = cross(up, n);
+    return qFromRows(right, up, n);
+}
+/** The value facing the player in `orientation`. */
+function valueFacing(solid, orientation) {
+    if (solid.sides === 4) {
+        let best = 0;
+        for (let i = 1; i < 4; i++) {
+            if (qRotate(orientation, solid.vertices[i])[1] > qRotate(orientation, solid.vertices[best])[1])
+                best = i;
+        }
+        return best + 1;
+    }
+    let best = solid.faces[0];
+    for (const face of solid.faces) {
+        if (qRotate(orientation, face.normal)[2] > qRotate(orientation, best.normal)[2])
+            best = face;
+    }
+    return best.value;
+}
+function spinVector(spin) {
+    const toRadians = Math.PI / 180;
+    // World axes: x right, y up, z toward the player. Screen-clockwise is a
+    // negative turn about z.
+    return [finiteOr(spin.x, 0) * toRadians, finiteOr(spin.y, 0) * toRadians, -finiteOr(spin.z, 0) * toRadians];
+}
+function polygon(ctx, corners) {
+    ctx.beginPath();
+    corners.forEach(([x, y], i) => (i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y)));
+    ctx.closePath();
+}
+function finiteOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+// ---------------------------------------------------------------------------
+// Vectors and quaternions
+// ---------------------------------------------------------------------------
+function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function scaleVec(a, k) {
+    return [a[0] * k, a[1] * k, a[2] * k];
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function length(a) {
+    return Math.sqrt(dot(a, a));
+}
+function normalize(a) {
+    const l = length(a);
+    return l > 0 ? scaleVec(a, 1 / l) : [0, 0, 1];
+}
+function qAxisAngle(axis, angle) {
+    const half = angle / 2;
+    const s = Math.sin(half);
+    return [Math.cos(half), axis[0] * s, axis[1] * s, axis[2] * s];
+}
+function qMul(a, b) {
+    return [
+        a[0] * b[0] - a[1] * b[1] - a[2] * b[2] - a[3] * b[3],
+        a[0] * b[1] + a[1] * b[0] + a[2] * b[3] - a[3] * b[2],
+        a[0] * b[2] - a[1] * b[3] + a[2] * b[0] + a[3] * b[1],
+        a[0] * b[3] + a[1] * b[2] - a[2] * b[1] + a[3] * b[0],
+    ];
+}
+function qConjugate(q) {
+    return [q[0], -q[1], -q[2], -q[3]];
+}
+function qNormalize(q) {
+    const l = Math.hypot(q[0], q[1], q[2], q[3]) || 1;
+    return [q[0] / l, q[1] / l, q[2] / l, q[3] / l];
+}
+function qRotate(q, v) {
+    const [w, x, y, z] = q;
+    // v + 2w(q × v) + 2 q × (q × v), with q the vector part.
+    const tx = 2 * (y * v[2] - z * v[1]);
+    const ty = 2 * (z * v[0] - x * v[2]);
+    const tz = 2 * (x * v[1] - y * v[0]);
+    return [v[0] + w * tx + (y * tz - z * ty), v[1] + w * ty + (z * tx - x * tz), v[2] + w * tz + (x * ty - y * tx)];
+}
+/** The shortest turn a unit quaternion makes: its angle and axis. */
+function qToAxisAngle(q) {
+    const [w, x, y, z] = q[0] < 0 ? [-q[0], -q[1], -q[2], -q[3]] : q;
+    const s = Math.hypot(x, y, z);
+    if (s < 1e-9)
+        return [0, [0, 0, 1]];
+    return [2 * Math.atan2(s, w), [x / s, y / s, z / s]];
+}
+/** The rotation whose matrix has these rows. */
+function qFromRows(r0, r1, r2) {
+    const m00 = r0[0], m01 = r0[1], m02 = r0[2];
+    const m10 = r1[0], m11 = r1[1], m12 = r1[2];
+    const m20 = r2[0], m21 = r2[1], m22 = r2[2];
+    const trace = m00 + m11 + m22;
+    let q;
+    if (trace > 0) {
+        const s = Math.sqrt(trace + 1) * 2;
+        q = [s / 4, (m21 - m12) / s, (m02 - m20) / s, (m10 - m01) / s];
+    }
+    else if (m00 > m11 && m00 > m22) {
+        const s = Math.sqrt(1 + m00 - m11 - m22) * 2;
+        q = [(m21 - m12) / s, s / 4, (m01 + m10) / s, (m02 + m20) / s];
+    }
+    else if (m11 > m22) {
+        const s = Math.sqrt(1 + m11 - m00 - m22) * 2;
+        q = [(m02 - m20) / s, (m01 + m10) / s, s / 4, (m12 + m21) / s];
+    }
+    else {
+        const s = Math.sqrt(1 + m22 - m00 - m11) * 2;
+        q = [(m10 - m01) / s, (m02 + m20) / s, (m12 + m21) / s, s / 4];
+    }
+    return qNormalize(q);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.37",
+  "version": "1.0.0-alpha.38",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",