@dice-o-rolla/dice-engine 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+Dice O Rolla
+Copyright 2026 Dmitriy Pyankov
+
+This product is licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,60 @@
+# `@dice-o-rolla/dice-engine`
+
+Framework-neutral orchestration for physically simulated polyhedral dice. The package exposes a
+backend-neutral engine and an optional browser composition backed by Rapier and Three.js.
+
+## Browser usage
+
+```ts
+import { createDefaultDiceEngine } from '@dice-o-rolla/dice-engine/browser';
+
+const container = document.querySelector<HTMLElement>('#dice-tray');
+if (container === null) throw new Error('Missing dice tray');
+
+const engine = await createDefaultDiceEngine({ container });
+const result = await engine.roll('2d20 + 4');
+
+console.log(result.total, result.dice);
+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.
+
+## Custom adapters
+
+```ts
+import { DiceEngine } from '@dice-o-rolla/dice-engine';
+
+const engine = new DiceEngine({ physics, renderer });
+await engine.initialize();
+```
+
+The main entry point depends on domain contracts rather than concrete Rapier or Three.js types.
+
+## Supported notation
+
+The initial grammar supports standard polyhedral expressions and integer modifiers, including:
+
+```text
+d20
+4d6 + 2
+d%
+d100
+d66
+```
+
+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.
+
+## Trust and cleanup
+
+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.
+
+## License
+
+Licensed under the Apache License, Version 2.0. The package archive includes `LICENSE`, `NOTICE`, and
+`THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Third-party notices
+
+## 3DDiceRoller
+
+The geometry model and physical dice behavior were informed by 3DDiceRoller by MajorVictory,
+released under The Unlicense.
+
+- Source: <https://github.com/MajorVictory/3DDiceRoller>
+- License: <https://unlicense.org/>
+
+## Runtime dependencies
+
+- Three.js is distributed under the MIT License: <https://github.com/mrdoob/three.js>.
+- Rapier is distributed under the Apache License 2.0:
+  <https://github.com/dimforge/rapier.js>.
+
+The UNLICENSED anvil-dice-engine project was used only for architectural comparison. No source code,
+assets, sounds, shaders, or textures from that project are included in this distribution.

package/dist/browser.d.ts

@@ -0,0 +1,11 @@
+import { type RapierPhysicsWorldOptions } from '@dice-o-rolla/dice-physics-rapier';
+import { type ThreeDiceRendererOptions } from '@dice-o-rolla/dice-renderer-three';
+import type { DiceEngine } from './dice-engine.js';
+import type { DiceEngineOptions } from './types.js';
+export interface DefaultDiceEngineOptions {
+    readonly container: HTMLElement;
+    readonly physics?: RapierPhysicsWorldOptions;
+    readonly renderer?: ThreeDiceRendererOptions;
+    readonly engine?: Omit<DiceEngineOptions, 'physics' | 'renderer'>;
+}
+export declare function createDefaultDiceEngine(options: DefaultDiceEngineOptions): Promise<DiceEngine>;

package/dist/browser.js

@@ -0,0 +1,12 @@
+/// <reference lib="dom" />
+import { cryptoRandomSource } from '@dice-o-rolla/dice-core';
+import { RapierPhysics } from '@dice-o-rolla/dice-physics-rapier';
+import { ThreeDiceRenderer, } from '@dice-o-rolla/dice-renderer-three';
+import { initializeOwnedDiceEngine } from './composition.js';
+export async function createDefaultDiceEngine(options) {
+    const physics = await RapierPhysics.create(options.physics);
+    return initializeOwnedDiceEngine(physics, () => new ThreeDiceRenderer(options.container, options.renderer), {
+        ...options.engine,
+        random: options.engine?.random ?? cryptoRandomSource,
+    });
+}

package/dist/composition.d.ts

@@ -0,0 +1,5 @@
+import type { PhysicsWorld } from '@dice-o-rolla/dice-physics';
+import type { DiceRenderer } from '@dice-o-rolla/dice-renderer';
+import { DiceEngine } from './dice-engine.js';
+import type { DiceEngineOptions } from './types.js';
+export declare function initializeOwnedDiceEngine(physics: PhysicsWorld, createRenderer: () => DiceRenderer, options: Omit<DiceEngineOptions, 'physics' | 'renderer'>): Promise<DiceEngine>;

package/dist/composition.js

@@ -0,0 +1,31 @@
+import { DiceEngine } from './dice-engine.js';
+export async function initializeOwnedDiceEngine(physics, createRenderer, options) {
+    let renderer;
+    try {
+        renderer = createRenderer();
+        const engine = new DiceEngine({ ...options, physics, renderer });
+        await engine.initialize();
+        return engine;
+    }
+    catch (error) {
+        const cleanupErrors = [];
+        try {
+            renderer?.destroy();
+        }
+        catch (cleanupError) {
+            cleanupErrors.push(cleanupError);
+        }
+        try {
+            physics.destroy();
+        }
+        catch (cleanupError) {
+            cleanupErrors.push(cleanupError);
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], 'Dice engine initialization failed', {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}

package/dist/defaults.d.ts

@@ -0,0 +1,3 @@
+import type { DiceTheme, FrameScheduler } from './types.js';
+export declare const DEFAULT_THEME: DiceTheme;
+export declare const defaultFrameScheduler: FrameScheduler;

package/dist/defaults.js

@@ -0,0 +1,19 @@
+export const DEFAULT_THEME = Object.freeze({
+    material: 'plastic',
+    bodyColor: '#f7f3e8',
+    labelColor: '#181818',
+    roughness: 0.28,
+    metalness: 0,
+});
+export const defaultFrameScheduler = {
+    request(callback) {
+        const animationFrame = globalThis;
+        if (typeof animationFrame.requestAnimationFrame === 'function' &&
+            typeof animationFrame.cancelAnimationFrame === 'function') {
+            const handle = animationFrame.requestAnimationFrame(callback);
+            return { cancel: () => animationFrame.cancelAnimationFrame?.(handle) };
+        }
+        const handle = setTimeout(() => callback(performance.now()), 16);
+        return { cancel: () => clearTimeout(handle) };
+    },
+};

package/dist/dice-engine.d.ts

@@ -0,0 +1,16 @@
+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';
+export declare class DiceEngine extends TypedEventEmitter<DiceEngineEvents> implements DiceEngineFacade {
+    #private;
+    constructor(options: DiceEngineOptions);
+    initialize(): Promise<void>;
+    roll(notation: string, options?: RollOptions): Promise<RollResult>;
+    cancel(sessionId?: string): boolean;
+    clear(): void;
+    resize(viewport: RendererViewport): void;
+    setTheme(theme: Partial<DiceTheme>): DiceTheme;
+    get theme(): DiceTheme;
+    destroy(): void;
+}

package/dist/dice-engine.js

@@ -0,0 +1,583 @@
+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 { DEFAULT_THEME, defaultFrameScheduler } from './defaults.js';
+import { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
+const DEFAULT_SETTLING = {
+    linearVelocityThreshold: 0.08,
+    angularVelocityThreshold: 0.08,
+    stableTimeMs: 300,
+    maxRollTimeMs: 10_000,
+};
+const DEFAULT_THROW = {
+    position: {
+        x: { min: -2, max: 2 },
+        y: { min: 3.5, max: 5 },
+        z: { min: -2, max: 2 },
+    },
+    impulse: {
+        x: { min: -2.5, max: 2.5 },
+        y: { min: 0.5, max: 2 },
+        z: { min: -2.5, max: 2.5 },
+    },
+    torqueImpulse: {
+        x: { min: -3, max: 3 },
+        y: { min: -3, max: 3 },
+        z: { min: -3, max: 3 },
+    },
+};
+const DEFAULT_TRAY = {
+    width: 10,
+    depth: 10,
+    wallHeight: 6,
+    wallThickness: 0.25,
+    material: { friction: 0.8, restitution: 0.1 },
+};
+const DEFAULT_DICE_MATERIAL = {
+    friction: 0.7,
+    restitution: 0.15,
+    linearDamping: 0.25,
+    angularDamping: 0.25,
+};
+const DEFAULT_LIMITS = Object.freeze({
+    maxNotationLength: 256,
+    maxLogicalDice: 50,
+    maxPhysicalDice: 50,
+    maxQueuedRolls: 8,
+});
+const D100_TENS_LABELS = Object.freeze({
+    1: 10,
+    2: 20,
+    3: 30,
+    4: 40,
+    5: 50,
+    6: 60,
+    7: 70,
+    8: 80,
+    9: 90,
+    10: '00',
+});
+const D66_TENS_LABELS = Object.freeze({ 1: 10, 2: 20, 3: 30, 4: 40, 5: 50, 6: 60 });
+function snapshotSession(session) {
+    return Object.freeze({
+        id: session.id,
+        notation: session.notation,
+        state: session.state,
+        createdAt: session.createdAt,
+        ...(session.startedAt === undefined ? {} : { startedAt: session.startedAt }),
+        ...(session.completedAt === undefined ? {} : { completedAt: session.completedAt }),
+    });
+}
+function toRenderState(die) {
+    return {
+        id: die.id,
+        geometryId: die.geometryType,
+        ...(die.faceLabels === undefined ? {} : { faceLabels: die.faceLabels }),
+        previous: die.previous,
+        current: die.current,
+    };
+}
+function assertPositive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive finite number`);
+    }
+}
+function assertPositiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+export class DiceEngine extends TypedEventEmitter {
+    #physics;
+    #renderer;
+    #scheduler;
+    #now;
+    #fixedStepSeconds;
+    #maxFrameDeltaSeconds;
+    #settling;
+    #throwGenerator;
+    #tray;
+    #diceMaterial;
+    #limits;
+    #queue = [];
+    #displayedDieIds = new Set();
+    #active;
+    #frameToken;
+    #lastFrameMs = 0;
+    #accumulatorSeconds = 0;
+    #nextSessionId = 1;
+    #initialized = false;
+    #destroyed = false;
+    #theme;
+    constructor(options) {
+        super();
+        this.#physics = options.physics;
+        this.#renderer = options.renderer;
+        this.#scheduler = options.scheduler ?? defaultFrameScheduler;
+        this.#now = options.now ?? (() => performance.now());
+        this.#fixedStepSeconds = options.fixedStepSeconds ?? 1 / 60;
+        this.#maxFrameDeltaSeconds = options.maxFrameDeltaSeconds ?? 0.25;
+        assertPositive(this.#fixedStepSeconds, 'fixedStepSeconds');
+        assertPositive(this.#maxFrameDeltaSeconds, 'maxFrameDeltaSeconds');
+        this.#settling = options.settling ?? DEFAULT_SETTLING;
+        this.#throwGenerator = new ThrowGenerator(options.random ?? mathRandomSource, options.throw ?? DEFAULT_THROW);
+        this.#tray = options.tray ?? DEFAULT_TRAY;
+        this.#diceMaterial = options.diceMaterial ?? DEFAULT_DICE_MATERIAL;
+        this.#limits = Object.freeze({ ...DEFAULT_LIMITS, ...options.limits });
+        for (const [name, value] of [
+            ['maxNotationLength', this.#limits.maxNotationLength],
+            ['maxLogicalDice', this.#limits.maxLogicalDice],
+            ['maxPhysicalDice', this.#limits.maxPhysicalDice],
+            ['maxQueuedRolls', this.#limits.maxQueuedRolls],
+        ]) {
+            assertPositiveSafeInteger(value, `limits.${name}`);
+        }
+        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;
+    }
+    roll(notation, options = {}) {
+        try {
+            this.#assertReady();
+            if ((options.mode ?? 'queue') !== 'queue') {
+                throw new RangeError('Only queue roll mode is currently supported');
+            }
+            if (notation.length > this.#limits.maxNotationLength) {
+                throw new RollLimitExceededError('notation-length', this.#limits.maxNotationLength, notation.length);
+            }
+            const parsed = parseNotation(notation);
+            this.#assertSupportedAndWithinLimits(parsed);
+            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);
+            if (options.signal?.aborted === true) {
+                this.#rejectCancelled(task);
+                return task.promise;
+            }
+            this.#queue.push(task);
+            this.#startNext();
+            return task.promise;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    cancel(sessionId) {
+        this.#assertAlive();
+        if (this.#active !== undefined &&
+            (sessionId === undefined || this.#active.task.session.id === sessionId)) {
+            const task = this.#active.task;
+            this.#cancelActive(task);
+            return true;
+        }
+        const index = this.#queue.findIndex((task) => sessionId === undefined || task.session.id === sessionId);
+        const task = index < 0 ? undefined : this.#queue.splice(index, 1)[0];
+        if (task === undefined)
+            return false;
+        this.#rejectCancelled(task);
+        return true;
+    }
+    clear() {
+        this.#assertAlive();
+        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.#physics.clear();
+        this.#renderer.clear();
+        this.#displayedDieIds.clear();
+        this.#accumulatorSeconds = 0;
+    }
+    resize(viewport) {
+        this.#assertReady();
+        this.#renderer.resize(viewport);
+    }
+    setTheme(theme) {
+        this.#assertAlive();
+        this.#theme = this.#mergeTheme({ ...this.#theme, ...theme });
+        if (this.#initialized)
+            this.#renderer.setTheme(this.#theme);
+        this.emit('theme:change', this.#theme);
+        return this.#theme;
+    }
+    get theme() {
+        return this.#theme;
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.clear();
+        this.#renderer.destroy();
+        this.#physics.destroy();
+        super.clear();
+        this.#initialized = false;
+        this.#destroyed = true;
+    }
+    #createTask(notation, parsed, signal) {
+        const session = {
+            id: `roll-${this.#nextSessionId++}`,
+            notation,
+            state: 'pending',
+            createdAt: this.#now(),
+        };
+        let resolve;
+        let reject;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        const abortListener = signal === undefined ? undefined : () => void this.cancel(session.id);
+        if (abortListener !== undefined)
+            signal?.addEventListener('abort', abortListener, { once: true });
+        return {
+            session,
+            parsed,
+            promise,
+            resolve,
+            reject,
+            ...(signal === undefined ? {} : { signal }),
+            ...(abortListener === undefined ? {} : { abortListener }),
+        };
+    }
+    #startNext() {
+        if (this.#active !== undefined || this.#queue.length === 0)
+            return;
+        const task = this.#queue.shift();
+        if (task === undefined)
+            return;
+        this.#removeDisplayedDice();
+        task.session.state = 'rolling';
+        task.session.startedAt = this.#now();
+        try {
+            const dice = this.#createDice(task);
+            this.#active = { task, dice };
+            this.emit('roll:start', snapshotSession(task.session));
+            this.#lastFrameMs = this.#now();
+            this.#accumulatorSeconds = 0;
+            this.#scheduleFrame();
+        }
+        catch (error) {
+            const active = this.#active;
+            if (active?.task === task)
+                this.#failActive(active, error);
+            else
+                this.#failTask(task, error);
+        }
+    }
+    #createDice(task) {
+        const dice = [];
+        let index = 0;
+        const specs = this.#createPhysicalSpecs(task);
+        const totalDice = specs.length;
+        try {
+            for (const spec of specs) {
+                const geometry = getDieGeometry(spec.geometryType);
+                const id = `${task.session.id}:die-${index++}`;
+                const generated = this.#throwGenerator.generate();
+                const position = this.#placeDie(generated.position, index - 1, totalDice);
+                const body = this.#physics.createDie({
+                    id,
+                    type: spec.geometryType,
+                    collider: {
+                        kind: 'convex-hull',
+                        vertices: geometry.vertices.map(([x, y, z]) => ({ x, y, z })),
+                    },
+                    scale: 1,
+                    mass: 1,
+                    material: this.#diceMaterial,
+                    position,
+                    quaternion: generated.quaternion,
+                });
+                const state = body.getState();
+                const die = {
+                    id,
+                    type: spec.type,
+                    geometryType: spec.geometryType,
+                    ...(spec.component === undefined ? {} : { component: spec.component }),
+                    ...(spec.faceLabels === undefined ? {} : { faceLabels: spec.faceLabels }),
+                    body,
+                    detector: new SettlingDetector(this.#settling),
+                    previous: state,
+                    current: state,
+                };
+                dice.push(die);
+                this.#renderer.createDie(toRenderState(die));
+                body.applyImpulse(generated.impulse, generated.torqueImpulse);
+            }
+            return dice;
+        }
+        catch (error) {
+            for (const die of dice) {
+                this.#physics.removeDie(die.id);
+                this.#renderer.removeDie(die.id);
+            }
+            throw error;
+        }
+    }
+    #createPhysicalSpecs(task) {
+        const specs = [];
+        let groupIndex = 0;
+        for (const expression of task.parsed.expressions) {
+            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`);
+                for (let count = 0; count < expression.count; count += 1) {
+                    specs.push({ type, geometryType: type });
+                }
+                continue;
+            }
+            for (let count = 0; count < expression.count; count += 1) {
+                const groupId = `${task.session.id}:group-${groupIndex++}`;
+                if (expression.type === 'd100') {
+                    specs.push({
+                        type: 'd100',
+                        geometryType: 'd10',
+                        component: { groupId, groupType: 'd100', role: 'tens' },
+                        faceLabels: D100_TENS_LABELS,
+                    });
+                    specs.push({
+                        type: 'd10',
+                        geometryType: 'd10',
+                        component: { groupId, groupType: 'd100', role: 'units' },
+                    });
+                    continue;
+                }
+                specs.push({
+                    type: 'd6',
+                    geometryType: 'd6',
+                    component: { groupId, groupType: 'd66', role: 'tens' },
+                    faceLabels: D66_TENS_LABELS,
+                });
+                specs.push({
+                    type: 'd6',
+                    geometryType: 'd6',
+                    component: { groupId, groupType: 'd66', role: 'units' },
+                });
+            }
+        }
+        return specs;
+    }
+    #placeDie(generated, index, total) {
+        if (total <= 4)
+            return generated;
+        const columns = Math.ceil(Math.sqrt((total * this.#tray.width) / this.#tray.depth));
+        const rows = Math.ceil(total / columns);
+        const column = index % columns;
+        const row = Math.floor(index / columns);
+        const cellWidth = (this.#tray.width - 1) / columns;
+        const cellDepth = (this.#tray.depth - 1) / rows;
+        return {
+            x: (column - (columns - 1) / 2) * cellWidth + generated.x * 0.03,
+            y: generated.y,
+            z: (row - (rows - 1) / 2) * cellDepth + generated.z * 0.03,
+        };
+    }
+    #scheduleFrame() {
+        if (this.#active === undefined || this.#frameToken !== undefined)
+            return;
+        this.#frameToken = this.#scheduler.request((timestampMs) => {
+            this.#frameToken = undefined;
+            this.#runFrame(timestampMs);
+        });
+    }
+    #runFrame(timestampMs) {
+        const active = this.#active;
+        if (active === undefined)
+            return;
+        try {
+            const frameDelta = Math.max(0, Math.min((timestampMs - this.#lastFrameMs) / 1_000, this.#maxFrameDeltaSeconds));
+            this.#lastFrameMs = timestampMs;
+            this.#accumulatorSeconds += frameDelta;
+            while (this.#accumulatorSeconds >= this.#fixedStepSeconds) {
+                for (const die of active.dice)
+                    die.previous = die.current;
+                this.#physics.step(this.#fixedStepSeconds);
+                this.#accumulatorSeconds -= this.#fixedStepSeconds;
+                for (const die of active.dice) {
+                    die.current = die.body.getState();
+                    if (die.result !== undefined)
+                        continue;
+                    const settling = die.detector.update(die.current, this.#fixedStepSeconds * 1_000);
+                    if (settling === 'timed-out')
+                        throw new RollTimeoutError(active.task.session.id);
+                    if (settling === 'settled') {
+                        const geometry = getDieGeometry(die.geometryType);
+                        const faceValue = resolveFace(geometry, die.current.quaternion);
+                        die.result = this.#createDieResult(die, faceValue);
+                        this.emit('die:settled', { sessionId: active.task.session.id, die: die.result });
+                    }
+                }
+            }
+            for (const die of active.dice)
+                this.#renderer.updateDie(toRenderState(die));
+            const allSettled = active.dice.every((die) => die.result !== undefined);
+            this.#renderer.render(allSettled ? 1 : this.#accumulatorSeconds / this.#fixedStepSeconds);
+            if (allSettled) {
+                this.#completeActive(active);
+                return;
+            }
+            this.#scheduleFrame();
+        }
+        catch (error) {
+            this.#failActive(active, error);
+        }
+    }
+    #createDieResult(die, 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 });
+        }
+        const { groupId, groupType, role } = die.component;
+        const digit = groupType === 'd100' ? faceValue % 10 : faceValue;
+        return Object.freeze({
+            id: die.id,
+            type: die.type,
+            value: role === 'tens' ? digit * 10 : digit,
+            component: Object.freeze({ groupId, groupType, role, faceValue }),
+        });
+    }
+    #completeActive(active) {
+        const session = active.task.session;
+        session.state = 'settled';
+        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 result = createRollResult({
+            id: session.id,
+            notation: session.notation,
+            dice: diceResults,
+            modifier: getNotationModifier(active.task.parsed),
+            startedAt: session.startedAt,
+            completedAt: session.completedAt,
+        });
+        for (const die of active.dice)
+            this.#displayedDieIds.add(die.id);
+        this.#active = undefined;
+        this.#detachAbort(active.task);
+        active.task.resolve(result);
+        this.emit('roll:complete', result);
+        this.#startNext();
+    }
+    #cancelActive(task) {
+        this.#frameToken?.cancel();
+        this.#frameToken = undefined;
+        const active = this.#active;
+        this.#active = undefined;
+        if (active !== undefined)
+            this.#removeDice(active.dice);
+        this.#rejectCancelled(task);
+        this.#startNext();
+    }
+    #rejectCancelled(task) {
+        task.session.state = 'cancelled';
+        task.session.completedAt = this.#now();
+        this.#detachAbort(task);
+        task.reject(new RollCancelledError(task.session.id));
+        this.emit('roll:cancel', snapshotSession(task.session));
+    }
+    #failActive(active, error) {
+        this.#active = undefined;
+        this.#removeDice(active.dice);
+        this.#failTask(active.task, error);
+    }
+    #failTask(task, error) {
+        task.session.state = 'failed';
+        task.session.completedAt = this.#now();
+        this.#detachAbort(task);
+        task.reject(error);
+        this.emit('error', { session: snapshotSession(task.session), error });
+        this.#startNext();
+    }
+    #removeDice(dice) {
+        for (const die of dice) {
+            this.#physics.removeDie(die.id);
+            this.#renderer.removeDie(die.id);
+        }
+    }
+    #removeDisplayedDice() {
+        for (const id of this.#displayedDieIds) {
+            this.#physics.removeDie(id);
+            this.#renderer.removeDie(id);
+        }
+        this.#displayedDieIds.clear();
+    }
+    #detachAbort(task) {
+        if (task.signal !== undefined && task.abortListener !== undefined) {
+            task.signal.removeEventListener('abort', task.abortListener);
+        }
+    }
+    #assertSupportedAndWithinLimits(parsed) {
+        let logicalDice = 0;
+        let physicalDice = 0;
+        for (const expression of parsed.expressions) {
+            if (expression.kind === 'modifier')
+                continue;
+            if (expression.kind === 'dice') {
+                const type = `d${expression.sides}`;
+                if (!isDieType(type) || !hasDieGeometry(type)) {
+                    throw new RangeError(`${type} is not supported by the current engine`);
+                }
+            }
+            logicalDice = this.#addWithinLimit(logicalDice, expression.count, 'logical-dice', this.#limits.maxLogicalDice);
+            physicalDice = this.#addWeightedWithinLimit(physicalDice, expression.count, expression.kind === 'paired-dice' ? 2 : 1, 'physical-dice', this.#limits.maxPhysicalDice);
+        }
+    }
+    #addWithinLimit(current, increment, limit, maximum) {
+        if (increment > maximum - current) {
+            throw new RollLimitExceededError(limit, maximum, current + increment);
+        }
+        return current + increment;
+    }
+    #addWeightedWithinLimit(current, count, weight, limit, maximum) {
+        if (count > Math.floor((maximum - current) / weight)) {
+            throw new RollLimitExceededError(limit, maximum, current + count * weight);
+        }
+        return current + count * weight;
+    }
+    #mergeTheme(theme) {
+        const merged = Object.freeze({ ...DEFAULT_THEME, ...theme });
+        if (merged.bodyColor.length === 0 || merged.labelColor.length === 0) {
+            throw new RangeError('Theme colors must not be empty');
+        }
+        for (const [name, value] of [
+            ['roughness', merged.roughness],
+            ['metalness', merged.metalness],
+        ]) {
+            if (!Number.isFinite(value) || value < 0 || value > 1) {
+                throw new RangeError(`Theme ${name} must be a finite number in [0, 1]`);
+            }
+        }
+        return merged;
+    }
+    #assertReady() {
+        this.#assertAlive();
+        if (!this.#initialized)
+            throw new Error('DiceEngine has not been initialized');
+    }
+    #assertAlive() {
+        if (this.#destroyed)
+            throw new DiceEngineDestroyedError();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class RollCancelledError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class RollTimeoutError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class DiceEngineDestroyedError extends Error {
+    constructor();
+}
+export type RollLimit = 'notation-length' | 'logical-dice' | 'physical-dice' | 'queue-size';
+export declare class RollLimitExceededError extends RangeError {
+    readonly limit: RollLimit;
+    readonly maximum: number;
+    readonly actual: number;
+    constructor(limit: RollLimit, maximum: number, actual: number);
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+export class RollCancelledError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Roll ${sessionId} was cancelled`);
+        this.name = 'RollCancelledError';
+        this.sessionId = sessionId;
+    }
+}
+export class RollTimeoutError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Roll ${sessionId} did not settle before the timeout`);
+        this.name = 'RollTimeoutError';
+        this.sessionId = sessionId;
+    }
+}
+export class DiceEngineDestroyedError extends Error {
+    constructor() {
+        super('DiceEngine has been destroyed');
+        this.name = 'DiceEngineDestroyedError';
+    }
+}
+export class RollLimitExceededError extends RangeError {
+    limit;
+    maximum;
+    actual;
+    constructor(limit, maximum, actual) {
+        super(`Roll exceeds ${limit} limit of ${maximum} (received ${actual})`);
+        this.name = 'RollLimitExceededError';
+        this.limit = limit;
+        this.maximum = maximum;
+        this.actual = actual;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { DiceEngine } from './dice-engine.js';
+export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+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';
+export interface FrameToken {
+    cancel(): void;
+}
+export interface FrameScheduler {
+    request(callback: (timestampMs: number) => void): FrameToken;
+}
+export type DiceMaterialType = RendererTheme['material'];
+export type DiceTheme = RendererTheme;
+export interface RollOptions {
+    readonly mode?: RollMode;
+    readonly signal?: AbortSignal;
+}
+export interface DiceEngineLimits {
+    readonly maxNotationLength: number;
+    readonly maxLogicalDice: number;
+    readonly maxPhysicalDice: number;
+    readonly maxQueuedRolls: number;
+}
+export interface DiceEngineEvents {
+    readonly 'roll:start': RollSession;
+    readonly 'die:settled': {
+        readonly sessionId: string;
+        readonly die: DieResult;
+    };
+    readonly 'roll:complete': RollResult;
+    readonly 'roll:cancel': RollSession;
+    readonly 'theme:change': DiceTheme;
+    readonly error: {
+        readonly session: RollSession;
+        readonly error: unknown;
+    };
+}
+export interface DiceEngineOptions {
+    readonly physics: PhysicsWorld;
+    readonly renderer: DiceRenderer;
+    readonly random?: RandomSource;
+    readonly scheduler?: FrameScheduler;
+    readonly now?: () => number;
+    readonly fixedStepSeconds?: number;
+    readonly maxFrameDeltaSeconds?: number;
+    readonly settling?: SettlingOptions;
+    readonly throw?: ThrowGeneratorOptions;
+    readonly tray?: TrayOptions;
+    readonly diceMaterial?: DicePhysicsMaterial;
+    readonly theme?: Partial<DiceTheme>;
+    readonly limits?: Partial<DiceEngineLimits>;
+}
+export interface DiceEngineFacade {
+    initialize(): Promise<void>;
+    roll(notation: string, options?: RollOptions): Promise<RollResult>;
+    cancel(sessionId?: string): boolean;
+    clear(): void;
+    resize(viewport: RendererViewport): void;
+    setTheme(theme: Partial<DiceTheme>): DiceTheme;
+    destroy(): void;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dice-o-rolla/dice-engine",
+  "version": "0.1.0",
+  "description": "Framework-neutral physical dice engine with Rapier and Three.js browser adapters.",
+  "keywords": [
+    "dice",
+    "dice-roller",
+    "physics",
+    "rpg",
+    "three.js",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@dice-o-rolla/dice-core": "0.1.0",
+    "@dice-o-rolla/dice-geometry": "0.1.0",
+    "@dice-o-rolla/dice-physics": "0.1.0",
+    "@dice-o-rolla/dice-physics-rapier": "0.1.0",
+    "@dice-o-rolla/dice-renderer": "0.1.0",
+    "@dice-o-rolla/dice-renderer-three": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}