minecraft-renderer 0.1.106 → 0.1.108

package/src/lighting/versioning/pendingSectionFlush.ts

@@ -0,0 +1,123 @@
+//@ts-nocheck
+/**
+ * Flush policy for buffered section geometry (`pendingSectionUpdates`).
+ *
+ * A remesh of an already-visible section must not be installed alone while a
+ * face neighbour is still being re-meshed: the neighbour's faces towards this
+ * section were culled against the OLD block state, so installing one side
+ * first exposes a see-through hole (the "sky flash" on dig/place).
+ *
+ * The policy therefore works on *groups*: pending sections that are face
+ * adjacent form a connected group, and a group is installed only when every
+ * outstanding neighbour of every member has arrived. When the buffer deadline
+ * expires we still flush, but we flush the whole group in one batch — never a
+ * single member, which is exactly the hole the buffer exists to prevent.
+ */
+
+export type PendingFlushQuery = {
+  /** Keys currently buffered, in insertion order. */
+  pendingKeys: Iterable<string>
+  /** When each key was first buffered. */
+  startedAt: (key: string) => number | undefined
+  now: number
+  maxBufferMs: number
+  sectionHeight: number
+  /** Section is dirty on a worker and its geometry has not arrived yet. */
+  isOutstanding: (key: string) => boolean
+  /**
+   * When set, neighbour waits use topology outstanding instead of covering/light
+   * outstanding. Omit for bit-for-bit legacy flush behavior.
+   */
+  isTopologyOutstanding?: (key: string) => boolean
+  /** Section currently has geometry on screen (an air section has none). */
+  hasSectionObject: (key: string) => boolean
+}
+
+export function faceNeighborKeys(key: string, sectionHeight: number): string[] {
+  const [sx, sy, sz] = key.split(',').map(Number)
+  return [
+    `${sx - 16},${sy},${sz}`,
+    `${sx + 16},${sy},${sz}`,
+    `${sx},${sy - sectionHeight},${sz}`,
+    `${sx},${sy + sectionHeight},${sz}`,
+    `${sx},${sy},${sz - 16}`,
+    `${sx},${sy},${sz + 16}`
+  ]
+}
+
+/**
+ * Connected components of the buffered sections under face adjacency. Members
+ * of one component must be installed in the same frame.
+ */
+export function pendingSectionGroups(pendingKeys: Iterable<string>, sectionHeight: number): string[][] {
+  const remaining = new Set(pendingKeys)
+  const groups: string[][] = []
+  for (const seed of [...remaining]) {
+    if (!remaining.has(seed)) continue
+    const group: string[] = []
+    const stack = [seed]
+    remaining.delete(seed)
+    while (stack.length > 0) {
+      const key = stack.pop()!
+      group.push(key)
+      for (const neighbor of faceNeighborKeys(key, sectionHeight)) {
+        if (remaining.delete(neighbor)) stack.push(neighbor)
+      }
+    }
+    groups.push(group)
+  }
+  return groups
+}
+
+export type PendingFlushReason = 'group-complete' | 'deadline'
+
+export type ReadySectionFlush = {
+  key: string
+  reason: PendingFlushReason
+}
+
+/**
+ * Keys to install this frame. Either a group is complete (no member still
+ * waiting on a visible neighbour) or its oldest member has run out of buffer
+ * time — in both cases the whole group goes out together.
+ */
+export function selectReadySectionFlushes(query: PendingFlushQuery): ReadySectionFlush[] {
+  const { now, maxBufferMs, sectionHeight } = query
+  const ready: ReadySectionFlush[] = []
+
+  for (const group of pendingSectionGroups(query.pendingKeys, sectionHeight)) {
+    const members = new Set(group)
+
+    let oldestStart = now
+    for (const key of group) {
+      const startedAt = query.startedAt(key) ?? now
+      if (startedAt < oldestStart) oldestStart = startedAt
+    }
+    const expired = now - oldestStart >= maxBufferMs
+
+    let waitingOnNeighbor = false
+    if (!expired) {
+      for (const key of group) {
+        for (const neighbor of faceNeighborKeys(key, sectionHeight)) {
+          if (members.has(neighbor)) continue
+          const neighborOutstanding = query.isTopologyOutstanding ? query.isTopologyOutstanding(neighbor) : query.isOutstanding(neighbor)
+          if (neighborOutstanding && query.hasSectionObject(neighbor)) {
+            waitingOnNeighbor = true
+            break
+          }
+        }
+        if (waitingOnNeighbor) break
+      }
+    }
+
+    if (waitingOnNeighbor) continue
+    const reason: PendingFlushReason = expired ? 'deadline' : 'group-complete'
+    for (const key of group) ready.push({ key, reason })
+  }
+
+  return ready
+}
+
+export function selectReadySectionUpdates(query: PendingFlushQuery): string[] {
+  return selectReadySectionFlushes(query).map(item => item.key)
+}

package/src/mesher-shared/lightNibblePack.ts

@@ -0,0 +1,26 @@
+//@ts-nocheck
+/** Packed 2048-byte nibble section ↔ unpacked 4096-byte per-block values. */
+
+export const PACKED_LIGHT_SECTION_BYTES = 2048
+export const UNPACKED_LIGHT_SECTION_BYTES = 4096
+
+export function packUnpackedLightSection(unpacked: Uint8Array): Uint8Array {
+  const packed = new Uint8Array(PACKED_LIGHT_SECTION_BYTES)
+  const n = Math.min(unpacked.length, UNPACKED_LIGHT_SECTION_BYTES)
+  for (let i = 0; i < n; i++) {
+    const v = unpacked[i]! & 0x0f
+    const byte = i >> 1
+    packed[byte] = i & 1 ? (packed[byte]! & 0x0f) | (v << 4) : (packed[byte]! & 0xf0) | v
+  }
+  return packed
+}
+
+export function unpackPackedLightSection(packed: Uint8Array): Uint8Array {
+  const unpacked = new Uint8Array(UNPACKED_LIGHT_SECTION_BYTES)
+  const n = Math.min(packed.length, PACKED_LIGHT_SECTION_BYTES)
+  for (let i = 0; i < n * 2 && i < UNPACKED_LIGHT_SECTION_BYTES; i++) {
+    const byte = packed[i >> 1] ?? 0
+    unpacked[i] = i & 1 ? byte >> 4 : byte & 0x0f
+  }
+  return unpacked
+}

package/src/mesher-shared/mcDataWorkerShim.cjs

@@ -11,7 +11,7 @@
 const mcDataToNode = require('minecraft-data/lib/loader')
 const indexer = require('minecraft-data/lib/indexer.js')
 
-function createVersion (type, suppliedVersion, protocolVersions) {
+function createVersion(type, suppliedVersion, protocolVersions) {
   const versions = indexer.buildIndexFromArray(protocolVersions, 'minecraftVersion') ?? {}
   // Allows comparisons against majorVersion even if `other` is not present in the versions list (e.g. 1.17.0 exists but not 1.17)
   for (const key in versions) {
@@ -23,12 +23,14 @@ function createVersion (type, suppliedVersion, protocolVersions) {
   // the supplied dataVersion is authoritative: the current version doesn't have to be present in the supplied list
   self.dataVersion = suppliedVersion.dataVersion ?? versions[suppliedVersion.minecraftVersion]?.dataVersion
   const v1 = self.dataVersion ?? 0
-  const raise = other => { throw new RangeError(`Version '${other}' not found in protocolVersions supplied by the main thread for ${type}`) }
-  self['>='] = other => versions[other] ? v1 >= versions[other].dataVersion : raise(other)
-  self['>'] = other => versions[other] ? v1 > versions[other].dataVersion : raise(other)
-  self['<'] = other => versions[other] ? v1 < versions[other].dataVersion : raise(other)
-  self['<='] = other => versions[other] ? v1 <= versions[other].dataVersion : raise(other)
-  self['=='] = other => versions[other] ? v1 === versions[other].dataVersion : raise(other)
+  const raise = other => {
+    throw new RangeError(`Version '${other}' not found in protocolVersions supplied by the main thread for ${type}`)
+  }
+  self['>='] = other => (versions[other] ? v1 >= versions[other].dataVersion : raise(other))
+  self['>'] = other => (versions[other] ? v1 > versions[other].dataVersion : raise(other))
+  self['<'] = other => (versions[other] ? v1 < versions[other].dataVersion : raise(other))
+  self['<='] = other => (versions[other] ? v1 <= versions[other].dataVersion : raise(other))
+  self['=='] = other => (versions[other] ? v1 === versions[other].dataVersion : raise(other))
   self.type = type
   self.majorVersion = suppliedVersion.majorVersion
   return self

package/src/mesher-shared/modelsGeometryCommon.test.ts

@@ -44,7 +44,12 @@ describe('buildElementRotation', () => {
 
   it('treats a rotation without any angle as no rotation', () => {
     const { localMatrix, localShift } = buildElementRotation({ origin })
-    localMatrix.forEach((row, i) => close(row, [0, 1, 2].map(j => (i === j ? 1 : 0))))
+    localMatrix.forEach((row, i) =>
+      close(
+        row,
+        [0, 1, 2].map(j => (i === j ? 1 : 0))
+      )
+    )
     close(localShift, [0, 0, 0])
   })
 })

package/src/mesher-shared/shared.ts

@@ -87,8 +87,53 @@ export type MesherGeometryOutput = {
   visibilitySet?: number
 }
 
+export type MeshGeometryMode = 'owner' | 'legacyBootstrap'
+
+export type MesherGeometryVersionFields = {
+  sessionEpoch?: number
+  columnIncarnation?: number
+  requestId?: number
+  topologyRevision?: number
+  lightPublicationVersion?: number
+  worldGeneration?: number
+  neighborTopologyRevisions?: Array<{ key: string; topologyRevision: number }>
+  meshMode?: MeshGeometryMode
+  clientLightRequestId?: number
+  clientLightEditSeq?: number
+  clientLightSessionEpoch?: number
+}
+
+export type MesherWorkerDirtyMessage = {
+  type: 'dirty'
+  x: number
+  y: number
+  z: number
+  value?: boolean
+  config?: MesherConfig
+} & MesherGeometryVersionFields
+
+export type MesherWorkerOwnerPublicationMessage = {
+  type: 'applyOwnerLightPublication'
+  worldGeneration: number
+  publicationVersion: number
+  sessionEpoch?: number
+  sections: Array<{ sx: number; sy: number; sz: number; blockLight: Uint8Array; skyLight?: Uint8Array }>
+}
+
+export type MesherWorkerRevertOwnerMessage = {
+  type: 'revertOwnerLightToIncoming'
+  sessionEpoch: number
+  worldGeneration: number
+}
+
+export type MesherWorkerOwnerFenceMessage = {
+  type: 'setOwnerAcceptFence'
+  sessionEpoch: number
+  rejectOwnerPublications: boolean
+}
+
 export interface MesherMainEvents {
-  geometry: { type: 'geometry'; key: string; geometry: MesherGeometryOutput; workerIndex: number }
+  geometry: { type: 'geometry'; key: string; geometry: MesherGeometryOutput; workerIndex: number } & MesherGeometryVersionFields
   sectionFinished: {
     type: 'sectionFinished'
     key: string
@@ -108,6 +153,8 @@ export interface MesherMainEvents {
     // Per-event counts for the column-mode conversion cache.
     preCacheHits?: number
     preCacheMisses?: number
+    preWasmParseHits?: number
+    preWasmParseMisses?: number
     chunkCount?: number
     worldColumns3x3?: number
     parsedCache3x3?: number

package/src/three/chunkMeshManager.ts

@@ -35,6 +35,7 @@ import { disposeObject } from './threeJsUtils'
 import { getBannerTexture, createBannerMesh, releaseBannerTexture } from './bannerRenderer'
 import { getSignTexture, releaseSignTexture, disposeAllSignTextures } from './signTextureCache'
 import { BlockEntityLightRegistry } from '../lib/blockEntityLightRegistry'
+import { isClientLightTraceEnabled, recordClientLightTraceGpuSample } from '../lighting/debug/clientLightTrace'
 import { SectionOcclusionCull, hsvToRgb } from './occlusion/sectionOcclusionCull'
 
 export interface ChunkMeshPool {
@@ -285,6 +286,15 @@ export class ChunkMeshManager {
     if (this.globalLegacyShaderMaterial) setLegacySkyLevel(this.globalLegacyShaderMaterial, value)
     if (this.globalLegacyBlendShaderMaterial) setLegacySkyLevel(this.globalLegacyBlendShaderMaterial, value)
     this.blockEntityLightRegistry.setSkyLevel(value)
+    this.worldRenderer.entityLightController?.setSkyLevel(value)
+  }
+
+  getSkyLevel(): number {
+    return this.blockEntityLightRegistry.getSkyLevel()
+  }
+
+  getLightmapParams(): BlockLightmapParams {
+    return this.blockEntityLightRegistry.getLightmapParams()
   }
 
   setShadingTheme(theme: 'vanilla' | 'high-contrast', cardinalLight: string): void {
@@ -300,6 +310,7 @@ export class ChunkMeshManager {
     if (this.globalLegacyShaderMaterial) setLegacyLightmapParams(this.globalLegacyShaderMaterial, params)
     if (this.globalLegacyBlendShaderMaterial) setLegacyLightmapParams(this.globalLegacyBlendShaderMaterial, params)
     this.blockEntityLightRegistry.setLightmapParams(params)
+    this.worldRenderer.entityLightController?.setLightmapParams(params)
   }
 
   private getLegacyShaderMaterial(): THREE.ShaderMaterial {
@@ -591,6 +602,21 @@ export class ChunkMeshManager {
       gb.setVisibleSpans(spans)
     }
 
+    if (isClientLightTraceEnabled()) {
+      const cubeFaces = gb?.getVisibleFaceCount() ?? 0
+      const legacyQuads = (opaqueBuf?.getVisibleQuadCount() ?? 0) + (blendBuf?.getVisibleQuadCount() ?? 0)
+      const drawableFaces = cubeFaces + legacyQuads
+      recordClientLightTraceGpuSample('gpuDrawn', drawableFaces, () => ({
+        phase: 'gpuDrawn',
+        drawableFaces,
+        pendingReplace: !!(gb?.hasPendingReplace() || opaqueBuf?.hasPendingReplace() || blendBuf?.hasPendingReplace()),
+        pendingMove: !!(gb?.getPendingMove() || opaqueBuf?.getPendingMove() || blendBuf?.getPendingMove()),
+        unuploadedRanges:
+          (gb?.getPendingDirtyRanges().length ?? 0) + (opaqueBuf?.getPendingDirtyRanges().length ?? 0) + (blendBuf?.getPendingDirtyRanges().length ?? 0),
+        cullReason: smartCull ? 'frustum+occlusion' : 'frustum'
+      }))
+    }
+
     this.lastBufferStateKey = this.bufferStateKey()
     this.updatePooledLegacyCullState(cameraWorldX, cameraWorldY, cameraWorldZ, smartCull, occlusionVisible)
   }

package/src/three/entities.ts

@@ -9,7 +9,6 @@ import { inferModelType, loadCapeToCanvas, loadEarsToCanvasFromSkin } from 'skin
 import { flat, fromFormattedString } from '@xmcl/text-component'
 import mojangson from 'mojangson'
 import { snakeCase } from 'change-case'
-import { Item } from 'prismarine-item'
 import { isEntityAttackable } from 'mineflayer-mouse/dist/attackableEntity'
 import { Team } from 'mineflayer'
 import PrismarineChatLoader from 'prismarine-chat'
@@ -34,6 +33,7 @@ import { releaseVehiclePassengerPosition } from './entity/vehiclePassengerRender
 import { updateVehiclePassengerPositions as applyVehiclePassengerPositions } from './entity/vehiclePassengerUpdate'
 import { applyNetworkHeadPitch, storeNetworkHeadPitch, storeNetworkHeadYaw } from './entity/networkHeadPitchRendering'
 import { processRemoteBoatPassengerRotations, type RemoteBoatPassengerEntity } from './entity/remoteBoatPassengerRotation'
+import { isClientLightTraceEnabled, recordClientLightTrace } from '../lighting/debug/clientLightTrace'
 import {
   ENTITY_TWEEN_DURATION_MS,
   applyLocalHorseCameraYawLock,
@@ -59,9 +59,11 @@ import {
   type HorseHeadRig
 } from './entity/horseHeadAnimation'
 import { WalkingGeneralSwing } from './entity/animations'
+import { LEG_ANIMATION_USER_DATA_KEY, LEG_RIG_USER_DATA_KEY, applyLegRig, createLegRig, type LegRig } from './entity/legWalkAnimation'
 import { disposeObject, loadNearestFilterTexture, loadTexture, loadThreeJsTextureFromUrl } from './threeJsUtils'
 import { armorModel, armorTextures, elytraTexture } from './entity/armorModels'
 import { WorldRendererThree } from './worldRendererThree'
+import type { EntityLightMeta } from '../lighting/entity/entityLightController'
 import { IndexedData } from 'minecraft-data'
 import { ItemSpecificContextProperties } from '../playerState/types'
 
@@ -380,6 +382,8 @@ function getEntityMesh(
   return cube
 }
 
+type EquipmentItem = import('prismarine-entity').Entity['equipment'][number]
+
 export type SceneEntity = THREE.Object3D & {
   playerObject?: PlayerObjectType
   username?: string
@@ -469,9 +473,12 @@ export class Entities {
     }
 
     this.updateEntityEquipment(this.playerEntity, playerData)
+    this.registerEntityLight(this.playerEntity, this.playerEntity.originalEntity)
+    this.invalidateEntityLight(this.playerEntity)
   }
 
   clear() {
+    this.worldRenderer.entityLightController?.clear()
     for (const mesh of Object.values(this.entities)) {
       this.worldRenderer.sceneOrigin.removeAndUntrack(mesh)
       disposeObject(mesh)
@@ -592,18 +599,27 @@ export class Entities {
 
       const horseHeadRig = entity.userData[HORSE_HEAD_RIG_USER_DATA_KEY] as HorseHeadRig | undefined
       const horseAnimation = entity.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] as HorseHeadAnimationState | undefined
+      let limbAnimation: ReturnType<typeof updateHorseHeadAnimationFrame> | undefined
       if (horseHeadRig && horseAnimation) {
-        const animation = updateHorseHeadAnimationFrame(horseAnimation, dt)
+        limbAnimation = updateHorseHeadAnimationFrame(horseAnimation, dt)
         const pose = calculateHorseHeadPose({
           entityPitch: entity.userData._horseHeadPitch ?? 0,
           headYaw: entity.userData._horseHeadYaw ?? entity.userData._horseBodyYaw ?? 0,
           bodyYaw: entity.userData._horseBodyYaw ?? 0,
-          limbSwing: animation.limbSwing,
-          limbSwingAmount: animation.limbSwingAmount
+          limbSwing: limbAnimation.limbSwing,
+          limbSwingAmount: limbAnimation.limbSwingAmount
         })
         applyHorseHeadPose(horseHeadRig, pose)
       }
 
+      const legRig = entity.userData[LEG_RIG_USER_DATA_KEY] as LegRig | undefined
+      const legAnimation = entity.userData[LEG_ANIMATION_USER_DATA_KEY] as HorseHeadAnimationState | undefined
+      if (legRig && legAnimation) {
+        // Horses share one state between head and legs, it must only be advanced once per frame.
+        limbAnimation ??= updateHorseHeadAnimationFrame(legAnimation, dt)
+        applyLegRig(legRig, limbAnimation.limbSwing, limbAnimation.limbSwingAmount)
+      }
+
       if (!isPlayerEntity && playerObject) {
         applyNetworkHeadPitch(playerObject, entity.userData)
       }
@@ -642,6 +658,7 @@ export class Entities {
     this.applyRemoteBoatPassengerRotations()
     this.applyLocalThirdPersonPlayerRotation()
     this.updateBoatPaddleAnimations(dt)
+    this.applyEntityLights()
   }
 
   private applyRemoteBoatPassengerRotations() {
@@ -1034,6 +1051,7 @@ export class Entities {
     if (!playerObject || !playerObject.playerObject?.animation) return
     const anim = playerObject.playerObject.animation as any
     if (anim.swingArm) {
+      if (isClientLightTraceEnabled()) recordClientLightTrace({ phase: 'inputHand' })
       anim.swingArm()
     }
   }
@@ -1046,6 +1064,7 @@ export class Entities {
     if (!anim) return
 
     if (animation === 'oneSwing') {
+      if (isClientLightTraceEnabled()) recordClientLightTrace({ phase: 'inputHand' })
       anim.swingArm()
       return
     }
@@ -1187,6 +1206,8 @@ export class Entities {
       e.userData._rotTween?.stop()
       e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] = undefined
       e.userData[HORSE_HEAD_RIG_USER_DATA_KEY] = undefined
+      e.userData[LEG_ANIMATION_USER_DATA_KEY] = undefined
+      e.userData[LEG_RIG_USER_DATA_KEY] = undefined
       const boatMesh = e.children.find(c => c.name === 'mesh')
       if (boatMesh) disposeBoatWaterPatch(boatMesh)
       if (e.additionalCleanup) e.additionalCleanup()
@@ -1194,6 +1215,7 @@ export class Entities {
         if (c['additionalCleanup']) c['additionalCleanup']()
       })
       this.onRemoveEntity(entity)
+      this.worldRenderer.entityLightController?.unregister(e)
       this.worldRenderer.sceneOrigin.removeAndUntrack(e)
       disposeObject(e)
       // todo dispose textures as well ?
@@ -1320,6 +1342,11 @@ export class Entities {
         e.userData[HORSE_HEAD_RIG_USER_DATA_KEY] = horseHeadRig
         e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] = createHorseHeadAnimationState()
       }
+      const legRig = isPlayerModel ? undefined : createLegRig(mesh, entity.name)
+      if (legRig) {
+        e.userData[LEG_RIG_USER_DATA_KEY] = legRig
+        e.userData[LEG_ANIMATION_USER_DATA_KEY] = e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] ?? createHorseHeadAnimationState()
+      }
     } else {
       mesh = e.children.find(c => c.name === 'mesh')
       if (entity.renderHints) {
@@ -1518,6 +1545,12 @@ export class Entities {
     this.updateNameTagVisibility(e)
 
     this.updateEntityPosition(entity, justAdded, overrides)
+    if (justAdded) {
+      this.registerEntityLight(e, entity)
+    } else {
+      this.worldRenderer.entityLightController?.setMeta(e, this.entityLightMeta(entity))
+      this.invalidateEntityLight(e)
+    }
   }
 
   applyEntityRenderHints(e: SceneEntity, entity: SceneEntity['originalEntity']) {
@@ -1596,7 +1629,7 @@ export class Entities {
           })
           .start()
       }
-      const horseAnimation = e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] as HorseHeadAnimationState | undefined
+      const horseAnimation = (e.userData[HORSE_HEAD_ANIMATION_USER_DATA_KEY] ?? e.userData[LEG_ANIMATION_USER_DATA_KEY]) as HorseHeadAnimationState | undefined
       if (!headRotationOnly && horseAnimation && Number.isFinite(entity.position.x) && Number.isFinite(entity.position.z)) {
         setHorseHeadAnimationPosition(horseAnimation, entity.position)
       }
@@ -1761,7 +1794,7 @@ export class Entities {
     return texture
   }
 
-  addItemModel(entityMesh: SceneEntity, hand: 'left' | 'right', item: Item, isPlayer = false) {
+  addItemModel(entityMesh: SceneEntity, hand: 'left' | 'right', item: EquipmentItem, isPlayer = false) {
     const bedrockParentName = `bone_${hand}item`
     const itemName = `custom_item_${hand}`
 
@@ -1814,8 +1847,52 @@ export class Entities {
     }
   }
 
+  onEntityMeshReady(mesh: THREE.Object3D) {
+    this.worldRenderer.entityLightController?.invalidateFromDescendant(mesh)
+  }
+
+  private entityLightSharedMaterials() {
+    return new Set<THREE.Material>([this.worldRenderer.material])
+  }
+
+  private entityLightMeta(entity: SceneEntity['originalEntity']): EntityLightMeta {
+    const localPlayerId = this.playerEntity?.originalEntity.id
+    const useLocalEyeHeight = entity.name === 'player' && localPlayerId !== undefined && entity.id === localPlayerId
+    return {
+      name: entity.name,
+      height: entity.height,
+      eyeHeight: useLocalEyeHeight ? this.worldRenderer.playerStateReactive.eyeHeight : undefined
+    }
+  }
+
+  private registerEntityLight(root: SceneEntity, entity: SceneEntity['originalEntity']) {
+    this.worldRenderer.entityLightController?.register(root, this.entityLightMeta(entity), this.entityLightSharedMaterials())
+  }
+
+  private invalidateEntityLight(root: THREE.Object3D) {
+    this.worldRenderer.entityLightController?.invalidateMaterials(root)
+  }
+
+  private applyEntityLights() {
+    const controller = this.worldRenderer.entityLightController
+    if (!controller) return
+    const shared = this.entityLightSharedMaterials()
+    const apply = (root: SceneEntity | null) => {
+      if (!root) return
+      if (root === this.playerEntity) {
+        controller.setMeta(root, this.entityLightMeta(root.originalEntity))
+      }
+      const worldPos = this.worldRenderer.sceneOrigin.getWorldPosition(root)
+      if (!worldPos) return
+      controller.update(root, worldPos, shared)
+    }
+    for (const entity of Object.values(this.entities)) apply(entity)
+    apply(this.playerEntity)
+  }
+
   handleDamageEvent(entityId, damageAmount) {
-    const entityMesh = this.entities[entityId]?.children.find(c => c.name === 'mesh')
+    const entity = this.entities[entityId]
+    const entityMesh = entity?.children.find(c => c.name === 'mesh')
     if (entityMesh) {
       entityMesh.traverse(child => {
         if (child instanceof THREE.Mesh && child.material.clone) {
@@ -1828,6 +1905,18 @@ export class Entities {
         }
       })
     }
+    if (entity) {
+      this.worldRenderer.entityLightController?.markFlash(entity)
+      this.invalidateEntityLight(entity)
+      setTimeout(() => {
+        if (!this.entities[entityId]) return
+        this.worldRenderer.entityLightController?.endFlash(entity)
+        const worldPos = this.worldRenderer.sceneOrigin.getWorldPosition(entity)
+        if (worldPos) {
+          this.worldRenderer.entityLightController?.update(entity, worldPos, this.entityLightSharedMaterials())
+        }
+      }, 500)
+    }
   }
 
   raycastSceneDebug() {
@@ -1921,7 +2010,7 @@ function getSpecificEntityMetadata<T extends keyof EntityMetadataVersions>(name:
   return getGeneralEntitiesMetadata(entity, mcData) as any
 }
 
-function addArmorModel(worldRenderer: WorldRendererThree, entityMesh: THREE.Object3D, slotType: string, item: Item, layer = 1, overlay = false) {
+function addArmorModel(worldRenderer: WorldRendererThree, entityMesh: THREE.Object3D, slotType: string, item: EquipmentItem, layer = 1, overlay = false) {
   if (!item) {
     removeArmorModel(entityMesh, slotType)
     return

package/src/three/entity/EntityMesh.ts

@@ -536,6 +536,7 @@ export class EntityMesh {
                     controller.playAnimation(gltf.animations[0].name, loop)
                   }
                 }
+                worldRenderer?.entities.onEntityMeshReady(this.mesh)
               })
               .catch(err => {
                 console.error('Failed to load GLTF model:', err)