@aethervtt/shard-dice 0.0.0-stage → 0.1.0

package/dist/effects.js

@@ -0,0 +1,196 @@
+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."
+    }),
+    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",
+    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[];

package/dist/entrances.js

@@ -0,0 +1,54 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { DICE_BUDGETS } from "./attachments.js";
+const MAX_ENTRANCES = 2;
+const entrances = /* @__PURE__ */ new Map();
+function budget(name, message) {
+  return new ShardError("dice/entrance-budget", `Entrance "${name}" ${message}`, {
+    hint: "Trim the scene, or raise DICE_BUDGETS with setDiceBudgets before defining it."
+  });
+}
+function defineDiceEntrance(name, def) {
+  if (!(def.vertices > 0) || def.vertices > DICE_BUDGETS.entranceVertices) {
+    throw budget(
+      name,
+      `declares ${def.vertices} vertices; the budget is ${DICE_BUDGETS.entranceVertices}`
+    );
+  }
+  if (!(def.durationMs > 0) || def.durationMs > DICE_BUDGETS.entranceMs) {
+    throw budget(name, `runs ${def.durationMs} ms; the budget is ${DICE_BUDGETS.entranceMs}`);
+  }
+  if (!(def.landAtMs >= 0 && def.landAtMs <= def.durationMs)) {
+    throw new ShardError(
+      "dice/invalid-entrance",
+      `Entrance "${name}" lands at ${def.landAtMs} ms, outside its ${def.durationMs} ms`,
+      { hint: "landAtMs is when the die lands: between 0 and durationMs.", path: "landAtMs" }
+    );
+  }
+  const spot = def.spot;
+  if (spot && spot !== "center" && !(Math.abs(spot[0]) <= 1 && Math.abs(spot[1]) <= 1)) {
+    throw new ShardError("dice/invalid-entrance", `Entrance "${name}" wants a spot off the tray`, {
+      hint: "spot is 'center', or [u, v] with each in \u22121..1 of the tray.",
+      path: "spot"
+    });
+  }
+  const existing = entrances.get(name);
+  if (existing && existing !== def) {
+    throw new ShardError("dice/registry-conflict", `Entrance "${name}" is already defined`, {
+      hint: "Give the new entrance its own name."
+    });
+  }
+  entrances.set(name, def);
+  return def;
+}
+function findDiceEntrance(name) {
+  return entrances.get(name);
+}
+function allDiceEntrances() {
+  return [...entrances.keys()].sort();
+}
+export {
+  MAX_ENTRANCES,
+  allDiceEntrances,
+  defineDiceEntrance,
+  findDiceEntrance
+};

package/dist/families.d.ts

@@ -0,0 +1,17 @@
+/** Opaque, one color, a few flecks in the pour. */
+export declare const SOLID: import("./material.js").DiceFamily;
+/**
+ * Translucent-looking resin without transparency: a tonal depth fake. Looking straight into a
+ * face sees deep color, swirled through the body; grazing angles and the chamfer catch light like
+ * thin resin does. The face on top glows a little once landed.
+ */
+export declare const RESIN: import("./material.js").DiceFamily;
+/** Metal: tinted by baseColor, brushed, with polished worn edges and enamel marks. */
+export declare const METAL: import("./material.js").DiceFamily;
+/**
+ * Glass: blended, clear through the middle of a face and bright at grazing angles, with opaque
+ * marks. Blended dice cast no shadow, so they get a contact blob on the tray. Always see-through,
+ * but not a fixed blend: the large-pool tier draws it opaque, so its dice batch.
+ */
+export declare const GLASS: import("./material.js").DiceFamily;
+export declare const BUILTIN_FAMILIES: readonly [import("./material.js").DiceFamily, import("./material.js").DiceFamily, import("./material.js").DiceFamily, import("./material.js").DiceFamily];

package/dist/families.js

@@ -0,0 +1,131 @@
+import { t } from "@aethervtt/shard-core";
+import { defineDiceFamily } from "./material.js";
+const SOLID = defineDiceFamily("dice/SolidDice", {
+  fields: {
+    fleck: t.f32({
+      default: 0.25,
+      min: 0,
+      max: 1,
+      description: "How many flecks show in the body."
+    }),
+    fleckColor: t.color({ default: [1, 1, 1, 1], description: "Fleck color (linear)." }),
+    fleckScale: t.f32({
+      default: 16,
+      min: 1,
+      description: "Fleck density, per unit of die radius."
+    })
+  },
+  surface: `
+  let speck = smoothstep(0.8, 0.88, dice_noise(local * F.fleckScale));
+  p.base_color = mix(p.base_color, F.fleckColor.rgb, speck * F.fleck * m.face);`,
+  description: "Solid dice: an opaque body, optional flecks."
+});
+const RESIN = defineDiceFamily("dice/ResinDice", {
+  fields: {
+    resinDeep: t.color({
+      default: [0.02, 0.18, 0.2, 1],
+      description: "The deep tone, looking into the body."
+    }),
+    resinGlow: t.color({
+      default: [0.3, 0.9, 0.82, 1],
+      description: "The light tone, at thin edges."
+    }),
+    resinDepth: t.f32({
+      default: 0.85,
+      min: 0,
+      max: 1,
+      description: "How much of the tones replace baseColor."
+    }),
+    resinSwirl: t.f32({ default: 0.55, min: 0, max: 1, description: "Swirl through the pour." }),
+    resinScale: t.f32({
+      default: 2.4,
+      min: 0.1,
+      description: "Swirl size, per unit of die radius."
+    }),
+    resinLight: t.f32({
+      default: 2600,
+      min: 0,
+      unit: "cd/m\xB2",
+      description: "Light at thin edges."
+    }),
+    resinResultGlow: t.f32({
+      default: 3e3,
+      min: 0,
+      unit: "cd/m\xB2",
+      description: "Glow of the marks on top once landed."
+    }),
+    resinOpacity: t.f32({
+      default: 1,
+      min: 0.2,
+      max: 1,
+      description: "Below 1, the resin is see-through: its material blends (no shadow; a contact blob instead)."
+    })
+  },
+  surface: `
+  let nv = clamp(dot(p.normal, v), 0.0, 1.0);
+  let swirl = dice_fbm(local * F.resinScale + vec3f(value * 1.7));
+  let depth = clamp(pow(nv, 0.6) * (1.0 - 0.5 * F.resinSwirl) + swirl * F.resinSwirl * 0.6, 0.0, 1.0);
+  let tone = mix(F.resinGlow.rgb, F.resinDeep.rgb, depth);
+  p.base_color = mix(p.base_color, tone, F.resinDepth);
+  let thin = pow(1.0 - nv, 3.0) + (1.0 - m.face) * 0.45;
+  p.emissive += F.resinGlow.rgb * F.resinLight * thin;
+  p.emissive += look.mark_color.rgb * F.resinResultGlow * look.result * m.top * m.coverage;
+  p.roughness = min(p.roughness, 0.22);
+  p.alpha = F.resinOpacity;`,
+  translucent: (params) => typeof params.resinOpacity === "number" && params.resinOpacity < 1,
+  description: "Resin dice: a tonal depth fake, swirl, glowing thin edges, a lit result face."
+});
+const METAL = defineDiceFamily("dice/MetalDice", {
+  fields: {
+    metalWear: t.f32({ default: 0.6, min: 0, max: 1, description: "Polished, brighter edges." }),
+    metalGrain: t.f32({
+      default: 0.4,
+      min: 0,
+      max: 1,
+      description: "Brushed streaks in the roughness."
+    })
+  },
+  surface: `
+  p.metallic = 1.0;
+  let grain = dice_noise(local * vec3f(70.0, 2.5, 70.0));
+  p.roughness = clamp(p.roughness * (1.0 + (grain - 0.5) * F.metalGrain), 0.05, 1.0);
+  let edge = 1.0 - m.face;
+  p.roughness = mix(p.roughness, p.roughness * 0.35, edge * F.metalWear);
+  p.base_color = mix(p.base_color, min(p.base_color * 1.3 + vec3f(0.04), vec3f(1.0)), edge * F.metalWear);`,
+  description: "Metal dice: brushed, worn bright at the edges, enamel marks."
+});
+const GLASS = defineDiceFamily("dice/GlassDice", {
+  fields: {
+    glassClarity: t.f32({
+      default: 0.8,
+      min: 0,
+      max: 1,
+      description: "How clear the body is face-on."
+    }),
+    glassSparkle: t.f32({
+      default: 0.5,
+      min: 0,
+      max: 1,
+      description: "Inner glints as the die turns."
+    })
+  },
+  translucent: () => true,
+  surface: `
+  let nv = clamp(dot(p.normal, v), 0.0, 1.0);
+  let fresnel = pow(1.0 - nv, 2.5);
+  p.alpha = mix(1.0 - F.glassClarity, 0.9, fresnel) * m.face + (1.0 - m.face) * 0.55;
+  p.roughness = min(p.roughness, 0.08);
+  p.metallic = 0.0;
+  let glint = pow(dice_noise(local * 5.0 + v * 2.5), 10.0) * F.glassSparkle;
+  p.emissive += p.base_color * glint * 9000.0;
+  p.alpha = max(p.alpha, min(1.0, glint * 2.0));`,
+  description: "Glass dice: clear bodies, bright rims, opaque marks."
+});
+const BUILTIN_FAMILIES = [SOLID, RESIN, METAL, GLASS];
+export {
+  BUILTIN_FAMILIES,
+  GLASS,
+  METAL,
+  RESIN,
+  SOLID
+};

package/dist/glyphs.d.ts

@@ -0,0 +1,29 @@
+import type { OutlineCommand } from '@aethervtt/shard-text';
+export interface DiceGlyphDef {
+    /** SVG path data (M L H V C S Q T A Z, absolute or relative), in `viewBox` units, y down. */
+    path: string;
+    /** min-x, min-y, width, height. Default 0 0 100 100. */
+    viewBox?: [number, number, number, number];
+}
+export interface DiceGlyph {
+    name: string;
+    /** The outline in glyph units: y up, the viewBox's middle at the origin, its height 1. */
+    commands: OutlineCommand[];
+    /** Width over height of the viewBox. */
+    aspect: number;
+}
+/** SVG path data to outline commands (still y down, in path units). */
+export declare function parseSvgPath(d: string, name?: string): OutlineCommand[];
+/** Maps commands through (x, y) → (a·x + b, c·y + d). */
+declare function transform(cmds: OutlineCommand[], a: number, b: number, c: number, d: number): OutlineCommand[];
+/**
+ * Registers a glyph a face layout can name. The same path again is a no-op; a different one under
+ * a taken name throws `dice/registry-conflict`.
+ */
+export declare function defineDiceGlyph(name: string, def: DiceGlyphDef): DiceGlyph;
+export declare function findDiceGlyph(name: string): DiceGlyph | undefined;
+export declare function allDiceGlyphs(): string[];
+export { transform as transformOutline };
+/** Built-in glyphs, in a 100 × 100 box. */
+export declare const BUILTIN_GLYPHS: Readonly<Record<string, DiceGlyphDef>>;
+export declare function registerBuiltinGlyphs(): void;