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

package/README.md

@@ -13,6 +13,13 @@ KTX2 capability detection and GPU-backed asset setup available in perspective an
 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,5 @@
 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';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-renderer-three",
-  "version": "0.4.0",
+  "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.4.0",
-    "@dice-o-rolla/dice-renderer": "0.4.0",
+    "@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"
   },