@aethervtt/shard-dice 0.0.0-stage → 0.2.0

package/dist/builtins.js

@@ -0,0 +1,335 @@
+import { defineDie } from "./definition.js";
+const PHI = (1 + Math.sqrt(5)) / 2;
+function unitRadius(points) {
+  const c = [0, 1, 2].map((k) => points.reduce((s, p) => s + p[k], 0) / points.length);
+  const centered = points.map((p) => p.map((v, k) => v - c[k]));
+  const r = Math.max(...centered.map((p) => Math.sqrt(p[0] ** 2 + p[1] ** 2 + p[2] ** 2)));
+  return Float32Array.from(centered.flatMap((p) => p.map((v) => v / r)));
+}
+const R0 = 0.7799999713897705;
+const R1 = 0.6310332417488098;
+const R2 = 0.24103325605392456;
+const Z1 = 0.45847249031066895;
+const Z2 = 0.7418240904808044;
+const RING = 0.10557281225919724;
+const TRAPEZOHEDRON = Float32Array.from([
+  0,
+  1,
+  0,
+  0,
+  -1,
+  0,
+  R0,
+  RING,
+  0,
+  R1,
+  -RING,
+  Z1,
+  R2,
+  RING,
+  Z2,
+  -R2,
+  -RING,
+  Z2,
+  -R1,
+  RING,
+  Z1,
+  -R0,
+  -RING,
+  0,
+  -R1,
+  RING,
+  -Z1,
+  -R2,
+  -RING,
+  -Z2,
+  R2,
+  RING,
+  -Z2,
+  R1,
+  -RING,
+  -Z1
+]);
+function dodecahedron() {
+  const inverse = 1 / PHI;
+  const out = [];
+  for (const x of [-1, 1]) for (const y of [-1, 1]) for (const z of [-1, 1]) out.push([x, y, z]);
+  for (const a of [-inverse, inverse]) {
+    for (const b of [-PHI, PHI]) out.push([0, a, b], [a, b, 0], [b, 0, a]);
+  }
+  return out;
+}
+const D10_VALUES = {
+  "1:9:10:11": 8,
+  "1:7:8:9": 10,
+  "1:2:3:11": 2,
+  "1:5:6:7": 4,
+  "1:3:4:5": 6,
+  "0:8:9:10": 3,
+  "0:2:10:11": 5,
+  "0:6:7:8": 7,
+  "0:2:3:4": 9,
+  "0:4:5:6": 1
+};
+const D4 = {
+  version: 1,
+  id: "d4",
+  sides: 4,
+  vertices: unitRadius([
+    [1, 1, 1],
+    [-1, -1, 1],
+    [-1, 1, -1],
+    [1, -1, -1]
+  ]),
+  read: "vertex",
+  // Aether numbers the d4's vertices by direction: sorted by y, then z, then x.
+  values: { "0": 4, "1": 2, "2": 3, "3": 1 },
+  collider: "hull",
+  sizeMm: 15,
+  bevel: 0.06,
+  markScale: 0.31
+};
+const D6 = {
+  version: 1,
+  id: "d6",
+  sides: 6,
+  vertices: unitRadius([
+    [-1, -1, -1],
+    [-1, -1, 1],
+    [-1, 1, -1],
+    [-1, 1, 1],
+    [1, -1, -1],
+    [1, -1, 1],
+    [1, 1, -1],
+    [1, 1, 1]
+  ]),
+  read: "face",
+  values: {
+    "0:1:4:5": 1,
+    "0:2:4:6": 2,
+    "0:1:2:3": 3,
+    "4:5:6:7": 4,
+    "1:3:5:7": 5,
+    "2:3:6:7": 6
+  },
+  collider: "hull",
+  sizeMm: 16,
+  bevel: 0.082,
+  markScale: 0.5,
+  oppositesSum: true
+};
+const D8 = {
+  version: 1,
+  id: "d8",
+  sides: 8,
+  vertices: unitRadius([
+    [1, 0, 0],
+    [-1, 0, 0],
+    [0, 1, 0],
+    [0, -1, 0],
+    [0, 0, 1],
+    [0, 0, -1]
+  ]),
+  read: "face",
+  values: {
+    "1:3:5": 2,
+    "0:3:5": 6,
+    "1:3:4": 8,
+    "0:3:4": 4,
+    "1:2:5": 5,
+    "0:2:5": 1,
+    "1:2:4": 3,
+    "0:2:4": 7
+  },
+  collider: "hull",
+  sizeMm: 16,
+  bevel: 0.082,
+  markScale: 0.4,
+  oppositesSum: true
+};
+const D10 = {
+  version: 1,
+  id: "d10",
+  sides: 10,
+  vertices: TRAPEZOHEDRON,
+  read: "face",
+  values: D10_VALUES,
+  labels: { 10: "0" },
+  collider: "hull",
+  sizeMm: 16,
+  bevel: 0.13,
+  markScale: 0.36
+};
+const D10_TENS = {
+  version: 1,
+  id: "d10-tens",
+  sides: 10,
+  vertices: TRAPEZOHEDRON,
+  read: "face",
+  values: D10_VALUES,
+  labels: {
+    1: "10",
+    2: "20",
+    3: "30",
+    4: "40",
+    5: "50",
+    6: "60",
+    7: "70",
+    8: "80",
+    9: "90",
+    10: "00"
+  },
+  collider: "hull",
+  sizeMm: 16,
+  bevel: 0.13,
+  markScale: 0.32
+};
+const D12 = {
+  version: 1,
+  id: "d12",
+  sides: 12,
+  vertices: unitRadius(dodecahedron()),
+  read: "face",
+  values: {
+    "1:5:9:11:15": 4,
+    "0:4:8:9:15": 7,
+    "4:5:13:15:19": 11,
+    "0:1:9:10:16": 5,
+    "0:2:8:10:14": 10,
+    "4:6:8:13:14": 1,
+    "1:3:11:16:17": 12,
+    "5:7:11:17:19": 3,
+    "2:3:10:12:16": 2,
+    "6:7:13:18:19": 8,
+    "2:6:12:14:18": 9,
+    "3:7:12:17:18": 6
+  },
+  collider: "hull",
+  sizeMm: 14,
+  bevel: 0.082,
+  markScale: 0.42,
+  oppositesSum: true
+};
+const D20 = {
+  version: 1,
+  id: "d20",
+  sides: 20,
+  vertices: unitRadius([
+    [-1, PHI, 0],
+    [1, PHI, 0],
+    [-1, -PHI, 0],
+    [1, -PHI, 0],
+    [0, -1, PHI],
+    [0, 1, PHI],
+    [0, -1, -PHI],
+    [0, 1, -PHI],
+    [PHI, 0, -1],
+    [PHI, 0, 1],
+    [-PHI, 0, -1],
+    [-PHI, 0, 1]
+  ]),
+  read: "face",
+  values: {
+    "2:3:6": 1,
+    "2:3:4": 19,
+    "2:6:10": 13,
+    "3:6:8": 7,
+    "2:4:11": 10,
+    "3:4:9": 3,
+    "2:10:11": 12,
+    "3:8:9": 17,
+    "6:7:10": 6,
+    "6:7:8": 16,
+    "4:5:11": 5,
+    "4:5:9": 15,
+    "0:10:11": 4,
+    "1:8:9": 9,
+    "0:7:10": 18,
+    "1:7:8": 11,
+    "0:5:11": 14,
+    "1:5:9": 8,
+    "0:1:7": 2,
+    "0:1:5": 20
+  },
+  collider: "hull",
+  sizeMm: 18,
+  bevel: 0.082,
+  markScale: 0.38,
+  oppositesSum: true
+};
+function fibonacciSphere(count) {
+  const golden = Math.PI * (3 - Math.sqrt(5));
+  const out = new Float32Array(count * 3);
+  for (let i = 0; i < count; i++) {
+    const y = 1 - (i + 0.5) * 2 / count;
+    const r = Math.sqrt(1 - y * y);
+    const a = i * golden;
+    out[i * 3] = Math.cos(a) * r;
+    out[i * 3 + 1] = y;
+    out[i * 3 + 2] = Math.sin(a) * r;
+  }
+  return out;
+}
+const D100_BALL = {
+  version: 1,
+  id: "d100-ball",
+  sides: 100,
+  vertices: fibonacciSphere(100),
+  read: "face",
+  values: Object.fromEntries(Array.from({ length: 100 }, (_, i) => [String(i), i + 1])),
+  collider: "ball",
+  sizeMm: 22,
+  bevel: 0.1,
+  markScale: 0.3
+};
+const BUILTIN_DICE = [
+  D4,
+  D6,
+  D8,
+  D10,
+  D10_TENS,
+  D12,
+  D20,
+  D100_BALL
+];
+let registered = false;
+function registerBuiltinDice() {
+  if (registered) return;
+  registered = true;
+  for (const def of BUILTIN_DICE) defineDie(def);
+}
+const DIE_KINDS = ["d4", "d6", "d8", "d10", "d12", "d20", "d100", "percentile"];
+const KIND_DEFINITIONS = {
+  d4: ["d4"],
+  d6: ["d6"],
+  d8: ["d8"],
+  d10: ["d10"],
+  d12: ["d12"],
+  d20: ["d20"],
+  d100: ["d100-ball"],
+  percentile: ["d10-tens", "d10"]
+};
+function kindSides(kind) {
+  return kind === "percentile" || kind === "d100" ? 100 : Number(kind.slice(1));
+}
+function percentileValues(value) {
+  const tens = Math.floor(value % 100 / 10);
+  const units = value % 10;
+  return [tens === 0 ? 10 : tens, units === 0 ? 10 : units];
+}
+export {
+  BUILTIN_DICE,
+  D10,
+  D100_BALL,
+  D10_TENS,
+  D12,
+  D20,
+  D4,
+  D6,
+  D8,
+  DIE_KINDS,
+  KIND_DEFINITIONS,
+  kindSides,
+  percentileValues,
+  registerBuiltinDice
+};

package/dist/cells.d.ts

@@ -0,0 +1,33 @@
+import type { DieGeometry } from './definition.js';
+import { type V3 } from './math.js';
+export interface FaceCell {
+    face: number;
+    /** The value the face reads (undefined on a d4: its marks are per corner). */
+    value: number | undefined;
+    col: number;
+    row: number;
+    /** The face's frame: marks read up along `bitangent`. */
+    tangent: V3;
+    bitangent: V3;
+    center: V3;
+    /** Half the side of the square, in face units, that maps onto the cell's inner square. */
+    extent: number;
+}
+export interface CellLayout {
+    cols: number;
+    rows: number;
+    /** Cell side in atlas pixels. */
+    cell: number;
+    /** Margin inside each cell, as a fraction of its side. */
+    pad: number;
+    faces: FaceCell[];
+}
+export declare const CELL_PAD = 0.06;
+/** Distance range of the atlas, in pixels: marks shade from ±range / 2 of their outline. */
+export declare const MARK_RANGE = 8;
+/** The cells of a die's faces: a near-square grid, faces in polytope order. */
+export declare function cellLayout(g: DieGeometry): CellLayout;
+/** A point on a face in its cell's pixels: x right, y up from the cell's bottom-left corner. */
+export declare function cellPixel(layout: CellLayout, cell: FaceCell, p: V3): [number, number];
+/** A point on a face as atlas UVs (v down, as textures sample). */
+export declare function cellUv(layout: CellLayout, cell: FaceCell, p: V3, out: number[], o: number): void;

package/dist/cells.js

@@ -0,0 +1,53 @@
+import { cross, dot, stableTangent, sub } from "./math.js";
+const CELL_PAD = 0.06;
+const MARK_RANGE = 8;
+const layouts = /* @__PURE__ */ new WeakMap();
+function cellLayout(g) {
+  const cached = layouts.get(g);
+  if (cached) return cached;
+  const faces = g.polytope.faces;
+  const cols = Math.ceil(Math.sqrt(faces.length));
+  const rows = Math.ceil(faces.length / cols);
+  const cell = faces.length <= 24 ? 128 : 64;
+  const out = faces.map((face, i) => {
+    const value = g.faceValues[i];
+    const frame = value === void 0 ? void 0 : g.frames[value - 1];
+    const tangent = frame ? frame.tangent : stableTangent(face.normal);
+    const bitangent = frame ? frame.bitangent : cross(face.normal, tangent);
+    let extent = 1e-6;
+    for (const v of face.vertices) {
+      const d = sub(g.polytope.points[v], face.center);
+      extent = Math.max(extent, Math.abs(dot(d, tangent)), Math.abs(dot(d, bitangent)));
+    }
+    return {
+      face: i,
+      value,
+      col: i % cols,
+      row: Math.floor(i / cols),
+      tangent,
+      bitangent,
+      center: face.center,
+      extent
+    };
+  });
+  const layout = { cols, rows, cell, pad: CELL_PAD, faces: out };
+  layouts.set(g, layout);
+  return layout;
+}
+function cellPixel(layout, cell, p) {
+  const d = sub(p, cell.center);
+  const k = layout.cell * (1 - 2 * layout.pad) / (2 * cell.extent);
+  return [layout.cell / 2 + dot(d, cell.tangent) * k, layout.cell / 2 + dot(d, cell.bitangent) * k];
+}
+function cellUv(layout, cell, p, out, o) {
+  const [x, y] = cellPixel(layout, cell, p);
+  out[o] = (cell.col * layout.cell + x) / (layout.cols * layout.cell);
+  out[o + 1] = (cell.row * layout.cell + (layout.cell - y)) / (layout.rows * layout.cell);
+}
+export {
+  CELL_PAD,
+  MARK_RANGE,
+  cellLayout,
+  cellPixel,
+  cellUv
+};

package/dist/components.d.ts

@@ -0,0 +1,14 @@
+/** A die on the table. Spawned and despawned by the dice table; read-only to everyone else. */
+export declare const DiceDie: import("@aethervtt/shard-core").ComponentDef<{
+    readonly index: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    readonly kind: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly definition: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly value: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly label: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly dropped: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+/** Scene hook: an entity with this plays its roll when it appears (for shard screenshot, tests). */
+export declare const DiceRollRequest: import("@aethervtt/shard-core").ComponentDef<{
+    readonly roll: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+    readonly replace: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;

package/dist/components.js

@@ -0,0 +1,27 @@
+import { defineComponent, t } from "@aethervtt/shard-core";
+const DiceDie = defineComponent(
+  "dice/Die",
+  {
+    index: t.u8({ description: "Its body in the roll (percentile dice are two bodies)." }),
+    kind: t.string({ description: "The roll die kind: d4 \u2026 d20, d100, percentile." }),
+    definition: t.string({ description: "The die definition it shows." }),
+    value: t.u16({ description: "The definition's value on top once landed." }),
+    label: t.string({ description: "The printed mark on top." }),
+    dropped: t.bool({ description: "A dropped die: excluded from effects and attachments." })
+  },
+  { description: "A die the dice table is presenting." }
+);
+const DiceRollRequest = defineComponent(
+  "dice/RollRequest",
+  {
+    roll: t.json({
+      description: "A DiceRoll: { id, dice: [{ kind, value, skin: { guid } }], seed, tray, motion, \u2026 }."
+    }),
+    replace: t.bool({ description: "Dismiss a roll that is playing instead of waiting for it." })
+  },
+  { description: "Plays a dice roll when spawned; removed once the table takes it." }
+);
+export {
+  DiceDie,
+  DiceRollRequest
+};

package/dist/definition-asset.d.ts

@@ -0,0 +1,19 @@
+import { type Infer } from '@aethervtt/shard-core';
+import type { DieDefinition } from './definition.js';
+export declare const DieDefinitionAsset: import("@aethervtt/shard-assets").DataType<{
+    readonly version: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    readonly id: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly sides: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    readonly vertices: import("@aethervtt/shard-core").FieldType<number[], "object">;
+    readonly read: import("@aethervtt/shard-core").FieldType<"face" | "vertex", "u8">;
+    readonly values: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+    readonly labels: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+    readonly collider: import("@aethervtt/shard-core").FieldType<"ball" | "hull", "u8">;
+    readonly sizeMm: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly bevel: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly markScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly oppositesSum: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}, "dice/DieDefinition">;
+export type DieDefinitionAssetValue = Infer<typeof DieDefinitionAsset>;
+/** The definition a `*.die.json` describes (check it with validateDieDefinition). */
+export declare function dieDefinitionOf(value: DieDefinitionAssetValue): DieDefinition;

package/dist/definition-asset.js

@@ -0,0 +1,60 @@
+import { defineDataType } from "@aethervtt/shard-assets";
+import { t } from "@aethervtt/shard-core";
+const DieDefinitionAsset = defineDataType(
+  "dice/DieDefinition",
+  {
+    version: t.u8({ default: 1, min: 1, max: 1, description: "Format version: 1." }),
+    id: t.string({ description: "'d20', 'd10-tens', 'd100-ball'." }),
+    sides: t.u8({ min: 2, max: 100, description: "How many values it shows." }),
+    vertices: t.list(t.f32(), {
+      description: "Canonical points, x y z each, unit radius, in a fixed order: vertex ids index them."
+    }),
+    read: t.enum(["face", "vertex"], {
+      description: "The face on top reads, or (d4) the vertex on top."
+    }),
+    values: t.json({
+      default: {},
+      description: "Value by sorted vertex ids of a face ('0:1:4:5') or by a vertex id ('3')."
+    }),
+    labels: t.json({
+      default: {},
+      description: "The printed mark per value where it isn't the value ('00')."
+    }),
+    collider: t.enum(["hull", "ball"], { description: "A hull of the vertices, or a ball." }),
+    sizeMm: t.f32({ default: 16, min: 1, unit: "mm", description: "Landed footprint diameter." }),
+    bevel: t.f32({
+      default: 0.082,
+      min: 0,
+      max: 0.3,
+      description: "Chamfer toward each face center."
+    }),
+    markScale: t.f32({
+      default: 0.4,
+      min: 0.05,
+      max: 1,
+      description: "Mark height, of a face's size."
+    }),
+    oppositesSum: t.bool({ description: "Opposite faces must sum to sides + 1." })
+  },
+  { extension: "die", description: "A die: its shape, numbering and printed labels." }
+);
+function dieDefinitionOf(value) {
+  return {
+    version: 1,
+    id: value.id,
+    sides: value.sides,
+    vertices: Float32Array.from(value.vertices),
+    read: value.read,
+    values: value.values,
+    labels: value.labels,
+    collider: value.collider,
+    sizeMm: value.sizeMm,
+    bevel: value.bevel,
+    markScale: value.markScale,
+    oppositesSum: value.oppositesSum
+  };
+}
+export {
+  DieDefinitionAsset,
+  dieDefinitionOf
+};

package/dist/definition.d.ts

@@ -0,0 +1,98 @@
+import { ShardError } from '@aethervtt/shard-core';
+import { type Face } from './hull.js';
+import { type Q4, type V3 } from './math.js';
+/**
+ * A die's shape and numbering, as data (0054). Built-ins cover d4 to d20, the two percentile d10s
+ * and a d100 ball; a host can register more with `defineDie`.
+ */
+export interface DieDefinition {
+    version: 1;
+    /** 'd20', 'd10-tens', 'd100-ball'. */
+    id: string;
+    sides: number;
+    /**
+     * Canonical points, unit radius, in a fixed order: vertex ids are indices into it. For a ball,
+     * each point is a cell's center (its normal).
+     */
+    vertices: Float32Array;
+    /** The face on top reads, or (d4) the vertex on top. */
+    read: 'face' | 'vertex';
+    /**
+     * Value by sorted vertex ids of a face (`'0:1:4:5'`), or by a vertex id (`'3'`) for vertex dice
+     * and ball cells. Keyed by ids, so the numbering doesn't depend on the order a hull returns.
+     */
+    values: Record<string, number>;
+    /** The printed mark per value, where it isn't the value: `'00'` … `'90'`, or 10 → `'0'`. */
+    labels?: Record<number, string>;
+    /** A hull of the vertices, or a ball (every rotation is a symmetry). */
+    collider: 'hull' | 'ball';
+    /** Footprint diameter of a landed die, before the presentation scale. */
+    sizeMm: number;
+    /** Chamfer: how far each face corner moves toward its face's center (0..0.3). */
+    bevel: number;
+    /** Mark height as a fraction of a face's size (the atlas cell's inner square). */
+    markScale?: number;
+    /** Opposite faces must sum to `sides + 1` (checked by the validator). */
+    oppositesSum?: boolean;
+}
+/** A value's reading frame on the die: where it points, and which way its mark reads up. */
+export interface ValueFrame {
+    value: number;
+    /** The direction that's up when this value shows: a face normal, or the d4's vertex. */
+    normal: V3;
+    /** Across the mark, left to right. */
+    tangent: V3;
+    /** The mark's up. `tangent × bitangent = normal`. */
+    bitangent: V3;
+}
+/** What the engine derives from a definition, once per content hash. */
+export interface DieGeometry {
+    definition: DieDefinition;
+    hash: number;
+    /** Unit-radius points (a ball's cell centers). */
+    points: V3[];
+    /** The polytope that's drawn and (for hulls) collided: faces with ordered vertices. */
+    polytope: {
+        points: V3[];
+        faces: Face[];
+    };
+    /** The value each polytope face carries (face dice), or undefined (d4: marks per corner). */
+    faceValues: (number | undefined)[];
+    /** d4: the value at each point (vertex id → value). */
+    vertexValues: number[] | undefined;
+    /** Frames by value (index value − 1). */
+    frames: ValueFrame[];
+    /** Rotations mapping the die onto itself; empty for a ball (every rotation is one). */
+    symmetries: Q4[];
+    /** Landed footprint diameter at unit radius: the size a die of this definition shows. */
+    footprint: number;
+    /** Distance from the center to the floor when resting on a face (1 for a ball). */
+    restHeight: number;
+}
+/** 32-bit FNV-1a over the definition's canonical content. */
+export declare function dieHash(def: DieDefinition): number;
+/**
+ * Checks a definition and returns every problem, with a path to the field: every face (or vertex,
+ * or cell) has exactly one value, values are 1..sides with no duplicates, labels name real values,
+ * and opposite faces sum to `sides + 1` where the definition opts in.
+ */
+export declare function validateDieDefinition(def: DieDefinition): ShardError[];
+/**
+ * Derives a definition's faces, value frames and symmetry group, cached by its content hash.
+ * Throws `dice/invalid-definition` naming the first problem.
+ */
+export declare function dieGeometry(def: DieDefinition): DieGeometry;
+/** The value's frame, or `dice/invalid-value` if the die can't show it. */
+export declare function frameOf(geometry: DieGeometry, value: number): ValueFrame;
+/** The printed mark of a value: its label, or the value itself. */
+export declare function labelOf(def: DieDefinition, value: number): string;
+/**
+ * Registers a definition by id so skins and rolls can name it. Registering the same content again
+ * is a no-op; a different definition under a taken id throws `dice/registry-conflict`.
+ */
+export declare function defineDie(def: DieDefinition): DieDefinition;
+export declare function findDie(id: string): DieDefinition | undefined;
+export declare function requireDie(id: string): DieDefinition;
+export declare function allDice(): DieDefinition[];
+/** Scale of a die of `def` at presentation scale 1: its footprint is `sizeMm` relative to the d20's 18 mm. */
+export declare function physicalScale(geometry: DieGeometry, reference: DieGeometry): number;