minecraft-renderer 0.1.95 → 0.1.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-renderer",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "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

@@ -145,41 +145,116 @@ function shortestYawRadians(fromYawRad: number, toYawRad: number): number {
   return norm > Math.PI ? norm - TAU_YAW : norm
 }
 
+/** Voice chat presence for a player, drawn as a small mic glyph before their nametag. */
+export type PlayerVoiceState = 'speaking' | 'muted' | 'idle'
+
+/**
+ * Draws a small mic glyph centered at the origin of the current transform.
+ * `size` is the glyph's bounding box (both width and height).
+ */
+function drawVoiceStateIcon(ctx: OffscreenCanvasRenderingContext2D, state: PlayerVoiceState, cx: number, cy: number, size: number) {
+  const color = state === 'speaking' ? '#3ddc47' : state === 'muted' ? '#ff5555' : '#cfcfcf'
+
+  ctx.save()
+  ctx.translate(cx, cy)
+
+  if (state === 'speaking') {
+    ctx.beginPath()
+    ctx.arc(0, 0, size * 0.62, 0, Math.PI * 2)
+    ctx.strokeStyle = 'rgba(61, 220, 71, 0.55)'
+    ctx.lineWidth = Math.max(1, size * 0.08)
+    ctx.stroke()
+  }
+
+  ctx.fillStyle = color
+  ctx.strokeStyle = color
+  ctx.lineWidth = Math.max(1, size * 0.12)
+
+  // Mic body: a rounded capsule
+  const bodyWidth = size * 0.34
+  const bodyHeight = size * 0.55
+  const bodyRadius = bodyWidth / 2
+  ctx.beginPath()
+  ctx.moveTo(-bodyRadius, -bodyHeight / 2 + bodyRadius)
+  ctx.arcTo(-bodyRadius, -bodyHeight / 2, 0, -bodyHeight / 2, bodyRadius)
+  ctx.arcTo(bodyRadius, -bodyHeight / 2, bodyRadius, -bodyHeight / 2 + bodyRadius, bodyRadius)
+  ctx.lineTo(bodyRadius, bodyHeight / 2 - bodyRadius)
+  ctx.arcTo(bodyRadius, bodyHeight / 2, 0, bodyHeight / 2, bodyRadius)
+  ctx.arcTo(-bodyRadius, bodyHeight / 2, -bodyRadius, bodyHeight / 2 - bodyRadius, bodyRadius)
+  ctx.closePath()
+  ctx.fill()
+
+  // Stand: arc + base line
+  ctx.beginPath()
+  ctx.arc(0, bodyHeight / 2 - bodyRadius / 2, size * 0.32, Math.PI * 0.15, Math.PI * 0.85, false)
+  ctx.stroke()
+  ctx.beginPath()
+  ctx.moveTo(0, size * 0.5)
+  ctx.lineTo(0, size * 0.62)
+  ctx.stroke()
+
+  if (state === 'muted') {
+    ctx.beginPath()
+    ctx.moveTo(-size * 0.42, -size * 0.42)
+    ctx.lineTo(size * 0.42, size * 0.42)
+    ctx.stroke()
+  }
+
+  ctx.restore()
+}
+
 function getUsernameTexture(
-  { username, nameTagBackgroundColor = 'rgba(0, 0, 0, 0.3)', nameTagTextOpacity = 255 }: any,
+  { username, nameTagBackgroundColor = 'rgba(0, 0, 0, 0.3)', nameTagTextOpacity = 255, voiceState }: any,
   { fontFamily = 'mojangles' }: any,
   version: string
 ) {
-  const canvas = createCanvas(64, 64)
-
+  const measureCanvas = createCanvas(64, 64)
   const PrismarineChat = PrismarineChatLoader(version)
 
-  const ctx = canvas.getContext('2d')
-  if (!ctx) throw new Error('Could not get 2d context')
+  const measureCtx = measureCanvas.getContext('2d')
+  if (!measureCtx) throw new Error('Could not get 2d context')
 
   const fontSize = 48
   const padding = 5
-  ctx.font = `${fontSize}px ${fontFamily}`
+  measureCtx.font = `${fontSize}px ${fontFamily}`
 
   const plainLines = String(typeof username === 'string' ? username : new PrismarineChat(username).toString()).split('\n')
   let textWidth = 0
   for (const line of plainLines) {
-    const width = ctx.measureText(line).width + padding * 2
+    const width = measureCtx.measureText(line).width + padding * 2
     if (width > textWidth) textWidth = width
   }
 
-  canvas.width = textWidth
-  canvas.height = (fontSize + padding) * plainLines.length
+  const height = (fontSize + padding) * plainLines.length
 
-  ctx.fillStyle = nameTagBackgroundColor
-  ctx.fillRect(0, 0, canvas.width, canvas.height)
+  // Render the text on its own canvas first so the existing centered-text
+  // layout in renderComponent() is unaffected by the icon we add alongside it.
+  const textCanvas = createCanvas(textWidth, height)
+  const textCtx = textCanvas.getContext('2d')
+  if (!textCtx) throw new Error('Could not get 2d context')
 
-  ctx.globalAlpha = nameTagTextOpacity / 255
+  textCtx.fillStyle = nameTagBackgroundColor
+  textCtx.fillRect(0, 0, textCanvas.width, textCanvas.height)
+  textCtx.globalAlpha = nameTagTextOpacity / 255
 
-  const textRendered = renderComponent(username, PrismarineChat, canvas, fontSize, 'white', -padding + fontSize)
+  const textRendered = renderComponent(username, PrismarineChat, textCanvas, fontSize, 'white', -padding + fontSize)
   if (!textRendered) return undefined
 
-  ctx.globalAlpha = 1
+  textCtx.globalAlpha = 1
+
+  if (!voiceState) return textCanvas
+
+  const iconSize = fontSize * 0.55
+  const iconAreaWidth = iconSize + padding * 2
+
+  const canvas = createCanvas(iconAreaWidth + textWidth, height)
+  const ctx = canvas.getContext('2d')
+  if (!ctx) throw new Error('Could not get 2d context')
+
+  ctx.fillStyle = nameTagBackgroundColor
+  ctx.fillRect(0, 0, canvas.width, canvas.height)
+  drawVoiceStateIcon(ctx, voiceState, iconAreaWidth / 2, canvas.height / 2, iconSize)
+  ctx.drawImage(textCanvas, iconAreaWidth, 0)
 
   return canvas
 }
@@ -234,6 +309,13 @@ const addNametag = (entity, options: { fontFamily: string }, mesh, version: stri
   return nameTag
 }
 
+/** Player nametags are placed above the skin model and scaled up; text_display/mob nametags are not. */
+function applyPlayerNametagTransform(nametag: THREE.Object3D | undefined, playerObject: { position: THREE.Vector3; scale: THREE.Vector3 }) {
+  if (!nametag) return
+  nametag.position.y = playerObject.position.y + playerObject.scale.y * 16 + 3
+  nametag.scale.multiplyScalar(12)
+}
+
 // todo cleanup
 const nametags = {}
 
@@ -395,6 +477,7 @@ export class Entities {
     }
     this.entities = {}
     this.currentSkinUrls = {}
+    this.playerVoiceStates = {}
 
     // Clean up player entity
     if (this.playerEntity) {
@@ -447,9 +530,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)
@@ -739,6 +820,33 @@ export class Entities {
     return playerObject
   }
 
+  /** Current voice chat presence per entity id, keyed as a string. Absent = no voice indicator. */
+  playerVoiceStates: Record<string, PlayerVoiceState> = {}
+
+  /**
+   * Show or hide the mic glyph on a player's nametag. `state` undefined hides it
+   * (e.g. the player left voice chat, or walked out of proximity range).
+   * Regenerates the nametag texture, so callers should only invoke this on
+   * actual state transitions (speaking start/stop, mute toggle), not per-frame.
+   */
+  setPlayerVoiceState(entityId: string | number, username: string, state: PlayerVoiceState | undefined) {
+    const key = String(entityId)
+    if (state) {
+      this.playerVoiceStates[key] = state
+    } else {
+      delete this.playerVoiceStates[key]
+    }
+
+    const e = this.entities[entityId]
+    const playerObject = e?.playerObject
+    if (!e || !playerObject) return
+    const mesh = e.children.find(c => c.name === 'mesh')
+    if (!mesh) return
+
+    const nametag = addNametag({ username, voiceState: state }, this.entitiesOptions, mesh, this.worldRenderer.version)
+    applyPlayerNametagTransform(nametag, playerObject)
+  }
+
   uuidPerSkinUrlsCache = {} as Record<string, { skinUrl?: string; capeUrl?: string }>
   currentSkinUrls = {} as Record<string, string>
 
@@ -1089,6 +1197,7 @@ export class Entities {
       disposeObject(e)
       // todo dispose textures as well ?
       delete this.entities[entity.id]
+      delete this.playerVoiceStates[String(entity.id)]
       return
     }
     if (!this.isRenderingAllowed()) return
@@ -1160,11 +1269,13 @@ export class Entities {
         mesh = wrapper
 
         if (entity.username) {
-          const nametag = addNametag(entity, { fontFamily: 'mojangles' }, wrapper, this.worldRenderer.version)
-          if (nametag) {
-            nametag.position.y = playerObject.position.y + playerObject.scale.y * 16 + 3
-            nametag.scale.multiplyScalar(12)
-          }
+          const nametag = addNametag(
+            { ...entity, voiceState: this.playerVoiceStates[entity.id] },
+            { fontFamily: 'mojangles' },
+            wrapper,
+            this.worldRenderer.version
+          )
+          applyPlayerNametagTransform(nametag, playerObject)
         }
       } else {
         mesh = getEntityMesh(this.mcData, entity, this.worldRenderer, this.entitiesOptions, { ...overrides, customModel: entity['customModel'] })

package/src/three/graphicsBackendBase.ts

@@ -35,6 +35,7 @@ export const getBackendMethods = (worldRenderer: WorldRendererThree): any => {
     playEntityAnimation: worldRenderer.entities.playAnimation.bind(worldRenderer.entities),
     damageEntity: worldRenderer.entities.handleDamageEvent.bind(worldRenderer.entities),
     updatePlayerSkin: worldRenderer.entities.updatePlayerSkin.bind(worldRenderer.entities),
+    setPlayerVoiceState: worldRenderer.entities.setPlayerVoiceState.bind(worldRenderer.entities),
     applyTemporaryPlayerSkinOverride: worldRenderer.entities.applyTemporaryPlayerSkinOverride.bind(worldRenderer.entities),
     changeHandSwingingState: worldRenderer.changeHandSwingingState.bind(worldRenderer),
     getHighestBlocks: worldRenderer.getHighestBlocks.bind(worldRenderer),

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)
     )
   }