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

package/dist/errors.d.ts

@@ -16,3 +16,10 @@ export declare class RollLimitExceededError extends RangeError {
     readonly actual: number;
     constructor(limit: RollLimit, maximum: number, actual: number);
 }
+export type TraceLimit = 'events' | 'frames' | 'samples';
+export declare class TraceLimitExceededError extends RangeError {
+    readonly limit: TraceLimit;
+    readonly maximum: number;
+    readonly actual: number;
+    constructor(limit: TraceLimit, maximum: number, actual: number);
+}

package/dist/errors.js

@@ -32,3 +32,15 @@ export class RollLimitExceededError extends RangeError {
         this.actual = actual;
     }
 }
+export class TraceLimitExceededError extends RangeError {
+    limit;
+    maximum;
+    actual;
+    constructor(limit, maximum, actual) {
+        super(`Physical roll trace exceeds ${limit} limit of ${maximum} (received ${actual})`);
+        this.name = 'TraceLimitExceededError';
+        this.limit = limit;
+        this.maximum = maximum;
+        this.actual = actual;
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 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 { 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 { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, type PhysicalDieType, } from './visual-presets.js';
+export { DICE_ENGINE_VERSION } from './version.js';

package/dist/index.js

@@ -1,2 +1,4 @@
 export { DiceEngine } from './dice-engine.js';
-export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
+export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, TraceLimitExceededError, } from './errors.js';
+export { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, } from './visual-presets.js';
+export { DICE_ENGINE_VERSION } from './version.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 { DieResult, DieType, 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';
+import type { PhysicalDieType } from './visual-presets.js';
 export interface FrameToken {
     cancel(): void;
 }
@@ -13,18 +15,129 @@ export interface RollOptions {
     readonly mode?: RollMode;
     readonly signal?: AbortSignal;
 }
+export interface SimulateOptions {
+    readonly seed: number;
+    readonly captureFrames?: boolean;
+    /** Capture one frame every N fixed simulation steps. */
+    readonly frameIntervalSteps?: number;
+}
+export interface ReplayOptions {
+    readonly theme?: Partial<DiceTheme>;
+    readonly signal?: AbortSignal;
+}
+export interface PhysicalRollFrameDie {
+    readonly id: string;
+    readonly position: Vector3Like;
+    readonly quaternion: QuaternionLike;
+}
+export interface PhysicalRollFrame {
+    readonly elapsedSeconds: number;
+    readonly dice: readonly PhysicalRollFrameDie[];
+}
+export interface PhysicalRollTraceDie {
+    readonly id: string;
+    readonly type: DieType;
+    readonly presetId: string;
+    readonly geometryId: string;
+    readonly definitionFingerprint: string;
+    readonly scale: number;
+    readonly faceLabels?: Readonly<Record<number, string | number>>;
+    readonly initial: {
+        readonly position: Vector3Like;
+        readonly quaternion: QuaternionLike;
+        readonly impulse: Vector3Like;
+        readonly torqueImpulse: Vector3Like;
+    };
+}
+export interface PhysicalRollTraceCollisionEvent {
+    readonly kind: 'collision';
+    readonly elapsedSeconds: number;
+    readonly dieId: string;
+    readonly otherDieId?: string;
+    readonly started: boolean;
+}
+export interface PhysicalRollTraceImpactEvent {
+    readonly kind: 'impact';
+    readonly elapsedSeconds: number;
+    readonly dieId: string;
+    readonly otherDieId?: string;
+    readonly force: number;
+}
+export type PhysicalRollTraceEvent = PhysicalRollTraceCollisionEvent | PhysicalRollTraceImpactEvent;
+export interface PhysicalRollTraceProfile {
+    readonly fixedStepSeconds: number;
+    readonly settling: SettlingOptions;
+    readonly throw: ThrowGeneratorOptions;
+    readonly tray: TrayOptions;
+    readonly diceMaterial: DicePhysicsMaterial;
+}
+export interface PhysicalRollTraceProducer {
+    readonly name: '@dice-o-rolla/dice-engine';
+    readonly version: string;
+}
+/** JSON-serializable, renderer-neutral output of a deterministic physical simulation. */
+export interface PhysicalRollTrace {
+    readonly version: 1;
+    readonly producer: PhysicalRollTraceProducer;
+    readonly notation: string;
+    readonly seed: number;
+    readonly fixedStepSeconds: number;
+    readonly frameIntervalSteps: number;
+    readonly durationSeconds: number;
+    readonly profile: PhysicalRollTraceProfile;
+    readonly dice: readonly PhysicalRollTraceDie[];
+    readonly frames: readonly PhysicalRollFrame[];
+    readonly events: readonly PhysicalRollTraceEvent[];
+    readonly result: RollResult;
+}
+export interface DiceTraceLimits {
+    readonly maxFrames: number;
+    readonly maxSamples: number;
+    readonly maxEvents: number;
+}
+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,13 +160,23 @@ export interface DiceEngineOptions {
     readonly diceMaterial?: DicePhysicsMaterial;
     readonly theme?: Partial<DiceTheme>;
     readonly limits?: Partial<DiceEngineLimits>;
+    readonly traceLimits?: Partial<DiceTraceLimits>;
+    readonly visualPresets?: readonly VisualPresetDescriptor[];
+    readonly visualPresetIds?: Partial<Readonly<Record<PhysicalDieType, string>>>;
+    readonly collisionEvents?: Partial<DiceCollisionEventOptions>;
 }
 export interface DiceEngineFacade {
     initialize(): Promise<void>;
     roll(notation: string, options?: RollOptions): Promise<RollResult>;
+    simulate(notation: string, options: SimulateOptions): Promise<PhysicalRollTrace>;
+    replay(trace: PhysicalRollTrace, options?: ReplayOptions): Promise<void>;
     cancel(sessionId?: string): boolean;
     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/version.d.ts

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

package/dist/version.js

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

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.3.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.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"
   },
   "engines": {
     "node": ">=20.0.0"