@dice-o-rolla/dice-engine 0.3.0 → 0.4.0

package/README.md

@@ -73,6 +73,11 @@ labels, and optional value map. `skinId` and `soundPackId` are opaque applicatio
 the engine does not load assets. Skins and sound definitions belong in the optional
 `@dice-o-rolla/dice-assets` package, which is not a dependency of the engine.
 
+Use `visualPresetSelector` in `roll()` or `simulate()` options to select a registered preset for
+each physical die. The callback receives stable term/die/physical indices, physical and logical die
+types, the current default, and paired-component metadata. Returning `undefined` keeps the default;
+the engine rejects unknown IDs and presets for another physical die type before creating bodies.
+
 The engine emits `die:spawn` and `die:remove` lifecycle events. Collision events are opt-in through
 `DiceEngineOptions.collisionEvents`, bounded by `maxEventsPerFrame`, and suitable for an external
 sound or effects adapter.

package/dist/dice-engine.js

@@ -293,7 +293,7 @@ export class DiceEngine extends TypedEventEmitter {
             if (this.#active !== undefined && this.#queue.length >= this.#limits.maxQueuedRolls) {
                 throw new RollLimitExceededError('queue-size', this.#limits.maxQueuedRolls, this.#queue.length + 1);
             }
-            const task = this.#createTask(notation, parsed, options.signal);
+            const task = this.#createTask(notation, parsed, options);
             if (options.signal?.aborted === true) {
                 this.#rejectCancelled(task);
                 return task.promise;
@@ -320,6 +320,7 @@ export class DiceEngine extends TypedEventEmitter {
         const throwGenerator = new ThrowGenerator(random, this.#throwOptions);
         const simulationId = `simulation-${this.#nextSimulationId++}`;
         this.#removeDisplayedDice();
+        this.#physics.clear();
         const dice = [];
         let trace;
         let failure;
@@ -327,7 +328,7 @@ export class DiceEngine extends TypedEventEmitter {
             this.#physics.setCollisionEventsEnabled(true);
             this.#physics.drainCollisionEvents();
             this.#physics.drainImpactEvents();
-            dice.push(...this.#createSimulationDice(parsed, simulationId, throwGenerator));
+            dice.push(...this.#createSimulationDice(parsed, simulationId, throwGenerator, options.visualPresetSelector));
             const captureFrames = options.captureFrames === true;
             const frames = [];
             const events = [];
@@ -504,7 +505,7 @@ export class DiceEngine extends TypedEventEmitter {
             if (abortListener !== undefined) {
                 options.signal?.addEventListener('abort', abortListener, { once: true });
             }
-            this.#replay = {
+            const replay = {
                 trace,
                 resolve,
                 reject,
@@ -513,7 +514,13 @@ export class DiceEngine extends TypedEventEmitter {
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
                 ...(abortListener === undefined ? {} : { abortListener }),
             };
-            this.#scheduleReplayFrame();
+            this.#replay = replay;
+            try {
+                this.#scheduleReplayFrame();
+            }
+            catch (error) {
+                this.#finishReplay(replay, error);
+            }
             return promise;
         }
         catch (error) {
@@ -670,7 +677,8 @@ export class DiceEngine extends TypedEventEmitter {
         this.#renderer.setTheme(this.#theme);
         this.#initialized = true;
     }
-    #createTask(notation, parsed, signal) {
+    #createTask(notation, parsed, options) {
+        const { signal, visualPresetSelector } = options;
         const session = {
             id: `roll-${this.#nextSessionId++}`,
             notation,
@@ -694,6 +702,7 @@ export class DiceEngine extends TypedEventEmitter {
             reject,
             ...(signal === undefined ? {} : { signal }),
             ...(abortListener === undefined ? {} : { abortListener }),
+            ...(visualPresetSelector === undefined ? {} : { visualPresetSelector }),
         };
     }
     #startNext() {
@@ -724,7 +733,7 @@ export class DiceEngine extends TypedEventEmitter {
     #createDice(task) {
         const dice = [];
         let index = 0;
-        const specs = this.#createPhysicalSpecs(task.parsed, task.session.id);
+        const specs = this.#createPhysicalSpecs(task.parsed, task.session.id, task.visualPresetSelector);
         const totalDice = specs.length;
         try {
             for (const spec of specs) {
@@ -793,9 +802,9 @@ export class DiceEngine extends TypedEventEmitter {
             });
         }
     }
-    #createSimulationDice(parsed, simulationId, throwGenerator) {
+    #createSimulationDice(parsed, simulationId, throwGenerator, visualPresetSelector) {
         const dice = [];
-        const specs = this.#createPhysicalSpecs(parsed, simulationId);
+        const specs = this.#createPhysicalSpecs(parsed, simulationId, visualPresetSelector);
         const totalDice = specs.length;
         try {
             for (const [index, spec] of specs.entries()) {
@@ -881,7 +890,7 @@ export class DiceEngine extends TypedEventEmitter {
         }
         events.push(Object.freeze(event));
     }
-    #createPhysicalSpecs(parsed, sessionId) {
+    #createPhysicalSpecs(parsed, sessionId, visualPresetSelector) {
         const specs = [];
         let groupIndex = 0;
         for (const [expressionIndex, expression] of parsed.expressions.entries()) {
@@ -894,8 +903,16 @@ export class DiceEngine extends TypedEventEmitter {
                     throw new RangeError(`${type} is not a standard die type`);
                 if (!isPhysicalDieType(type))
                     throw new RangeError(`${type} is not a physical die type`);
-                const preset = this.getVisualPreset(type);
                 for (let count = 0; count < expression.count; count += 1) {
+                    const physicalIndex = specs.length;
+                    const preset = this.#resolveVisualPreset({
+                        physicalDieType: type,
+                        logicalDieType: type,
+                        termId,
+                        expressionIndex,
+                        dieIndex: count,
+                        physicalIndex,
+                    }, visualPresetSelector);
                     specs.push({
                         type,
                         geometryType: this.#getPresetGeometryType(preset),
@@ -903,7 +920,7 @@ export class DiceEngine extends TypedEventEmitter {
                         termId,
                         expressionIndex,
                         dieIndex: count,
-                        physicalIndex: specs.length,
+                        physicalIndex,
                         ...(expression.selection === undefined ? {} : { selection: expression.selection }),
                         ...(expression.score === undefined ? {} : { scoreRules: expression.score }),
                     });
@@ -913,56 +930,119 @@ export class DiceEngine extends TypedEventEmitter {
             for (let count = 0; count < expression.count; count += 1) {
                 const groupId = `${sessionId}:group-${groupIndex++}`;
                 if (expression.type === 'd100') {
-                    const preset = this.getVisualPreset('d10');
+                    const tensPhysicalIndex = specs.length;
+                    const tensPreset = this.#resolveVisualPreset({
+                        physicalDieType: 'd10',
+                        logicalDieType: 'd100',
+                        termId,
+                        expressionIndex,
+                        dieIndex: count,
+                        physicalIndex: tensPhysicalIndex,
+                        component: { groupType: 'd100', role: 'tens' },
+                    }, visualPresetSelector);
                     specs.push({
                         type: 'd100',
-                        geometryType: this.#getPresetGeometryType(preset),
-                        preset,
+                        geometryType: this.#getPresetGeometryType(tensPreset),
+                        preset: tensPreset,
                         termId,
                         expressionIndex,
                         dieIndex: count,
-                        physicalIndex: specs.length,
+                        physicalIndex: tensPhysicalIndex,
                         component: { groupId, groupType: 'd100', role: 'tens' },
                         faceLabels: D100_TENS_LABELS,
                     });
+                    const unitsPhysicalIndex = specs.length;
+                    const unitsPreset = this.#resolveVisualPreset({
+                        physicalDieType: 'd10',
+                        logicalDieType: 'd100',
+                        termId,
+                        expressionIndex,
+                        dieIndex: count,
+                        physicalIndex: unitsPhysicalIndex,
+                        component: { groupType: 'd100', role: 'units' },
+                    }, visualPresetSelector);
                     specs.push({
                         type: 'd10',
-                        geometryType: this.#getPresetGeometryType(preset),
-                        preset,
+                        geometryType: this.#getPresetGeometryType(unitsPreset),
+                        preset: unitsPreset,
                         termId,
                         expressionIndex,
                         dieIndex: count,
-                        physicalIndex: specs.length,
+                        physicalIndex: unitsPhysicalIndex,
                         component: { groupId, groupType: 'd100', role: 'units' },
                     });
                     continue;
                 }
-                const preset = this.getVisualPreset('d6');
+                const tensPhysicalIndex = specs.length;
+                const tensPreset = this.#resolveVisualPreset({
+                    physicalDieType: 'd6',
+                    logicalDieType: 'd66',
+                    termId,
+                    expressionIndex,
+                    dieIndex: count,
+                    physicalIndex: tensPhysicalIndex,
+                    component: { groupType: 'd66', role: 'tens' },
+                }, visualPresetSelector);
                 specs.push({
                     type: 'd6',
-                    geometryType: this.#getPresetGeometryType(preset),
-                    preset,
+                    geometryType: this.#getPresetGeometryType(tensPreset),
+                    preset: tensPreset,
                     termId,
                     expressionIndex,
                     dieIndex: count,
-                    physicalIndex: specs.length,
+                    physicalIndex: tensPhysicalIndex,
                     component: { groupId, groupType: 'd66', role: 'tens' },
                     faceLabels: D66_TENS_LABELS,
                 });
+                const unitsPhysicalIndex = specs.length;
+                const unitsPreset = this.#resolveVisualPreset({
+                    physicalDieType: 'd6',
+                    logicalDieType: 'd66',
+                    termId,
+                    expressionIndex,
+                    dieIndex: count,
+                    physicalIndex: unitsPhysicalIndex,
+                    component: { groupType: 'd66', role: 'units' },
+                }, visualPresetSelector);
                 specs.push({
                     type: 'd6',
-                    geometryType: this.#getPresetGeometryType(preset),
-                    preset,
+                    geometryType: this.#getPresetGeometryType(unitsPreset),
+                    preset: unitsPreset,
                     termId,
                     expressionIndex,
                     dieIndex: count,
-                    physicalIndex: specs.length,
+                    physicalIndex: unitsPhysicalIndex,
                     component: { groupId, groupType: 'd66', role: 'units' },
                 });
             }
         }
         return specs;
     }
+    #resolveVisualPreset(coordinates, selector) {
+        const defaultPreset = this.getVisualPreset(coordinates.physicalDieType);
+        if (selector === undefined)
+            return defaultPreset;
+        const context = Object.freeze({
+            ...coordinates,
+            ...(coordinates.component === undefined
+                ? {}
+                : { component: Object.freeze({ ...coordinates.component }) }),
+            defaultPresetId: defaultPreset.id,
+        });
+        const selectedId = selector(context);
+        if (selectedId === undefined)
+            return defaultPreset;
+        if (typeof selectedId !== 'string') {
+            throw new TypeError('visualPresetSelector must return a preset ID or undefined');
+        }
+        const preset = this.#visualPresets.get(selectedId);
+        if (preset === undefined)
+            throw new RangeError(`Unknown visual preset: ${selectedId}`);
+        if (preset.dieType !== coordinates.physicalDieType) {
+            throw new RangeError(`Visual preset "${selectedId}" is for ${preset.dieType}, not ${coordinates.physicalDieType}`);
+        }
+        return preset;
+    }
     #placeDie(generated, index, total) {
         if (total <= 4)
             return generated;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { DiceEngine } from './dice-engine.js';
 export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, TraceLimitExceededError, } from './errors.js';
 export type { RollLimit, TraceLimit } from './errors.js';
-export type { DiceEngineEvents, DiceEngineFacade, DiceEngineLimits, DiceEngineOptions, DiceCollisionEvent, DiceImpactEvent, DiceCollisionEventOptions, DiceMaterialType, DiceRemovalReason, DiceRemoveEvent, DiceTheme, DiceTraceLimits, DiceVisualEvent, FrameScheduler, FrameToken, PhysicalRollFrame, PhysicalRollFrameDie, PhysicalRollTrace, PhysicalRollTraceCollisionEvent, PhysicalRollTraceDie, PhysicalRollTraceEvent, PhysicalRollTraceImpactEvent, PhysicalRollTraceProducer, PhysicalRollTraceProfile, RegisterEngineVisualPresetOptions, ReplayOptions, RollOptions, SimulateOptions, } from './types.js';
+export type { DiceEngineEvents, DiceEngineFacade, DiceEngineLimits, DiceEngineOptions, DiceCollisionEvent, DiceImpactEvent, DiceCollisionEventOptions, DiceMaterialType, DiceRemovalReason, DiceRemoveEvent, DiceTheme, DiceTraceLimits, DiceVisualEvent, FrameScheduler, FrameToken, PhysicalRollFrame, PhysicalRollFrameDie, PhysicalRollTrace, PhysicalRollTraceCollisionEvent, PhysicalRollTraceDie, PhysicalRollTraceEvent, PhysicalRollTraceImpactEvent, PhysicalRollTraceProducer, PhysicalRollTraceProfile, RegisterEngineVisualPresetOptions, ReplayOptions, RollOptions, SimulateOptions, VisualPresetSelectionContext, VisualPresetSelector, } from './types.js';
 export { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, type PhysicalDieType, } from './visual-presets.js';
 export { DICE_ENGINE_VERSION } from './version.js';

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { DieResult, DieType, QuaternionLike, RandomSource, RollMode, RollResult, RollSession, Vector3Like } from '@dice-o-rolla/dice-core';
+import type { DiceComponentRole, DieResult, DieType, PairedDiceType, QuaternionLike, RandomSource, RollMode, RollResult, RollSession, Vector3Like } from '@dice-o-rolla/dice-core';
 import type { DicePhysicsMaterial, PhysicsWorld, SettlingOptions, ThrowGeneratorOptions, TrayOptions } from '@dice-o-rolla/dice-physics';
 import type { DiceRenderer, RendererTheme, RendererViewport } from '@dice-o-rolla/dice-renderer';
 import type { RegisterVisualPresetOptions, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
@@ -11,15 +11,34 @@ export interface FrameScheduler {
 }
 export type DiceMaterialType = RendererTheme['material'];
 export type DiceTheme = RendererTheme;
+export interface VisualPresetSelectionContext {
+    /** Physical polyhedron being allocated. Paired dice use d10 or d6 here. */
+    readonly physicalDieType: PhysicalDieType;
+    /** Notation-level die type. Paired components retain d100 or d66 here. */
+    readonly logicalDieType: PhysicalDieType | PairedDiceType;
+    readonly termId: string;
+    readonly expressionIndex: number;
+    readonly dieIndex: number;
+    readonly physicalIndex: number;
+    readonly defaultPresetId: string;
+    readonly component?: {
+        readonly groupType: PairedDiceType;
+        readonly role: DiceComponentRole;
+    };
+}
+/** Returns a registered preset ID, or undefined to retain the selected default. */
+export type VisualPresetSelector = (context: VisualPresetSelectionContext) => string | undefined;
 export interface RollOptions {
     readonly mode?: RollMode;
     readonly signal?: AbortSignal;
+    readonly visualPresetSelector?: VisualPresetSelector;
 }
 export interface SimulateOptions {
     readonly seed: number;
     readonly captureFrames?: boolean;
     /** Capture one frame every N fixed simulation steps. */
     readonly frameIntervalSteps?: number;
+    readonly visualPresetSelector?: VisualPresetSelector;
 }
 export interface ReplayOptions {
     readonly theme?: Partial<DiceTheme>;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Runtime package version used in portable trace provenance. */
-export declare const DICE_ENGINE_VERSION = "0.3.0";
+export declare const DICE_ENGINE_VERSION = "0.4.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Runtime package version used in portable trace provenance. */
-export const DICE_ENGINE_VERSION = '0.3.0';
+export const DICE_ENGINE_VERSION = '0.4.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-engine",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Framework-neutral physical dice engine with Rapier and Three.js browser adapters.",
   "keywords": [
     "dice",
@@ -47,12 +47,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@dice-o-rolla/dice-core": "0.3.0",
-    "@dice-o-rolla/dice-geometry": "0.3.0",
-    "@dice-o-rolla/dice-physics": "0.3.0",
-    "@dice-o-rolla/dice-physics-rapier": "0.3.0",
-    "@dice-o-rolla/dice-renderer": "0.3.0",
-    "@dice-o-rolla/dice-renderer-three": "0.3.0"
+    "@dice-o-rolla/dice-core": "0.4.0",
+    "@dice-o-rolla/dice-geometry": "0.4.0",
+    "@dice-o-rolla/dice-physics": "0.4.0",
+    "@dice-o-rolla/dice-physics-rapier": "0.4.0",
+    "@dice-o-rolla/dice-renderer": "0.4.0",
+    "@dice-o-rolla/dice-renderer-three": "0.4.0"
   },
   "engines": {
     "node": ">=20.0.0"