minecraft-renderer 0.1.107 → 0.1.108

package/src/lighting/entity/entityLightController.test.ts

@@ -0,0 +1,216 @@
+//@ts-nocheck
+import { describe, expect, it } from 'vitest'
+import * as THREE from 'three'
+import { blockEntityBrightness, DEFAULT_LIGHTMAP_PARAMS } from '../../lib/blockEntityLighting'
+import { EntityLightController, entityProbeBlock, resolveEntityLightOverride } from './entityLightController'
+
+const nightSky = 4 / 15
+
+function makeController(
+  getLight: (x: number, y: number, z: number) => { block: number; sky: number } = () => ({ block: 0, sky: 1 }),
+  extras: Partial<ConstructorParameters<typeof EntityLightController>[0]> = {}
+) {
+  let skyLevel = 1
+  let lightingEnabled = true
+  let globalRevision = 1
+  const columnRevisions = new Map<string, number>([['0,0', 1]])
+  const controller = new EntityLightController({
+    getLight,
+    getSkyLevel: () => skyLevel,
+    getLightmapParams: () => DEFAULT_LIGHTMAP_PARAMS,
+    getColumnRevision: (cx, cz) => columnRevisions.get(`${cx},${cz}`),
+    getGlobalRevision: () => globalRevision,
+    lightingEnabled: () => lightingEnabled,
+    ...extras
+  })
+  return {
+    controller,
+    setSkyLevel: (value: number) => {
+      skyLevel = value
+      controller.setSkyLevel(value)
+    },
+    setLightingEnabled: (value: boolean) => {
+      lightingEnabled = value
+    },
+    bumpColumn: () => {
+      columnRevisions.set('0,0', (columnRevisions.get('0,0') ?? 0) + 1)
+    },
+    bumpFarColumn: () => {
+      columnRevisions.set('16,0', (columnRevisions.get('16,0') ?? 0) + 1)
+    }
+  }
+}
+
+describe('entityProbeBlock', () => {
+  it('samples the eye block, not the block above the AABB', () => {
+    expect(entityProbeBlock({ x: 8.2, y: 64.3, z: 8.7 }, 1.62)).toEqual({ x: 8, y: 65, z: 8 })
+    expect(entityProbeBlock({ x: 8.2, y: 64.3, z: 8.7 }, 1.8)).toEqual({ x: 8, y: 66, z: 8 })
+  })
+})
+
+describe('resolveEntityLightOverride', () => {
+  it('fullbrights only reliably identified glow item frames', () => {
+    expect(resolveEntityLightOverride('glow_item_frame')).toBe('fullbright')
+    expect(resolveEntityLightOverride('item_frame')).toBe('normal')
+    expect(resolveEntityLightOverride('blaze')).toBe('normal')
+  })
+})
+
+describe('EntityLightController', () => {
+  it('multiplies immutable base tint and is idempotent', () => {
+    const { controller } = makeController(() => ({ block: 0, sky: 1 }))
+    const material = new THREE.MeshLambertMaterial({ color: 0xb5_6d_51 })
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(), material)
+    const root = new THREE.Group()
+    root.add(mesh)
+    const base = material.color.clone()
+    controller.register(root, { eyeHeight: 1.62 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    const brightness = blockEntityBrightness(0, 1, 1)
+    expect(material.color.r).toBeCloseTo(base.r * brightness, 5)
+    expect(material.color.g).toBeCloseTo(base.g * brightness, 5)
+    expect(material.color.b).toBeCloseTo(base.b * brightness, 5)
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(base.r * brightness, 5)
+  })
+
+  it('clones a shared material and leaves the original fullbright', () => {
+    const shared = new THREE.MeshBasicMaterial({ color: 0xff_00_00 })
+    const { controller } = makeController(() => ({ block: 0, sky: 0 }))
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(), shared)
+    const root = new THREE.Group()
+    root.add(mesh)
+    controller.register(root, { eyeHeight: 0 }, new Set([shared]))
+    controller.update(root, { x: 1, y: 64, z: 1 })
+    expect(shared.color.getHex()).toBe(0xff_00_00)
+    expect(mesh.material).not.toBe(shared)
+    const brightness = blockEntityBrightness(0, 0, 1)
+    expect((mesh.material as THREE.MeshBasicMaterial).color.r).toBeCloseTo(1 * brightness, 5)
+  })
+
+  it('keeps two roots independent and skips debug helpers', () => {
+    let sample = { block: 1, sky: 1 }
+    const { controller } = makeController(() => sample)
+    const brightMat = new THREE.MeshBasicMaterial({ color: 0xff_ff_ff })
+    const darkMat = new THREE.MeshBasicMaterial({ color: 0xff_ff_ff })
+    const debugMat = new THREE.MeshBasicMaterial({ color: 0x00_ff_00 })
+    const bright = new THREE.Group()
+    bright.add(new THREE.Mesh(new THREE.BoxGeometry(), brightMat))
+    const dark = new THREE.Group()
+    dark.add(new THREE.Mesh(new THREE.BoxGeometry(), darkMat))
+    const debug = new THREE.Mesh(new THREE.BoxGeometry(), debugMat)
+    debug.name = 'debug'
+    dark.add(debug)
+    controller.register(bright, { eyeHeight: 0 })
+    controller.register(dark, { eyeHeight: 0 })
+    controller.update(bright, { x: 1, y: 64, z: 1 })
+    sample = { block: 0, sky: 0 }
+    controller.update(dark, { x: 20, y: 64, z: 20 })
+    expect(brightMat.color.r).toBeCloseTo(1, 5)
+    expect(darkMat.color.r).toBeCloseTo(blockEntityBrightness(0, 0, 1), 5)
+    expect(debugMat.color.getHex()).toBe(0x00_ff_00)
+  })
+
+  it('refreshes on sky change and stays fullbright when lighting is disabled', () => {
+    const { controller, setSkyLevel, setLightingEnabled } = makeController(() => ({ block: 0, sky: 1 }))
+    const material = new THREE.MeshBasicMaterial({ color: 0xff_ff_ff })
+    const root = new THREE.Group()
+    root.add(new THREE.Mesh(new THREE.BoxGeometry(), material))
+    controller.register(root, { eyeHeight: 0 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    setSkyLevel(nightSky)
+    expect(material.color.r).toBeCloseTo(blockEntityBrightness(0, 1, nightSky), 5)
+    setLightingEnabled(false)
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(1, 5)
+  })
+
+  it('resamples a stationary root when the column revision changes', () => {
+    let sample = { block: 1, sky: 1 }
+    const { controller, bumpColumn } = makeController(() => sample)
+    const material = new THREE.MeshBasicMaterial({ color: 0xff_ff_ff })
+    const root = new THREE.Group()
+    root.add(new THREE.Mesh(new THREE.BoxGeometry(), material))
+    controller.register(root, { eyeHeight: 0 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(1, 5)
+    sample = { block: 0, sky: 0 }
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(1, 5)
+    bumpColumn()
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(blockEntityBrightness(0, 0, 1), 5)
+  })
+
+  it('does not resample when only a distant column revision changes', () => {
+    let sample = { block: 1, sky: 1 }
+    const { controller, bumpFarColumn } = makeController(() => sample)
+    const material = new THREE.MeshBasicMaterial({ color: 0xff_ff_ff })
+    const root = new THREE.Group()
+    root.add(new THREE.Mesh(new THREE.BoxGeometry(), material))
+    controller.register(root, { eyeHeight: 0 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(1, 5)
+    sample = { block: 0, sky: 0 }
+    bumpFarColumn()
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(1, 5)
+  })
+
+  it('adopts an authored material retint after invalidation', () => {
+    const { controller } = makeController(() => ({ block: 0, sky: 0 }))
+    const material = new THREE.MeshBasicMaterial({ color: 0xb5_6d_51 })
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(), material)
+    const root = new THREE.Group()
+    root.add(mesh)
+    controller.register(root, { eyeHeight: 0 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    const brightness = blockEntityBrightness(0, 0, 1)
+    const brown = new THREE.Color(0xb5_6d_51)
+    expect(material.color.r).toBeCloseTo(brown.r * brightness, 5)
+    material.color.setHex(0x00_ff_00)
+    controller.invalidateMaterials(root)
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(0, 5)
+    expect(material.color.g).toBeCloseTo(brightness, 5)
+    expect(material.color.b).toBeCloseTo(0, 5)
+  })
+
+  it('keeps glow item frames fullbright and recovers after a damage flash', () => {
+    const { controller } = makeController(() => ({ block: 0, sky: 0 }))
+    const material = new THREE.MeshBasicMaterial({ color: 0xaa_aa_aa })
+    const baseR = material.color.r
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(), material)
+    const root = new THREE.Group()
+    root.add(mesh)
+    controller.register(root, { name: 'glow_item_frame', eyeHeight: 0 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.r).toBeCloseTo(baseR, 5)
+
+    const flashed = material.clone()
+    flashed.color.set(0xff_00_00)
+    mesh.material = flashed
+    controller.markFlash(root, 500)
+    controller.invalidateMaterials(root)
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(flashed.color.getHex()).toBe(0xff_00_00)
+    controller.endFlash(root)
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(flashed.color.r).toBeCloseTo(baseR, 5)
+  })
+
+  it('unregisters so later updates do not keep mutating materials', () => {
+    const { controller } = makeController(() => ({ block: 0, sky: 0 }))
+    const material = new THREE.MeshBasicMaterial({ color: 0xff_ff_ff })
+    const root = new THREE.Group()
+    root.add(new THREE.Mesh(new THREE.BoxGeometry(), material))
+    controller.register(root, { eyeHeight: 0 })
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    const dim = material.color.r
+    controller.unregister(root)
+    material.color.setHex(0xff_ff_ff)
+    controller.update(root, { x: 8, y: 64, z: 8 })
+    expect(material.color.getHex()).toBe(0xff_ff_ff)
+    expect(dim).toBeLessThan(1)
+  })
+})

package/src/lighting/entity/entityLightController.ts

@@ -0,0 +1,322 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { blockEntityBrightness, DEFAULT_LIGHTMAP_PARAMS, type BlockLightmapParams } from '../../lib/blockEntityLighting'
+
+export type EntityLightOverride = 'normal' | 'fullbright'
+
+export type EntityLightWorldPos = { x: number; y: number; z: number }
+
+export type EntityLightMeta = {
+  name?: string
+  height?: number
+  eyeHeight?: number
+}
+
+export type EntityLightSampler = {
+  getLight: (x: number, y: number, z: number) => { block: number; sky: number }
+  getSkyLevel: () => number
+  getLightmapParams: () => BlockLightmapParams
+  getColumnRevision: (chunkX: number, chunkZ: number) => number | undefined
+  getGlobalRevision: () => number
+  lightingEnabled: () => boolean
+}
+
+const BASE_COLOR_KEY = 'entityLightBaseColor'
+const LAST_APPLIED_COLOR_KEY = 'entityLightLastAppliedColor'
+const COLOR_EPSILON = 1e-4
+const LIVING_EYE_HEIGHT_RATIO = 0.85
+
+type ColorBearingMaterial = THREE.Material & { color: THREE.Color }
+
+type ControlledMaterial = {
+  material: ColorBearingMaterial
+  base: THREE.Color
+}
+
+type TrackedRoot = {
+  meta: EntityLightMeta
+  override: EntityLightOverride
+  materials: ControlledMaterial[]
+  materialsDirty: boolean
+  flashing: boolean
+  lastProbe?: { x: number; y: number; z: number }
+  lastColumnRevision?: number
+  lastGlobalRevision?: number
+  lastSkyLevel?: number
+  lastLightmapParams?: BlockLightmapParams
+  lastLightingEnabled?: boolean
+  lastBrightness?: number
+}
+
+const alignColumn = (coord: number) => Math.floor(coord / 16) * 16
+
+export function resolveEntityEyeHeight(meta: EntityLightMeta = {}): number {
+  if (Number.isFinite(meta.eyeHeight)) return meta.eyeHeight as number
+  if (Number.isFinite(meta.height)) return (meta.height as number) * LIVING_EYE_HEIGHT_RATIO
+  return 0
+}
+
+export function entityProbeBlock(worldPos: EntityLightWorldPos, eyeHeight = 0): { x: number; y: number; z: number } {
+  return {
+    x: Math.floor(worldPos.x),
+    y: Math.floor(worldPos.y + eyeHeight),
+    z: Math.floor(worldPos.z)
+  }
+}
+
+export function resolveEntityLightOverride(name?: string): EntityLightOverride {
+  return name === 'glow_item_frame' ? 'fullbright' : 'normal'
+}
+
+type Rgb = { r: number; g: number; b: number }
+
+const hasColor = (material: THREE.Material): material is ColorBearingMaterial => !!material && (material as ColorBearingMaterial).color instanceof THREE.Color
+
+const readRgb = (material: ColorBearingMaterial, key: string): THREE.Color | undefined => {
+  const stored = material.userData?.[key] as Rgb | undefined
+  if (!stored || !Number.isFinite(stored.r) || !Number.isFinite(stored.g) || !Number.isFinite(stored.b)) return undefined
+  return new THREE.Color(stored.r, stored.g, stored.b)
+}
+
+const storeRgb = (material: ColorBearingMaterial, key: string, color: THREE.Color) => {
+  material.userData[key] = { r: color.r, g: color.g, b: color.b }
+}
+
+const colorsClose = (a: THREE.Color, b: THREE.Color) =>
+  Math.abs(a.r - b.r) < COLOR_EPSILON && Math.abs(a.g - b.g) < COLOR_EPSILON && Math.abs(a.b - b.b) < COLOR_EPSILON
+
+const readStoredBase = (material: ColorBearingMaterial): THREE.Color | undefined => readRgb(material, BASE_COLOR_KEY)
+
+const storeBase = (material: ColorBearingMaterial, base: THREE.Color) => {
+  storeRgb(material, BASE_COLOR_KEY, base)
+}
+
+const readLastApplied = (material: ColorBearingMaterial): THREE.Color | undefined => readRgb(material, LAST_APPLIED_COLOR_KEY)
+
+const storeLastApplied = (material: ColorBearingMaterial, color: THREE.Color) => {
+  storeRgb(material, LAST_APPLIED_COLOR_KEY, color)
+}
+
+const resolveBaseColor = (material: ColorBearingMaterial, flashing: boolean): THREE.Color => {
+  const stored = readStoredBase(material)
+  if (!stored) {
+    const base = material.color.clone()
+    storeBase(material, base)
+    return base
+  }
+  if (flashing) return stored
+  const lastApplied = readLastApplied(material)
+  if (lastApplied && colorsClose(material.color, lastApplied)) return stored
+  const base = material.color.clone()
+  storeBase(material, base)
+  return base
+}
+
+const applyBrightnessToMaterial = (entry: ControlledMaterial, brightness: number) => {
+  entry.material.color.setRGB(entry.base.r * brightness, entry.base.g * brightness, entry.base.b * brightness)
+  storeLastApplied(entry.material, entry.material.color)
+}
+
+const lightmapParamsEqual = (a?: BlockLightmapParams, b?: BlockLightmapParams) =>
+  a === b ||
+  (!!a &&
+    !!b &&
+    (a.curve ?? DEFAULT_LIGHTMAP_PARAMS.curve) === (b.curve ?? DEFAULT_LIGHTMAP_PARAMS.curve) &&
+    (a.minBrightness ?? DEFAULT_LIGHTMAP_PARAMS.minBrightness) === (b.minBrightness ?? DEFAULT_LIGHTMAP_PARAMS.minBrightness) &&
+    (a.gamma ?? DEFAULT_LIGHTMAP_PARAMS.gamma) === (b.gamma ?? DEFAULT_LIGHTMAP_PARAMS.gamma))
+
+export class EntityLightController {
+  private readonly roots = new Map<THREE.Object3D, TrackedRoot>()
+  private skyLevel = 1
+  private lightmapParams: BlockLightmapParams = { ...DEFAULT_LIGHTMAP_PARAMS }
+
+  constructor(private readonly sampler: EntityLightSampler) {
+    this.skyLevel = sampler.getSkyLevel()
+    this.lightmapParams = { ...DEFAULT_LIGHTMAP_PARAMS, ...sampler.getLightmapParams() }
+  }
+
+  setSkyLevel(value: number) {
+    this.skyLevel = value
+    this.refreshAll()
+  }
+
+  setLightmapParams(params: BlockLightmapParams) {
+    this.lightmapParams = { ...this.lightmapParams, ...params }
+    this.refreshAll()
+  }
+
+  register(root: THREE.Object3D, meta: EntityLightMeta = {}, sharedMaterials?: Iterable<THREE.Material>) {
+    const shared = sharedMaterials ? new Set(sharedMaterials) : undefined
+    const existing = this.roots.get(root)
+    if (existing) {
+      existing.meta = { ...existing.meta, ...meta }
+      existing.override = resolveEntityLightOverride(existing.meta.name)
+      existing.materialsDirty = true
+      existing.lastProbe = undefined
+      if (shared) this.discoverMaterials(root, existing, shared)
+      return
+    }
+    const tracked: TrackedRoot = {
+      meta,
+      override: resolveEntityLightOverride(meta.name),
+      materials: [],
+      materialsDirty: true,
+      flashing: false
+    }
+    this.roots.set(root, tracked)
+    if (shared) this.discoverMaterials(root, tracked, shared)
+  }
+
+  setMeta(root: THREE.Object3D, meta: EntityLightMeta) {
+    const tracked = this.roots.get(root)
+    if (!tracked) return
+    tracked.meta = { ...tracked.meta, ...meta }
+    tracked.override = resolveEntityLightOverride(tracked.meta.name)
+    tracked.lastProbe = undefined
+  }
+
+  unregister(root: THREE.Object3D) {
+    this.roots.delete(root)
+  }
+
+  clear() {
+    this.roots.clear()
+  }
+
+  invalidateMaterials(root: THREE.Object3D) {
+    const tracked = this.roots.get(root)
+    if (!tracked) return
+    tracked.materialsDirty = true
+    tracked.lastProbe = undefined
+  }
+
+  invalidateFromDescendant(node: THREE.Object3D) {
+    let current: THREE.Object3D | null = node
+    while (current) {
+      if (this.roots.has(current)) {
+        this.invalidateMaterials(current)
+        return
+      }
+      current = current.parent
+    }
+  }
+
+  markFlash(root: THREE.Object3D, _durationMs?: number) {
+    const tracked = this.roots.get(root)
+    if (!tracked) return
+    tracked.flashing = true
+  }
+
+  endFlash(root: THREE.Object3D) {
+    const tracked = this.roots.get(root)
+    if (!tracked) return
+    tracked.flashing = false
+    tracked.lastProbe = undefined
+  }
+
+  update(root: THREE.Object3D, worldPos: EntityLightWorldPos, sharedMaterials?: Iterable<THREE.Material>) {
+    const tracked = this.roots.get(root)
+    if (!tracked) return
+    const materialsWereDirty = tracked.materialsDirty
+    if (tracked.materialsDirty) {
+      this.discoverMaterials(root, tracked, sharedMaterials ? new Set(sharedMaterials) : undefined)
+    }
+
+    const lightingEnabled = this.sampler.lightingEnabled()
+    const probe = entityProbeBlock(worldPos, resolveEntityEyeHeight(tracked.meta))
+    const columnRevision = this.sampler.getColumnRevision(alignColumn(probe.x), alignColumn(probe.z))
+    const globalRevision = this.sampler.getGlobalRevision()
+    const skyLevel = this.skyLevel
+    const lightmapParams = this.lightmapParams
+
+    const unchanged =
+      tracked.lastProbe &&
+      tracked.lastProbe.x === probe.x &&
+      tracked.lastProbe.y === probe.y &&
+      tracked.lastProbe.z === probe.z &&
+      tracked.lastColumnRevision === columnRevision &&
+      tracked.lastGlobalRevision === globalRevision &&
+      tracked.lastSkyLevel === skyLevel &&
+      tracked.lastLightingEnabled === lightingEnabled &&
+      lightmapParamsEqual(tracked.lastLightmapParams, lightmapParams)
+
+    if (unchanged && !materialsWereDirty) return
+
+    tracked.lastProbe = probe
+    tracked.lastColumnRevision = columnRevision
+    tracked.lastGlobalRevision = globalRevision
+    tracked.lastSkyLevel = skyLevel
+    tracked.lastLightmapParams = lightmapParams
+    tracked.lastLightingEnabled = lightingEnabled
+
+    if (tracked.flashing) return
+
+    const brightness = this.computeBrightness(tracked, probe, lightingEnabled)
+    tracked.lastBrightness = brightness
+    for (const entry of tracked.materials) {
+      applyBrightnessToMaterial(entry, brightness)
+    }
+  }
+
+  private refreshAll() {
+    for (const [root, tracked] of this.roots) {
+      if (tracked.flashing || tracked.materialsDirty) {
+        tracked.lastProbe = undefined
+        continue
+      }
+      const lightingEnabled = this.sampler.lightingEnabled()
+      const probe = tracked.lastProbe ?? { x: 0, y: 0, z: 0 }
+      const brightness = tracked.lastProbe ? this.computeBrightness(tracked, probe, lightingEnabled) : undefined
+      if (brightness === undefined) {
+        tracked.lastProbe = undefined
+        continue
+      }
+      tracked.lastSkyLevel = this.skyLevel
+      tracked.lastLightmapParams = this.lightmapParams
+      tracked.lastLightingEnabled = lightingEnabled
+      tracked.lastBrightness = brightness
+      for (const entry of tracked.materials) {
+        applyBrightnessToMaterial(entry, brightness)
+      }
+      void root
+    }
+  }
+
+  private computeBrightness(tracked: TrackedRoot, probe: { x: number; y: number; z: number }, lightingEnabled: boolean) {
+    if (!lightingEnabled || tracked.override === 'fullbright') return 1
+    const sample = this.sampler.getLight(probe.x, probe.y, probe.z)
+    return blockEntityBrightness(sample.block, sample.sky, this.skyLevel, this.lightmapParams)
+  }
+
+  private discoverMaterials(root: THREE.Object3D, tracked: TrackedRoot, sharedMaterials?: Set<THREE.Material>) {
+    const next: ControlledMaterial[] = []
+    const seen = new Set<THREE.Material>()
+    root.traverse(child => {
+      if (child.name === 'debug') return
+      const raw = (child as THREE.Mesh).material
+      if (!raw) return
+      const list = Array.isArray(raw) ? raw : [raw]
+      let replacedArray = false
+      const nextList = list.map((material, index) => {
+        if (!hasColor(material) || seen.has(material)) return material
+        seen.add(material)
+        let current = material
+        if (sharedMaterials?.has(current)) {
+          current = current.clone() as ColorBearingMaterial
+          if (Array.isArray(raw)) {
+            list[index] = current
+            replacedArray = true
+          } else {
+            ;(child as THREE.Mesh).material = current
+          }
+        }
+        const base = resolveBaseColor(current, tracked.flashing)
+        next.push({ material: current, base })
+        return current
+      })
+      if (replacedArray) (child as THREE.Mesh).material = nextList
+    })
+    tracked.materials = next
+    tracked.materialsDirty = false
+  }
+}