@dice-o-rolla/dice-renderer-three 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ThreeMaterialFactory, type DiceMaterialStyle, type FaceLabel, type FaceMaterialOptions, } from './material-factory.js';
-export { createPolyhedronGeometry, createFaceUvs, DEFAULT_THREE_THEME, getFaceLabel, ThreeDiceMeshFactory, type ThreeDiceMesh, } from './mesh-factory.js';
+export { createPolyhedronGeometry, createFaceUvs, DEFAULT_THREE_THEME, getFaceLabel, ThreeDiceMeshFactory, type ThreeDiceMesh, type FaceMaterialContext, type FaceMaterialResource, type ThreeFaceMaterialProvider, } from './mesh-factory.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/mesh-factory.d.ts

@@ -1,18 +1,32 @@
 import type { PolygonDefinition, PolyhedronDefinition } from '@dice-o-rolla/dice-geometry';
-import type { RendererTheme } from '@dice-o-rolla/dice-renderer';
+import type { RendererTheme, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
 import { BufferGeometry, Mesh, type MeshStandardMaterial } from 'three';
-import { ThreeMaterialFactory } from './material-factory.js';
 type Vector2Tuple = readonly [u: number, v: number];
 export declare const DEFAULT_THREE_THEME: RendererTheme;
 export interface ThreeDiceMesh {
     readonly mesh: Mesh<BufferGeometry, MeshStandardMaterial[]>;
     dispose(): void;
 }
+export interface FaceMaterialContext {
+    readonly label: string | number | readonly number[];
+    readonly faceValue: number;
+    readonly theme: RendererTheme;
+    readonly preset?: VisualPresetDescriptor;
+    readonly labelScale?: number;
+}
+export interface FaceMaterialResource {
+    readonly material: MeshStandardMaterial;
+    dispose(): void;
+}
+export interface ThreeFaceMaterialProvider {
+    createFace(context: FaceMaterialContext): FaceMaterialResource;
+    dispose?(): void;
+}
 export declare function createPolyhedronGeometry(definition: PolyhedronDefinition, scale?: number): BufferGeometry;
 export declare class ThreeDiceMeshFactory {
     #private;
-    constructor(materials?: ThreeMaterialFactory);
-    create(definition: PolyhedronDefinition, theme?: RendererTheme, scale?: number, faceLabels?: Readonly<Record<number, string | number>>): ThreeDiceMesh;
+    constructor(materials?: ThreeFaceMaterialProvider);
+    create(definition: PolyhedronDefinition, theme?: RendererTheme, scale?: number, faceLabels?: Readonly<Record<number, string | number>>, preset?: VisualPresetDescriptor): ThreeDiceMesh;
     createD6(theme?: RendererTheme, scale?: number): ThreeDiceMesh;
 }
 export declare function createFaceUvs(definition: PolyhedronDefinition, face: PolygonDefinition): readonly Vector2Tuple[];

package/dist/mesh-factory.js

@@ -42,12 +42,19 @@ export function createPolyhedronGeometry(definition, scale = 1) {
 }
 export class ThreeDiceMeshFactory {
     #materials;
-    constructor(materials = new ThreeMaterialFactory()) {
+    constructor(materials = defaultMaterialProvider()) {
         this.#materials = materials;
     }
-    create(definition, theme = DEFAULT_THREE_THEME, scale = 1, faceLabels) {
+    create(definition, theme = DEFAULT_THREE_THEME, scale = 1, faceLabels, preset) {
         const geometry = createPolyhedronGeometry(definition, scale);
-        const materials = definition.faces.map((face) => this.#materials.createFace(getFaceLabel(definition, face, faceLabels), theme, definition.id === 'd10' ? { labelScale: D10_LABEL_SCALE } : undefined));
+        const resources = definition.faces.map((face) => this.#materials.createFace({
+            label: getFaceLabel(definition, face, faceLabels),
+            faceValue: face.value,
+            theme,
+            ...(preset === undefined ? {} : { preset }),
+            ...(definition.id === 'd10' ? { labelScale: D10_LABEL_SCALE } : {}),
+        }));
+        const materials = resources.map(({ material }) => material);
         const mesh = new Mesh(geometry, materials);
         mesh.castShadow = true;
         mesh.receiveShadow = true;
@@ -55,10 +62,8 @@ export class ThreeDiceMeshFactory {
             mesh,
             dispose() {
                 geometry.dispose();
-                for (const material of materials) {
-                    material.map?.dispose();
-                    material.dispose();
-                }
+                for (const resource of resources)
+                    resource.dispose();
             },
         };
     }
@@ -66,6 +71,21 @@ export class ThreeDiceMeshFactory {
         return this.create(D6_DEFINITION, theme, scale);
     }
 }
+function defaultMaterialProvider() {
+    const factory = new ThreeMaterialFactory();
+    return {
+        createFace(context) {
+            const material = factory.createFace(context.label, context.theme, context.labelScale === undefined ? {} : { labelScale: context.labelScale });
+            return {
+                material,
+                dispose() {
+                    material.map?.dispose();
+                    material.dispose();
+                },
+            };
+        },
+    };
+}
 export function createFaceUvs(definition, face) {
     if (definition.id !== 'd10') {
         return face.indices.map((_, index) => {

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

@@ -1,15 +1,20 @@
-import type { DiceRenderer, RenderDieState, RendererTheme, RendererViewport } from '@dice-o-rolla/dice-renderer';
+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);
 }
 export declare class ThreeDiceRenderer implements DiceRenderer {
     #private;
     constructor(container: HTMLElement, options?: ThreeDiceRendererOptions);
     initialize(): void;
+    registerPreset(preset: VisualPresetDescriptor): void;
+    unregisterPreset(id: string): void;
     createDie(state: RenderDieState): void;
     updateDie(state: RenderDieState): void;
     removeDie(id: string): void;

package/dist/three-dice-renderer.js

@@ -1,13 +1,15 @@
 import { getDieGeometry, getRegisteredDieTypes } from '@dice-o-rolla/dice-geometry';
 import { PCFShadowMap, WebGLRenderer } from 'three';
-import { DEFAULT_THREE_THEME, ThreeDiceMeshFactory } from './mesh-factory.js';
+import { DEFAULT_THREE_THEME, ThreeDiceMeshFactory, } from './mesh-factory.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 },
@@ -22,8 +24,11 @@ function copyState(state) {
 export class ThreeDiceRenderer {
     #container;
     #options;
-    #meshFactory = new ThreeDiceMeshFactory();
+    #meshFactory;
+    #materialProvider;
     #entries = new Map();
+    #presets = new Map();
+    #pendingPresetRemovals = new Set();
     #viewportLimits;
     #theme;
     #scene;
@@ -34,6 +39,9 @@ export class ThreeDiceRenderer {
     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.#theme = {
             material: options.material ?? DEFAULT_THREE_THEME.material,
@@ -54,6 +62,10 @@ export class ThreeDiceRenderer {
             alpha: true,
             powerPreference: 'high-performance',
         });
+        if (typeof this.#options.materialProvider === 'function') {
+            this.#materialProvider = this.#options.materialProvider(renderer);
+            this.#meshFactory = new ThreeDiceMeshFactory(this.#materialProvider);
+        }
         renderer.shadowMap.enabled = true;
         renderer.shadowMap.type = PCFShadowMap;
         this.#container.append(renderer.domElement);
@@ -66,11 +78,24 @@ export class ThreeDiceRenderer {
             this.#resizeObserver.observe(this.#container);
         }
     }
+    registerPreset(preset) {
+        this.#assertAlive();
+        this.#pendingPresetRemovals.delete(preset.id);
+        this.#presets.set(preset.id, preset);
+    }
+    unregisterPreset(id) {
+        this.#assertAlive();
+        if ([...this.#entries.values()].some((entry) => entry.state.presetId === id)) {
+            this.#pendingPresetRemovals.add(id);
+            return;
+        }
+        this.#presets.delete(id);
+    }
     createDie(state) {
         this.#assertInitialized();
         if (this.#entries.has(state.id))
             throw new Error(`A render die with id "${state.id}" already exists`);
-        const resource = this.#createResource(state.geometryId, state.faceLabels);
+        const resource = this.#createResource(state);
         const ownedState = copyState(state);
         applyInterpolatedTransform(resource.mesh, ownedState, 1);
         this.#scene?.value.add(resource.mesh);
@@ -84,6 +109,9 @@ export class ThreeDiceRenderer {
         if (state.geometryId !== entry.state.geometryId) {
             throw new Error('A die geometry cannot be changed after creation');
         }
+        if (state.presetId !== entry.state.presetId || state.scale !== entry.state.scale) {
+            throw new Error('A die visual preset cannot be changed after creation');
+        }
         if (!haveEqualFaceLabels(state.faceLabels, entry.state.faceLabels)) {
             throw new Error('Die face labels cannot be changed after creation');
         }
@@ -97,6 +125,7 @@ export class ThreeDiceRenderer {
         this.#scene?.value.remove(entry.resource.mesh);
         entry.resource.dispose();
         this.#entries.delete(id);
+        this.#releasePendingPreset(entry.state.presetId);
     }
     render(alpha) {
         this.#assertInitialized();
@@ -116,7 +145,7 @@ export class ThreeDiceRenderer {
         this.#assertAlive();
         this.#theme = { ...theme };
         for (const entry of this.#entries.values()) {
-            const replacement = this.#createResource(entry.state.geometryId, entry.state.faceLabels);
+            const replacement = this.#createResource(entry.state);
             applyInterpolatedTransform(replacement.mesh, entry.state, 1);
             this.#scene?.value.remove(entry.resource.mesh);
             entry.resource.dispose();
@@ -144,6 +173,10 @@ export class ThreeDiceRenderer {
         this.#scene = undefined;
         this.#camera = undefined;
         this.#renderer = undefined;
+        this.#presets.clear();
+        this.#pendingPresetRemovals.clear();
+        this.#materialProvider?.dispose?.();
+        this.#materialProvider = undefined;
         this.#destroyed = true;
     }
     #resizeToContainer() {
@@ -156,11 +189,25 @@ export class ThreeDiceRenderer {
             pixelRatio: globalThis.devicePixelRatio || 1,
         }, this.#viewportLimits));
     }
-    #createResource(geometryId, faceLabels) {
-        const type = getRegisteredDieTypes().find((registered) => registered === geometryId);
+    #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: ${geometryId}`);
-        return this.#meshFactory.create(getDieGeometry(type), this.#theme, 1, faceLabels);
+            throw new Error(`Unsupported geometry: ${state.geometryId}`);
+        return this.#meshFactory.create(getDieGeometry(type), this.#theme, state.scale, state.faceLabels, preset);
+    }
+    #releasePendingPreset(presetId) {
+        if (!this.#pendingPresetRemovals.has(presetId))
+            return;
+        if ([...this.#entries.values()].some((entry) => entry.state.presetId === presetId))
+            return;
+        this.#pendingPresetRemovals.delete(presetId);
+        this.#presets.delete(presetId);
     }
     #assertAlive() {
         if (this.#destroyed)

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

@@ -1,4 +1,4 @@
-import type { DiceRenderer, RenderDieState, RendererTheme, RendererViewport } from '@dice-o-rolla/dice-renderer';
+import type { DiceRenderer, RenderDieState, RendererTheme, RendererViewport, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
 import { type TopDownCameraOptions } from './top-down-camera.js';
 import { type ViewportLimitOptions } from './viewport-limits.js';
 export interface TopDownDiceRendererOptions extends Partial<RendererTheme>, ViewportLimitOptions, TopDownCameraOptions {
@@ -9,6 +9,8 @@ export declare class TopDownDiceRenderer implements DiceRenderer {
     #private;
     constructor(container: HTMLElement, options?: TopDownDiceRendererOptions);
     initialize(): void;
+    registerPreset(preset: VisualPresetDescriptor): void;
+    unregisterPreset(id: string): void;
     createDie(state: RenderDieState): void;
     updateDie(state: RenderDieState): void;
     removeDie(id: string): void;

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

@@ -9,6 +9,8 @@ export class TopDownDiceRenderer {
     #options;
     #meshFactory = new ThreeDiceMeshFactory();
     #entries = new Map();
+    #presets = new Map();
+    #pendingPresetRemovals = new Set();
     #viewportLimits;
     #trayWidth;
     #trayDepth;
@@ -79,12 +81,25 @@ export class TopDownDiceRenderer {
             this.#resizeObserver.observe(this.#container);
         }
     }
+    registerPreset(preset) {
+        this.#assertAlive();
+        this.#pendingPresetRemovals.delete(preset.id);
+        this.#presets.set(preset.id, preset);
+    }
+    unregisterPreset(id) {
+        this.#assertAlive();
+        if ([...this.#entries.values()].some((entry) => entry.state.presetId === id)) {
+            this.#pendingPresetRemovals.add(id);
+            return;
+        }
+        this.#presets.delete(id);
+    }
     createDie(state) {
         this.#assertInitialized();
         if (this.#entries.has(state.id)) {
             throw new Error(`A render die with id "${state.id}" already exists`);
         }
-        const resource = this.#createResource(state.geometryId, state.faceLabels);
+        const resource = this.#createResource(state);
         const ownedState = copyState(state);
         applyInterpolatedTransform(resource.mesh, ownedState, 1);
         this.#scene?.add(resource.mesh);
@@ -98,6 +113,9 @@ export class TopDownDiceRenderer {
         if (entry.state.geometryId !== state.geometryId) {
             throw new Error('A die geometry cannot be changed after creation');
         }
+        if (state.presetId !== entry.state.presetId || state.scale !== entry.state.scale) {
+            throw new Error('A die visual preset cannot be changed after creation');
+        }
         if (!haveEqualFaceLabels(entry.state.faceLabels, state.faceLabels)) {
             throw new Error('Die face labels cannot be changed after creation');
         }
@@ -111,6 +129,7 @@ export class TopDownDiceRenderer {
         this.#scene?.remove(entry.resource.mesh);
         entry.resource.dispose();
         this.#entries.delete(id);
+        this.#releasePendingPreset(entry.state.presetId);
     }
     render(alpha) {
         this.#assertInitialized();
@@ -130,7 +149,7 @@ export class TopDownDiceRenderer {
         this.#assertAlive();
         this.#theme = { ...theme };
         for (const entry of this.#entries.values()) {
-            const replacement = this.#createResource(entry.state.geometryId, entry.state.faceLabels);
+            const replacement = this.#createResource(entry.state);
             applyInterpolatedTransform(replacement.mesh, entry.state, 1);
             this.#scene?.remove(entry.resource.mesh);
             entry.resource.dispose();
@@ -164,6 +183,8 @@ export class TopDownDiceRenderer {
         this.#floorMaterial = undefined;
         this.#keyLight = undefined;
         this.#resizeObserver = undefined;
+        this.#presets.clear();
+        this.#pendingPresetRemovals.clear();
         this.#destroyed = true;
     }
     #resizeToContainer() {
@@ -176,11 +197,25 @@ export class TopDownDiceRenderer {
             pixelRatio: globalThis.devicePixelRatio || 1,
         }, this.#viewportLimits));
     }
-    #createResource(geometryId, faceLabels) {
-        const type = getRegisteredDieTypes().find((registered) => registered === geometryId);
+    #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: ${geometryId}`);
-        return this.#meshFactory.create(getDieGeometry(type), this.#theme, 1, faceLabels);
+            throw new Error(`Unsupported geometry: ${state.geometryId}`);
+        return this.#meshFactory.create(getDieGeometry(type), this.#theme, state.scale, state.faceLabels);
+    }
+    #releasePendingPreset(presetId) {
+        if (!this.#pendingPresetRemovals.has(presetId))
+            return;
+        if ([...this.#entries.values()].some((entry) => entry.state.presetId === presetId))
+            return;
+        this.#pendingPresetRemovals.delete(presetId);
+        this.#presets.delete(presetId);
     }
     #assertAlive() {
         if (this.#destroyed)
@@ -196,7 +231,9 @@ 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 },

package/package.json

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