@dice-o-rolla/dice-renderer-three 0.3.1 → 0.5.0

package/README.md

@@ -7,6 +7,19 @@ 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.
+
+A material provider may implement `getSurfaceUvs(definition, preset)` to return a complete
+`SurfaceUvMap` keyed by physical face value. Coordinates follow each face's vertex order. The
+mesh factory validates them before allocation and writes them to `uv1`, preserving the original
+`uv` channel for labels. Assign `texture.channel = 1` for maps that use the surface unwrap.
+`createPolyhedronGeometry(definition, scale, surfaceUvs)` also accepts the map directly;
+`validateSurfaceUvs` is available for early validation. Omitting the map preserves existing UVs.
+
 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 { createPolyhedronGeometry, validateSurfaceUvs, type SurfaceUvMap, type Vector2Tuple, 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/index.js

@@ -1,5 +1,5 @@
 export { ThreeMaterialFactory, } from './material-factory.js';
-export { createPolyhedronGeometry, createFaceUvs, DEFAULT_THREE_THEME, getFaceLabel, ThreeDiceMeshFactory, } from './mesh-factory.js';
+export { createPolyhedronGeometry, validateSurfaceUvs, createFaceUvs, DEFAULT_THREE_THEME, getFaceLabel, ThreeDiceMeshFactory, } from './mesh-factory.js';
 export { ThreeCamera, ThreeLighting, ThreeScene } from './scene.js';
 export { TopDownCamera } from './top-down-camera.js';
 export { TopDownDiceRenderer } from './top-down-dice-renderer.js';

package/dist/mesh-factory.d.ts

@@ -1,7 +1,7 @@
 import type { PolygonDefinition, PolyhedronDefinition } from '@dice-o-rolla/dice-geometry';
 import type { RendererTheme, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
 import { BufferGeometry, Mesh, type MeshStandardMaterial } from 'three';
-type Vector2Tuple = readonly [u: number, v: number];
+export type Vector2Tuple = readonly [u: number, v: number];
 export declare const DEFAULT_THREE_THEME: RendererTheme;
 export interface ThreeDiceMesh {
     readonly mesh: Mesh<BufferGeometry, MeshStandardMaterial[]>;
@@ -18,11 +18,13 @@ export interface FaceMaterialResource {
     readonly material: MeshStandardMaterial;
     dispose(): void;
 }
+export type SurfaceUvMap = Readonly<Record<number, readonly Vector2Tuple[]>>;
 export interface ThreeFaceMaterialProvider {
+    getSurfaceUvs?(definition: PolyhedronDefinition, preset?: VisualPresetDescriptor): SurfaceUvMap | undefined;
     createFace(context: FaceMaterialContext): FaceMaterialResource;
     dispose?(): void;
 }
-export declare function createPolyhedronGeometry(definition: PolyhedronDefinition, scale?: number): BufferGeometry;
+export declare function createPolyhedronGeometry(definition: PolyhedronDefinition, scale?: number, surfaceUvs?: SurfaceUvMap): BufferGeometry;
 export declare class ThreeDiceMeshFactory {
     #private;
     constructor(materials?: ThreeFaceMaterialProvider);
@@ -31,4 +33,5 @@ export declare class ThreeDiceMeshFactory {
 }
 export declare function createFaceUvs(definition: PolyhedronDefinition, face: PolygonDefinition): readonly Vector2Tuple[];
 export declare function getFaceLabel(definition: PolyhedronDefinition, face: PolygonDefinition, faceLabels?: Readonly<Record<number, string | number>>): string | number | readonly number[];
-export {};
+/** Validate complete per-corner UVs before allocating geometry or materials. */
+export declare function validateSurfaceUvs(definition: PolyhedronDefinition, uvs: SurfaceUvMap): void;

package/dist/mesh-factory.js

@@ -10,10 +10,13 @@ export const DEFAULT_THREE_THEME = Object.freeze({
     roughness: 0.28,
     metalness: 0,
 });
-export function createPolyhedronGeometry(definition, scale = 1) {
+export function createPolyhedronGeometry(definition, scale = 1, surfaceUvs) {
     if (!Number.isFinite(scale) || scale <= 0) {
         throw new RangeError('scale must be a positive finite number');
     }
+    if (surfaceUvs !== undefined)
+        validateSurfaceUvs(definition, surfaceUvs);
+    const surface = [];
     const positions = [];
     const uvs = [];
     const geometry = new BufferGeometry();
@@ -30,12 +33,15 @@ export function createPolyhedronGeometry(definition, scale = 1) {
                 }
                 positions.push(vertex[0] * scale, vertex[1] * scale, vertex[2] * scale);
                 uvs.push(uv[0], uv[1]);
+                const mapped = surfaceUvs?.[face.value]?.[faceIndex] ?? uv;
+                surface.push(mapped[0], mapped[1]);
             }
         }
         geometry.addGroup(start, positions.length / 3 - start, materialIndex);
     });
     geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));
     geometry.setAttribute('uv', new Float32BufferAttribute(uvs, 2));
+    geometry.setAttribute('uv1', new Float32BufferAttribute(surface, 2));
     geometry.computeVertexNormals();
     geometry.computeBoundingSphere();
     return geometry;
@@ -46,14 +52,24 @@ export class ThreeDiceMeshFactory {
         this.#materials = materials;
     }
     create(definition, theme = DEFAULT_THREE_THEME, scale = 1, faceLabels, preset) {
-        const geometry = createPolyhedronGeometry(definition, scale);
-        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 geometry = createPolyhedronGeometry(definition, scale, this.#materials.getSurfaceUvs?.(definition, preset));
+        const resources = [];
+        try {
+            for (const face of definition.faces)
+                resources.push(this.#materials.createFace({
+                    label: getFaceLabel(definition, face, faceLabels),
+                    faceValue: face.value,
+                    theme,
+                    ...(preset === undefined ? {} : { preset }),
+                    ...(definition.id === 'd10' ? { labelScale: D10_LABEL_SCALE } : {}),
+                }));
+        }
+        catch (error) {
+            geometry.dispose();
+            for (const resource of resources)
+                resource.dispose();
+            throw error;
+        }
         const materials = resources.map(({ material }) => material);
         const mesh = new Mesh(geometry, materials);
         mesh.castShadow = true;
@@ -169,3 +185,24 @@ export function getFaceLabel(definition, face, faceLabels) {
         return 0;
     return face.value;
 }
+/** Validate complete per-corner UVs before allocating geometry or materials. */
+export function validateSurfaceUvs(definition, uvs) {
+    const fail = (face) => {
+        throw new RangeError(`Geometry "${definition.id}" face ${face}: invalid surface UVs`);
+    };
+    for (const key of Object.keys(uvs)) {
+        if (!definition.faces.some((face) => String(face.value) === key))
+            fail(Number(key));
+    }
+    for (const face of definition.faces) {
+        const coordinates = uvs[face.value];
+        if (!Array.isArray(coordinates) || coordinates.length !== face.indices.length)
+            fail(face.value);
+        for (const uv of coordinates) {
+            if (!Array.isArray(uv) ||
+                uv.length !== 2 ||
+                !uv.every((value) => Number.isFinite(value) && value >= 0 && value <= 1))
+                fail(face.value);
+        }
+    }
+}

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.1",
+  "version": "0.5.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.1",
-    "@dice-o-rolla/dice-renderer": "0.3.1",
+    "@dice-o-rolla/dice-geometry": "0.5.0",
+    "@dice-o-rolla/dice-renderer": "0.5.0",
     "@types/three": "^0.185.0",
     "three": "^0.185.0"
   },