feat(voxel-renderer): allow to customize the material properties (#204)

Author: fraxken

.changeset/old-cloths-visit.md

@@ -0,0 +1,5 @@
+---
+"@jolly-pixel/voxel.renderer": minor
+---
+
+Allow to customize the material in VoxelRenderer options

packages/voxel-renderer/docs/Tileset.md

@@ -81,10 +81,6 @@ Throws if no tileset is loaded or the referenced ID is unknown.
 
 Returns the shared texture for a tileset. Defaults to `defaultTilesetId`.
 
-#### `createMaterial(tilesetId?: string): THREE.MeshLambertMaterial`
-
-Lazily creates and caches a `MeshLambertMaterial` backed by the tileset texture.
-
 #### `getDefinitions(): Array<TilesetDefinition & { cols: number; rows: number }>`
 
 Returns all registered tileset definitions with `cols` and `rows` resolved from the image.

packages/voxel-renderer/docs/VoxelRenderer.md

@@ -8,11 +8,24 @@ Each chunk is rebuilt only when its content changes, keeping GPU work proportion
 ## VoxelRendererOptions
 
 ```ts
+type MaterialCustomizerFn = (
+  material: THREE.MeshLambertMaterial | THREE.MeshStandardMaterial,
+  tilesetId: string
+) => void;
+
 interface VoxelRendererOptions {
   /** Side length of each chunk in voxels. Default: `16`. */
   chunkSize?: number;
+  
   /** Chunk material preset. `"standard"` enables PBR at higher GPU cost. Default: `"lambert"`. */
   material?: "lambert" | "standard";
+
+  /**
+   * Optional callback to customize each material after it is created.
+   * Called with the material instance and the tileset ID it corresponds to
+   */
+  materialCustomizer?: MaterialCustomizerFn;
+  
   /**
    * Fragments with alpha below this value are discarded.
    * Set `0` to disable cutout transparency. Default: `0.1`.

packages/voxel-renderer/examples/scripts/demo-tiled.ts

@@ -26,12 +26,12 @@ const { world } = runtime;
 
 // ── Scene ─────────────────────────────────────────────────────────────────────
 const scene = world.sceneManager.getSource();
-scene.background = new THREE.Color("#87ceeb");
+scene.background = new THREE.Color("#211331");
 
-const dirLight = new THREE.DirectionalLight(new THREE.Color("#ffffff"), 1.5);
+const dirLight = new THREE.DirectionalLight(new THREE.Color("#f6faff"), 2);
 dirLight.position.set(20, 40, 30);
 scene.add(
-  new THREE.AmbientLight(new THREE.Color("#ffffff"), 1.5),
+  new THREE.AmbientLight(new THREE.Color("#ffffff"), 2.5),
   dirLight
 );
 
@@ -48,7 +48,13 @@ world.createActor("camera")
 // No blocks or layers supplied here — load() will register them from the JSON.
 world.createActor("map")
   .addComponent(VoxelRenderer, {
-    material: "lambert"
+    material: "lambert",
+    materialCustomizer: (material) => {
+      if (material instanceof THREE.MeshStandardMaterial) {
+        material.metalness = 0;
+        material.roughness = 0.85;
+      }
+    }
   })
   .addComponent(VoxelBehavior);
 

packages/voxel-renderer/src/VoxelRenderer.ts

@@ -43,6 +43,11 @@ import type { VoxelEntry, VoxelCoord } from "./world/types.ts";
 import { packTransform, type FACE } from "./utils/math.ts";
 import { FACE_OFFSETS } from "./mesh/math.ts";
 
+type MaterialCustomizerFn = (
+  material: THREE.MeshLambertMaterial | THREE.MeshStandardMaterial,
+  tilesetId: string
+) => void;
+
 export const VoxelRotation = {
   /** No rotation (default). */
   None: 0,
@@ -91,6 +96,13 @@ export interface VoxelRendererOptions {
    * is faster but only supports a simple diffuse map.
    */
   material?: "lambert" | "standard";
+
+  /**
+   * Optional callback to customize each material after it is created.
+   * Called with the material instance and the tileset ID it corresponds to
+   */
+  materialCustomizer?: MaterialCustomizerFn;
+
   /**
    * Optional list of layer names to create on initialization.
    */
@@ -145,6 +157,7 @@ export class VoxelRenderer extends ActorComponent {
    * One material per tileset ID. Created lazily; disposed on tileset reload or destroy.
    */
   #materials = new Map<string, THREE.MeshLambertMaterial | THREE.MeshStandardMaterial>();
+  #materialCustomizer?: MaterialCustomizerFn;
   #materialType: "lambert" | "standard";
   #alphaTest: number;
 
@@ -160,6 +173,7 @@ export class VoxelRenderer extends ActorComponent {
     const {
       chunkSize = 16,
       material = "lambert",
+      materialCustomizer,
       layers = [],
       rapier,
       blocks = [],
@@ -168,6 +182,7 @@ export class VoxelRenderer extends ActorComponent {
     } = options;
 
     this.#materialType = material;
+    this.#materialCustomizer = materialCustomizer;
     this.#alphaTest = alphaTest;
 
     this.world = new VoxelWorld(chunkSize);
@@ -422,7 +437,9 @@ export class VoxelRenderer extends ActorComponent {
       return material;
     }
 
-    const texture = this.tilesetManager.getTexture(tilesetId) ?? null;
+    const texture = this.tilesetManager.getTexture(
+      tilesetId
+    ) ?? null;
 
     if (this.#materialType === "standard") {
       material = new THREE.MeshStandardMaterial({
@@ -438,6 +455,7 @@ export class VoxelRenderer extends ActorComponent {
         alphaTest: this.#alphaTest
       });
     }
+    this.#materialCustomizer?.(material, tilesetId);
 
     this.#materials.set(tilesetId, material);
 

packages/voxel-renderer/src/tileset/TilesetManager.ts

@@ -35,11 +35,11 @@ export interface TilesetEntry {
 /**
  * Manages tileset textures and computes UV regions for each tile.
  *
- * UV formula (Y-flipped for WebGL origin):
- *   offsetU = col * tileW / imgW
- *   offsetV = 1 - (row + 1) * tileH / imgH
- *   scaleU  = tileW / imgW
- *   scaleV  = tileH / imgH
+ * UV formula (Y-flipped for WebGL origin, half-texel inset to prevent bleeding):
+ *   offsetU = col * tileW / imgW + 0.5 / imgW
+ *   offsetV = 1 - (row + 1) * tileH / imgH + 0.5 / imgH
+ *   scaleU  = (tileW - 1) / imgW
+ *   scaleV  = (tileH - 1) / imgH
  *
  * A single shared THREE.Texture is kept per tileset — no per-tile cloning.
  * NearestFilter is used to preserve pixel-art crispness.
@@ -112,11 +112,18 @@ export class TilesetManager {
     const imgW = cols * tileSize;
     const imgH = rows * tileSize;
 
+    // Inset by half a texel on each side so UV edge vertices sample the
+    // centre of the first/last texel rather than the boundary between tiles.
+    // This prevents floating-point interpolation from bleeding into adjacent
+    // tiles in the atlas (the "white line between blocks" artifact).
+    const halfTexelU = 0.5 / imgW;
+    const halfTexelV = 0.5 / imgH;
+
     return {
-      offsetU: ref.col * tileSize / imgW,
-      offsetV: 1 - ((ref.row + 1) * tileSize / imgH),
-      scaleU: tileSize / imgW,
-      scaleV: tileSize / imgH
+      offsetU: ref.col * tileSize / imgW + halfTexelU,
+      offsetV: 1 - ((ref.row + 1) * tileSize / imgH) + halfTexelV,
+      scaleU: (tileSize - 1) / imgW,
+      scaleV: (tileSize - 1) / imgH
     };
   }
 
@@ -133,34 +140,6 @@ export class TilesetManager {
       undefined;
   }
 
-  /**
-   * Returns (or lazily creates) a MeshLambertMaterial using the tileset texture.
-   * The material is cached per-tileset to avoid redundant GPU uploads.
-   */
-  createMaterial(
-    tilesetId?: string
-  ): THREE.MeshLambertMaterial {
-    const id = tilesetId ?? this.#defaultTilesetId;
-    if (id === null) {
-      throw new Error("TilesetManager: no tilesets have been loaded.");
-    }
-
-    const entry = this.#tilesets.get(id);
-    if (!entry) {
-      throw new Error(`TilesetManager: tileset "${id}" is not loaded.`);
-    }
-
-    if (!entry.material) {
-      entry.material = new THREE.MeshLambertMaterial({
-        map: entry.texture,
-        side: THREE.FrontSide,
-        alphaTest: 0.1
-      });
-    }
-
-    return entry.material;
-  }
-
   getDefinitions(): ResolvedTilesetDefinition[] {
     return [
       ...this.#tilesets.values()

packages/voxel-renderer/test/tileset/TilesetManager.spec.ts

@@ -104,48 +104,59 @@ describe("TilesetManager.getTileUV", () => {
     const manager = new TilesetManager();
     manager.registerTexture(makeDef("terrain", 16, 4, 4), mockTexture(64, 64));
 
-    it("tile (col=0, row=0): offsetU=0, offsetV=0.75, scaleU=0.25, scaleV=0.25", () => {
-      // offsetV = 1 - (0+1)/4 = 0.75
+    it("tile (col=0, row=0): offsetU/offsetV/scale (inset by half-texel)", () => {
+      // halfTexel = 0.5 / (cols*tileSize) = 0.5 / 64 = 0.0078125
+      // offsetU = 0 + halfTexel = 0.0078125
+      // offsetV = 1 - (0+1)/4 + halfTexel = 0.7578125
+      // scaleU = scaleV = (tileSize - 1) / imgW = 15/64 = 0.234375
       const uv = manager.getTileUV({ col: 0, row: 0 });
-      assert.ok(approxEqual(uv.offsetU, 0));
-      assert.ok(approxEqual(uv.offsetV, 0.75));
-      assert.ok(approxEqual(uv.scaleU, 0.25));
-      assert.ok(approxEqual(uv.scaleV, 0.25));
+      assert.ok(approxEqual(uv.offsetU, 0.0078125));
+      assert.ok(approxEqual(uv.offsetV, 0.7578125));
+      assert.ok(approxEqual(uv.scaleU, 15 / 64));
+      assert.ok(approxEqual(uv.scaleV, 15 / 64));
     });
 
-    it("tile (col=1, row=0): offsetU=0.25", () => {
+    it("tile (col=1, row=0): offsetU/offsetV (inset by half-texel)", () => {
+      // offsetU = 1*16/64 + halfTexel = 0.2578125
+      // offsetV = 0.7578125
       const uv = manager.getTileUV({ col: 1, row: 0 });
-      assert.ok(approxEqual(uv.offsetU, 0.25));
-      assert.ok(approxEqual(uv.offsetV, 0.75));
+      assert.ok(approxEqual(uv.offsetU, 0.2578125));
+      assert.ok(approxEqual(uv.offsetV, 0.7578125));
     });
 
-    it("tile (col=0, row=3) is the bottom row: offsetV=0", () => {
-      // offsetV = 1 - (3+1)/4 = 0
+    it("tile (col=0, row=3) is the bottom row: offsetV (inset by half-texel)", () => {
+      // offsetV = 1 - (3+1)/4 + halfTexel = 0.0078125
       const uv = manager.getTileUV({ col: 0, row: 3 });
-      assert.ok(approxEqual(uv.offsetV, 0));
+      assert.ok(approxEqual(uv.offsetV, 0.0078125));
     });
 
-    it("tile (col=3, row=3): offsetU=0.75, offsetV=0", () => {
+    it("tile (col=3, row=3): offsetU/offsetV (inset by half-texel)", () => {
+      // offsetU = 3*16/64 + halfTexel = 0.7578125
+      // offsetV = halfTexel = 0.0078125
       const uv = manager.getTileUV({ col: 3, row: 3 });
-      assert.ok(approxEqual(uv.offsetU, 0.75));
-      assert.ok(approxEqual(uv.offsetV, 0));
+      assert.ok(approxEqual(uv.offsetU, 0.7578125));
+      assert.ok(approxEqual(uv.offsetV, 0.0078125));
     });
   });
 
   describe("UV computation — 2-col 2-row atlas (tileSize=16, image=32×32)", () => {
     const manager = new TilesetManager();
     manager.registerTexture(makeDef("small", 16, 2, 2), mockTexture(32, 32));
 
-    it("scaleU = scaleV = 0.5", () => {
+    it("scaleU = scaleV (inset by half-texel)", () => {
+      // cols=2, tileSize=16 => imgW=32, halfTexel=0.5/32=0.015625
+      // scale = (16 - 1) / 32 = 15/32 = 0.46875
       const uv = manager.getTileUV({ col: 0, row: 0 });
-      assert.ok(approxEqual(uv.scaleU, 0.5));
-      assert.ok(approxEqual(uv.scaleV, 0.5));
+      assert.ok(approxEqual(uv.scaleU, 15 / 32));
+      assert.ok(approxEqual(uv.scaleV, 15 / 32));
     });
 
-    it("tile (col=1, row=1): offsetU=0.5, offsetV=0", () => {
+    it("tile (col=1, row=1): offsetU/offsetV (inset by half-texel)", () => {
+      // offsetU = 1*16/32 + halfTexel = 0.515625
+      // offsetV = 1 - ((1+1)*16/32) + halfTexel = 0.015625
       const uv = manager.getTileUV({ col: 1, row: 1 });
-      assert.ok(approxEqual(uv.offsetU, 0.5));
-      assert.ok(approxEqual(uv.offsetV, 0));
+      assert.ok(approxEqual(uv.offsetU, 0.515625));
+      assert.ok(approxEqual(uv.offsetV, 0.015625));
     });
   });
 
@@ -155,8 +166,8 @@ describe("TilesetManager.getTileUV", () => {
     manager.registerTexture(makeDef("walls", 16, 2, 2), mockTexture(32, 32));
 
     const uv = manager.getTileUV({ col: 0, row: 0, tilesetId: "walls" });
-    // walls is 2-col, 2-row → scaleU=0.5
-    assert.ok(approxEqual(uv.scaleU, 0.5));
+    // walls is 2-col, 2-row → scaleU=(tileSize-1)/(cols*tileSize)=15/32
+    assert.ok(approxEqual(uv.scaleU, 15 / 32));
   });
 });