minecraft-renderer 0.1.106 → 0.1.108

package/src/lighting/cache/rendererLightCache.test.ts

@@ -0,0 +1,158 @@
+//@ts-nocheck
+import { describe, expect, it } from 'vitest'
+import Chunks from 'prismarine-chunk'
+import MinecraftData from 'minecraft-data'
+import { Vec3 } from 'vec3'
+import { RENDERER_LIGHT_BYTES_PER_SECTION, RendererLightCache } from './rendererLightCache'
+
+const VERSION = '1.16.5'
+
+function makeChunk() {
+  const Chunk = Chunks(VERSION) as any
+  return new Chunk(undefined as any)
+}
+
+function makePresentZeroSection(y = 64) {
+  const mcData = MinecraftData(VERSION)
+  const chunk = makeChunk()
+  const stoneId = mcData.blocksByName.stone.defaultState
+  chunk.setBlockStateId(new Vec3(8, y, 8), stoneId)
+  // Allocate light sections, then zero them. All-zero light is otherwise omitted
+  // and must stay the fullbright "absent section" fallback.
+  chunk.setBlockLight(new Vec3(8, y, 8), 1)
+  chunk.setSkyLight(new Vec3(8, y, 8), 1)
+  chunk.setBlockLight(new Vec3(8, y, 8), 0)
+  chunk.setSkyLight(new Vec3(8, y, 8), 0)
+  return chunk
+}
+
+function makeLitBlock(blockLight: number, skyLight: number, x = 8, y = 64, z = 8) {
+  const mcData = MinecraftData(VERSION)
+  const chunk = makeChunk()
+  const stoneId = mcData.blocksByName.stone.defaultState
+  chunk.setBlockStateId(new Vec3(x, y, z), stoneId)
+  chunk.setBlockLight(new Vec3(x, y, z), blockLight)
+  chunk.setSkyLight(new Vec3(x, y, z), skyLight)
+  return chunk
+}
+
+describe('RendererLightCache', () => {
+  it('returns fullbright for a missing column or absent section', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    expect(cache.getLight(8, 64, 8)).toEqual({ block: 0, sky: 1 })
+
+    cache.ingestColumn(0, 0, makeChunk().toJson())
+    expect(cache.getLight(8, 64, 8)).toEqual({ block: 0, sky: 1 })
+  })
+
+  it('applies +2 floor for a present raw-zero section and clamps at 15', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    cache.ingestColumn(0, 0, makePresentZeroSection().toJson())
+    expect(cache.getLight(8, 64, 8).block).toBeCloseTo(2 / 15, 5)
+    expect(cache.getLight(8, 64, 8).sky).toBeCloseTo(2 / 15, 5)
+
+    cache.ingestColumn(0, 0, makeLitBlock(14, 14).toJson())
+    expect(cache.getLight(8, 64, 8)).toEqual({ block: 1, sky: 1 })
+  })
+
+  it('reads packed channels at negative chunk coordinates', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    cache.ingestColumn(-16, -16, makeLitBlock(13, 4, 15, 64, 15).toJson())
+    const light = cache.getLight(-1, 64, -1)
+    expect(light.block).toBeCloseTo(15 / 15, 5)
+    expect(light.sky).toBeCloseTo(6 / 15, 5)
+  })
+
+  it('does not bump column revision on identical re-ingest', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    const json = makeLitBlock(10, 5).toJson()
+    const first = cache.ingestColumn(0, 0, json)
+    const second = cache.ingestColumn(0, 0, json)
+    expect(first.changed).toBe(true)
+    expect(second.changed).toBe(false)
+    expect(second.revision).toBe(first.revision)
+    expect(cache.getColumnRevision(0, 0)).toBe(first.revision)
+  })
+
+  it('bumps revision when light changes and forgets removed columns', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    const first = cache.ingestColumn(0, 0, makeLitBlock(3, 0).toJson())
+    const second = cache.ingestColumn(0, 0, makeLitBlock(12, 0).toJson())
+    expect(second.changed).toBe(true)
+    expect(second.revision).toBeGreaterThan(first.revision)
+    expect(cache.getLight(8, 64, 8).block).toBeCloseTo(14 / 15, 5)
+
+    const globalBefore = cache.getGlobalRevision()
+    cache.removeColumn(0, 0)
+    expect(cache.getLight(8, 64, 8)).toEqual({ block: 0, sky: 1 })
+    expect(cache.getGlobalRevision()).toBe(globalBefore)
+    expect(cache.getAllocatedSectionCount()).toBe(0)
+  })
+
+  it('does not bump global revision on ingest of another column', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    cache.ingestColumn(0, 0, makeLitBlock(3, 0).toJson())
+    const globalBefore = cache.getGlobalRevision()
+    cache.ingestColumn(16, 0, makeLitBlock(12, 0).toJson())
+    expect(cache.getGlobalRevision()).toBe(globalBefore)
+    expect(cache.getColumnRevision(16, 0)).toBeGreaterThan(0)
+  })
+
+  it('keeps prior column state when ingest fails', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    const ok = cache.ingestColumn(0, 0, makeLitBlock(8, 0).toJson())
+    const failed = cache.ingestColumn(0, 0, { not: 'a-chunk' })
+    expect(failed.changed).toBe(false)
+    expect(failed.revision).toBe(ok.revision)
+    expect(cache.getLight(8, 64, 8).block).toBeCloseTo(10 / 15, 5)
+  })
+
+  it('clear and bounds change drop light and bump the global revision', () => {
+    const cache = new RendererLightCache(VERSION)
+    cache.setWorldBounds(0, 256)
+    cache.ingestColumn(16, 32, makeLitBlock(15, 15).toJson())
+    expect(cache.getAllocatedBytes()).toBeGreaterThanOrEqual(RENDERER_LIGHT_BYTES_PER_SECTION)
+    const globalBefore = cache.getGlobalRevision()
+    cache.clear()
+    expect(cache.getLight(24, 64, 40)).toEqual({ block: 0, sky: 1 })
+    expect(cache.getGlobalRevision()).toBeGreaterThan(globalBefore)
+  })
+})
+
+describe('RendererLightCache 1.18+', () => {
+  const VERSION_118 = '1.18.2'
+  const MIN_Y = -64
+  const WORLD_HEIGHT = 384
+
+  function make118Chunk() {
+    const Chunk = Chunks(VERSION_118) as any
+    return new Chunk({ minY: MIN_Y, worldHeight: WORLD_HEIGHT })
+  }
+
+  function make118LitBlock(blockLight: number, skyLight: number, x = 8, y = -60, z = 8) {
+    const mcData = MinecraftData(VERSION_118)
+    const chunk = make118Chunk()
+    const stoneId = mcData.blocksByName.stone.defaultState
+    chunk.setBlockStateId(new Vec3(x, y, z), stoneId)
+    chunk.setBlockLight(new Vec3(x, y, z), blockLight)
+    chunk.setSkyLight(new Vec3(x, y, z), skyLight)
+    return chunk
+  }
+
+  it('packs and reads light in a negative-Y section', () => {
+    const cache = new RendererLightCache(VERSION_118)
+    cache.setWorldBounds(MIN_Y, WORLD_HEIGHT)
+    cache.ingestColumn(0, 0, make118LitBlock(11, 3).toJson())
+    const light = cache.getLight(8, -60, 8)
+    expect(light.block).toBeCloseTo(13 / 15, 5)
+    expect(light.sky).toBeCloseTo(5 / 15, 5)
+    expect(cache.getLight(8, -64, 8).block).toBeGreaterThan(0)
+  })
+})

package/src/lighting/cache/rendererLightCache.ts

@@ -0,0 +1,248 @@
+//@ts-nocheck
+import Chunks from 'prismarine-chunk'
+import { Vec3 } from 'vec3'
+
+/** 16³ blocks, one packed byte (block<<4 | sky) per block. */
+export const RENDERER_LIGHT_BYTES_PER_SECTION = 4096
+
+const FULLBRIGHT = { block: 0, sky: 1 } as const
+
+const sectionKey = (sx: number, sy: number, sz: number) => `${sx},${sy},${sz}`
+const columnKey = (sx: number, sz: number) => `${sx},${sz}`
+const alignSection = (coord: number) => Math.floor(coord / 16) * 16
+const localCoord = (coord: number) => ((coord % 16) + 16) % 16
+const blockIndex = (lx: number, ly: number, lz: number) => lx + lz * 16 + ly * 256
+
+const channelNorm = (raw: number) => Math.min(15, raw + 2) / 15
+
+const getLightSectionIndex = (y: number, minY = 0) => Math.floor((y - minY) / 16) + 1
+
+const hasChunkSection = (column: any, pos: Vec3) => {
+  if (column._getSection) return column._getSection(pos)
+  if (column.skyLightSections) {
+    return column.skyLightSections[getLightSectionIndex(pos.y, column.minY)] || column.blockLightSections[getLightSectionIndex(pos.y, column.minY)]
+  }
+  if (column.sections) return column.sections[pos.y >> 4]
+  return false
+}
+
+const unpackNibble = (packed: Uint8Array, lx: number, ly: number, lz: number) => {
+  const local = (ly << 8) | (lz << 4) | lx
+  const byte = packed[local >> 1] ?? 0
+  return local & 1 ? byte >> 4 : byte & 0x0f
+}
+
+const hashBytes = (sections: Map<string, Uint8Array>) => {
+  let hash = 2166136261
+  const keys = [...sections.keys()].sort()
+  for (const key of keys) {
+    const data = sections.get(key)!
+    for (let i = 0; i < key.length; i++) {
+      hash ^= key.charCodeAt(i)
+      hash = Math.imul(hash, 16777619)
+    }
+    for (let i = 0; i < data.length; i++) {
+      hash ^= data[i]!
+      hash = Math.imul(hash, 16777619)
+    }
+  }
+  return hash >>> 0
+}
+
+type LightChunk = {
+  getBlockLight: (pos: Vec3) => number
+  getSkyLight: (pos: Vec3) => number
+  minY?: number
+  _getSection?: (pos: Vec3) => unknown
+  skyLightSections?: unknown[]
+  blockLightSections?: unknown[]
+  sections?: unknown
+}
+
+export type RendererLightSample = { block: number; sky: number }
+
+export type RendererLightIngestResult = { changed: boolean; revision: number }
+
+/**
+ * Main-thread packed block/sky light for entity sampling.
+ * Absent sections stay fullbright; present raw-zero gets the project +2 floor.
+ */
+export class RendererLightCache {
+  private readonly sections = new Map<string, Uint8Array>()
+  private readonly columnHashes = new Map<string, number>()
+  private readonly columnRevisions = new Map<string, number>()
+  private Chunk: ReturnType<typeof Chunks>
+  private worldMinY = 0
+  private worldMaxY = 256
+  private globalRevision = 0
+  private nextColumnRevision = 1
+
+  constructor(version: string) {
+    this.Chunk = Chunks(version) as ReturnType<typeof Chunks>
+  }
+
+  setVersion(version: string) {
+    this.Chunk = Chunks(version) as ReturnType<typeof Chunks>
+    this.clear()
+  }
+
+  setWorldBounds(minY: number, worldHeight: number) {
+    if (this.worldMinY === minY && this.worldMaxY === worldHeight) return
+    this.worldMinY = minY
+    this.worldMaxY = worldHeight
+    this.clear()
+  }
+
+  clear() {
+    if (this.sections.size === 0 && this.columnRevisions.size === 0) {
+      this.globalRevision++
+      return
+    }
+    this.sections.clear()
+    this.columnHashes.clear()
+    this.columnRevisions.clear()
+    this.globalRevision++
+  }
+
+  getAllocatedSectionCount(): number {
+    return this.sections.size
+  }
+
+  getAllocatedBytes(): number {
+    return this.sections.size * RENDERER_LIGHT_BYTES_PER_SECTION
+  }
+
+  getGlobalRevision(): number {
+    return this.globalRevision
+  }
+
+  getColumnRevision(chunkX: number, chunkZ: number): number | undefined {
+    return this.columnRevisions.get(columnKey(alignSection(chunkX), alignSection(chunkZ)))
+  }
+
+  removeColumn(chunkX: number, chunkZ: number) {
+    const sx = alignSection(chunkX)
+    const sz = alignSection(chunkZ)
+    const col = columnKey(sx, sz)
+    const syStart = alignSection(this.worldMinY)
+    for (let sy = syStart; sy < this.worldMaxY; sy += 16) {
+      this.sections.delete(sectionKey(sx, sy, sz))
+    }
+    this.columnHashes.delete(col)
+    this.columnRevisions.delete(col)
+  }
+
+  /**
+   * Direct publication write: packed 2048-byte nibble channels.
+   * Block-only sections keep the current sky nibble; missing sky is 0, never 15.
+   * `sx/sy/sz` are world-aligned section origins.
+   */
+  ingestPackedSections(sections: Array<{ sx: number; sy: number; sz: number; blockLight: Uint8Array; skyLight?: Uint8Array }>): RendererLightIngestResult {
+    const touchedColumns = new Set<string>()
+    for (const section of sections) {
+      const sx = alignSection(section.sx)
+      const sy = alignSection(section.sy)
+      const sz = alignSection(section.sz)
+      if (section.blockLight.length !== 2048) continue
+      if (section.skyLight && section.skyLight.length !== 2048) continue
+      const key = sectionKey(sx, sy, sz)
+      const prev = this.sections.get(key)
+      const data = prev ? new Uint8Array(prev) : new Uint8Array(RENDERER_LIGHT_BYTES_PER_SECTION)
+      for (let ly = 0; ly < 16; ly++) {
+        for (let lz = 0; lz < 16; lz++) {
+          for (let lx = 0; lx < 16; lx++) {
+            const idx = blockIndex(lx, ly, lz)
+            const block = unpackNibble(section.blockLight, lx, ly, lz)
+            const sky = section.skyLight ? unpackNibble(section.skyLight, lx, ly, lz) : data[idx]! & 0x0f
+            data[idx] = (block << 4) | sky
+          }
+        }
+      }
+      this.sections.set(key, data)
+      touchedColumns.add(columnKey(sx, sz))
+    }
+
+    let revision = 0
+    for (const col of touchedColumns) {
+      revision = this.nextColumnRevision++
+      this.columnRevisions.set(col, revision)
+      const packed = new Map<string, Uint8Array>()
+      for (const [key, data] of this.sections) {
+        const [colSx, , colSz] = key.split(',').map(Number)
+        if (`${colSx},${colSz}` === col) packed.set(key, data)
+      }
+      this.columnHashes.set(col, hashBytes(packed))
+    }
+    return { changed: touchedColumns.size > 0, revision }
+  }
+
+  ingestColumn(chunkX: number, chunkZ: number, chunkJson: unknown): RendererLightIngestResult {
+    const sx = alignSection(chunkX)
+    const sz = alignSection(chunkZ)
+    const col = columnKey(sx, sz)
+    const previousRevision = this.columnRevisions.get(col) ?? 0
+
+    let chunk: LightChunk
+    try {
+      chunk = this.Chunk.fromJson(chunkJson as Parameters<ReturnType<typeof Chunks>['fromJson']>[0]) as unknown as LightChunk
+      if (typeof chunk?.getBlockLight !== 'function' || typeof chunk?.getSkyLight !== 'function') {
+        throw new Error('invalid chunk light API')
+      }
+    } catch {
+      return { changed: false, revision: previousRevision }
+    }
+
+    const packed = new Map<string, Uint8Array>()
+    const pos = new Vec3(0, 0, 0)
+    const syStart = alignSection(this.worldMinY)
+    for (let sy = syStart; sy < this.worldMaxY; sy += 16) {
+      pos.set(0, sy, 0)
+      if (!hasChunkSection(chunk, pos)) continue
+      const data = new Uint8Array(RENDERER_LIGHT_BYTES_PER_SECTION)
+      for (let ly = 0; ly < 16; ly++) {
+        pos.y = sy + ly
+        for (let lz = 0; lz < 16; lz++) {
+          pos.z = lz
+          for (let lx = 0; lx < 16; lx++) {
+            pos.x = lx
+            const block = Math.max(0, Math.min(15, chunk.getBlockLight(pos) | 0))
+            const sky = Math.max(0, Math.min(15, chunk.getSkyLight(pos) | 0))
+            data[blockIndex(lx, ly, lz)] = (block << 4) | sky
+          }
+        }
+      }
+      packed.set(sectionKey(sx, sy, sz), data)
+    }
+
+    const hash = hashBytes(packed)
+    if (this.columnHashes.get(col) === hash && this.columnRevisions.has(col)) {
+      return { changed: false, revision: previousRevision }
+    }
+
+    const syStartRemove = alignSection(this.worldMinY)
+    for (let sy = syStartRemove; sy < this.worldMaxY; sy += 16) {
+      this.sections.delete(sectionKey(sx, sy, sz))
+    }
+    for (const [key, data] of packed) {
+      this.sections.set(key, data)
+    }
+    this.columnHashes.set(col, hash)
+    const revision = this.nextColumnRevision++
+    this.columnRevisions.set(col, revision)
+    return { changed: true, revision }
+  }
+
+  getLight(x: number, y: number, z: number): RendererLightSample {
+    if (y < this.worldMinY || y >= this.worldMaxY) return { ...FULLBRIGHT }
+    const sx = alignSection(x)
+    const sy = alignSection(y)
+    const sz = alignSection(z)
+    const data = this.sections.get(sectionKey(sx, sy, sz))
+    if (!data) return { ...FULLBRIGHT }
+    const packed = data[blockIndex(localCoord(x), y - sy, localCoord(z))] ?? 0
+    return {
+      block: channelNorm(packed >> 4),
+      sky: channelNorm(packed & 0x0f)
+    }
+  }
+}

package/src/lighting/coordinator/clientLightCoordinator.test.ts

@@ -0,0 +1,102 @@
+//@ts-nocheck
+import { describe, expect, test, vi } from 'vitest'
+import { Vec3 } from 'vec3'
+import { defaultWorldRendererConfig } from '../../graphicsBackend/config'
+import { ClientLightCoordinator, type ClientLightHost } from './clientLightCoordinator'
+
+function createHost(overrides: Partial<ClientLightHost> = {}) {
+  const dispatched: Array<{ pos: Vec3; value: boolean; useChangeWorker: boolean }> = []
+  const host: ClientLightHost = {
+    version: '1.17.1',
+    workers: [],
+    rendererLightCache: {} as ClientLightHost['rendererLightCache'],
+    worldRendererConfig: { ...defaultWorldRendererConfig },
+    worldSizeParams: { minY: 0, worldHeight: 256 },
+    playerStateReactive: {} as ClientLightHost['playerStateReactive'],
+    sectionsWaiting: new Map(),
+    loadedChunks: {},
+    sectionDirtyLightMeta: new Map(),
+    getSectionHeight: () => 16,
+    getWorkerNumber: () => 0,
+    setSectionDirty: vi.fn(),
+    dispatchDirtyImmediate: (pos, value, useChangeWorker) => dispatched.push({ pos, value, useChangeWorker }),
+    createLightOwnerWorker: vi.fn(),
+    ...overrides
+  }
+  return { host, dispatched, coordinator: new ClientLightCoordinator(host) }
+}
+
+describe('ClientLightCoordinator', () => {
+  test('stays inert and accepts geometry while the owner is disabled', () => {
+    const { coordinator } = createHost()
+    coordinator.maybeSpawn()
+    expect(coordinator.isSessionLive()).toBe(false)
+    expect(coordinator.hasOwner()).toBe(false)
+    expect(coordinator.evaluateOwnerGeometry({ type: 'geometry', key: '0,64,0' })).toEqual({ accepted: true, keepCovering: false })
+  })
+
+  test('explains why the owner did not start when the version gate refuses it', () => {
+    const { coordinator } = createHost({ version: '1.20.4', worldRendererConfig: { ...defaultWorldRendererConfig, enableClientLightOwner: true } })
+    coordinator.maybeSpawn()
+    expect(coordinator.isSessionLive()).toBe(false)
+    expect(coordinator.getFailureReason()).toContain('1.17.1')
+  })
+
+  test('a block change bumps the touched section and an edge neighbour, and tracks the edit', () => {
+    const { coordinator } = createHost()
+    coordinator.noteBlockChange(new Vec3(0, 64, 5), 1, true)
+    expect(coordinator.topologyRevisionBySection.has('0,64,0')).toBe(true)
+    expect(coordinator.topologyRevisionBySection.has('-16,64,0')).toBe(true)
+    expect(coordinator.topologyRevisionBySection.has('16,64,0')).toBe(false)
+    expect(coordinator.interactiveSections.has('0,64,0')).toBe(true)
+    // neighbours of an interactive section count as interactive work too
+    expect(coordinator.sectionTouchesInteractiveWork('16,64,0')).toBe(true)
+    expect(coordinator.sectionTouchesInteractiveWork('48,64,0')).toBe(false)
+  })
+
+  test('neighbour topology is not bumped when neighbour updates are off', () => {
+    const { coordinator } = createHost()
+    coordinator.noteBlockChange(new Vec3(0, 64, 5), 1, false)
+    expect([...coordinator.topologyRevisionBySection.keys()]).toEqual(['0,64,0'])
+  })
+
+  test('removing a column bumps its incarnation and forgets only that column', () => {
+    const { coordinator } = createHost()
+    coordinator.topologyRevisionBySection.set('0,64,0', 3)
+    coordinator.topologyRevisionBySection.set('16,64,0', 3)
+    coordinator.pendingCoveringBySection.set('0,32,0', { requiredVersion: 1, worldGeneration: 1 })
+    coordinator.pendingTopologyBySection.set('0,32,0', 2)
+    coordinator.rejectedFinishedBySection.set('0,32,0', 1)
+    const before = coordinator.columnIncarnationFor('0,0')
+
+    coordinator.onColumnRemoved(0, 0)
+
+    expect(coordinator.columnIncarnationFor('0,0')).toBe(before + 1)
+    expect(coordinator.columnIncarnationFor('16,0')).toBe(1)
+    expect([...coordinator.topologyRevisionBySection.keys()]).toEqual(['16,64,0'])
+    expect(coordinator.pendingCoveringBySection.size).toBe(0)
+    expect(coordinator.pendingTopologyBySection.size).toBe(0)
+    expect(coordinator.rejectedFinishedBySection.size).toBe(0)
+  })
+
+  test('rejected finishes are consumed one by one', () => {
+    const { coordinator } = createHost()
+    coordinator.noteRejectedOwnerGeometry('0,64,0', undefined, { expectLaterFinished: true })
+    coordinator.noteRejectedOwnerGeometry('0,64,0', undefined, { expectLaterFinished: true })
+    expect(coordinator.consumeRejectedFinish('0,64,0')).toBe(true)
+    expect(coordinator.consumeRejectedFinish('0,64,0')).toBe(true)
+    expect(coordinator.consumeRejectedFinish('0,64,0')).toBe(false)
+  })
+
+  test('dirty stamps carry no owner versions while the owner is off, and urgency is restored', () => {
+    const { coordinator } = createHost()
+    const { lightMeta, ownerVersions, traceIds } = coordinator.describeDirty(new Vec3(0, 64, 0), '0,64,0')
+    expect(lightMeta).toBeUndefined()
+    expect(ownerVersions).toEqual({})
+    expect(traceIds).toBeUndefined()
+
+    coordinator.nextDirtyUrgent = true
+    coordinator.withDirtyUrgency(false, () => expect(coordinator.nextDirtyUrgent).toBe(false))
+    expect(coordinator.nextDirtyUrgent).toBe(true)
+  })
+})