@aethervtt/shard-dice 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-dice
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/attachments.d.ts

@@ -0,0 +1,79 @@
+import type { AudioClipAsset, PlaySoundOptions } from '@aethervtt/shard-audio';
+import { type AssetRef, type Entity, type World } from '@aethervtt/shard-core';
+import type { ScreenEffectParams } from '@aethervtt/shard-render';
+import type { DieKind } from './builtins.js';
+import type { AccentCue } from './sound.js';
+export declare const MAX_ATTACHMENTS = 4;
+/**
+ * What the registries hold scenes to (0065): vertices an attachment or an entrance may declare, and
+ * an entrance's longest run. Module-wide, like the registries: set them before defining.
+ */
+export declare const DICE_BUDGETS: {
+    attachmentVertices: number;
+    entranceVertices: number;
+    entranceMs: number;
+};
+/** Raises (or lowers) the budgets; call it before defining attachments and entrances. */
+export declare function setDiceBudgets(budgets: Partial<typeof DICE_BUDGETS>): void;
+/** What a host scene on a die (an attachment, or an entrance, 0065) can reach and do. */
+export interface DiceSceneContext {
+    world: World;
+    /** The die: parent what you spawn to it (ChildOf) so it follows the die. */
+    die: Entity;
+    kind: DieKind;
+    value: number;
+    label: string;
+    /** The die's world scale. */
+    scale: number;
+    /** From the recipe effect that named the scene, so one scene serves many skins. */
+    params: Record<string, unknown>;
+    /** The dice camera: face it (spawnDiceWindow). */
+    camera: Entity;
+    /** From the roll and the die: variation that's the same for every viewer. */
+    seed: number;
+    /** The roll's sound gain, 0..1 (`sound` applies it). */
+    soundGain: number;
+    /** Where a world point (default: the die) is in the dice view's CSS pixels; null behind the camera. */
+    screen(point?: ArrayLike<number>): [number, number] | null;
+    /**
+     * Publishes (or refreshes) a lens field (0063) centered on the die, in the dice view's CSS
+     * pixels. False when the table doesn't allow fields (reduced motion, effects off, large pools)
+     * or 4 others are live.
+     */
+    lens(field: {
+        radius: number;
+        strength: number;
+        ttlMs?: number;
+    }): boolean;
+    /**
+     * Publishes (or refreshes) a screen effect (0065) of this kind, centered on the die (or `at`),
+     * for the host's table to draw (`fire`). False when the table doesn't allow effects or 8 are live.
+     */
+    effect(effect: {
+        kind: string;
+        radius: number;
+        ttlMs?: number;
+        params?: ScreenEffectParams;
+        at?: ArrayLike<number>;
+    }): boolean;
+    /** Plays a clip at the roll's sound gain (a range scales too); stopped when the roll ends. -1 without audio. */
+    sound(clip: AssetRef | AudioClipAsset, options?: PlaySoundOptions): number;
+    /** Plays one of the package's accent cues. */
+    cue(cue: AccentCue, gain?: number): void;
+}
+export type DiceAttachmentContext = DiceSceneContext;
+export interface DiceAttachmentDef {
+    /** Vertices it draws, within `DICE_BUDGETS.attachmentVertices`: declared, and held to. */
+    vertices: number;
+    /** Spawns the scene. Returns what it spawned (the package despawns it). */
+    spawn(ctx: DiceAttachmentContext): Entity[];
+    /**
+     * Runs each frame while it's alive, with seconds since it spawned; frames keep coming while any
+     * attachment has one. Return true to keep it, false when it's done (it's despawned).
+     */
+    update?(ctx: DiceAttachmentContext, seconds: number, entities: readonly Entity[]): boolean;
+}
+/** Registers a scene recipes can attach to landed dice by name. */
+export declare function defineDiceAttachment(name: string, def: DiceAttachmentDef): DiceAttachmentDef;
+export declare function findDiceAttachment(name: string): DiceAttachmentDef | undefined;
+export declare function allDiceAttachments(): string[];

package/dist/attachments.js

@@ -0,0 +1,43 @@
+import { ShardError } from "@aethervtt/shard-core";
+const MAX_ATTACHMENTS = 4;
+const DICE_BUDGETS = {
+  attachmentVertices: 12e3,
+  entranceVertices: 6e4,
+  entranceMs: 8e3
+};
+function setDiceBudgets(budgets) {
+  Object.assign(DICE_BUDGETS, budgets);
+}
+const attachments = /* @__PURE__ */ new Map();
+function defineDiceAttachment(name, def) {
+  const budget = DICE_BUDGETS.attachmentVertices;
+  if (!(def.vertices > 0) || def.vertices > budget) {
+    throw new ShardError(
+      "dice/attachment-budget",
+      `Attachment "${name}" declares ${def.vertices} vertices; the budget is ${budget}`,
+      { hint: "Draw fewer vertices, split the effect, or raise it with setDiceBudgets first." }
+    );
+  }
+  const existing = attachments.get(name);
+  if (existing && existing !== def) {
+    throw new ShardError("dice/registry-conflict", `Attachment "${name}" is already defined`, {
+      hint: "Give the new attachment its own name."
+    });
+  }
+  attachments.set(name, def);
+  return def;
+}
+function findDiceAttachment(name) {
+  return attachments.get(name);
+}
+function allDiceAttachments() {
+  return [...attachments.keys()].sort();
+}
+export {
+  DICE_BUDGETS,
+  MAX_ATTACHMENTS,
+  allDiceAttachments,
+  defineDiceAttachment,
+  findDiceAttachment,
+  setDiceBudgets
+};

package/dist/audio.d.ts

@@ -0,0 +1,19 @@
+import { type AssetRef, type World } from '@aethervtt/shard-core';
+/** Default category for dice, including procedural fallback sounds. */
+export declare const DICE_AUDIO_BUS = "dice";
+/** Preserve host controls; a configured mixer must explicitly include its dice route. */
+export declare function ensureDiceAudioBus(world: World): void;
+/** A roll owns preparation and instances, independently of rendering and the host's storage. */
+export declare class DiceAudioSession {
+    private readonly bindings;
+    private readonly leases;
+    private readonly instances;
+    private closed;
+    private readonly world;
+    private readonly gain;
+    constructor(world: World, gain: number);
+    prepare(refs: readonly AssetRef[]): Promise<void>;
+    /** Returns true for configured bindings, even when silent, so defaults do not also play. */
+    play(ref: AssetRef | null, seed: number, strength: number, pitch: number, value: number, high: boolean, low: boolean, count: number, contact?: number, gain?: number): boolean;
+    dispose(): void;
+}

package/dist/audio.js

@@ -0,0 +1,187 @@
+import {
+  AudioBuses,
+  AudioEvent,
+  AudioEventsState,
+  AudioMixState,
+  AudioState,
+  audioEvents,
+  playAudioEvent,
+  prepareAudio,
+  stopAudioEvent
+} from "@aethervtt/shard-audio";
+import { ShardError } from "@aethervtt/shard-core";
+const DICE_AUDIO_BUS = "dice";
+const INPUTS = ["strength", "pitch", "value", "high", "low", "count", "contact"];
+function ensureDiceAudioBus(world) {
+  if (!world.hasResource(AudioState)) return;
+  const graph = world.tryResource(AudioMixState)?.graph;
+  if (graph && !graph.buses.some((bus) => bus.id === DICE_AUDIO_BUS && !bus.return))
+    throw new ShardError("dice/audio-bus", "The active mixer needs an ordinary dice bus", {
+      hint: "Add dice under master in the host mixer before rolling.",
+      path: "/buses"
+    });
+  const buses = world.resource(AudioBuses);
+  buses[DICE_AUDIO_BUS] ??= { volume: 1, muted: false, parent: "master" };
+  if (buses[DICE_AUDIO_BUS].parent !== "master" || buses[DICE_AUDIO_BUS].userDomain === false)
+    throw new ShardError(
+      "dice/audio-bus",
+      "Dice must be an ordinary category directly under master",
+      {
+        hint: "Independent dice user controls require their own category, including effect tails.",
+        path: "/buses/dice"
+      }
+    );
+}
+function key(ref) {
+  return ref.guid ?? ref.path ?? "";
+}
+class DiceAudioSession {
+  bindings = /* @__PURE__ */ new Map();
+  leases = [];
+  instances = [];
+  closed = false;
+  world;
+  gain;
+  constructor(world, gain) {
+    this.world = world;
+    this.gain = gain;
+  }
+  async prepare(refs) {
+    if (this.closed || this.gain <= 0 || !this.world.hasResource(AudioState)) return;
+    ensureDiceAudioBus(this.world);
+    if (refs.length && !this.world.hasResource(AudioEventsState))
+      throw new ShardError(
+        "dice/audio-events-missing",
+        "Authored dice sounds need audioEventsPlugin",
+        {
+          hint: "Install audioEventsPlugin alongside audioPlugin, or remove the event bindings."
+        }
+      );
+    try {
+      for (const ref of refs) {
+        if (this.closed) return;
+        if (this.bindings.has(key(ref))) continue;
+        const lease = await prepareAudio(this.world, ref);
+        if (this.closed) {
+          lease.release();
+          return;
+        }
+        this.leases.push(lease);
+        const plan = lease.events[0];
+        if (!plan || lease.events.length !== 1)
+          throw new ShardError("dice/audio-event", "Dice bindings require one audio event");
+        const definition = plan.definition;
+        if (definition.mode !== "oneshot" || definition.layers.some((layer) => layer.spatial))
+          throw new ShardError(
+            "dice/audio-event",
+            "Dice presentation events must be flat one-shots"
+          );
+        const buses = this.world.resource(AudioBuses);
+        for (const layer of definition.layers) {
+          let bus = layer.bus || definition.bus;
+          let depth = 0;
+          while (bus && bus !== DICE_AUDIO_BUS && depth++ < 64) bus = buses[bus]?.parent ?? "";
+          if (bus !== DICE_AUDIO_BUS)
+            throw new ShardError("dice/audio-bus", "Dice event layers must route through dice", {
+              path: `/layers/${layer.id}/bus`,
+              hint: "Set the event bus to dice or a child bus in the host mixer."
+            });
+        }
+        const inputs = [];
+        for (const parameter of definition.parameters) {
+          if (!INPUTS.includes(parameter.name)) continue;
+          if (parameter.readonly || parameter.kind === "label" || ["strength", "pitch"].includes(parameter.name) && parameter.kind !== "continuous")
+            throw new ShardError("dice/audio-parameter", `Invalid dice input ${parameter.name}`, {
+              path: `/parameters/${parameter.name}`,
+              hint: "Use writable numeric inputs; strength and pitch must be continuous."
+            });
+          inputs.push(parameter.name);
+        }
+        this.bindings.set(key(ref), { ref: plan.source ?? ref, inputs, revision: plan.revision });
+      }
+    } catch (error) {
+      this.dispose();
+      throw error;
+    }
+  }
+  /** Returns true for configured bindings, even when silent, so defaults do not also play. */
+  play(ref, seed, strength, pitch, value, high, low, count, contact = 0, gain = 1) {
+    if (!ref) return false;
+    if (this.closed || this.gain <= 0 || !this.world.hasResource(AudioState)) return true;
+    const binding = this.bindings.get(key(ref));
+    if (!binding)
+      throw new ShardError("dice/audio-not-prepared", "Prepare the dice event before playback");
+    const current = this.world.resource(AudioEvent.store).get(binding.ref);
+    if (!current || JSON.stringify(AudioEvent.serialize(current)) !== binding.revision)
+      throw new ShardError("dice/audio-changed", "A dice event changed during its roll", {
+        hint: "Start a new roll to prepare the changed event and validate its routing and inputs."
+      });
+    const parameters = {};
+    for (let i = 0; i < binding.inputs.length; i++) {
+      const input = binding.inputs[i];
+      switch (input) {
+        case "strength":
+          parameters[input] = strength;
+          break;
+        case "pitch":
+          parameters[input] = pitch;
+          break;
+        case "value":
+          parameters[input] = value;
+          break;
+        case "high":
+          parameters[input] = high ? 1 : 0;
+          break;
+        case "low":
+          parameters[input] = low ? 1 : 0;
+          break;
+        case "count":
+          parameters[input] = count;
+          break;
+        case "contact":
+          parameters[input] = contact;
+          break;
+      }
+    }
+    const state = audioEvents(this.world);
+    let keep = 0;
+    for (let i = 0; i < this.instances.length; i++) {
+      const id = this.instances[i];
+      for (let j = 0; j < state.instances.length; j++) {
+        const instance = state.instances[j];
+        if (instance?.id === id && instance.state !== "ended" && instance.state !== "failed") {
+          this.instances[keep++] = id;
+          break;
+        }
+      }
+    }
+    this.instances.length = keep;
+    try {
+      this.instances.push(
+        playAudioEvent(this.world, binding.ref, {
+          seed: seed >>> 0,
+          volume: this.gain * gain,
+          parameters
+        })
+      );
+    } catch (error) {
+      if (!(error instanceof ShardError) || error.code !== "audio/capacity") throw error;
+    }
+    return true;
+  }
+  dispose() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.world.hasResource(AudioEventsState))
+      for (const id of this.instances) stopAudioEvent(this.world, id, { release: 0 });
+    for (const lease of this.leases) lease.release();
+    this.instances.length = 0;
+    this.leases.length = 0;
+    this.bindings.clear();
+  }
+}
+export {
+  DICE_AUDIO_BUS,
+  DiceAudioSession,
+  ensureDiceAudioBus
+};

package/dist/builtins.d.ts

@@ -0,0 +1,25 @@
+import { type DieDefinition } from './definition.js';
+export declare const D4: DieDefinition;
+export declare const D6: DieDefinition;
+export declare const D8: DieDefinition;
+/** A d10 printing 1–9 and 0 (the value 10). Opposite digits sum to 9, so it doesn't opt in. */
+export declare const D10: DieDefinition;
+/** A percentile's tens die: the d10's shape and numbering, printing 10–90 and 00 (the value 10). */
+export declare const D10_TENS: DieDefinition;
+export declare const D12: DieDefinition;
+export declare const D20: DieDefinition;
+export declare const D100_BALL: DieDefinition;
+export declare const BUILTIN_DICE: readonly DieDefinition[];
+/** Registers the built-ins (idempotent). The dice plugin calls it; tests and tools can too. */
+export declare function registerBuiltinDice(): void;
+/** The kinds a roll names, and the definitions each plays (percentile plays two). */
+export declare const DIE_KINDS: readonly ['d4', 'd6', 'd8', 'd10', 'd12', 'd20', 'd100', 'percentile'];
+export type DieKind = (typeof DIE_KINDS)[number];
+export declare const KIND_DEFINITIONS: Readonly<Record<DieKind, readonly string[]>>;
+/** The values a kind can show: percentile 1..100 over its two dice. */
+export declare function kindSides(kind: DieKind): number;
+/**
+ * A percentile value as its two dice's values: tens then units. 100 shows 00 and 0, and 7 shows 00
+ * and 7. Each d10 value 10 prints as its zero ('00' on the tens die, '0' on the units die).
+ */
+export declare function percentileValues(value: number): [number, number];