@dice-o-rolla/dice-engine 0.1.1 → 0.2.0

package/README.md

@@ -19,7 +19,9 @@ engine.destroy();
 ```
 
 The browser entry point initializes Rapier WASM, creates the Three.js renderer, uses Web Crypto for
-throw generation, and releases partially initialized resources if composition fails.
+throw generation, and releases partially initialized resources if composition fails. Concurrent
+`initialize()` calls coalesce, while every roll promise terminates by settlement, cancellation,
+timeout, or failure.
 
 ## Custom adapters
 
@@ -32,6 +34,17 @@ await engine.initialize();
 
 The main entry point depends on domain contracts rather than concrete Rapier or Three.js types.
 
+## Visual presets and optional effects
+
+`registerVisualPreset()` associates a logical die with a validated physical geometry, scale, face
+labels, and optional value map. `skinId` and `soundPackId` are opaque application-owned references;
+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.
+
+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.
+
 ## Supported notation
 
 The initial grammar supports standard polyhedral expressions and integer modifiers, including:
@@ -39,11 +52,19 @@ The initial grammar supports standard polyhedral expressions and integer modifie
 ```text
 d20
 4d6 + 2
+4d6kh3
+2d20kl1
+5d20s{1=-2,17..19=1,20=2}
 d%
 d100
 d66
 ```
 
+Keep/drop rolls retain every physical die in `result.dice` and expose the selection through
+`included`. Score maps expose each contribution through `score`; unlisted faces contribute zero.
+Selection is applied before scoring, followed by integer modifiers. Paired `d%`, `d100`, and `d66`
+terms currently reject keep/drop and score operations.
+
 Default resource limits reject oversized notation, more than 50 logical or physical dice, and more
 than eight pending rolls. Consumers may lower or explicitly raise these limits through
 `DiceEngineOptions.limits` after testing their target devices.
@@ -52,7 +73,11 @@ than eight pending rolls. Consumers may lower or explicitly raise these limits t
 
 Client-side results are not authoritative for rankings, prizes, or wagering. Call `destroy()` when
 the engine is no longer needed to release frame scheduling, observers, physics resources, WebGL
-resources, and the renderer canvas.
+resources, and the renderer canvas. `clear()` keeps the engine reusable; `destroy()` is idempotent
+and final. See the canonical
+[lifecycle and runtime contract](https://github.com/creepiest-space/dice-o-rolla/blob/main/docs/engine.md).
+Consumers upgrading from `0.1` should also review the
+[0.2 migration notes](https://github.com/creepiest-space/dice-o-rolla/blob/main/docs/migration-0.2.md).
 
 ## License
 

package/dist/dice-engine.d.ts

@@ -1,7 +1,8 @@
 import { TypedEventEmitter } from '@dice-o-rolla/dice-core';
 import type { RollResult } from '@dice-o-rolla/dice-core';
-import type { RendererViewport } from '@dice-o-rolla/dice-renderer';
-import type { DiceEngineEvents, DiceEngineFacade, DiceEngineOptions, DiceTheme, RollOptions } from './types.js';
+import { type RendererViewport, type VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
+import type { DiceEngineEvents, DiceEngineFacade, DiceEngineOptions, DiceTheme, RegisterEngineVisualPresetOptions, RollOptions } from './types.js';
+import { type PhysicalDieType } from './visual-presets.js';
 export declare class DiceEngine extends TypedEventEmitter<DiceEngineEvents> implements DiceEngineFacade {
     #private;
     constructor(options: DiceEngineOptions);
@@ -12,5 +13,9 @@ export declare class DiceEngine extends TypedEventEmitter<DiceEngineEvents> impl
     resize(viewport: RendererViewport): void;
     setTheme(theme: Partial<DiceTheme>): DiceTheme;
     get theme(): DiceTheme;
+    registerVisualPreset(source: VisualPresetDescriptor, options?: RegisterEngineVisualPresetOptions): VisualPresetDescriptor;
+    unregisterVisualPreset(id: string): boolean;
+    setVisualPreset(dieType: PhysicalDieType, presetId: string): void;
+    getVisualPreset(dieType: PhysicalDieType): VisualPresetDescriptor;
     destroy(): void;
 }

package/dist/dice-engine.js

@@ -1,8 +1,10 @@
 import { createRollResult, getNotationModifier, isDieType, mathRandomSource, parseNotation, TypedEventEmitter, } from '@dice-o-rolla/dice-core';
 import { getDieGeometry, hasDieGeometry, resolveFace } from '@dice-o-rolla/dice-geometry';
 import { SettlingDetector, ThrowGenerator } from '@dice-o-rolla/dice-physics';
+import { createVisualPresetDescriptor, VisualPresetRegistry, } from '@dice-o-rolla/dice-renderer';
 import { DEFAULT_THEME, defaultFrameScheduler } from './defaults.js';
 import { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
+import { getStandardVisualPresetId, isPhysicalDieType, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, } from './visual-presets.js';
 const DEFAULT_SETTLING = {
     linearVelocityThreshold: 0.08,
     angularVelocityThreshold: 0.08,
@@ -45,6 +47,7 @@ const DEFAULT_LIMITS = Object.freeze({
     maxPhysicalDice: 50,
     maxQueuedRolls: 8,
 });
+const DEFAULT_COLLISION_EVENTS = Object.freeze({ enabled: false, maxEventsPerFrame: 32 });
 const D100_TENS_LABELS = Object.freeze({
     1: 10,
     2: 20,
@@ -71,12 +74,21 @@ function snapshotSession(session) {
 function toRenderState(die) {
     return {
         id: die.id,
+        presetId: die.preset.id,
         geometryId: die.geometryType,
+        scale: die.preset.scale ?? 1,
         ...(die.faceLabels === undefined ? {} : { faceLabels: die.faceLabels }),
         previous: die.previous,
         current: die.current,
     };
 }
+function mergeFaceLabels(preset, roll) {
+    if (preset === undefined)
+        return roll;
+    if (roll === undefined)
+        return preset;
+    return Object.freeze({ ...preset, ...roll });
+}
 function assertPositive(value, name) {
     if (!Number.isFinite(value) || value <= 0) {
         throw new RangeError(`${name} must be a positive finite number`);
@@ -99,13 +111,18 @@ export class DiceEngine extends TypedEventEmitter {
     #tray;
     #diceMaterial;
     #limits;
+    #collisionEvents;
+    #visualPresets = new VisualPresetRegistry(STANDARD_VISUAL_PRESETS);
+    #visualPresetIds = new Map();
     #queue = [];
     #displayedDieIds = new Set();
+    #dieEvents = new Map();
     #active;
     #frameToken;
     #lastFrameMs = 0;
     #accumulatorSeconds = 0;
     #nextSessionId = 1;
+    #initialization;
     #initialized = false;
     #destroyed = false;
     #theme;
@@ -124,6 +141,11 @@ export class DiceEngine extends TypedEventEmitter {
         this.#tray = options.tray ?? DEFAULT_TRAY;
         this.#diceMaterial = options.diceMaterial ?? DEFAULT_DICE_MATERIAL;
         this.#limits = Object.freeze({ ...DEFAULT_LIMITS, ...options.limits });
+        this.#collisionEvents = Object.freeze({
+            ...DEFAULT_COLLISION_EVENTS,
+            ...options.collisionEvents,
+        });
+        assertPositiveSafeInteger(this.#collisionEvents.maxEventsPerFrame, 'collisionEvents.maxEventsPerFrame');
         for (const [name, value] of [
             ['maxNotationLength', this.#limits.maxNotationLength],
             ['maxLogicalDice', this.#limits.maxLogicalDice],
@@ -132,16 +154,33 @@ export class DiceEngine extends TypedEventEmitter {
         ]) {
             assertPositiveSafeInteger(value, `limits.${name}`);
         }
+        for (const type of PHYSICAL_DIE_TYPES) {
+            this.#visualPresetIds.set(type, getStandardVisualPresetId(type));
+        }
+        for (const preset of options.visualPresets ?? [])
+            this.registerVisualPreset(preset);
+        for (const type of PHYSICAL_DIE_TYPES) {
+            const presetId = options.visualPresetIds?.[type];
+            if (presetId !== undefined)
+                this.setVisualPreset(type, presetId);
+        }
         this.#theme = this.#mergeTheme(options.theme ?? {});
     }
     async initialize() {
         this.#assertAlive();
         if (this.#initialized)
             return;
-        this.#physics.configureTray(this.#tray);
-        await this.#renderer.initialize();
-        this.#renderer.setTheme(this.#theme);
-        this.#initialized = true;
+        if (this.#initialization !== undefined)
+            return this.#initialization;
+        const initialization = this.#performInitialization();
+        this.#initialization = initialization;
+        try {
+            await initialization;
+        }
+        finally {
+            if (this.#initialization === initialization)
+                this.#initialization = undefined;
+        }
     }
     roll(notation, options = {}) {
         try {
@@ -196,10 +235,8 @@ export class DiceEngine extends TypedEventEmitter {
         }
         for (const task of this.#queue.splice(0))
             this.#rejectCancelled(task);
-        this.#physics.clear();
-        this.#renderer.clear();
-        this.#displayedDieIds.clear();
         this.#accumulatorSeconds = 0;
+        this.#clearRenderedDice('cleared');
     }
     resize(viewport) {
         this.#assertReady();
@@ -216,15 +253,102 @@ export class DiceEngine extends TypedEventEmitter {
     get theme() {
         return this.#theme;
     }
+    registerVisualPreset(source, options = {}) {
+        this.#assertAlive();
+        const preset = createVisualPresetDescriptor(source);
+        this.#assertValidVisualPreset(preset);
+        if ([...this.#dieEvents.values()].some((event) => event.presetId === preset.id)) {
+            throw new Error(`Visual preset "${preset.id}" is currently in use`);
+        }
+        const existing = this.#visualPresets.get(preset.id);
+        if (existing !== undefined && options.replace !== true) {
+            throw new Error(`Visual preset "${preset.id}" is already registered`);
+        }
+        if (this.#initialized)
+            this.#renderer.registerPreset(preset);
+        this.#visualPresets.register(preset, options.replace === undefined ? {} : { replace: options.replace });
+        if (options.makeDefault === true) {
+            if (!isPhysicalDieType(preset.dieType)) {
+                throw new Error(`Visual preset has an invalid physical die type: ${preset.dieType}`);
+            }
+            this.#visualPresetIds.set(preset.dieType, preset.id);
+        }
+        return preset;
+    }
+    unregisterVisualPreset(id) {
+        this.#assertAlive();
+        if (STANDARD_VISUAL_PRESETS.some((preset) => preset.id === id)) {
+            throw new Error(`Built-in visual preset "${id}" cannot be unregistered`);
+        }
+        const preset = this.#visualPresets.unregister(id);
+        if (preset === undefined)
+            return false;
+        if (!isPhysicalDieType(preset.dieType)) {
+            throw new Error(`Visual preset has an invalid physical die type: ${preset.dieType}`);
+        }
+        const type = preset.dieType;
+        if (this.#visualPresetIds.get(type) === id) {
+            this.#visualPresetIds.set(type, getStandardVisualPresetId(type));
+        }
+        if (this.#initialized)
+            this.#renderer.unregisterPreset(id);
+        return true;
+    }
+    setVisualPreset(dieType, presetId) {
+        this.#assertAlive();
+        if (!PHYSICAL_DIE_TYPES.includes(dieType)) {
+            throw new RangeError(`${dieType} is not a physical die type`);
+        }
+        const preset = this.#visualPresets.get(presetId);
+        if (preset === undefined)
+            throw new RangeError(`Unknown visual preset: ${presetId}`);
+        if (preset.dieType !== dieType) {
+            throw new RangeError(`Visual preset "${presetId}" is for ${preset.dieType}, not ${dieType}`);
+        }
+        this.#visualPresetIds.set(dieType, presetId);
+    }
+    getVisualPreset(dieType) {
+        this.#assertAlive();
+        const id = this.#visualPresetIds.get(dieType);
+        const preset = id === undefined ? undefined : this.#visualPresets.get(id);
+        if (preset === undefined)
+            throw new Error(`No visual preset is selected for ${dieType}`);
+        return preset;
+    }
     destroy() {
         if (this.#destroyed)
             return;
-        this.clear();
-        this.#renderer.destroy();
-        this.#physics.destroy();
+        this.#destroyed = true;
+        this.#frameToken?.cancel();
+        this.#frameToken = undefined;
+        if (this.#active !== undefined) {
+            const task = this.#active.task;
+            this.#active = undefined;
+            this.#rejectCancelled(task);
+        }
+        for (const task of this.#queue.splice(0))
+            this.#rejectCancelled(task);
+        this.#forgetRenderedDice('destroyed');
+        const cleanupErrors = this.#runCleanup([
+            () => this.#renderer.destroy(),
+            () => this.#physics.destroy(),
+        ]);
         super.clear();
+        this.#initialization = undefined;
         this.#initialized = false;
-        this.#destroyed = true;
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError(cleanupErrors, 'DiceEngine teardown failed');
+        }
+    }
+    async #performInitialization() {
+        this.#physics.configureTray(this.#tray);
+        this.#physics.setCollisionEventsEnabled(this.#collisionEvents.enabled);
+        await this.#renderer.initialize();
+        this.#assertAlive();
+        for (const preset of this.#visualPresets.list())
+            this.#renderer.registerPreset(preset);
+        this.#renderer.setTheme(this.#theme);
+        this.#initialized = true;
     }
     #createTask(notation, parsed, signal) {
         const session = {
@@ -285,6 +409,7 @@ export class DiceEngine extends TypedEventEmitter {
         try {
             for (const spec of specs) {
                 const geometry = getDieGeometry(spec.geometryType);
+                const faceLabels = mergeFaceLabels(spec.preset.faceLabels, spec.faceLabels);
                 const id = `${task.session.id}:die-${index++}`;
                 const generated = this.#throwGenerator.generate();
                 const position = this.#placeDie(generated.position, index - 1, totalDice);
@@ -295,7 +420,7 @@ export class DiceEngine extends TypedEventEmitter {
                         kind: 'convex-hull',
                         vertices: geometry.vertices.map(([x, y, z]) => ({ x, y, z })),
                     },
-                    scale: 1,
+                    scale: spec.preset.scale ?? 1,
                     mass: 1,
                     material: this.#diceMaterial,
                     position,
@@ -306,8 +431,12 @@ export class DiceEngine extends TypedEventEmitter {
                     id,
                     type: spec.type,
                     geometryType: spec.geometryType,
+                    preset: spec.preset,
+                    expressionIndex: spec.expressionIndex,
+                    ...(spec.selection === undefined ? {} : { selection: spec.selection }),
+                    ...(spec.scoreRules === undefined ? {} : { scoreRules: spec.scoreRules }),
                     ...(spec.component === undefined ? {} : { component: spec.component }),
-                    ...(spec.faceLabels === undefined ? {} : { faceLabels: spec.faceLabels }),
+                    ...(faceLabels === undefined ? {} : { faceLabels }),
                     body,
                     detector: new SettlingDetector(this.#settling),
                     previous: state,
@@ -316,57 +445,90 @@ export class DiceEngine extends TypedEventEmitter {
                 dice.push(die);
                 this.#renderer.createDie(toRenderState(die));
                 body.applyImpulse(generated.impulse, generated.torqueImpulse);
+                const event = Object.freeze({
+                    sessionId: task.session.id,
+                    dieId: id,
+                    dieType: spec.type,
+                    presetId: spec.preset.id,
+                    ...(spec.preset.skinId === undefined ? {} : { skinId: spec.preset.skinId }),
+                    ...(spec.preset.soundPackId === undefined
+                        ? {}
+                        : { soundPackId: spec.preset.soundPackId }),
+                });
+                this.#dieEvents.set(id, event);
+                this.emit('die:spawn', event);
             }
             return dice;
         }
         catch (error) {
-            for (const die of dice) {
-                this.#physics.removeDie(die.id);
-                this.#renderer.removeDie(die.id);
-            }
-            throw error;
+            const cleanupErrors = this.#removeDiceSafely(dice, 'failed');
+            if (cleanupErrors.length === 0)
+                throw error;
+            throw new AggregateError([error, ...cleanupErrors], 'Failed to create dice', {
+                cause: error,
+            });
         }
     }
     #createPhysicalSpecs(task) {
         const specs = [];
         let groupIndex = 0;
-        for (const expression of task.parsed.expressions) {
+        for (const [expressionIndex, expression] of task.parsed.expressions.entries()) {
             if (expression.kind === 'modifier')
                 continue;
             if (expression.kind === 'dice') {
                 const type = `d${expression.sides}`;
                 if (!isDieType(type))
                     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) {
-                    specs.push({ type, geometryType: type });
+                    specs.push({
+                        type,
+                        geometryType: this.#getPresetGeometryType(preset),
+                        preset,
+                        expressionIndex,
+                        ...(expression.selection === undefined ? {} : { selection: expression.selection }),
+                        ...(expression.score === undefined ? {} : { scoreRules: expression.score }),
+                    });
                 }
                 continue;
             }
             for (let count = 0; count < expression.count; count += 1) {
                 const groupId = `${task.session.id}:group-${groupIndex++}`;
                 if (expression.type === 'd100') {
+                    const preset = this.getVisualPreset('d10');
                     specs.push({
                         type: 'd100',
-                        geometryType: 'd10',
+                        geometryType: this.#getPresetGeometryType(preset),
+                        preset,
+                        expressionIndex,
                         component: { groupId, groupType: 'd100', role: 'tens' },
                         faceLabels: D100_TENS_LABELS,
                     });
                     specs.push({
                         type: 'd10',
-                        geometryType: 'd10',
+                        geometryType: this.#getPresetGeometryType(preset),
+                        preset,
+                        expressionIndex,
                         component: { groupId, groupType: 'd100', role: 'units' },
                     });
                     continue;
                 }
+                const preset = this.getVisualPreset('d6');
                 specs.push({
                     type: 'd6',
-                    geometryType: 'd6',
+                    geometryType: this.#getPresetGeometryType(preset),
+                    preset,
+                    expressionIndex,
                     component: { groupId, groupType: 'd66', role: 'tens' },
                     faceLabels: D66_TENS_LABELS,
                 });
                 specs.push({
                     type: 'd6',
-                    geometryType: 'd6',
+                    geometryType: this.#getPresetGeometryType(preset),
+                    preset,
+                    expressionIndex,
                     component: { groupId, groupType: 'd66', role: 'units' },
                 });
             }
@@ -404,10 +566,39 @@ export class DiceEngine extends TypedEventEmitter {
             const frameDelta = Math.max(0, Math.min((timestampMs - this.#lastFrameMs) / 1_000, this.#maxFrameDeltaSeconds));
             this.#lastFrameMs = timestampMs;
             this.#accumulatorSeconds += frameDelta;
+            let emittedCollisionEvents = 0;
             while (this.#accumulatorSeconds >= this.#fixedStepSeconds) {
                 for (const die of active.dice)
                     die.previous = die.current;
                 this.#physics.step(this.#fixedStepSeconds);
+                if (this.#collisionEvents.enabled) {
+                    for (const collision of this.#physics.drainCollisionEvents()) {
+                        if (emittedCollisionEvents >= this.#collisionEvents.maxEventsPerFrame)
+                            continue;
+                        const event = this.#dieEvents.get(collision.dieId);
+                        if (event === undefined)
+                            continue;
+                        this.emit('die:collision', Object.freeze({
+                            ...event,
+                            ...(collision.otherDieId === undefined ? {} : { otherDieId: collision.otherDieId }),
+                            started: collision.started,
+                        }));
+                        emittedCollisionEvents += 1;
+                    }
+                    for (const impact of this.#physics.drainImpactEvents()) {
+                        if (emittedCollisionEvents >= this.#collisionEvents.maxEventsPerFrame)
+                            continue;
+                        const event = this.#dieEvents.get(impact.dieId);
+                        if (event === undefined)
+                            continue;
+                        this.emit('die:impact', Object.freeze({
+                            ...event,
+                            ...(impact.otherDieId === undefined ? {} : { otherDieId: impact.otherDieId }),
+                            force: impact.force,
+                        }));
+                        emittedCollisionEvents += 1;
+                    }
+                }
                 this.#accumulatorSeconds -= this.#fixedStepSeconds;
                 for (const die of active.dice) {
                     die.current = die.body.getState();
@@ -439,18 +630,19 @@ export class DiceEngine extends TypedEventEmitter {
         }
     }
     #createDieResult(die, faceValue) {
+        const mappedValue = die.preset.valueMap?.[faceValue] ?? faceValue;
         if (die.component === undefined) {
             if (die.type === 'd100')
                 throw new Error('A d100 result requires percentile component data');
-            return Object.freeze({ id: die.id, type: die.type, value: faceValue });
+            return Object.freeze({ id: die.id, type: die.type, value: mappedValue });
         }
         const { groupId, groupType, role } = die.component;
-        const digit = groupType === 'd100' ? faceValue % 10 : faceValue;
+        const digit = groupType === 'd100' ? mappedValue % 10 : mappedValue;
         return Object.freeze({
             id: die.id,
             type: die.type,
             value: role === 'tens' ? digit * 10 : digit,
-            component: Object.freeze({ groupId, groupType, role, faceValue }),
+            component: Object.freeze({ groupId, groupType, role, faceValue: mappedValue }),
         });
     }
     #completeActive(active) {
@@ -459,11 +651,7 @@ export class DiceEngine extends TypedEventEmitter {
         session.completedAt = this.#now();
         if (session.startedAt === undefined)
             throw new Error('Active roll has no start time');
-        const diceResults = active.dice.map((die) => {
-            if (die.result === undefined)
-                throw new Error(`Die ${die.id} has no settled result`);
-            return die.result;
-        });
+        const diceResults = this.#applyRollRules(active.dice);
         const result = createRollResult({
             id: session.id,
             notation: session.notation,
@@ -480,14 +668,70 @@ export class DiceEngine extends TypedEventEmitter {
         this.emit('roll:complete', result);
         this.#startNext();
     }
+    #applyRollRules(dice) {
+        const expressionGroups = new Map();
+        for (const die of dice) {
+            const group = expressionGroups.get(die.expressionIndex) ?? [];
+            group.push(die);
+            expressionGroups.set(die.expressionIndex, group);
+        }
+        const inclusion = new Map();
+        for (const group of expressionGroups.values()) {
+            const selection = group[0]?.selection;
+            if (selection === undefined)
+                continue;
+            const ranked = group
+                .map((die, index) => {
+                if (die.result === undefined)
+                    throw new Error(`Die ${die.id} has no settled result`);
+                return { die, index, value: die.result.value };
+            })
+                .toSorted((left, right) => {
+                const highest = selection.operator === 'kh' || selection.operator === 'dh';
+                const valueOrder = highest ? right.value - left.value : left.value - right.value;
+                return valueOrder === 0 ? left.index - right.index : valueOrder;
+            });
+            const selected = new Set(ranked.slice(0, selection.count).map(({ die }) => die.id));
+            const keepsSelected = selection.operator === 'kh' || selection.operator === 'kl';
+            for (const die of group) {
+                inclusion.set(die.id, keepsSelected ? selected.has(die.id) : !selected.has(die.id));
+            }
+        }
+        return dice.map((die) => {
+            if (die.result === undefined)
+                throw new Error(`Die ${die.id} has no settled result`);
+            const included = inclusion.get(die.id);
+            const score = die.scoreRules === undefined
+                ? undefined
+                : this.#scoreFace(die.result.value, die.scoreRules);
+            if (included === undefined && score === undefined)
+                return die.result;
+            if (die.result.component !== undefined) {
+                throw new Error(`Paired die ${die.id} cannot use keep/drop or score rules`);
+            }
+            return Object.freeze({
+                ...die.result,
+                ...(included === undefined ? {} : { included }),
+                ...(score === undefined ? {} : { score }),
+            });
+        });
+    }
+    #scoreFace(value, rules) {
+        return rules.find((rule) => value >= rule.minimum && value <= rule.maximum)?.score ?? 0;
+    }
     #cancelActive(task) {
         this.#frameToken?.cancel();
         this.#frameToken = undefined;
         const active = this.#active;
         this.#active = undefined;
-        if (active !== undefined)
-            this.#removeDice(active.dice);
+        const cleanupErrors = active === undefined ? [] : this.#removeDiceSafely(active.dice, 'cancelled');
         this.#rejectCancelled(task);
+        if (cleanupErrors.length > 0) {
+            this.emit('error', {
+                session: snapshotSession(task.session),
+                error: new AggregateError(cleanupErrors, `Failed to clean up ${task.session.id}`),
+            });
+        }
         this.#startNext();
     }
     #rejectCancelled(task) {
@@ -499,8 +743,12 @@ export class DiceEngine extends TypedEventEmitter {
     }
     #failActive(active, error) {
         this.#active = undefined;
-        this.#removeDice(active.dice);
-        this.#failTask(active.task, error);
+        const cleanupErrors = this.#removeDiceSafely(active.dice, 'failed');
+        this.#failTask(active.task, cleanupErrors.length === 0
+            ? error
+            : new AggregateError([error, ...cleanupErrors], `Roll ${active.task.session.id} failed`, {
+                cause: error,
+            }));
     }
     #failTask(task, error) {
         task.session.state = 'failed';
@@ -510,18 +758,81 @@ export class DiceEngine extends TypedEventEmitter {
         this.emit('error', { session: snapshotSession(task.session), error });
         this.#startNext();
     }
-    #removeDice(dice) {
+    #removeDiceSafely(dice, reason) {
+        const errors = [];
         for (const die of dice) {
-            this.#physics.removeDie(die.id);
-            this.#renderer.removeDie(die.id);
+            try {
+                this.#removeDie(die.id, reason);
+            }
+            catch (error) {
+                if (error instanceof AggregateError)
+                    errors.push(...error.errors);
+                else
+                    errors.push(error);
+            }
         }
+        return errors;
     }
     #removeDisplayedDice() {
+        const cleanupErrors = [];
         for (const id of this.#displayedDieIds) {
-            this.#physics.removeDie(id);
-            this.#renderer.removeDie(id);
+            try {
+                this.#removeDie(id, 'replaced');
+            }
+            catch (error) {
+                if (error instanceof AggregateError)
+                    cleanupErrors.push(...error.errors);
+                else
+                    cleanupErrors.push(error);
+            }
         }
         this.#displayedDieIds.clear();
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError(cleanupErrors, 'Failed to remove displayed dice');
+        }
+    }
+    #removeDie(id, reason) {
+        const cleanupErrors = this.#runCleanup([
+            () => this.#physics.removeDie(id),
+            () => this.#renderer.removeDie(id),
+        ]);
+        const event = this.#dieEvents.get(id);
+        if (event !== undefined) {
+            this.#dieEvents.delete(id);
+            this.emit('die:remove', Object.freeze({ ...event, reason }));
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError(cleanupErrors, `Failed to remove die ${id}`);
+        }
+    }
+    #clearRenderedDice(reason) {
+        const cleanupErrors = this.#runCleanup([
+            () => this.#physics.clear(),
+            () => this.#renderer.clear(),
+        ]);
+        this.#forgetRenderedDice(reason);
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError(cleanupErrors, 'Failed to clear rendered dice');
+        }
+    }
+    #forgetRenderedDice(reason) {
+        for (const event of this.#dieEvents.values()) {
+            this.emit('die:remove', Object.freeze({ ...event, reason }));
+        }
+        this.#dieEvents.clear();
+        this.#displayedDieIds.clear();
+    }
+    #runCleanup(actions) {
+        const errors = [];
+        for (const action of actions) {
+            try {
+                action();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        return errors;
     }
     #detachAbort(task) {
         if (task.signal !== undefined && task.abortListener !== undefined) {
@@ -571,6 +882,40 @@ export class DiceEngine extends TypedEventEmitter {
         }
         return merged;
     }
+    #assertValidVisualPreset(preset) {
+        if (!isDieType(preset.dieType) || !isPhysicalDieType(preset.dieType)) {
+            throw new RangeError(`Visual preset die type is not supported: ${preset.dieType}`);
+        }
+        if (!isDieType(preset.geometryId) || !hasDieGeometry(preset.geometryId)) {
+            throw new RangeError(`Visual preset geometry is not registered: ${preset.geometryId}`);
+        }
+        const geometry = getDieGeometry(preset.geometryId);
+        const faceValues = new Set(geometry.faces.map((face) => face.value));
+        const logicalSides = Number(preset.dieType.slice(1));
+        if (preset.valueMap !== undefined) {
+            const mappedFaces = Object.keys(preset.valueMap).map(Number);
+            if (mappedFaces.length !== faceValues.size ||
+                mappedFaces.some((face) => !faceValues.has(face))) {
+                throw new RangeError('Visual preset valueMap must map every geometry face exactly once');
+            }
+        }
+        for (const face of faceValues) {
+            const value = preset.valueMap?.[face] ?? face;
+            if (!Number.isSafeInteger(value) || value < 1 || value > logicalSides) {
+                throw new RangeError(`Visual preset maps geometry face ${face} outside ${preset.dieType}`);
+            }
+        }
+        if (preset.faceLabels !== undefined &&
+            Object.keys(preset.faceLabels).some((face) => !faceValues.has(Number(face)))) {
+            throw new RangeError('Visual preset faceLabels contain a face absent from its geometry');
+        }
+    }
+    #getPresetGeometryType(preset) {
+        if (!isDieType(preset.geometryId) || !hasDieGeometry(preset.geometryId)) {
+            throw new RangeError(`Visual preset geometry is not registered: ${preset.geometryId}`);
+        }
+        return preset.geometryId;
+    }
     #assertReady() {
         this.#assertAlive();
         if (!this.#initialized)

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { DiceEngine } from './dice-engine.js';
 export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
 export type { RollLimit } from './errors.js';
-export type { DiceEngineEvents, DiceEngineFacade, DiceEngineLimits, DiceEngineOptions, DiceMaterialType, DiceTheme, FrameScheduler, FrameToken, RollOptions, } from './types.js';
+export type { DiceEngineEvents, DiceEngineFacade, DiceEngineLimits, DiceEngineOptions, DiceCollisionEvent, DiceImpactEvent, DiceCollisionEventOptions, DiceMaterialType, DiceRemovalReason, DiceRemoveEvent, DiceTheme, DiceVisualEvent, FrameScheduler, FrameToken, RegisterEngineVisualPresetOptions, RollOptions, } from './types.js';
+export { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, type PhysicalDieType, } from './visual-presets.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 export { DiceEngine } from './dice-engine.js';
 export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
+export { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, } from './visual-presets.js';

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 import type { DieResult, RandomSource, RollMode, RollResult, RollSession } 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';
+import type { PhysicalDieType } from './visual-presets.js';
 export interface FrameToken {
     cancel(): void;
 }
@@ -13,18 +15,49 @@ export interface RollOptions {
     readonly mode?: RollMode;
     readonly signal?: AbortSignal;
 }
+export interface RegisterEngineVisualPresetOptions extends RegisterVisualPresetOptions {
+    readonly makeDefault?: boolean;
+}
 export interface DiceEngineLimits {
     readonly maxNotationLength: number;
     readonly maxLogicalDice: number;
     readonly maxPhysicalDice: number;
     readonly maxQueuedRolls: number;
 }
+export interface DiceVisualEvent {
+    readonly sessionId: string;
+    readonly dieId: string;
+    readonly dieType: string;
+    readonly presetId: string;
+    readonly skinId?: string;
+    readonly soundPackId?: string;
+}
+export type DiceRemovalReason = 'replaced' | 'cancelled' | 'failed' | 'cleared' | 'destroyed';
+export interface DiceRemoveEvent extends DiceVisualEvent {
+    readonly reason: DiceRemovalReason;
+}
+export interface DiceCollisionEvent extends DiceVisualEvent {
+    readonly otherDieId?: string;
+    readonly started: boolean;
+}
+export interface DiceImpactEvent extends DiceVisualEvent {
+    readonly otherDieId?: string;
+    readonly force: number;
+}
+export interface DiceCollisionEventOptions {
+    readonly enabled: boolean;
+    readonly maxEventsPerFrame: number;
+}
 export interface DiceEngineEvents {
     readonly 'roll:start': RollSession;
+    readonly 'die:spawn': DiceVisualEvent;
     readonly 'die:settled': {
         readonly sessionId: string;
         readonly die: DieResult;
     };
+    readonly 'die:remove': DiceRemoveEvent;
+    readonly 'die:collision': DiceCollisionEvent;
+    readonly 'die:impact': DiceImpactEvent;
     readonly 'roll:complete': RollResult;
     readonly 'roll:cancel': RollSession;
     readonly 'theme:change': DiceTheme;
@@ -47,6 +80,9 @@ export interface DiceEngineOptions {
     readonly diceMaterial?: DicePhysicsMaterial;
     readonly theme?: Partial<DiceTheme>;
     readonly limits?: Partial<DiceEngineLimits>;
+    readonly visualPresets?: readonly VisualPresetDescriptor[];
+    readonly visualPresetIds?: Partial<Readonly<Record<PhysicalDieType, string>>>;
+    readonly collisionEvents?: Partial<DiceCollisionEventOptions>;
 }
 export interface DiceEngineFacade {
     initialize(): Promise<void>;
@@ -55,5 +91,9 @@ export interface DiceEngineFacade {
     clear(): void;
     resize(viewport: RendererViewport): void;
     setTheme(theme: Partial<DiceTheme>): DiceTheme;
+    registerVisualPreset(preset: VisualPresetDescriptor, options?: RegisterEngineVisualPresetOptions): VisualPresetDescriptor;
+    unregisterVisualPreset(id: string): boolean;
+    setVisualPreset(dieType: PhysicalDieType, presetId: string): void;
+    getVisualPreset(dieType: PhysicalDieType): VisualPresetDescriptor;
     destroy(): void;
 }

package/dist/visual-presets.d.ts

@@ -0,0 +1,7 @@
+import type { DieType } from '@dice-o-rolla/dice-core';
+import type { VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
+export type PhysicalDieType = Exclude<DieType, 'd100'>;
+export declare const PHYSICAL_DIE_TYPES: readonly PhysicalDieType[];
+export declare const STANDARD_VISUAL_PRESETS: readonly VisualPresetDescriptor[];
+export declare function getStandardVisualPresetId(dieType: PhysicalDieType): string;
+export declare function isPhysicalDieType(value: unknown): value is PhysicalDieType;

package/dist/visual-presets.js

@@ -0,0 +1,20 @@
+export const PHYSICAL_DIE_TYPES = Object.freeze([
+    'd4',
+    'd6',
+    'd8',
+    'd10',
+    'd12',
+    'd20',
+]);
+export const STANDARD_VISUAL_PRESETS = Object.freeze(PHYSICAL_DIE_TYPES.map((dieType) => Object.freeze({
+    id: `standard:${dieType}`,
+    dieType,
+    geometryId: dieType,
+    scale: 1,
+})));
+export function getStandardVisualPresetId(dieType) {
+    return `standard:${dieType}`;
+}
+export function isPhysicalDieType(value) {
+    return PHYSICAL_DIE_TYPES.some((type) => type === value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-engine",
-  "version": "0.1.1",
+  "version": "0.2.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.1.1",
-    "@dice-o-rolla/dice-geometry": "0.1.1",
-    "@dice-o-rolla/dice-physics": "0.1.1",
-    "@dice-o-rolla/dice-physics-rapier": "0.1.1",
-    "@dice-o-rolla/dice-renderer": "0.1.1",
-    "@dice-o-rolla/dice-renderer-three": "0.1.1"
+    "@dice-o-rolla/dice-core": "0.2.0",
+    "@dice-o-rolla/dice-geometry": "0.2.0",
+    "@dice-o-rolla/dice-physics": "0.2.0",
+    "@dice-o-rolla/dice-physics-rapier": "0.2.0",
+    "@dice-o-rolla/dice-renderer": "0.2.0",
+    "@dice-o-rolla/dice-renderer-three": "0.2.0"
   },
   "engines": {
     "node": ">=20.0.0"