minecraft-renderer 0.1.95 → 0.1.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.95",
+  "version": "0.1.96",
   "description": "The most Modular Minecraft world renderer with Three.js WebGL backend",
   "type": "module",
   "main": "./dist/index.js",

package/src/mesher-shared/exportedGeometryTypes.ts

@@ -1,6 +1,8 @@
 //@ts-nocheck
 /** Shared geometry export shapes (worker bridge + main-thread viewer). */
 
+import { SHADER_CUBES_FORMAT_VERSION } from './shaderCubeFormat'
+
 export interface ExportedSection {
   key: string
   position: { x: number; y: number; z: number }
@@ -25,7 +27,7 @@ export interface ExportedSection {
   shaderCubes?: {
     words: Uint32Array
     count: number
-    formatVersion: 3
+    formatVersion: typeof SHADER_CUBES_FORMAT_VERSION
   }
   visibilitySet?: number
 }

package/src/mesher-shared/shaderCubeFormat.ts

@@ -0,0 +1,3 @@
+//@ts-nocheck
+export const SHADER_CUBES_FORMAT_VERSION = 4 as const
+export const SHADER_CUBES_WORDS_PER_FACE = 4 as const

package/src/mesher-shared/shared.ts

@@ -1,5 +1,6 @@
 //@ts-nocheck
 import { BlockType } from '../playground/shared'
+import { SHADER_CUBES_FORMAT_VERSION } from './shaderCubeFormat'
 
 export const SECTION_HEIGHT = 16
 
@@ -80,7 +81,7 @@ export type MesherGeometryOutput = {
   shaderCubes?: {
     words: Uint32Array
     count: number
-    formatVersion: 3
+    formatVersion: typeof SHADER_CUBES_FORMAT_VERSION
   }
   /** Packed VisibilitySet (36 bits) for section occlusion / smart cull. */
   visibilitySet?: number

package/src/three/entities.ts

@@ -447,9 +447,7 @@ export class Entities {
   }
 
   private setSceneAttached(attached: boolean, entity: THREE.Object3D | null = null): void {
-    const targets = entity
-      ? [entity]
-      : [...Object.values(this.entities), ...(this.playerEntity ? [this.playerEntity] : [])]
+    const targets = entity ? [entity] : [...Object.values(this.entities), ...(this.playerEntity ? [this.playerEntity] : [])]
     for (const ent of targets) {
       if (attached) {
         if (!this.worldRenderer.scene.children.includes(ent)) this.worldRenderer.scene.add(ent)

package/src/three/shaders/cubeBlockShader.ts

@@ -7,6 +7,64 @@ export type { BlockLightmapParams }
 // Face order: UP=0, DOWN=1, EAST=2, WEST=3, SOUTH=4, NORTH=5
 // matches WASM mesher face order (mesher.rs FACE_NAMES)
 
+/** Term of tile-local UV in quad-corner coordinates (u, v ∈ {0,1}). */
+type FaceUvTerm = 'u' | '1-u' | 'v' | '1-v'
+
+/**
+ * Canonical tile-local UV per face for su>0, sv>0. Matches legacy elemFaces
+ * (+ implicit +180° on down; see render-from-wasm.ts `r += 180`).
+ * Index = faceId: UP, DOWN, EAST, WEST, SOUTH, NORTH.
+ * Single source of truth — GLSL and shaderCubeFaceUv() are generated from this.
+ */
+export const FACE_UV_TERMS: ReadonlyArray<readonly [FaceUvTerm, FaceUvTerm]> = [
+  ['u', '1-v'], // UP
+  ['1-u', 'v'], // DOWN
+  ['v', 'u'], // EAST
+  ['v', 'u'], // WEST
+  ['u', 'v'], // SOUTH
+  ['1-u', 'v'] // NORTH
+]
+
+const glslTerm = (t: FaceUvTerm) =>
+  ({
+    u: 'u',
+    v: 'v',
+    '1-u': '1.0 - u',
+    '1-v': '1.0 - v'
+  })[t]
+
+/** GLSL if/else-if chain for per-face UV — must stay in sync with FACE_UV_TERMS. */
+export function buildFaceUvGlsl(): string {
+  return FACE_UV_TERMS.map(([ut, vt], i) => `    ${i === 0 ? 'if' : 'else if'} (faceId == ${i}u) uv = vec2(${glslTerm(ut)}, ${glslTerm(vt)});`).join('\n')
+}
+
+function evalFaceUvTerm(t: FaceUvTerm, cu: number, cv: number): number {
+  switch (t) {
+    case 'u':
+      return cu
+    case '1-u':
+      return 1 - cu
+    case 'v':
+      return cv
+    case '1-v':
+      return 1 - cv
+  }
+}
+
+/** vi — quad corner in shader order (0..3): u = vi & 1, v = (vi >> 1) & 1. */
+export function shaderCubeFaceUv(faceId: number, vi: number, flipU: boolean, flipV: boolean): [number, number] {
+  const [ut, vt] = FACE_UV_TERMS[faceId] ?? FACE_UV_TERMS[0]
+  const cu = vi & 1
+  const cv = (vi >> 1) & 1
+  let uLocal = evalFaceUvTerm(ut, cu, cv)
+  let vLocal = evalFaceUvTerm(vt, cu, cv)
+  if (flipU) uLocal = 1 - uLocal
+  if (flipV) vLocal = 1 - vLocal
+  return [uLocal, vLocal]
+}
+
+const faceUvGlsl = buildFaceUvGlsl()
+
 const vertexShader = /* glsl */ `
 precision highp float;
 precision highp int;
@@ -143,18 +201,16 @@ void main() {
     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, v);
-    } else { // faceId == 5u
-        v_uv = vec2(1.0 - u, v);
-    }
+    // --- Per-face UV: canonical tile-local UV (su>0, sv>0), generated from
+    // FACE_UV_TERMS — same source as shaderCubeFaceUv() ---
+    vec2 uv;
+${faceUvGlsl}
+
+    // su/sv sign from resolved model: negative scale = mirror on axis.
+    // Bit offsets mirror WORD2.FLIP_U_SHIFT / WORD0.FLIP_V_SHIFT (GLSL cannot import TS).
+    if (((a_w2 >> 31u) & 0x1u) != 0u) uv.x = 1.0 - uv.x;
+    if (((a_w0 >> 31u) & 0x1u) != 0u) uv.y = 1.0 - uv.y;
+    v_uv = uv;
 
     // --- Position: section base (multiples of 16) + face quad + block-local 0..15 ---
     // Must mirror WORD2/WORD3 constants in TS (GLSL cannot import them).
@@ -321,6 +377,9 @@ void main() {
 }
 `
 
+/** Vertex shader source (includes generated face UV table). Exported for parity tests. */
+export const cubeBlockVertexShader = vertexShader
+
 export function createCubeBlockMaterial(): THREE.ShaderMaterial {
   return new THREE.ShaderMaterial({
     vertexShader,
@@ -417,7 +476,8 @@ export const WORD0 = {
   FACE_SHIFT: 12,
   TINT_SHIFT: 15,
   AO_SHIFT: 23,
-  TRANSPARENT_SHIFT: 31
+  /** sv<0 mirror flag — no free bits remain in word0 after this. */
+  FLIP_V_SHIFT: 31
 } as const
 
 export const WORD1 = {
@@ -434,7 +494,8 @@ export const WORD2 = {
   SECTION_X_HI_SHIFT: 19,
   SECTION_Z_HI_SHIFT: 25,
   SECTION_HI_BITS: 6,
-  SPARE_BITS: 1
+  /** su<0 mirror flag — no free bits remain in word2 after this. */
+  FLIP_U_SHIFT: 31
 } as const
 
 /** Section base X/Z: low 16 bits in a_w3, high 6 in a_w2 (22-bit biased section index). */

package/src/three/worldGeometryExport.ts

@@ -5,6 +5,7 @@ import type { ExportedSection, ExportedWorldGeometry } from '../mesher-shared/ex
 import { calculateSkyLightSimple } from '../lib/skyLight'
 import { bakeLegacyVertexColors } from '../lib/bakeLegacyLight'
 import { getShaderCubeResources } from '../wasm-mesher/bridge/shaderCubeBridge'
+import { SHADER_CUBES_FORMAT_VERSION } from '../mesher-shared/shaderCubeFormat'
 import { createCubeBlockMaterial, setCubeSkyLevel } from './shaders/cubeBlockShader'
 import { createShaderCubeMesh } from './shaderCubeMesh'
 
@@ -181,6 +182,8 @@ export function createMeshesFromExport(
 ): THREE.Group[] {
   const groups: THREE.Group[] = []
   const resolvedShaderMat = shaderMaterial ?? shaderMaterialForExport(material, skyLevel)
+  let skippedShaderCubeSections = 0
+  let skippedShaderCubeFormatVersion: number | undefined
 
   for (const section of exportData.sections) {
     const group = new THREE.Group()
@@ -213,9 +216,14 @@ export function createMeshesFromExport(
 
     const shaderCubes = section.shaderCubes
     if (shaderCubes && shaderCubes.count > 0 && resolvedShaderMat) {
-      const shaderMesh = createShaderCubeMesh(shaderCubes, resolvedShaderMat)
-      shaderMesh.position.set(section.position.x, section.position.y, section.position.z)
-      group.add(shaderMesh)
+      if (shaderCubes.formatVersion !== SHADER_CUBES_FORMAT_VERSION) {
+        skippedShaderCubeSections++
+        skippedShaderCubeFormatVersion ??= shaderCubes.formatVersion
+      } else {
+        const shaderMesh = createShaderCubeMesh(shaderCubes, resolvedShaderMat)
+        shaderMesh.position.set(section.position.x, section.position.y, section.position.z)
+        group.add(shaderMesh)
+      }
     }
 
     if (group.children.length > 0) {
@@ -223,6 +231,13 @@ export function createMeshesFromExport(
     }
   }
 
+  if (skippedShaderCubeSections > 0) {
+    console.warn(
+      `[worldGeometryExport] Skipped ${skippedShaderCubeSections} shader-cube section(s): ` +
+        `export format ${skippedShaderCubeFormatVersion} ≠ current ${SHADER_CUBES_FORMAT_VERSION}`
+    )
+  }
+
   return groups
 }
 

package/src/wasm-mesher/bridge/shaderCubeBridge.ts

@@ -6,12 +6,12 @@
  */
 
 import blocksAtlasesJson from 'mc-assets/dist/blocksAtlases.json'
+import { SHADER_CUBES_FORMAT_VERSION, SHADER_CUBES_WORDS_PER_FACE } from '../../mesher-shared/shaderCubeFormat'
 import { WORD0, WORD1, WORD2, WORD3 } from '../../three/shaders/cubeBlockShader'
 import { TextureIndexMapping, type TextureEntry } from '../../three/shaders/textureIndexMapping'
 import { TintPalette } from '../../three/shaders/tintPalette'
 
-export const SHADER_CUBES_FORMAT_VERSION = 3 as const
-export const SHADER_CUBES_WORDS_PER_FACE = 4 as const
+export { SHADER_CUBES_FORMAT_VERSION, SHADER_CUBES_WORDS_PER_FACE } from '../../mesher-shared/shaderCubeFormat'
 
 export type ShaderCubesOutput = {
   words: Uint32Array
@@ -83,32 +83,78 @@ let tintPalette: TintPalette | null = null
 let textureIndexMapping: TextureIndexMapping | null = null
 let tintsMissingWarned = false
 
-/** Convert mc-assets texture scales (normalized or negative) to pixel tile size for index lookup. */
-function normalizeTextureEntryForTileIndex(tex: { u?: number; v?: number; su?: number; sv?: number }, atlasWidth: number, tileSize: number): TextureEntry {
+type FaceTextureRef = TextureEntry & { tileIndex?: number }
+
+export type ResolvedFaceUv = { tileIndex: number; flipU: boolean; flipV: boolean }
+
+const UV_RESOLVE_EPS = 1e-6
+
+function isNearInteger(value: number): boolean {
+  return Math.abs(value - Math.round(value)) <= UV_RESOLVE_EPS
+}
+
+/**
+ * Resolve a face to (atlas tile + mirror flags).
+ * null ⇒ face does not fit exactly one aligned tile; block must use legacy path.
+ */
+export function resolveFaceUv(tex: FaceTextureRef, texMapping: TextureIndexMapping): ResolvedFaceUv | null {
+  const tileSize = 16
   let u = tex.u ?? 0
   let v = tex.v ?? 0
   let su = tex.su ?? tileSize
   let sv = tex.sv ?? tileSize
-  if (u > 0 && u <= 1) u = Math.round(u * atlasWidth)
-  if (v > 0 && v <= 1) v = Math.round(v * atlasWidth)
-  if (Math.abs(su) > 0 && Math.abs(su) <= 1) su = Math.round(Math.abs(su) * atlasWidth) || tileSize
-  else if (su < 0) su = tileSize
-  if (Math.abs(sv) > 0 && Math.abs(sv) <= 1) sv = Math.round(Math.abs(sv) * atlasWidth) || tileSize
-  else if (sv < 0) sv = tileSize
-  return { u, v, su, sv }
-}
 
-type FaceTextureRef = TextureEntry & { tileIndex?: number }
+  if (!Number.isFinite(u) || !Number.isFinite(v) || !Number.isFinite(su) || !Number.isFinite(sv)) {
+    return null
+  }
 
-/** Prefer atlas `tileIndex` from block model (legacy path uses the same). */
-export function resolveFaceTileIndex(tex: FaceTextureRef, texMapping: TextureIndexMapping): number {
-  const fromAtlas = tex.tileIndex
-  // tile 0 is a special/atlas-padding slot; use pixel fallback for block faces
-  if (typeof fromAtlas === 'number' && fromAtlas > 0 && fromAtlas < 4096) {
-    return fromAtlas
+  const atlasWidth = texMapping.getTilesPerRow() * tileSize
+  if (Math.abs(su) <= 1) {
+    u *= atlasWidth
+    v *= atlasWidth
+    su *= atlasWidth
+    sv *= atlasWidth
   }
-  const entry = normalizeTextureEntryForTileIndex(tex, texMapping.getTilesPerRow() * 16, 16)
-  return texMapping.tileIndexFromTextureEntry(entry)
+
+  if (!isNearInteger(u) || !isNearInteger(v) || !isNearInteger(su) || !isNearInteger(sv)) {
+    return null
+  }
+
+  const uPx = Math.round(u)
+  const vPx = Math.round(v)
+  const suPx = Math.round(su)
+  const svPx = Math.round(sv)
+
+  const flipU = suPx < 0
+  const flipV = svPx < 0
+
+  if (Math.abs(suPx) !== tileSize || Math.abs(svPx) !== tileSize) {
+    return null
+  }
+
+  const uMin = flipU ? uPx + suPx : uPx
+  const vMin = flipV ? vPx + svPx : vPx
+
+  if (uMin % tileSize !== 0 || vMin % tileSize !== 0) {
+    return null
+  }
+  if (uMin < 0 || vMin < 0) {
+    return null
+  }
+
+  const derived = texMapping.tileIndexFromPixelCoords(uMin, vMin)
+  if (derived < 0) {
+    return null
+  }
+
+  if (typeof tex.tileIndex === 'number') {
+    if (tex.tileIndex !== derived) {
+      return null
+    }
+    return { tileIndex: derived, flipU, flipV }
+  }
+
+  return { tileIndex: derived, flipU, flipV }
 }
 
 /** Main thread + worker: use `loadedData` set by the app / mesher (see mesherWasm). */
@@ -158,8 +204,8 @@ export function resetShaderCubeResources(): void {
 
 /**
  * Returns true when the block is a plain 1×1×1 cube that the instanced shader path
- * can render exactly like the legacy mesher (no model rotation, single un-rotated
- * element with all 6 cardinal faces present, atlas matches shader gate).
+ * can render with pixel-parity UV (no model rotation, single un-rotated element with
+ * all 6 cardinal faces present, each face exactly one aligned atlas tile).
  * Pass the already-resolved model variant (`modelVars[variantIndex][0]`).
  */
 export function isShaderCubeBlock(
@@ -191,7 +237,7 @@ export function isShaderCubeBlock(
     if ((eFace as { rotation?: number }).rotation) return false
     const tex = eFace.texture
     if (!tex) return false
-    if (resolveFaceTileIndex(tex as FaceTextureRef, texMapping) < 0) {
+    if (resolveFaceUv(tex as FaceTextureRef, texMapping) === null) {
       return false
     }
   }
@@ -199,7 +245,7 @@ export function isShaderCubeBlock(
   return true
 }
 
-function packWord0(lx: number, ly: number, lz: number, faceId: number, tintIndex: number, ao: number[]): number {
+function packWord0(lx: number, ly: number, lz: number, faceId: number, tintIndex: number, ao: number[], flipV: boolean): number {
   let w = 0
   w |= (lx & 0xf) << WORD0.LX_SHIFT
   w |= (ly & 0xf) << WORD0.LY_SHIFT
@@ -209,6 +255,9 @@ function packWord0(lx: number, ly: number, lz: number, faceId: number, tintIndex
   for (let i = 0; i < WORD0.NUM_CORNERS; i++) {
     w |= ((ao[i] ?? 3) & 3) << (WORD0.AO_SHIFT + i * WORD0.AO_BITS_PER_CORNER)
   }
+  if (flipV) {
+    w |= 1 << WORD0.FLIP_V_SHIFT
+  }
   return w >>> 0
 }
 
@@ -224,7 +273,7 @@ function biasedSectionIndex(sectionBaseCoord: number): number {
   return (Math.floor(sectionBaseCoord / 16) + WORD3.SECTION_BIAS) & WORD3.SECTION_MASK
 }
 
-export function packWord2(texIndex: number, aoDiagonalFlip: boolean, sectionBaseX: number, sectionBaseY: number, sectionBaseZ: number): number {
+export function packWord2(texIndex: number, aoDiagonalFlip: boolean, sectionBaseX: number, sectionBaseY: number, sectionBaseZ: number, flipU = false): number {
   let w = texIndex & ((1 << WORD2.TEX_INDEX_BITS) - 1)
   if (aoDiagonalFlip) {
     w |= 1 << WORD2.DIAGONAL_FLAG_SHIFT
@@ -235,6 +284,9 @@ export function packWord2(texIndex: number, aoDiagonalFlip: boolean, sectionBase
   const sz = biasedSectionIndex(sectionBaseZ)
   w |= ((sx >>> 16) & 0x3f) << WORD2.SECTION_X_HI_SHIFT
   w |= ((sz >>> 16) & 0x3f) << WORD2.SECTION_Z_HI_SHIFT
+  if (flipU) {
+    w |= 1 << WORD2.FLIP_U_SHIFT
+  }
   return w >>> 0
 }
 
@@ -346,11 +398,12 @@ export function tryBuildShaderCubeInstances(
 
     const eFace = faces[faceName]
     const tex = eFace.texture! as FaceTextureRef
-    const texIndex = resolveFaceTileIndex(tex, textureIndexMapping)
-    if (texIndex < 0) {
+    const resolved = resolveFaceUv(tex, textureIndexMapping)
+    if (resolved === null) {
       words.length = wordsStart
       return false
     }
+    const { tileIndex: texIndex, flipU, flipV } = resolved
 
     const rawAo = block.ao_data[faceDataIndex] ?? [3, 3, 3, 3]
     const rawLight = lightCombinedForFace(block, faceDataIndex)
@@ -372,9 +425,9 @@ export function tryBuildShaderCubeInstances(
     const tintIndex = tintPalette.getTintIndex(eFace.tintindex, cached.blockName, cached.blockProps, biome ?? 'plains')
 
     words.push(
-      packWord0(lx, ly, lz, faceIdx, tintIndex, ao),
+      packWord0(lx, ly, lz, faceIdx, tintIndex, ao, flipV),
       packWord1(lightCombined),
-      packWord2(texIndex, aoDiagonalFlip, sectionOrigin.x, sectionOrigin.y, sectionOrigin.z),
+      packWord2(texIndex, aoDiagonalFlip, sectionOrigin.x, sectionOrigin.y, sectionOrigin.z, flipU),
       packWord3(sectionOrigin.x, sectionOrigin.z)
     )
   }

package/src/wasm-mesher/tests/shaderCubeUvParity.test.ts

@@ -0,0 +1,226 @@
+//@ts-nocheck
+import { test, expect, beforeEach, vi } from 'vitest'
+import * as THREE from 'three'
+import { elemFaces } from '../../mesher-shared/modelsGeometryCommon'
+import { SHADER_CUBES_FORMAT_VERSION } from '../../mesher-shared/shaderCubeFormat'
+import { FACE_UV_TERMS, buildFaceUvGlsl, shaderCubeFaceUv, cubeBlockVertexShader, WORD0, WORD2 } from '../../three/shaders/cubeBlockShader'
+import {
+  AO_LIGHT_REMAP,
+  resetShaderCubeResources,
+  getShaderCubeResources,
+  resolveFaceUv,
+  isShaderCubeBlock,
+  tryBuildShaderCubeInstances,
+  SHADER_CUBES_WORDS_PER_FACE
+} from '../bridge/shaderCubeBridge'
+import { createMeshesFromExport } from '../../three/worldGeometryExport'
+
+const FACE_NAMES = ['up', 'down', 'east', 'west', 'south', 'north'] as const
+const SIGN_COMBOS: Array<[boolean, boolean]> = [
+  [false, false],
+  [true, false],
+  [false, true],
+  [true, true]
+]
+
+function requireShaderCubeResources() {
+  const resources = getShaderCubeResources()
+  if (!resources) throw new Error('shader cube resources unavailable in test')
+  return resources
+}
+
+/** Legacy tile-local UV (render-from-wasm.ts elemFaces + down +180°). */
+function legacyTileLocalUv(faceName: string, cornerIdx: number, suSign: number, svSign: number): [number, number] {
+  const [, , , cu, cv] = (elemFaces as Record<string, { corners: number[][] }>)[faceName]!.corners[cornerIdx]!
+  const r = faceName === 'down' ? 180 : 0
+  const uvcs = Math.cos((r * Math.PI) / 180)
+  const uvsn = -Math.sin((r * Math.PI) / 180)
+  const baseu = (cu - 0.5) * uvcs - (cv - 0.5) * uvsn + 0.5
+  const basev = (cu - 0.5) * uvsn + (cv - 0.5) * uvcs + 0.5
+  return [suSign < 0 ? 1 - baseu : baseu, svSign < 0 ? 1 - basev : basev]
+}
+
+beforeEach(() => {
+  resetShaderCubeResources()
+})
+
+test('shaderCubeFaceUv: 6 faces × 4 corners × 4 sign combos match legacy (96 cases)', () => {
+  for (let faceIdx = 0; faceIdx < 6; faceIdx++) {
+    const faceName = FACE_NAMES[faceIdx]!
+    for (let vi = 0; vi < 4; vi++) {
+      for (const [flipU, flipV] of SIGN_COMBOS) {
+        const suSign = flipU ? -1 : 1
+        const svSign = flipV ? -1 : 1
+        const elemCorner = AO_LIGHT_REMAP[faceIdx]![vi]!
+        const legacy = legacyTileLocalUv(faceName, elemCorner, suSign, svSign)
+        const shader = shaderCubeFaceUv(faceIdx, vi, flipU, flipV)
+        expect(shader[0]).toBeCloseTo(legacy[0], 9)
+        expect(shader[1]).toBeCloseTo(legacy[1], 9)
+      }
+    }
+  }
+})
+
+test('buildFaceUvGlsl: 6 branches match FACE_UV_TERMS and vertex shader embeds generated table', () => {
+  const glsl = buildFaceUvGlsl()
+  for (let i = 0; i < 6; i++) {
+    expect(glsl).toContain(`faceId == ${i}u`)
+    const [ut, vt] = FACE_UV_TERMS[i]!
+    const glslU = ut === 'u' ? 'u' : ut === 'v' ? 'v' : ut === '1-u' ? '1.0 - u' : '1.0 - v'
+    const glslV = vt === 'u' ? 'u' : vt === 'v' ? 'v' : vt === '1-u' ? '1.0 - u' : '1.0 - v'
+    expect(glsl).toContain(`vec2(${glslU}, ${glslV})`)
+  }
+  expect(cubeBlockVertexShader).toContain(glsl)
+  expect(cubeBlockVertexShader).toContain('a_w2 >> 31u')
+  expect(cubeBlockVertexShader).toContain('a_w0 >> 31u')
+})
+
+test('resolveFaceUv: crafting_table north/west regression', () => {
+  const { textureIndexMapping } = requireShaderCubeResources()
+
+  const north = resolveFaceUv({ u: 0.53125, v: 0, su: -0.015625, sv: 0.015625, tileIndex: 33 }, textureIndexMapping)
+  expect(north).toEqual({ tileIndex: 33, flipU: true, flipV: false })
+
+  const west = resolveFaceUv({ u: 0.515625, v: 0, su: 0.015625, sv: 0.015625, tileIndex: 33 }, textureIndexMapping)
+  expect(west).toEqual({ tileIndex: 33, flipU: false, flipV: false })
+})
+
+test('tryBuildShaderCubeInstances: crafting_table north sets FLIP_U_SHIFT', () => {
+  const { textureIndexMapping, tintPalette } = requireShaderCubeResources()
+  const craftingFaces = {
+    up: { texture: { u: 0.515625, v: 0, su: 0.015625, sv: 0.015625, tileIndex: 33 } },
+    down: { texture: { u: 0.53125, v: 0, su: -0.015625, sv: 0.015625, tileIndex: 33 } },
+    east: { texture: { u: 0.515625, v: 0, su: 0.015625, sv: 0.015625, tileIndex: 33 } },
+    west: { texture: { u: 0.515625, v: 0, su: 0.015625, sv: 0.015625, tileIndex: 33 } },
+    south: { texture: { u: 0.515625, v: 0, su: 0.015625, sv: 0.015625, tileIndex: 33 } },
+    north: { texture: { u: 0.53125, v: 0, su: -0.015625, sv: 0.015625, tileIndex: 33 } }
+  }
+  const model = { elements: [{ faces: craftingFaces }] }
+  const block = {
+    position: [0, 0, 0] as [number, number, number],
+    visible_faces: 1 << 5,
+    ao_data: [[3, 3, 3, 3]],
+    light_combined: [[255, 255, 255, 255]]
+  }
+  const words: number[] = []
+  const ok = tryBuildShaderCubeInstances(
+    block,
+    { blockName: 'crafting_table', blockProps: {}, isCube: true, model },
+    model,
+    { sectionOrigin: { x: 0, y: 0, z: 0 }, sectionHeight: 16, tintPalette, textureIndexMapping },
+    words
+  )
+  expect(ok).toBe(true)
+  expect(words.length).toBe(SHADER_CUBES_WORDS_PER_FACE)
+  expect(words[2]! & (1 << WORD2.FLIP_U_SHIFT)).not.toBe(0)
+})
+
+test('tryBuildShaderCubeInstances: sv<0 up face sets FLIP_V_SHIFT', () => {
+  const { textureIndexMapping, tintPalette } = requireShaderCubeResources()
+  const stdFace = { u: 0, v: 0, su: 16, sv: 16 }
+  const upSvNeg = { u: 0.515625, v: 0.015625, su: 0.015625, sv: -0.015625, tileIndex: 33 }
+  expect(resolveFaceUv(upSvNeg, textureIndexMapping)).toEqual({ tileIndex: 33, flipU: false, flipV: true })
+
+  const model = {
+    elements: [
+      {
+        faces: {
+          up: { texture: upSvNeg },
+          down: { texture: stdFace },
+          east: { texture: stdFace },
+          west: { texture: stdFace },
+          south: { texture: stdFace },
+          north: { texture: stdFace }
+        }
+      }
+    ]
+  }
+  const block = {
+    position: [0, 0, 0] as [number, number, number],
+    visible_faces: 1 << 0,
+    ao_data: [[3, 3, 3, 3]],
+    light_combined: [[255, 255, 255, 255]]
+  }
+  const words: number[] = []
+  const ok = tryBuildShaderCubeInstances(
+    block,
+    { blockName: 'observer', blockProps: { facing: 'north' }, isCube: true, model },
+    model,
+    { sectionOrigin: { x: 0, y: 0, z: 0 }, sectionHeight: 16, tintPalette, textureIndexMapping },
+    words
+  )
+  expect(ok).toBe(true)
+  expect(words.length).toBe(SHADER_CUBES_WORDS_PER_FACE)
+  expect(words[0]! & (1 << WORD0.FLIP_V_SHIFT)).not.toBe(0)
+  expect(words[2]! & (1 << WORD2.FLIP_U_SHIFT)).toBe(0)
+})
+
+test('resolveFaceUv gate: rejects crop, non-integer scale, misaligned tile, tileIndex mismatch, NaN', () => {
+  const { textureIndexMapping } = requireShaderCubeResources()
+
+  expect(resolveFaceUv({ u: 0, v: 0, su: 8, sv: 16 }, textureIndexMapping)).toBeNull()
+  expect(resolveFaceUv({ u: 0, v: 0, su: 15.6, sv: 16 }, textureIndexMapping)).toBeNull()
+  expect(resolveFaceUv({ u: 529, v: 0, su: 16, sv: 16 }, textureIndexMapping)).toBeNull()
+  expect(resolveFaceUv({ u: 0, v: 0, su: 16, sv: 16, tileIndex: 999 }, textureIndexMapping)).toBeNull()
+  expect(resolveFaceUv({ u: 0, v: 0, su: Number.NaN, sv: 16 }, textureIndexMapping)).toBeNull()
+})
+
+test('isShaderCubeBlock: rejects faces that fail resolveFaceUv gate', () => {
+  const { textureIndexMapping } = requireShaderCubeResources()
+  const baseFaces = {
+    up: { texture: { u: 0, v: 0, su: 16, sv: 16 } },
+    down: { texture: { u: 0, v: 0, su: 16, sv: 16 } },
+    east: { texture: { u: 0, v: 0, su: 16, sv: 16 } },
+    west: { texture: { u: 0, v: 0, su: 16, sv: 16 } },
+    south: { texture: { u: 0, v: 0, su: 16, sv: 16 } },
+    north: { texture: { u: 0, v: 0, su: 16, sv: 16 } }
+  }
+  const model = { elements: [{ faces: baseFaces }] }
+  expect(isShaderCubeBlock({ blockName: 'stone', blockProps: {}, isCube: true, model }, model, 16, textureIndexMapping)).toBe(true)
+
+  const cropped = {
+    elements: [{ faces: { ...baseFaces, up: { texture: { u: 0, v: 0, su: 8, sv: 16 } } } }]
+  }
+  expect(isShaderCubeBlock({ blockName: 'stone', blockProps: {}, isCube: true, model: cropped }, cropped, 16, textureIndexMapping)).toBe(false)
+})
+
+test('createMeshesFromExport: skips shader-cube sections with old formatVersion', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const material = new THREE.MeshBasicMaterial()
+  const v3Words = new Uint32Array([1, 2, 3, 4])
+  const v4Words = new Uint32Array([5, 6, 7, 8])
+
+  const groups = createMeshesFromExport(
+    {
+      version: 'test',
+      exportedAt: '',
+      camera: { position: { x: 0, y: 0, z: 0 }, rotation: { pitch: 0, yaw: 0 } },
+      sections: [
+        {
+          key: 'old',
+          position: { x: 0, y: 0, z: 0 },
+          geometry: { positions: [], normals: [], colors: [], skyLights: [], blockLights: [], uvs: [], indices: [] },
+          shaderCubes: { words: v3Words, count: 1, formatVersion: 3 as unknown as typeof SHADER_CUBES_FORMAT_VERSION }
+        },
+        {
+          key: 'new',
+          position: { x: 16, y: 0, z: 0 },
+          geometry: { positions: [], normals: [], colors: [], skyLights: [], blockLights: [], uvs: [], indices: [] },
+          shaderCubes: { words: v4Words, count: 1, formatVersion: SHADER_CUBES_FORMAT_VERSION }
+        }
+      ]
+    },
+    material,
+    new THREE.ShaderMaterial({ vertexShader: 'void main() {}', fragmentShader: 'void main() {}' })
+  )
+
+  expect(groups).toHaveLength(1)
+  expect(groups[0]!.children).toHaveLength(1)
+  expect(warn).toHaveBeenCalledOnce()
+  expect(warn.mock.calls[0]![0]).toContain('Skipped 1 shader-cube section')
+  expect(warn.mock.calls[0]![0]).toContain('3')
+  expect(warn.mock.calls[0]![0]).toContain(String(SHADER_CUBES_FORMAT_VERSION))
+
+  warn.mockRestore()
+  material.dispose()
+})

package/src/wasm-mesher/worker/mesherWasm.ts

@@ -4,6 +4,7 @@ import { convertChunkToWasm, getBlockMeta, type ChunkConversionResult } from '..
 import { extractColumnHeightmap, splitColumnWasmOutputToSections } from '../bridge/render-from-wasm'
 import { setBlockStatesData as setMesherData } from '../../mesher-shared/models'
 import { defaultMesherConfig, type MesherGeometryOutput, SECTION_HEIGHT } from '../../mesher-shared/shared'
+import { SHADER_CUBES_FORMAT_VERSION } from '../../mesher-shared/shaderCubeFormat'
 import { packVisibilitySet, VISIBILITY_SET_ALL_TRUE } from '../../mesher-shared/visibilitySet'
 import { VisGraph } from '../../mesher-shared/visGraph'
 import { worldColumnKey, World } from '../../mesher-shared/world'
@@ -1532,7 +1533,7 @@ function processColumnTick() {
             geometry.shaderCubes = {
               words: new Uint32Array(exported.shaderCubes.words),
               count: exported.shaderCubes.count,
-              formatVersion: 3
+              formatVersion: SHADER_CUBES_FORMAT_VERSION
             }
           }
           if (exported.blendGeometry && hasBlendMesh) {