@dice-o-rolla/dice-renderer-three 0.3.0 → 0.4.0

package/README.md

@@ -7,6 +7,12 @@ renderer and `TopDownDiceRenderer` for overhead application surfaces.
 import { ThreeDiceRenderer, TopDownDiceRenderer } from '@dice-o-rolla/dice-renderer-three';
 ```
 
+Both renderers accept the same `materialProvider` option, either as an existing
+`ThreeFaceMaterialProvider` or as a factory receiving the initialized `WebGLRenderer`. This keeps
+KTX2 capability detection and GPU-backed asset setup available in perspective and top-down layouts.
+Their common theme, resizing, framebuffer-limit, antialiasing, and material options are exported as
+`ThreeRendererOptions`; top-down options only extend that contract with camera and tray framing.
+
 Most browser applications should use the preassembled entry point from
 `@dice-o-rolla/dice-engine/browser`.
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { ThreeMaterialFactory, type DiceMaterialStyle, type FaceLabel, type FaceMaterialOptions, } from './material-factory.js';
 export { createPolyhedronGeometry, createFaceUvs, DEFAULT_THREE_THEME, getFaceLabel, ThreeDiceMeshFactory, type ThreeDiceMesh, type FaceMaterialContext, type FaceMaterialResource, type ThreeFaceMaterialProvider, } from './mesh-factory.js';
+export type { ThreeRendererOptions } from './renderer-options.js';
 export { ThreeCamera, ThreeLighting, ThreeScene } from './scene.js';
 export { TopDownCamera, type TopDownCameraOptions } from './top-down-camera.js';
 export { TopDownDiceRenderer, type TopDownDiceRendererOptions } from './top-down-dice-renderer.js';

package/dist/renderer-common.d.ts

@@ -0,0 +1,9 @@
+import type { RenderDieState, RendererTheme, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
+import type { ThreeDiceMesh, ThreeDiceMeshFactory } from './mesh-factory.js';
+export interface ThreeRenderEntry {
+    resource: ThreeDiceMesh;
+    state: RenderDieState;
+}
+export declare function copyRenderState(state: RenderDieState): RenderDieState;
+export declare function haveEqualFaceLabels(left: RenderDieState['faceLabels'], right: RenderDieState['faceLabels']): boolean;
+export declare function createDiceMeshResource(state: RenderDieState, presets: ReadonlyMap<string, VisualPresetDescriptor>, meshFactory: ThreeDiceMeshFactory, theme: RendererTheme): ThreeDiceMesh;

package/dist/renderer-common.js

@@ -0,0 +1,39 @@
+import { getDieGeometry, getRegisteredDieTypes } from '@dice-o-rolla/dice-geometry';
+export function copyRenderState(state) {
+    return {
+        id: state.id,
+        presetId: state.presetId,
+        geometryId: state.geometryId,
+        scale: state.scale,
+        ...(state.faceLabels === undefined ? {} : { faceLabels: { ...state.faceLabels } }),
+        previous: {
+            position: { ...state.previous.position },
+            quaternion: { ...state.previous.quaternion },
+        },
+        current: {
+            position: { ...state.current.position },
+            quaternion: { ...state.current.quaternion },
+        },
+    };
+}
+export function haveEqualFaceLabels(left, right) {
+    if (left === right)
+        return true;
+    if (left === undefined || right === undefined)
+        return false;
+    const leftEntries = Object.entries(left);
+    return (leftEntries.length === Object.keys(right).length &&
+        leftEntries.every(([face, label]) => right[Number(face)] === label));
+}
+export function createDiceMeshResource(state, presets, meshFactory, theme) {
+    const preset = presets.get(state.presetId);
+    if (preset === undefined)
+        throw new Error(`Unknown visual preset: ${state.presetId}`);
+    if (preset.geometryId !== state.geometryId || (preset.scale ?? 1) !== state.scale) {
+        throw new Error(`Render state does not match visual preset "${state.presetId}"`);
+    }
+    const type = getRegisteredDieTypes().find((registered) => registered === state.geometryId);
+    if (type === undefined)
+        throw new Error(`Unsupported geometry: ${state.geometryId}`);
+    return meshFactory.create(getDieGeometry(type), theme, state.scale, state.faceLabels, preset);
+}

package/dist/renderer-options.d.ts

@@ -0,0 +1,10 @@
+import type { RendererTheme } from '@dice-o-rolla/dice-renderer';
+import type { WebGLRenderer } from 'three';
+import type { ThreeFaceMaterialProvider } from './mesh-factory.js';
+import type { ViewportLimitOptions } from './viewport-limits.js';
+/** Options shared by every official Three.js dice renderer. */
+export interface ThreeRendererOptions extends Partial<RendererTheme>, ViewportLimitOptions {
+    readonly antialias?: boolean;
+    readonly observeResize?: boolean;
+    readonly materialProvider?: ThreeFaceMaterialProvider | ((renderer: WebGLRenderer) => ThreeFaceMaterialProvider);
+}

package/dist/three-dice-renderer.d.ts

@@ -1,13 +1,6 @@
 import type { DiceRenderer, RenderDieState, RendererTheme, RendererViewport, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
-import { WebGLRenderer } from 'three';
-import { type ThreeFaceMaterialProvider } from './mesh-factory.js';
-export interface ThreeDiceRendererOptions extends Partial<RendererTheme> {
-    readonly antialias?: boolean;
-    readonly observeResize?: boolean;
-    readonly maxPixelRatio?: number;
-    readonly maxViewportDimension?: number;
-    readonly maxFramebufferPixels?: number;
-    readonly materialProvider?: ThreeFaceMaterialProvider | ((renderer: WebGLRenderer) => ThreeFaceMaterialProvider);
+import type { ThreeRendererOptions } from './renderer-options.js';
+export interface ThreeDiceRendererOptions extends ThreeRendererOptions {
 }
 export declare class ThreeDiceRenderer implements DiceRenderer {
     #private;

package/dist/three-dice-renderer.js

@@ -1,26 +1,9 @@
-import { getDieGeometry, getRegisteredDieTypes } from '@dice-o-rolla/dice-geometry';
 import { PCFShadowMap, WebGLRenderer } from 'three';
 import { DEFAULT_THREE_THEME, ThreeDiceMeshFactory, } from './mesh-factory.js';
+import { copyRenderState, createDiceMeshResource, haveEqualFaceLabels, } from './renderer-common.js';
 import { ThreeCamera, ThreeScene } from './scene.js';
 import { applyInterpolatedTransform } from './transform.js';
 import { fitViewportToLimits, resolveViewportLimits, validateViewport, } from './viewport-limits.js';
-function copyState(state) {
-    return {
-        id: state.id,
-        presetId: state.presetId,
-        geometryId: state.geometryId,
-        scale: state.scale,
-        ...(state.faceLabels === undefined ? {} : { faceLabels: { ...state.faceLabels } }),
-        previous: {
-            position: { ...state.previous.position },
-            quaternion: { ...state.previous.quaternion },
-        },
-        current: {
-            position: { ...state.current.position },
-            quaternion: { ...state.current.quaternion },
-        },
-    };
-}
 export class ThreeDiceRenderer {
     #container;
     #options;
@@ -96,7 +79,7 @@ export class ThreeDiceRenderer {
         if (this.#entries.has(state.id))
             throw new Error(`A render die with id "${state.id}" already exists`);
         const resource = this.#createResource(state);
-        const ownedState = copyState(state);
+        const ownedState = copyRenderState(state);
         applyInterpolatedTransform(resource.mesh, ownedState, 1);
         this.#scene?.value.add(resource.mesh);
         this.#entries.set(state.id, { resource, state: ownedState });
@@ -115,7 +98,7 @@ export class ThreeDiceRenderer {
         if (!haveEqualFaceLabels(state.faceLabels, entry.state.faceLabels)) {
             throw new Error('Die face labels cannot be changed after creation');
         }
-        entry.state = copyState(state);
+        entry.state = copyRenderState(state);
     }
     removeDie(id) {
         this.#assertAlive();
@@ -190,16 +173,7 @@ export class ThreeDiceRenderer {
         }, this.#viewportLimits));
     }
     #createResource(state) {
-        const preset = this.#presets.get(state.presetId);
-        if (preset === undefined)
-            throw new Error(`Unknown visual preset: ${state.presetId}`);
-        if (preset.geometryId !== state.geometryId || (preset.scale ?? 1) !== state.scale) {
-            throw new Error(`Render state does not match visual preset "${state.presetId}"`);
-        }
-        const type = getRegisteredDieTypes().find((registered) => registered === state.geometryId);
-        if (type === undefined)
-            throw new Error(`Unsupported geometry: ${state.geometryId}`);
-        return this.#meshFactory.create(getDieGeometry(type), this.#theme, state.scale, state.faceLabels, preset);
+        return createDiceMeshResource(state, this.#presets, this.#meshFactory, this.#theme);
     }
     #releasePendingPreset(presetId) {
         if (!this.#pendingPresetRemovals.has(presetId))
@@ -215,17 +189,8 @@ export class ThreeDiceRenderer {
     }
     #assertInitialized() {
         this.#assertAlive();
-        if (this.#renderer === undefined)
+        if (this.#scene === undefined || this.#camera === undefined || this.#renderer === undefined) {
             throw new Error('Renderer has not been initialized');
+        }
     }
 }
-function haveEqualFaceLabels(left, right) {
-    if (left === right)
-        return true;
-    if (left === undefined || right === undefined)
-        return false;
-    const leftEntries = Object.entries(left);
-    const rightEntries = Object.entries(right);
-    return (leftEntries.length === rightEntries.length &&
-        leftEntries.every(([face, label]) => right[Number(face)] === label));
-}

package/dist/top-down-dice-renderer.d.ts

@@ -1,9 +1,7 @@
 import type { DiceRenderer, RenderDieState, RendererTheme, RendererViewport, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
+import type { ThreeRendererOptions } from './renderer-options.js';
 import { type TopDownCameraOptions } from './top-down-camera.js';
-import { type ViewportLimitOptions } from './viewport-limits.js';
-export interface TopDownDiceRendererOptions extends Partial<RendererTheme>, ViewportLimitOptions, TopDownCameraOptions {
-    readonly antialias?: boolean;
-    readonly observeResize?: boolean;
+export interface TopDownDiceRendererOptions extends ThreeRendererOptions, TopDownCameraOptions {
 }
 export declare class TopDownDiceRenderer implements DiceRenderer {
     #private;

package/dist/top-down-dice-renderer.js

@@ -1,13 +1,14 @@
-import { getDieGeometry, getRegisteredDieTypes } from '@dice-o-rolla/dice-geometry';
 import { AmbientLight, DirectionalLight, Mesh, PCFShadowMap, PlaneGeometry, Scene, ShadowMaterial, WebGLRenderer, } from 'three';
-import { DEFAULT_THREE_THEME, ThreeDiceMeshFactory } from './mesh-factory.js';
+import { DEFAULT_THREE_THEME, ThreeDiceMeshFactory, } from './mesh-factory.js';
+import { copyRenderState, createDiceMeshResource, haveEqualFaceLabels, } from './renderer-common.js';
 import { TopDownCamera } from './top-down-camera.js';
 import { applyInterpolatedTransform } from './transform.js';
 import { fitViewportToLimits, resolveViewportLimits, validateViewport, } from './viewport-limits.js';
 export class TopDownDiceRenderer {
     #container;
     #options;
-    #meshFactory = new ThreeDiceMeshFactory();
+    #meshFactory;
+    #materialProvider;
     #entries = new Map();
     #presets = new Map();
     #pendingPresetRemovals = new Set();
@@ -26,6 +27,9 @@ export class TopDownDiceRenderer {
     constructor(container, options = {}) {
         this.#container = container;
         this.#options = options;
+        this.#materialProvider =
+            typeof options.materialProvider === 'function' ? undefined : options.materialProvider;
+        this.#meshFactory = new ThreeDiceMeshFactory(this.#materialProvider);
         this.#viewportLimits = resolveViewportLimits(options);
         this.#trayWidth = options.trayWidth ?? 10;
         this.#trayDepth = options.trayDepth ?? 10;
@@ -65,6 +69,10 @@ export class TopDownDiceRenderer {
             alpha: true,
             powerPreference: 'high-performance',
         });
+        if (typeof this.#options.materialProvider === 'function') {
+            this.#materialProvider = this.#options.materialProvider(renderer);
+            this.#meshFactory = new ThreeDiceMeshFactory(this.#materialProvider);
+        }
         renderer.setClearColor(0x000000, 0);
         renderer.shadowMap.enabled = true;
         renderer.shadowMap.type = PCFShadowMap;
@@ -100,7 +108,7 @@ export class TopDownDiceRenderer {
             throw new Error(`A render die with id "${state.id}" already exists`);
         }
         const resource = this.#createResource(state);
-        const ownedState = copyState(state);
+        const ownedState = copyRenderState(state);
         applyInterpolatedTransform(resource.mesh, ownedState, 1);
         this.#scene?.add(resource.mesh);
         this.#entries.set(state.id, { resource, state: ownedState });
@@ -119,7 +127,7 @@ export class TopDownDiceRenderer {
         if (!haveEqualFaceLabels(entry.state.faceLabels, state.faceLabels)) {
             throw new Error('Die face labels cannot be changed after creation');
         }
-        entry.state = copyState(state);
+        entry.state = copyRenderState(state);
     }
     removeDie(id) {
         this.#assertAlive();
@@ -185,6 +193,8 @@ export class TopDownDiceRenderer {
         this.#resizeObserver = undefined;
         this.#presets.clear();
         this.#pendingPresetRemovals.clear();
+        this.#materialProvider?.dispose?.();
+        this.#materialProvider = undefined;
         this.#destroyed = true;
     }
     #resizeToContainer() {
@@ -198,16 +208,7 @@ export class TopDownDiceRenderer {
         }, this.#viewportLimits));
     }
     #createResource(state) {
-        const preset = this.#presets.get(state.presetId);
-        if (preset === undefined)
-            throw new Error(`Unknown visual preset: ${state.presetId}`);
-        if (preset.geometryId !== state.geometryId || (preset.scale ?? 1) !== state.scale) {
-            throw new Error(`Render state does not match visual preset "${state.presetId}"`);
-        }
-        const type = getRegisteredDieTypes().find((registered) => registered === state.geometryId);
-        if (type === undefined)
-            throw new Error(`Unsupported geometry: ${state.geometryId}`);
-        return this.#meshFactory.create(getDieGeometry(type), this.#theme, state.scale, state.faceLabels);
+        return createDiceMeshResource(state, this.#presets, this.#meshFactory, this.#theme);
     }
     #releasePendingPreset(presetId) {
         if (!this.#pendingPresetRemovals.has(presetId))
@@ -228,29 +229,3 @@ export class TopDownDiceRenderer {
         }
     }
 }
-function copyState(state) {
-    return {
-        id: state.id,
-        presetId: state.presetId,
-        geometryId: state.geometryId,
-        scale: state.scale,
-        ...(state.faceLabels === undefined ? {} : { faceLabels: { ...state.faceLabels } }),
-        previous: {
-            position: { ...state.previous.position },
-            quaternion: { ...state.previous.quaternion },
-        },
-        current: {
-            position: { ...state.current.position },
-            quaternion: { ...state.current.quaternion },
-        },
-    };
-}
-function haveEqualFaceLabels(left, right) {
-    if (left === right)
-        return true;
-    if (left === undefined || right === undefined)
-        return false;
-    const leftEntries = Object.entries(left);
-    return (leftEntries.length === Object.keys(right).length &&
-        leftEntries.every(([face, label]) => right[Number(face)] === label));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-renderer-three",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Three.js WebGL renderers for animated physical dice.",
   "keywords": [
     "dice",
@@ -40,8 +40,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@dice-o-rolla/dice-geometry": "0.3.0",
-    "@dice-o-rolla/dice-renderer": "0.3.0",
+    "@dice-o-rolla/dice-geometry": "0.4.0",
+    "@dice-o-rolla/dice-renderer": "0.4.0",
     "@types/three": "^0.185.0",
     "three": "^0.185.0"
   },