minecraft-renderer 0.1.47 → 0.1.49

package/src/three/shaders/cubeBlockShader.ts

@@ -0,0 +1,354 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+// Face order: UP=0, DOWN=1, EAST=2, WEST=3, SOUTH=4, NORTH=5
+// matches WASM mesher face order (mesher.rs FACE_NAMES)
+
+const vertexShader = /* glsl */ `
+precision highp float;
+precision highp int;
+
+layout(location = 0) in uint a_w0;
+layout(location = 1) in uint a_w1;
+layout(location = 2) in uint a_w2;
+layout(location = 3) in uint a_w3;
+
+// World camera position split for stable float32 subtraction (see relativePos below).
+uniform vec3 u_cameraOrigin;
+uniform vec3 u_cameraOriginFrac;
+
+out float v_light;
+out float v_ao;
+out vec2 v_uv;
+flat out int v_texIndex;
+flat out int v_tintIndex;
+flat out int v_faceId;
+
+// Logarithmic depth buffer support: Three.js injects USE_LOGDEPTHBUF when the
+// renderer has logarithmicDepthBuffer: true. Standard Three.js shader chunks
+// rewrite gl_FragDepth via these varyings — if we don't, our linear gl_FragCoord.z
+// fails depth test vs sibling meshes that DO write log depth (we'd be invisible).
+// The renderer always uses a perspective camera, so we skip the vIsPerspective
+// varying and always emit log depth — avoids the smooth-interpolation precision
+// issue where vIsPerspective lands on 0.9999… on some pixels and silently falls
+// back to linear gl_FragCoord.z, producing a white-noise z-fight pattern against
+// neighbouring meshes.
+#ifdef USE_LOGDEPTHBUF
+out float vFragDepth;
+#endif
+
+// Fog support: Three.js injects USE_FOG when scene.fog is set AND material.fog === true.
+// Standard MeshBasicMaterial enables this by default; ShaderMaterial does NOT, which is
+// why our blocks looked unaffected by distance haze while neighbouring legacy meshes
+// faded into the fog. createCubeBlockMaterial sets fog: true and merges
+// UniformsLib.fog so Three.js can auto-refresh the fog uniforms each frame.
+#ifdef USE_FOG
+out float vFogDepth;
+#endif
+
+// projectionMatrix / modelViewMatrix: injected by Three.js ShaderMaterial (do not redeclare)
+
+// BASE, DU, DV per face (UP=0, DOWN=1, EAST=2, WEST=3, SOUTH=4, NORTH=5)
+// position = BASE[faceId] + u * DU[faceId] + v * DV[faceId]
+const vec3 BASE[6] = vec3[6](
+    vec3(0.0, 1.0, 1.0),  // UP    (+Y)
+    vec3(1.0, 0.0, 1.0),  // DOWN  (-Y)
+    vec3(1.0, 1.0, 1.0),  // EAST  (+X)
+    vec3(0.0, 1.0, 0.0),  // WEST  (-X)
+    vec3(0.0, 1.0, 1.0),  // SOUTH (+Z)
+    vec3(1.0, 1.0, 0.0)   // NORTH (-Z)
+);
+
+const vec3 DU[6] = vec3[6](
+    vec3( 1.0, 0.0,  0.0),  // UP
+    vec3(-1.0, 0.0,  0.0),  // DOWN
+    vec3( 0.0,-1.0,  0.0),  // EAST
+    vec3( 0.0,-1.0,  0.0),  // WEST
+    vec3( 1.0, 0.0,  0.0),  // SOUTH
+    vec3(-1.0, 0.0,  0.0)   // NORTH
+);
+
+const vec3 DV[6] = vec3[6](
+    vec3(0.0, 0.0, -1.0),  // UP
+    vec3(0.0, 0.0, -1.0),  // DOWN
+    vec3(0.0, 0.0, -1.0),  // EAST
+    vec3(0.0, 0.0,  1.0),  // WEST
+    vec3(0.0,-1.0,  0.0),  // SOUTH
+    vec3(0.0,-1.0,  0.0)   // NORTH
+);
+
+// Per-(triangle, corner) -> quad corner index (vi), one table per diagonal mode.
+// Normal: T0=[0,1,2], T1=[2,1,3]. Flipped: T0=[0,3,2], T1=[0,1,3].
+const int VI_NORMAL[6]  = int[6](0, 1, 2, 2, 1, 3);
+const int VI_FLIPPED[6] = int[6](0, 3, 2, 0, 1, 3);
+
+void main() {
+    // Empty slot sentinel (freed section range in global buffer)
+    if (((a_w2 >> 18u) & 0x1u) != 0u) {
+        gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
+        return;
+    }
+
+    // Non-indexed geometry: 6 vertices per face instance (2 triangles)
+    int vi_total = gl_VertexID % 6;
+    int triangle = vi_total / 3;      // 0 or 1
+    int corner = vi_total - triangle * 3; // 0,1,2
+
+    uint faceId = (a_w0 >> 12u) & 0x7u;
+
+    // Diagonal flip flag from word2 bit 12
+    uint diagonalFlag = (a_w2 >> 12u) & 0x1u;
+
+    // SOUTH/NORTH (faceId 4/5) need reversed triangle winding so FrontSide culling
+    // shows them. Swap corner 1 <-> 2 within each triangle BEFORE the quad-corner
+    // lookup; this reverses winding while keeping all 4 quad corners covered.
+    // (The previous override of viPos only collapsed both triangles to the same
+    // 3 corners, dropping quad corner vi=3 entirely.)
+    int effCorner = corner;
+    if (faceId == 4u || faceId == 5u) {
+        if (corner == 1) effCorner = 2;
+        else if (corner == 2) effCorner = 1;
+    }
+    int effViTotal = triangle * 3 + effCorner;
+    int vi = (diagonalFlag == 0u) ? VI_NORMAL[effViTotal] : VI_FLIPPED[effViTotal];
+
+    float u = float(vi & 1);
+    float v = float((vi >> 1) & 1);
+
+    // --- word0: position + face + tint + AO ---
+    uint lx     = (a_w0)        & 0xFu;
+    uint ly     = (a_w0 >>  4u) & 0xFu;
+    uint lz     = (a_w0 >>  8u) & 0xFu;
+    uint tint   = (a_w0 >> 15u) & 0xFFu;
+
+    // AO: 2 bits per corner starting at bit 23
+    uint aoLevel = (a_w0 >> uint(23 + vi * 2)) & 0x3u;
+    v_ao = (float(aoLevel) + 1.0) / 4.0;
+
+    // --- word1: combined smooth light (8 bits per corner) ---
+    uint lightRaw = (a_w1 >> uint(vi * 8)) & 0xFFu;
+    v_light = float(lightRaw) / 255.0;
+
+    // --- word2: texture index ---
+    v_texIndex = int(a_w2 & 0xFFFu);
+    v_tintIndex = int(tint);
+    v_faceId = int(faceId);
+
+    // --- Per-face UV transform (legacy elemFaces + down +180°) ---
+    if (faceId == 0u) {
+        v_uv = vec2(u, 1.0 - v);
+    } else if (faceId == 1u) {
+        v_uv = vec2(1.0 - u, 1.0 - v);
+    } else if (faceId == 2u || faceId == 3u) {
+        v_uv = vec2(v, u);
+    } else if (faceId == 4u) {
+        v_uv = vec2(u, 1.0 - v);
+    } else { // faceId == 5u
+        v_uv = vec2(1.0 - u, 1.0 - v);
+    }
+
+    // --- Position: section base (multiples of 16) + face quad + block-local 0..15 ---
+    int sX = int(a_w3 & 0xFFFFu) - 32768;
+    int sZ = int((a_w3 >> 16u) & 0xFFFFu) - 32768;
+    int sY = int((a_w2 >> 13u) & 0x1Fu) - 4;
+    vec3 sectionBase = vec3(float(sX * 16), float(sY * 16), float(sZ * 16));
+    vec3 facePos = BASE[faceId] + u * DU[faceId] + v * DV[faceId];
+    vec3 blockLocal = vec3(float(lx), float(ly), float(lz));
+    // (sectionBase - u_cameraOrigin) is exact in float32; add small terms after.
+    vec3 relativePos = (sectionBase - u_cameraOrigin) + facePos + blockLocal - u_cameraOriginFrac;
+    vec4 mvPosition = modelViewMatrix * vec4(relativePos, 1.0);
+    gl_Position = projectionMatrix * mvPosition;
+
+#ifdef USE_LOGDEPTHBUF
+    // Mirrors three.js logdepthbuf_vertex chunk (EXT path: fragment writes gl_FragDepth).
+    vFragDepth = 1.0 + gl_Position.w;
+#endif
+
+#ifdef USE_FOG
+    // Mirrors three.js fog_vertex chunk: view-space depth (positive in front of camera).
+    vFogDepth = -mvPosition.z;
+#endif
+}
+`
+
+const fragmentShader = /* glsl */ `
+precision highp float;
+precision highp int;
+
+uniform sampler2D u_atlas;
+uniform sampler2D u_tintPalette;
+/** 0=normal 1=holes 2=tileIndex 3=faceId 4=atlasAlpha */
+uniform float u_debugMode;
+
+in float v_light;
+in float v_ao;
+in vec2 v_uv;
+flat in int v_texIndex;
+flat in int v_tintIndex;
+flat in int v_faceId;
+
+#ifdef USE_LOGDEPTHBUF
+uniform float logDepthBufFC;
+in float vFragDepth;
+#endif
+
+#ifdef USE_FOG
+uniform vec3 fogColor;
+in float vFogDepth;
+#ifdef FOG_EXP2
+uniform float fogDensity;
+#else
+uniform float fogNear;
+uniform float fogFar;
+#endif
+#endif
+
+out vec4 FragColor;
+
+void writeLogDepth() {
+#ifdef USE_LOGDEPTHBUF
+    // Camera is always perspective; skip the vIsPerspective branch from three.js
+    // standard chunks to avoid float-precision z-fight against neighbouring meshes.
+    gl_FragDepth = log2(vFragDepth) * logDepthBufFC * 0.5;
+#endif
+}
+
+// Mirrors three.js fog_fragment chunk: applied after lighting/tint on the final colour.
+void applyFog() {
+#ifdef USE_FOG
+#ifdef FOG_EXP2
+    float fogFactor = 1.0 - exp(-fogDensity * fogDensity * vFogDepth * vFogDepth);
+#else
+    float fogFactor = smoothstep(fogNear, fogFar, vFogDepth);
+#endif
+    FragColor.rgb = mix(FragColor.rgb, fogColor, fogFactor);
+#endif
+}
+
+void main() {
+    // Atlas sample (pixelated, no filtering)
+    ivec2 atlasSize = textureSize(u_atlas, 0);
+    int tilesPerRow = atlasSize.x / 16;
+    ivec2 tileOrigin = ivec2(v_texIndex % tilesPerRow, v_texIndex / tilesPerRow) * 16;
+    ivec2 texel = tileOrigin + clamp(ivec2(v_uv * 16.0), ivec2(0), ivec2(15));
+    vec4 baseColor = texelFetch(u_atlas, texel, 0);
+
+    if (u_debugMode > 3.5) {
+        FragColor = vec4(vec3(baseColor.a), 1.0);
+        writeLogDepth();
+        return;
+    }
+
+    if (u_debugMode > 2.5) {
+        if (v_faceId == 0) FragColor = vec4(1.0, 0.0, 0.0, 1.0);
+        else if (v_faceId == 1) FragColor = vec4(0.0, 1.0, 0.0, 1.0);
+        else if (v_faceId == 2) FragColor = vec4(0.0, 0.0, 1.0, 1.0);
+        else if (v_faceId == 3) FragColor = vec4(1.0, 1.0, 0.0, 1.0);
+        else if (v_faceId == 4) FragColor = vec4(1.0, 0.0, 1.0, 1.0);
+        else FragColor = vec4(0.0, 1.0, 1.0, 1.0);
+        writeLogDepth();
+        return;
+    }
+
+    if (u_debugMode > 1.5) {
+        float t = float(v_texIndex) / 4095.0;
+        FragColor = vec4(t, fract(float(v_texIndex) / 64.0), 0.0, 1.0);
+        writeLogDepth();
+        return;
+    }
+
+    if (baseColor.a < 0.01) {
+        if (u_debugMode > 0.5) {
+            FragColor = vec4(1.0, 0.0, 0.0, 1.0);
+            writeLogDepth();
+            return;
+        }
+        discard;
+    }
+
+    // Tint from palette (256x1 RGBA texture, index 0 = white [1,1,1])
+    vec3 tint = texelFetch(u_tintPalette, ivec2(v_tintIndex, 0), 0).rgb;
+
+    // Combined light * AO, identity brightness curve (no mcBrightness) to match the
+    // legacy CPU mesher output 1:1.
+    float brightness = v_light * v_ao;
+
+    // Opaque full cubes: always alpha 1 (legacy uses cutout material; avoids seeing blocks behind)
+    FragColor = vec4(baseColor.rgb * tint * brightness, 1.0);
+    applyFog();
+    writeLogDepth();
+}
+`
+
+export function createCubeBlockMaterial(): THREE.ShaderMaterial {
+    return new THREE.ShaderMaterial({
+        vertexShader,
+        fragmentShader,
+        // Merge UniformsLib.fog (fogColor/fogNear/fogFar/fogDensity) so Three.js's
+        // WebGLMaterials.refreshFogUniforms can keep them in sync with scene.fog each
+        // frame — only happens for materials with \`fog: true\` set below.
+        uniforms: THREE.UniformsUtils.merge([
+            THREE.UniformsLib.fog,
+            {
+                u_atlas: { value: null },
+                u_tintPalette: { value: null },
+                u_debugMode: { value: 0 },
+                u_cameraOrigin: { value: new THREE.Vector3() },
+                u_cameraOriginFrac: { value: new THREE.Vector3() },
+            },
+        ]),
+        // Opaque full cubes — WASM mesher already culls interior faces between
+        // solid neighbors, so no z-fighting between own faces. Keep NoBlending so
+        // the alpha=1 path writes pure pixels and depth.
+        transparent: false,
+        depthWrite: true,
+        depthTest: true,
+        blending: THREE.NoBlending,
+        glslVersion: THREE.GLSL3,
+        // Required for Three.js to inject \`#define USE_FOG\` (and refresh fog uniforms).
+        fog: true,
+    })
+}
+
+// Three geometry constants: 6 vertices per face (2 triangles, un-indexed)
+export const VERTICES_PER_FACE = 6
+
+// Word layout constants (for encoding/decoding instances)
+export const WORD0 = {
+    LX_BITS: 4,
+    LY_BITS: 4,
+    LZ_BITS: 4,
+    FACE_BITS: 3,
+    TINT_BITS: 8,
+    AO_BITS_PER_CORNER: 2,
+    NUM_CORNERS: 4,
+    // Bit offsets
+    LX_SHIFT: 0,
+    LY_SHIFT: 4,
+    LZ_SHIFT: 8,
+    FACE_SHIFT: 12,
+    TINT_SHIFT: 15,
+    AO_SHIFT: 23,
+    TRANSPARENT_SHIFT: 31,
+} as const
+
+export const WORD1 = {
+    LIGHT_BITS_PER_CORNER: 8,
+    NUM_CORNERS: 4,
+} as const
+
+export const WORD2 = {
+    TEX_INDEX_BITS: 12,
+    DIAGONAL_FLAG_SHIFT: 12,
+    SECTION_Y_SHIFT: 13,
+    SECTION_Y_BITS: 5,
+    EMPTY_SHIFT: 18,
+    SPARE_BITS: 13,
+} as const
+
+/** Section base X/Z packed into a_w3 (16-block units, biased). */
+export const WORD3 = {
+    SECTION_X_BITS: 16,
+    SECTION_Z_BITS: 16,
+    SECTION_BIAS: 32768,
+} as const

package/src/three/shaders/textureIndexMapping.ts

@@ -0,0 +1,122 @@
+//@ts-nocheck
+/**
+ * Maps texture atlas positions to 12-bit absolute tile indices used by the
+ * instanced shader-cube path.
+ *
+ * Requirement: atlas MUST be 1024×1024 with 16×16 tiles (max 4096 tiles fits in 12 bits).
+ * If atlas dimensions differ, `isValid()` returns false and callers must fall back to
+ * the legacy vertex path.
+ */
+
+// WorldBlockProvider interface (subset used by this module)
+export interface TextureAtlasInfo {
+    /** Atlas width in pixels (must be 1024) */
+    width: number
+    /** Atlas height in pixels (must be 1024) */
+    height: number
+    /** Tile size in pixels (must be 16) */
+    tileSize: number
+    /** Resolution scale (suSv = tileSize * resolution) */
+    suSv: number
+    /** Texture name → atlas position */
+    textures: Record<string, TextureEntry>
+}
+
+export interface TextureEntry {
+    /** Horizontal pixel offset within atlas */
+    u: number
+    /** Vertical pixel offset within atlas */
+    v: number
+    /** Horizontal pixel count (typically 16 or suSv) */
+    su: number
+    /** Vertical pixel count (typically 16 or suSv) */
+    sv: number
+}
+
+export class TextureIndexMapping {
+    private atlasWidth: number
+    private atlasHeight: number
+    private tileSize: number
+    private tilesPerRow: number
+    private maxTiles: number
+    private valid: boolean
+
+    constructor(atlasInfo: TextureAtlasInfo) {
+        this.atlasWidth = atlasInfo.width
+        this.atlasHeight = atlasInfo.height
+        this.tileSize = atlasInfo.tileSize
+        this.tilesPerRow = Math.floor(this.atlasWidth / this.tileSize)
+        this.maxTiles = this.tilesPerRow * Math.floor(this.atlasHeight / this.tileSize)
+
+        // Only valid when atlas matches the shader's hardcoded layout (1024×1024, 16×16 tiles).
+        this.valid = this.atlasWidth === 1024
+            && this.atlasHeight === 1024
+            && this.tileSize === 16
+            && this.maxTiles <= 4096 // 12-bit limit
+    }
+
+    /** True when 12-bit texIndex encoding is safe (atlas matches the shader's layout). */
+    isValid(): boolean {
+        return this.valid
+    }
+
+    /** Tiles per row in the atlas */
+    getTilesPerRow(): number {
+        return this.tilesPerRow
+    }
+
+    /**
+     * Compute absolute tile index from atlas pixel position.
+     * Returns -1 if the position is out of range or gate fails.
+     */
+    tileIndexFromPixelCoords(u: number, v: number): number {
+        if (!this.valid) return -1
+        const tileCol = Math.floor(u / this.tileSize)
+        const tileRow = Math.floor(v / this.tileSize)
+        if (tileCol < 0 || tileCol >= this.tilesPerRow || tileRow < 0) return -1
+        const index = tileRow * this.tilesPerRow + tileCol
+        if (index >= this.maxTiles) return -1
+        return index
+    }
+
+    /**
+     * Get tile index for a texture entry from the atlas.
+     * Returns -1 if the texture spans multiple tiles or gate fails.
+     */
+    tileIndexFromTextureEntry(entry: TextureEntry): number {
+        if (!this.valid) return -1
+        // Verify the texture occupies exactly one tile
+        if (entry.su !== this.tileSize || entry.sv !== this.tileSize) return -1
+        return this.tileIndexFromPixelCoords(entry.u, entry.v)
+    }
+
+    /**
+     * Look up tile index by texture name.
+     * Returns -1 if the texture is not found, spans multiple tiles, or gate fails.
+     */
+    tileIndexFromTextureName(
+        textureName: string,
+        atlasInfo: TextureAtlasInfo,
+    ): number {
+        if (!this.valid) return -1
+        // Try exact name, then strip namespace prefix
+        let entry = atlasInfo.textures[textureName]
+        if (!entry && textureName.includes(':')) {
+            entry = atlasInfo.textures[textureName.split(':')[1]]
+        }
+        if (!entry && textureName.includes('/')) {
+            entry = atlasInfo.textures[textureName.split('/')[1]]
+        }
+        if (!entry) {
+            // Try 'block/' prefix
+            entry = atlasInfo.textures[`block/${textureName}`]
+        }
+        if (!entry) {
+            // Try without 'block/' prefix
+            const stripped = textureName.replace(/^block\//, '')
+            entry = atlasInfo.textures[stripped]
+        }
+        if (!entry) return -1
+        return this.tileIndexFromTextureEntry(entry)
+    }
+}

package/src/three/shaders/tintPalette.ts

@@ -0,0 +1,198 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+// ---- Palette entry ----
+export interface TintPaletteEntry {
+    r: number // 0-1
+    g: number
+    b: number
+}
+
+// ---- Palette manager ----
+export class TintPalette {
+    private entries: TintPaletteEntry[] = [{ r: 1, g: 1, b: 1 }] // index 0 = white (no tint)
+    private colorToIndex: Map<number, number> = new Map() // packed color -> index
+    private categoryBiomeToIndex: Map<string, number> = new Map()
+    private texture: THREE.DataTexture | null = null
+    private ready = false
+
+    /** Pack [r,g,b] (0-1 floats) into a 24-bit integer for fast lookup */
+    private packColor(r: number, g: number, b: number): number {
+        const ri = Math.round(r * 255)
+        const gi = Math.round(g * 255)
+        const bi = Math.round(b * 255)
+        return (ri << 16) | (gi << 8) | bi
+    }
+
+    /** Add a tint entry, returns its palette index (reuses duplicates) */
+    add(r: number, g: number, b: number, category: string, key: string): number {
+        const packed = this.packColor(r, g, b)
+
+        // Try categorical lookup first (faster and preserves semantic grouping)
+        const catKey = `${category}:${key}`
+        const existing = this.categoryBiomeToIndex.get(catKey)
+        if (existing !== undefined) return existing
+
+        // Deduplicate by exact color
+        const colorIdx = this.colorToIndex.get(packed)
+        if (colorIdx !== undefined) {
+            this.categoryBiomeToIndex.set(catKey, colorIdx)
+            return colorIdx
+        }
+
+        const idx = this.entries.length
+        this.entries.push({ r, g, b })
+        this.colorToIndex.set(packed, idx)
+        this.categoryBiomeToIndex.set(catKey, idx)
+        return idx
+    }
+
+    /** Look up tint index for a specific block face */
+    getTintIndex(
+        faceTintIndex: number | undefined,
+        blockName: string,
+        blockProps: Record<string, any>,
+        biome: string,
+    ): number {
+        if (faceTintIndex === undefined) return 0 // white
+
+        if (faceTintIndex === 0) {
+            if (blockName === 'redstone_wire') {
+                return this.categoryBiomeToIndex.get(`redstone:${blockProps.power}`)
+                ?? this.categoryBiomeToIndex.get('redstone:0')
+                ?? 0
+            }
+            if (blockName === 'birch_leaves' || blockName === 'spruce_leaves' || blockName === 'lily_pad') {
+                return this.categoryBiomeToIndex.get(`constant:${blockName}`)
+                    ?? this.categoryBiomeToIndex.get('constant:default')
+                    ?? 0
+            }
+            if (blockName.includes('leaves') || blockName === 'vine') {
+                return this.categoryBiomeToIndex.get(`foliage:${biome}`) ?? this.categoryBiomeToIndex.get('foliage:plains') ?? 0
+            }
+            // Default: grass tint
+            return this.categoryBiomeToIndex.get(`grass:${biome}`) ?? this.categoryBiomeToIndex.get('grass:plains') ?? 0
+        }
+
+        return 0 // unknown tint index -> white
+    }
+
+    /** Get the palette entry at a given index */
+    getEntry(index: number): TintPaletteEntry {
+        return this.entries[index] ?? this.entries[0]
+    }
+
+    /** Total number of palette entries */
+    get size(): number {
+        return this.entries.length
+    }
+
+    /** Build RGBA Float32Array from palette entries (for DataTexture) */
+    private buildTextureData(): Float32Array {
+        // RGBA × 256 entries
+        const data = new Float32Array(256 * 4)
+        for (let i = 0; i < this.entries.length && i < 256; i++) {
+            const e = this.entries[i]
+            data[i * 4] = e.r
+            data[i * 4 + 1] = e.g
+            data[i * 4 + 2] = e.b
+            data[i * 4 + 3] = 1.0
+        }
+        return data
+    }
+
+    /** Create or update the Three.js DataTexture */
+    createTexture(): THREE.DataTexture {
+        if (this.texture) {
+            this.texture.dispose()
+            this.texture = null
+            this.ready = false
+        }
+        const data = this.buildTextureData()
+        const texture = new THREE.DataTexture(
+            data as any,
+            256, 1,
+            THREE.RGBAFormat,
+            THREE.FloatType,
+        ) as THREE.DataTexture
+        texture.minFilter = THREE.NearestFilter
+        texture.magFilter = THREE.NearestFilter
+        texture.wrapS = THREE.ClampToEdgeWrapping
+        texture.wrapT = THREE.ClampToEdgeWrapping
+        texture.needsUpdate = true
+        this.texture = texture
+        this.ready = true
+        return texture
+    }
+
+    getTexture(): THREE.DataTexture | null {
+        return this.texture
+    }
+
+    isReady(): boolean {
+        return this.ready
+    }
+
+    /** Precompute the full palette using tints data */
+    static fromTintsData(tintsData: Record<string, any>): TintPalette {
+        const palette = new TintPalette()
+        // Offsets to avoid collision with categorical keys — already handled by packColor dedup
+
+        function tintToGl(tint: number): [number, number, number] {
+            const r = ((tint >> 16) & 0xff) / 255
+            const g = ((tint >> 8) & 0xff) / 255
+            const b = (tint & 0xff) / 255
+            return [r, g, b]
+        }
+
+        // --- grass tint (per biome) ---
+        if (tintsData.grass) {
+            const grassDefault = tintToGl(tintsData.grass.default)
+            for (const { keys, color } of tintsData.grass.data ?? []) {
+                const c = tintToGl(color as number)
+                for (const biome of keys as string[]) {
+                    palette.add(c[0], c[1], c[2], 'grass', biome)
+                }
+            }
+            palette.add(grassDefault[0], grassDefault[1], grassDefault[2], 'grass', 'plains')
+        }
+
+        // --- foliage tint (per biome) ---
+        if (tintsData.foliage) {
+            const foliageDefault = tintToGl(tintsData.foliage.default)
+            for (const { keys, color } of tintsData.foliage.data ?? []) {
+                const c = tintToGl(color as number)
+                for (const biome of keys as string[]) {
+                    palette.add(c[0], c[1], c[2], 'foliage', biome)
+                }
+            }
+            palette.add(foliageDefault[0], foliageDefault[1], foliageDefault[2], 'foliage', 'plains')
+        }
+
+        // --- redstone tint (per power level 0-15) ---
+        if (tintsData.redstone) {
+            const rsDefault = tintToGl(tintsData.redstone.default)
+            for (const { keys, color } of tintsData.redstone.data ?? []) {
+                const c = tintToGl(color as number)
+                for (const key of keys as string[]) {
+                    palette.add(c[0], c[1], c[2], 'redstone', key)
+                }
+            }
+            palette.add(rsDefault[0], rsDefault[1], rsDefault[2], 'redstone', '0')
+        }
+
+        // --- constant tints (birch leaves, spruce leaves, lily pad) ---
+        if (tintsData.constant) {
+            const constDefault = tintToGl(tintsData.constant.default)
+            for (const { keys, color } of tintsData.constant.data ?? []) {
+                const c = tintToGl(color as number)
+                for (const key of keys as string[]) {
+                    palette.add(c[0], c[1], c[2], 'constant', key)
+                }
+            }
+            palette.add(constDefault[0], constDefault[1], constDefault[2], 'constant', 'default')
+        }
+
+        return palette
+    }
+}