@aethervtt/shard-dice 0.0.0-stage → 0.2.0

package/dist/definition.js

@@ -0,0 +1,320 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { convexFaces, pointsOf, symmetryGroup, tangentPolytope } from "./hull.js";
+import {
+  cross,
+  dot,
+  EPSILON,
+  length,
+  normalize,
+  qKey,
+  qRotate,
+  round,
+  scale,
+  stableTangent,
+  sub,
+  tangentOf
+} from "./math.js";
+function invalid(message, path, hint) {
+  return new ShardError("dice/invalid-definition", message, {
+    path,
+    hint: hint ?? "See DieDefinition in @aethervtt/shard-dice."
+  });
+}
+function dieHash(def) {
+  const canonical = JSON.stringify([
+    def.version,
+    def.id,
+    def.sides,
+    Array.from(def.vertices),
+    def.read,
+    Object.keys(def.values).sort().map((k) => [k, def.values[k]]),
+    Object.keys(def.labels ?? {}).map(Number).sort((a, b) => a - b).map((k) => [k, def.labels[k]]),
+    def.collider,
+    def.sizeMm,
+    def.bevel,
+    def.markScale ?? null,
+    def.oppositesSum ?? false
+  ]);
+  let h = 2166136261;
+  for (let i = 0; i < canonical.length; i++) {
+    h ^= canonical.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+const faceKey = (face) => [...face.vertices].sort((a, b) => a - b).join(":");
+function validateDieDefinition(def) {
+  const errors = [];
+  if (def.version !== 1) errors.push(invalid(`Version ${def.version} isn't 1`, "/version"));
+  if (typeof def.id !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(def.id))
+    errors.push(invalid(`id "${def.id}" isn't a lowercase id`, "/id"));
+  if (!Number.isInteger(def.sides) || def.sides < 2 || def.sides > 100)
+    errors.push(invalid("sides must be an integer from 2 to 100", "/sides"));
+  const v = def.vertices;
+  if (!(v instanceof Float32Array) || v.length < 12 || v.length % 3 !== 0) {
+    errors.push(invalid("vertices needs 4 or more x y z points in a Float32Array", "/vertices"));
+    return errors;
+  }
+  const points = pointsOf(v);
+  const radius = Math.max(...points.map(length));
+  if (Math.abs(radius - 1) > 1e-3)
+    errors.push(invalid(`vertices reach radius ${radius.toFixed(4)}, not 1`, "/vertices"));
+  if (def.collider === "ball") {
+    points.forEach((p, i) => {
+      if (Math.abs(length(p) - 1) > 1e-3)
+        errors.push(invalid(`Ball cell ${i} isn't on the unit sphere`, `/vertices/${i * 3}`));
+    });
+  }
+  if (!(def.sizeMm > 0)) errors.push(invalid("sizeMm must be positive", "/sizeMm"));
+  if (!(def.bevel >= 0 && def.bevel <= 0.3))
+    errors.push(invalid("bevel must be from 0 to 0.3", "/bevel"));
+  if (errors.length > 0) return errors;
+  const keys = [];
+  if (def.read === "vertex" || def.collider === "ball") {
+    for (let i = 0; i < points.length; i++) keys.push(String(i));
+  } else {
+    for (const face of convexFaces(points)) keys.push(faceKey(face));
+  }
+  if (keys.length !== def.sides) {
+    errors.push(
+      invalid(
+        `The shape has ${keys.length} ${def.read === "vertex" ? "vertices" : "faces"}, not ${def.sides}`,
+        "/sides"
+      )
+    );
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const key of keys) {
+    const value = def.values[key];
+    if (value === void 0) {
+      errors.push(
+        invalid(`Face ${key} has no value`, `/values/${key}`, `Give it one of 1..${def.sides}.`)
+      );
+      continue;
+    }
+    if (!Number.isInteger(value) || value < 1 || value > def.sides) {
+      errors.push(invalid(`Face ${key} has value ${value}, not 1..${def.sides}`, `/values/${key}`));
+      continue;
+    }
+    const other = seen.get(value);
+    if (other !== void 0)
+      errors.push(invalid(`Faces ${other} and ${key} both have value ${value}`, `/values/${key}`));
+    seen.set(value, key);
+  }
+  for (const key of Object.keys(def.values)) {
+    if (!keys.includes(key))
+      errors.push(invalid(`values names ${key}, which isn't a face of the shape`, `/values/${key}`));
+  }
+  for (const key of Object.keys(def.labels ?? {})) {
+    const value = Number(key);
+    if (!seen.has(value))
+      errors.push(invalid(`labels names value ${key}, which no face has`, `/labels/${key}`));
+  }
+  if (def.oppositesSum && def.read === "face" && def.collider === "hull") {
+    const faces = convexFaces(points);
+    for (const face of faces) {
+      const opposite = faces.find((f) => dot(f.normal, face.normal) < -1 + 1e-4);
+      if (!opposite) {
+        errors.push(invalid(`Face ${faceKey(face)} has no opposite face`, "/oppositesSum"));
+        continue;
+      }
+      const a = def.values[faceKey(face)];
+      const b = def.values[faceKey(opposite)];
+      if (a !== void 0 && b !== void 0 && a + b !== def.sides + 1) {
+        errors.push(
+          invalid(
+            `Opposite faces ${faceKey(face)} (${a}) and ${faceKey(opposite)} (${b}) don't sum to ${def.sides + 1}`,
+            `/values/${faceKey(face)}`
+          )
+        );
+      }
+    }
+  }
+  return errors;
+}
+function markUp(points, face) {
+  const d = face.vertices.map((i) => length(sub(points[i], face.center)));
+  const far = Math.max(...d);
+  const farthest = face.vertices.filter((_, k) => d[k] > far - 1e-4);
+  let toward;
+  if (farthest.length === 1) toward = points[farthest[0]];
+  else if (face.vertices.length % 2 === 1) toward = points[Math.min(...face.vertices)];
+  else {
+    const vs = face.vertices;
+    let best = [vs[0], vs[1]];
+    let bestKey = Number.POSITIVE_INFINITY;
+    for (let k = 0; k < vs.length; k++) {
+      const a = vs[k];
+      const b = vs[(k + 1) % vs.length];
+      const key = Math.min(a, b) * 1e3 + Math.max(a, b);
+      if (key < bestKey) {
+        bestKey = key;
+        best = [a, b];
+      }
+    }
+    toward = scale(add3(points[best[0]], points[best[1]]), 0.5);
+  }
+  return tangentOf(sub(toward, face.center), face.normal);
+}
+const add3 = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+function footprintOf(points, down) {
+  let r = 0;
+  for (const p of points) {
+    const along = dot(p, down);
+    const x = sub(p, scale(down, along));
+    r = Math.max(r, length(x));
+  }
+  return r * 2;
+}
+const cache = /* @__PURE__ */ new Map();
+const byObject = /* @__PURE__ */ new WeakMap();
+function dieGeometry(def) {
+  const known = byObject.get(def);
+  if (known) return known;
+  const hash = dieHash(def);
+  const cached = cache.get(hash);
+  if (cached) {
+    byObject.set(def, cached);
+    return cached;
+  }
+  const errors = validateDieDefinition(def);
+  if (errors.length > 0) throw errors[0];
+  const points = pointsOf(def.vertices).map((p) => p.map(round));
+  const ball = def.collider === "ball";
+  const polytope = ball ? tangentPolytope(points.map(normalize)) : { points, faces: convexFaces(points) };
+  const symmetries = ball ? [] : symmetryGroup(points);
+  const directions = [];
+  let faceValues;
+  let vertexValues;
+  if (def.read === "vertex") {
+    vertexValues = points.map((_, i) => def.values[String(i)]);
+    faceValues = polytope.faces.map(() => void 0);
+    points.forEach((p, i) => {
+      directions.push({ value: vertexValues[i], normal: normalize(p), face: void 0 });
+    });
+  } else if (ball) {
+    faceValues = points.map((_, i) => def.values[String(i)]);
+    polytope.faces.forEach((face, i) => {
+      directions.push({ value: faceValues[i], normal: face.normal, face });
+    });
+  } else {
+    faceValues = polytope.faces.map((f) => def.values[faceKey(f)]);
+    polytope.faces.forEach((face, i) => {
+      directions.push({ value: faceValues[i], normal: face.normal, face });
+    });
+  }
+  directions.sort((a, b) => a.value - b.value);
+  const frames = [];
+  if (ball) {
+    for (const d of directions) {
+      const n = d.normal;
+      const pole = Math.abs(n[1]) > 0.999 ? [0, 0, n[1] > 0 ? -1 : 1] : [0, 1, 0];
+      const b = tangentOf(pole, n);
+      frames.push({ value: d.value, normal: n, tangent: cross(b, n), bitangent: b });
+    }
+  } else {
+    const ref = directions[0];
+    let refUp;
+    if (def.read === "vertex") {
+      const vertex = points.findIndex((_, i) => vertexValues[i] === ref.value);
+      const adjacent = polytope.faces.filter((f) => f.vertices.includes(vertex)).sort((a, b) => Math.min(...a.vertices) - Math.min(...b.vertices))[0];
+      refUp = adjacent ? tangentOf(sub(points[vertex], adjacent.center), ref.normal) : stableTangent(ref.normal);
+    } else {
+      refUp = markUp(points, ref.face);
+    }
+    for (const d of directions) {
+      const candidates = symmetries.filter((q2) => length(sub(qRotate(q2, ref.normal), d.normal)) < EPSILON * 10).sort((a, b2) => qKey(a).localeCompare(qKey(b2)));
+      const q = candidates[0];
+      if (!q) {
+        throw invalid(
+          `No symmetry of ${def.id} carries value ${ref.value}'s face to value ${d.value}'s`,
+          "/vertices",
+          "Dice need a symmetry group that moves every face to every other (fair dice have one)."
+        );
+      }
+      const b = normalize(qRotate(q, refUp));
+      frames.push({ value: d.value, normal: d.normal, tangent: cross(b, d.normal), bitangent: b });
+    }
+  }
+  const up = frames[0].normal;
+  const down = scale(up, -1);
+  let rest = 0;
+  for (const p of polytope.points) rest = Math.max(rest, dot(p, down));
+  const geometry = {
+    definition: def,
+    hash,
+    points,
+    polytope,
+    faceValues,
+    vertexValues,
+    frames,
+    symmetries,
+    footprint: footprintOf(ball ? polytope.points : points, down),
+    restHeight: ball ? 1 : rest
+  };
+  cache.set(hash, geometry);
+  byObject.set(def, geometry);
+  return geometry;
+}
+function frameOf(geometry, value) {
+  const frame = Number.isInteger(value) ? geometry.frames[value - 1] : void 0;
+  if (!frame || frame.value !== value) {
+    throw new ShardError(
+      "dice/invalid-value",
+      `A ${geometry.definition.id} can't show ${value}: its values are 1 to ${geometry.frames.length}`,
+      { hint: "The host decides the result; pass one the die has." }
+    );
+  }
+  return frame;
+}
+function labelOf(def, value) {
+  return def.labels?.[value] ?? String(value);
+}
+const definitions = /* @__PURE__ */ new Map();
+function defineDie(def) {
+  const existing = definitions.get(def.id);
+  if (existing) {
+    if (dieHash(existing) === dieHash(def)) return existing;
+    throw new ShardError(
+      "dice/registry-conflict",
+      `Die "${def.id}" is already defined, differently`,
+      {
+        hint: "Give the new definition its own id."
+      }
+    );
+  }
+  const errors = validateDieDefinition(def);
+  if (errors.length > 0) throw errors[0];
+  definitions.set(def.id, def);
+  return def;
+}
+function findDie(id) {
+  return definitions.get(id);
+}
+function requireDie(id) {
+  const def = definitions.get(id);
+  if (!def) {
+    throw new ShardError("dice/unknown-die", `No die definition "${id}"`, {
+      hint: `Defined: ${[...definitions.keys()].join(", ")}. Register others with defineDie.`
+    });
+  }
+  return def;
+}
+function allDice() {
+  return [...definitions.values()];
+}
+function physicalScale(geometry, reference) {
+  return geometry.definition.sizeMm / reference.definition.sizeMm * (reference.footprint / geometry.footprint);
+}
+export {
+  allDice,
+  defineDie,
+  dieGeometry,
+  dieHash,
+  findDie,
+  frameOf,
+  labelOf,
+  physicalScale,
+  requireDie,
+  validateDieDefinition
+};

package/dist/dice-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dice-worker.js

@@ -0,0 +1,3 @@
+import { serveTracks } from "@aethervtt/shard-physics/worker";
+import { DICE_SETTLE_RULE, diceSettle } from "./settle.js";
+serveTracks({ rules: { [DICE_SETTLE_RULE]: diceSettle } });

package/dist/effects.d.ts

@@ -0,0 +1,99 @@
+import { type FieldValue, type Infer, ShardError } from '@aethervtt/shard-core';
+import type { DiceRoll, PhysicalDie } from './roll.js';
+declare const CONDITION: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+    kind: import("@aethervtt/shard-core").FieldType<"die" | "source" | "tag" | "total", "u8">;
+    die: import("@aethervtt/shard-core").FieldType<"any" | "d10" | "d100" | "d12" | "d20" | "d4" | "d6" | "d8" | "percentile", "u8">;
+    value: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    face: import("@aethervtt/shard-core").FieldType<string, "object">;
+    state: import("@aethervtt/shard-core").FieldType<"any" | "dropped" | "kept", "u8">;
+    rank: import("@aethervtt/shard-core").FieldType<"any" | "high" | "low", "u8">;
+    compare: import("@aethervtt/shard-core").FieldType<"eq" | "gte" | "lte", "u8">;
+    total: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    source: import("@aethervtt/shard-core").FieldType<"gm" | "mine" | "other", "u8">;
+    tag: import("@aethervtt/shard-core").FieldType<string, "object">;
+}>, "object">;
+declare const EFFECT: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+    kind: import("@aethervtt/shard-core").FieldType<"attachment" | "entrance" | "lens-pulse" | "light-pulse" | "particle-burst" | "sound-accent", "u8">;
+    color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    colors: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color[], "object">;
+    intensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    count: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    durationMs: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    cue: import("@aethervtt/shard-core").FieldType<"arcane-spark" | "resin-chime" | "void-whump", "u8">;
+    event: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"audio/AudioEvent"> | null, "object">;
+    gain: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    strength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    attachment: import("@aethervtt/shard-core").FieldType<string, "object">;
+    entrance: import("@aethervtt/shard-core").FieldType<string, "object">;
+    params: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+}>, "object">;
+/** An effect recipe: `data/**\/*.dice-effect.json`. */
+export declare const DiceEffectRecipe: import("@aethervtt/shard-assets").DataType<{
+    readonly version: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    readonly id: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly match: import("@aethervtt/shard-core").FieldType<"all" | "any", "u8">;
+    readonly conditions: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        kind: import("@aethervtt/shard-core").FieldType<"die" | "source" | "tag" | "total", "u8">;
+        die: import("@aethervtt/shard-core").FieldType<"any" | "d10" | "d100" | "d12" | "d20" | "d4" | "d6" | "d8" | "percentile", "u8">;
+        value: import("@aethervtt/shard-core").FieldType<number, "u16">;
+        face: import("@aethervtt/shard-core").FieldType<string, "object">;
+        state: import("@aethervtt/shard-core").FieldType<"any" | "dropped" | "kept", "u8">;
+        rank: import("@aethervtt/shard-core").FieldType<"any" | "high" | "low", "u8">;
+        compare: import("@aethervtt/shard-core").FieldType<"eq" | "gte" | "lte", "u8">;
+        total: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        source: import("@aethervtt/shard-core").FieldType<"gm" | "mine" | "other", "u8">;
+        tag: import("@aethervtt/shard-core").FieldType<string, "object">;
+    }>[], "object">;
+    readonly effects: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        kind: import("@aethervtt/shard-core").FieldType<"attachment" | "entrance" | "lens-pulse" | "light-pulse" | "particle-burst" | "sound-accent", "u8">;
+        color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+        colors: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color[], "object">;
+        intensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        count: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        durationMs: import("@aethervtt/shard-core").FieldType<number, "u16">;
+        cue: import("@aethervtt/shard-core").FieldType<"arcane-spark" | "resin-chime" | "void-whump", "u8">;
+        event: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"audio/AudioEvent"> | null, "object">;
+        gain: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        strength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        attachment: import("@aethervtt/shard-core").FieldType<string, "object">;
+        entrance: import("@aethervtt/shard-core").FieldType<string, "object">;
+        params: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+    }>[], "object">;
+}, "dice/DiceEffectRecipe">;
+export type DiceEffectRecipeValue = Infer<typeof DiceEffectRecipe>;
+export type DiceEffect = FieldValue<typeof EFFECT>;
+export type DiceCondition = FieldValue<typeof CONDITION>;
+export declare const RECIPE_LIMITS: {
+    conditions: number;
+    effects: number;
+    particles: number;
+    colors: number;
+    minDurationMs: number;
+    maxDurationMs: number;
+    recipesPerRoll: number;
+    params: number;
+};
+/** A recipe from its JSON form, with defaults filled in. */
+export declare function diceEffectRecipe(json: Record<string, unknown>): DiceEffectRecipeValue;
+/** A recipe's problems, each with a path into it. */
+export declare function recipeProblems(recipe: DiceEffectRecipeValue): ShardError[];
+/** A recipe that matched, and the dice its effects play on. */
+export interface MatchedRecipe {
+    recipe: DiceEffectRecipeValue;
+    /**
+     * Kept dice its effects anchor to: those meeting a die condition, or every kept die when it has
+     * none. Dropped dice never anchor effects, though conditions can match `state: 'dropped'`.
+     */
+    anchors: number[];
+}
+/**
+ * The recipes that play for a roll: each distinct one (by id) whose conditions match, at most 4.
+ * `degraded` says a bound refused more.
+ */
+export declare function matchRecipes(recipes: readonly DiceEffectRecipeValue[], roll: DiceRoll, dice: readonly PhysicalDie[]): {
+    matched: MatchedRecipe[];
+    degraded: boolean;
+};
+export {};

package/dist/effects.js

@@ -0,0 +1,200 @@
+import { defineDataType } from "@aethervtt/shard-assets";
+import { ShardError, t } from "@aethervtt/shard-core";
+import { DIE_KINDS } from "./builtins.js";
+const CONDITION = t.struct(
+  {
+    kind: t.enum(["die", "total", "source", "tag"], {
+      description: "die: a die of the roll matches; total: the roll total compares; source: who rolled; tag: a host tag."
+    }),
+    die: t.enum(["any", ...DIE_KINDS], { description: "die: the kind (any)." }),
+    value: t.u16({ description: "die: the value (0: any)." }),
+    face: t.string({ description: "die: the printed label on top ('00'); empty: any." }),
+    state: t.enum(["any", "kept", "dropped"], { description: "die: kept or dropped." }),
+    rank: t.enum(["any", "high", "low"], { description: "die: flagged high or low by the host." }),
+    compare: t.enum(["eq", "gte", "lte"], { description: "total: how it compares." }),
+    total: t.f32({ description: "total: the value compared with." }),
+    source: t.enum(["mine", "gm", "other"], { description: "source: who rolled." }),
+    tag: t.string({ description: "tag: a host semantic tag." })
+  },
+  { description: "One condition." }
+);
+const EFFECT = t.struct(
+  {
+    kind: t.enum(
+      ["light-pulse", "particle-burst", "sound-accent", "lens-pulse", "attachment", "entrance"],
+      {
+        description: "light-pulse: a point light swells and fades; particle-burst: CPU particles; sound-accent: a cue; lens-pulse: a lens field (0063) on the die; attachment: a registered scene on each matching die; entrance: a registered scene brings each matching die in instead of the tumble (0065)."
+      }
+    ),
+    color: t.color({ default: [1, 0.82, 0.45, 1], description: "light-pulse: color." }),
+    colors: t.list(t.color(), { description: "particle-burst: 1 to 4 colors." }),
+    intensity: t.f32({ default: 2, min: 0, max: 8, description: "light-pulse: 0..8." }),
+    count: t.u8({ default: 24, description: "particle-burst: particles, at most 32." }),
+    durationMs: t.u16({
+      default: 700,
+      description: "light-pulse, particle-burst, lens-pulse: 100..1200 ms."
+    }),
+    cue: t.enum(["resin-chime", "arcane-spark", "void-whump"], {
+      description: "sound-accent: the cue."
+    }),
+    event: t.handle("audio/AudioEvent", {
+      description: "sound-accent: optional authored event replacing the procedural cue."
+    }),
+    gain: t.f32({ default: 0.7, min: 0, max: 1, description: "sound-accent: 0..1." }),
+    radius: t.f32({
+      default: 150,
+      min: 0,
+      unit: "px",
+      description: "lens-pulse: field radius (CSS px)."
+    }),
+    strength: t.f32({
+      default: -0.6,
+      min: -1,
+      max: 1,
+      description: "lens-pulse: below 0 pulls in."
+    }),
+    attachment: t.string({ description: "attachment: the name given to defineDiceAttachment." }),
+    entrance: t.string({ description: "entrance: the name given to defineDiceEntrance." }),
+    params: t.json({
+      default: {},
+      description: "attachment, entrance: what the scene reads (at most 16 keys), so skins share one."
+    })
+  },
+  { description: "One effect." }
+);
+const DiceEffectRecipe = defineDataType(
+  "dice/DiceEffectRecipe",
+  {
+    version: t.u8({ default: 1, min: 1, max: 1, description: "Format version: 1." }),
+    id: t.string({ description: "Unique per recipe; the same recipe on two skins plays once." }),
+    match: t.enum(["all", "any"], {
+      description: "Every condition, or any of them. No conditions: always."
+    }),
+    conditions: t.list(CONDITION, { description: "At most 8." }),
+    effects: t.list(EFFECT, { description: "1 to 3." })
+  },
+  {
+    extension: "dice-effect",
+    lazyDependencies: true,
+    description: "Effects a skin plays when a roll matches its conditions."
+  }
+);
+const RECIPE_LIMITS = {
+  conditions: 8,
+  effects: 3,
+  particles: 32,
+  colors: 4,
+  minDurationMs: 100,
+  maxDurationMs: 1200,
+  recipesPerRoll: 4,
+  params: 16
+};
+function diceEffectRecipe(json) {
+  return DiceEffectRecipe.deserialize(json);
+}
+function bounds(message, path) {
+  return new ShardError("dice/recipe-bounds", message, {
+    path,
+    hint: `Recipes hold at most ${RECIPE_LIMITS.conditions} conditions and ${RECIPE_LIMITS.effects} effects; bursts ${RECIPE_LIMITS.particles} particles; durations ${RECIPE_LIMITS.minDurationMs}\u2013${RECIPE_LIMITS.maxDurationMs} ms; scene params ${RECIPE_LIMITS.params} keys.`
+  });
+}
+function recipeProblems(recipe) {
+  const out = [];
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(recipe.id))
+    out.push(
+      new ShardError("dice/invalid-recipe", `Recipe id "${recipe.id}" isn't a lowercase id`, {
+        path: "/id"
+      })
+    );
+  if (recipe.conditions.length > RECIPE_LIMITS.conditions)
+    out.push(
+      bounds(`Recipe "${recipe.id}" has ${recipe.conditions.length} conditions`, "/conditions")
+    );
+  if (recipe.effects.length < 1 || recipe.effects.length > RECIPE_LIMITS.effects)
+    out.push(bounds(`Recipe "${recipe.id}" has ${recipe.effects.length} effects`, "/effects"));
+  recipe.effects.forEach((e, i) => {
+    const path = `/effects/${i}`;
+    if (e.kind === "particle-burst") {
+      if (e.count < 1 || e.count > RECIPE_LIMITS.particles)
+        out.push(bounds(`A burst of ${e.count} particles`, `${path}/count`));
+      if (e.colors.length < 1 || e.colors.length > RECIPE_LIMITS.colors)
+        out.push(bounds(`A burst with ${e.colors.length} colors`, `${path}/colors`));
+    }
+    if (e.kind === "light-pulse" || e.kind === "particle-burst" || e.kind === "lens-pulse") {
+      if (e.durationMs < RECIPE_LIMITS.minDurationMs || e.durationMs > RECIPE_LIMITS.maxDurationMs)
+        out.push(bounds(`A ${e.durationMs} ms ${e.kind}`, `${path}/durationMs`));
+    }
+    if (e.kind === "attachment" && !e.attachment)
+      out.push(
+        new ShardError("dice/invalid-recipe", "An attachment effect names no attachment", {
+          path: `${path}/attachment`
+        })
+      );
+    if (e.kind === "entrance" && !e.entrance)
+      out.push(
+        new ShardError("dice/invalid-recipe", "An entrance effect names no entrance", {
+          path: `${path}/entrance`
+        })
+      );
+    const params = e.params;
+    if (params && typeof params === "object" && Object.keys(params).length > RECIPE_LIMITS.params)
+      out.push(bounds(`Params with ${Object.keys(params).length} keys`, `${path}/params`));
+  });
+  return out;
+}
+function dieMatches(c, d) {
+  if (c.die !== "any" && c.die !== d.kind) return false;
+  if (c.value !== 0 && c.value !== d.rolled) return false;
+  if (c.face && c.face !== d.label) return false;
+  if (c.state === "kept" && d.dropped) return false;
+  if (c.state === "dropped" && !d.dropped) return false;
+  if (c.rank === "high" && !d.high) return false;
+  if (c.rank === "low" && !d.low) return false;
+  return true;
+}
+function conditionMatches(c, roll, dice) {
+  switch (c.kind) {
+    case "total":
+      if (roll.total === void 0) return false;
+      return c.compare === "eq" ? roll.total === c.total : c.compare === "gte" ? roll.total >= c.total : roll.total <= c.total;
+    case "source": {
+      if (!roll.source) return false;
+      const who = roll.source.mine ? "mine" : roll.source.gm ? "gm" : "other";
+      return who === c.source;
+    }
+    case "tag":
+      return roll.tags?.includes(c.tag) ?? false;
+    default:
+      return dice.some((d) => dieMatches(c, d));
+  }
+}
+function matchRecipes(recipes, roll, dice) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const r of recipes) if (!unique.has(r.id)) unique.set(r.id, r);
+  const matched = [];
+  let degraded = false;
+  for (const recipe of unique.values()) {
+    const cs = recipe.conditions;
+    const ok = cs.length === 0 || (recipe.match === "all" ? cs.every((c) => conditionMatches(c, roll, dice)) : cs.some((c) => conditionMatches(c, roll, dice)));
+    if (!ok) continue;
+    if (matched.length >= RECIPE_LIMITS.recipesPerRoll) {
+      degraded = true;
+      continue;
+    }
+    const dieConditions = cs.filter((c) => c.kind === "die");
+    const anchors = [];
+    dice.forEach((d, i) => {
+      if (d.dropped) return;
+      if (dieConditions.length === 0 || dieConditions.some((c) => dieMatches(c, d))) anchors.push(i);
+    });
+    matched.push({ recipe, anchors });
+  }
+  return { matched, degraded };
+}
+export {
+  DiceEffectRecipe,
+  RECIPE_LIMITS,
+  diceEffectRecipe,
+  matchRecipes,
+  recipeProblems
+};

package/dist/entrances.d.ts

@@ -0,0 +1,48 @@
+import { type AssetRef, type Entity } from '@aethervtt/shard-core';
+import { type DiceSceneContext } from './attachments.js';
+/** Entrance dice in one roll; more matches tumble. */
+export declare const MAX_ENTRANCES = 2;
+/** What an entrance's scene can reach and do: a scene's context, and the die it brings in. */
+export interface DiceEntranceContext extends DiceSceneContext {
+    /** Where the die lands: the table's choice, target up with the readable twist. */
+    rest: {
+        position: [number, number, number];
+        rotation: [number, number, number, number];
+    };
+    /** When it lands, seconds from the scene's start. */
+    landAt: number;
+    /** The host skipped: the die has landed; wind down within 400 ms. */
+    readonly skipped: boolean;
+    /** Places the die this frame, before it lands (the table owns it after). */
+    pose(position: ArrayLike<number>, rotation: ArrayLike<number>, scale?: number): void;
+    /** Shows or hides the die before it lands (it starts hidden; landing shows it). */
+    show(visible: boolean): void;
+    /** Sets the family's own fields on this die's material (not the dice fields). */
+    material(fields: Record<string, unknown>): void;
+}
+export interface DiceEntranceDef {
+    /** Vertices it draws, within `DICE_BUDGETS.entranceVertices`: declared, and held to. */
+    vertices: number;
+    /** The whole scene, in ms, within `DICE_BUDGETS.entranceMs`. */
+    durationMs: number;
+    /** When the die lands, in ms from the start: at most `durationMs`. */
+    landAtMs: number;
+    /** Where it wants the die: the tray's center, or [u, v] in −1..1 of the tray. Default center. */
+    spot?: 'center' | readonly [number, number];
+    /** How hard the die lands, 0..1: its impact sound. Default 0.8. */
+    impact?: number;
+    /** Loaded before it plays; a roll waits at most 1.5 s for them after the physics is ready. */
+    assets?: readonly AssetRef[];
+    /** Spawns the scene; returns what it spawned (the table despawns it). */
+    spawn(ctx: DiceEntranceContext): Entity[];
+    /** Every frame from the start, with seconds since. Return false to end it early. */
+    update?(ctx: DiceEntranceContext, seconds: number, entities: readonly Entity[]): boolean | undefined;
+}
+/**
+ * Registers a scene that brings a die in (0065). Throws `dice/entrance-budget` for a scene over the
+ * budgets, `dice/invalid-entrance` for a landing outside it, `dice/registry-conflict` for a name
+ * taken.
+ */
+export declare function defineDiceEntrance(name: string, def: DiceEntranceDef): DiceEntranceDef;
+export declare function findDiceEntrance(name: string): DiceEntranceDef | undefined;
+export declare function allDiceEntrances(): string[];