minecraft-renderer 0.1.106 → 0.1.108

package/src/lighting/debug/clientLightTrace.test.ts

@@ -0,0 +1,271 @@
+//@ts-nocheck
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import {
+  CLIENT_LIGHT_TRACE_BATCH_MS,
+  CLIENT_LIGHT_TRACE_BATCH_SIZE,
+  CLIENT_LIGHT_TRACE_CAPACITY,
+  armClientLightTrace,
+  bumpClientLightTraceSessionEpoch,
+  clearClientLightTrace,
+  comparableNow,
+  dumpClientLightTrace,
+  enableClientLightTrace,
+  flushClientLightTracePosts,
+  getClientLightTraceAggregates,
+  getClientLightTraceEvents,
+  ingestRemoteClientLightTrace,
+  ingestRemoteClientLightTraceMessage,
+  isClientLightTraceArmed,
+  isClientLightTraceEnabled,
+  isClientLightTraceMessage,
+  maybeEnableClientLightTraceFromLocation,
+  nextClientLightEditSeq,
+  nextClientLightRequestId,
+  postClientLightTrace,
+  recordClientLightTrace,
+  recordClientLightTraceGpuSample,
+  requestClientLightTraceSample
+} from './clientLightTrace'
+
+afterEach(() => {
+  flushClientLightTracePosts()
+  enableClientLightTrace(false)
+  clearClientLightTrace()
+  vi.useRealTimers()
+})
+
+test('clientLightTrace is disabled by default and drops records', () => {
+  expect(isClientLightTraceEnabled()).toBe(false)
+  recordClientLightTrace({ phase: 'blockChange', sectionKey: '0,64,0' })
+  expect(getClientLightTraceEvents()).toEqual([])
+})
+
+test('clientLightTrace stores metadata-only events in a bounded ring when enabled', () => {
+  enableClientLightTrace(true)
+  const first = recordClientLightTrace({
+    phase: 'blockChange',
+    sectionKey: '0,64,0',
+    blockVersion: 3,
+    lightVersion: 7
+  })
+  expect(first).toBeDefined()
+  expect(first!.t).toBeGreaterThan(0)
+  expect(first!.timeOrigin).toBe(performance.timeOrigin)
+  expect(first!.t).toBe(first!.timeOrigin + first!.tLocal)
+  const events = getClientLightTraceEvents()
+  expect(events).toHaveLength(1)
+  expect(events[0]!.phase).toBe('blockChange')
+  expect(events[0]!.sectionKey).toBe('0,64,0')
+  expect(JSON.stringify(events[0])).not.toMatch(/positions|indices|shaderCubes|chunkJson/)
+})
+
+test('clientLightTrace wraps at capacity and keeps the newest events', () => {
+  enableClientLightTrace(true)
+  for (let i = 0; i < CLIENT_LIGHT_TRACE_CAPACITY + 5; i++) {
+    recordClientLightTrace({ phase: 'mesherEnqueue', requestId: i })
+  }
+  const events = getClientLightTraceEvents()
+  expect(events).toHaveLength(CLIENT_LIGHT_TRACE_CAPACITY)
+  expect(events[0]!.requestId).toBe(5)
+  expect(events[events.length - 1]!.requestId).toBe(CLIENT_LIGHT_TRACE_CAPACITY + 4)
+})
+
+test('clientLightTrace comparableNow is timeOrigin plus local now', () => {
+  const before = performance.timeOrigin + performance.now()
+  const stamped = comparableNow()
+  const after = performance.timeOrigin + performance.now()
+  expect(stamped).toBeGreaterThanOrEqual(before)
+  expect(stamped).toBeLessThanOrEqual(after)
+})
+
+test('clientLightTrace increments sessionEpoch, editSeq and requestId', () => {
+  enableClientLightTrace(true)
+  const epoch0 = bumpClientLightTraceSessionEpoch()
+  const epoch1 = bumpClientLightTraceSessionEpoch()
+  expect(epoch1).toBe(epoch0 + 1)
+  const editA = nextClientLightEditSeq()
+  const editB = nextClientLightEditSeq()
+  expect(editB).toBe(editA + 1)
+  const reqA = nextClientLightRequestId()
+  const reqB = nextClientLightRequestId()
+  expect(reqB).toBe(reqA + 1)
+  recordClientLightTrace({
+    phase: 'ownerEnqueue',
+    sessionEpoch: epoch1,
+    editSeq: editB,
+    requestId: reqB
+  })
+  expect(getClientLightTraceEvents()[0]).toMatchObject({
+    sessionEpoch: epoch1,
+    editSeq: editB,
+    requestId: reqB
+  })
+})
+
+test('clientLightTrace remote ingest keeps the worker timestamp', () => {
+  enableClientLightTrace(true)
+  const remoteT = 1_700_000_000_000.5
+  ingestRemoteClientLightTrace({
+    phase: 'mesherStart',
+    t: remoteT,
+    tLocal: 12,
+    timeOrigin: remoteT - 12,
+    sectionKey: '16,64,16',
+    requestId: 9
+  })
+  expect(getClientLightTraceEvents()[0]).toMatchObject({
+    phase: 'mesherStart',
+    t: remoteT,
+    requestId: 9
+  })
+})
+
+test('clientLightTrace remote ingest is a no-op while disabled', () => {
+  ingestRemoteClientLightTrace({
+    phase: 'mesherEnd',
+    t: 1,
+    tLocal: 1,
+    timeOrigin: 0
+  })
+  expect(getClientLightTraceEvents()).toEqual([])
+})
+
+test('clientLightTrace aggregates counts by phase without storing meshes', () => {
+  enableClientLightTrace(true)
+  recordClientLightTrace({ phase: 'gpuDrawn', drawableFaces: 8000, cullReason: 'frustum' })
+  recordClientLightTrace({ phase: 'gpuDrawn', drawableFaces: 8000, cullReason: 'occlusion' })
+  recordClientLightTrace({ phase: 'reject', sectionKey: '0,64,0' })
+  const agg = getClientLightTraceAggregates()
+  expect(agg.byPhase.gpuDrawn).toBe(2)
+  expect(agg.byPhase.reject).toBe(1)
+  expect(agg.count).toBe(3)
+  expect(agg.dropped).toBe(0)
+})
+
+describe('clientLightTrace enable from location search', () => {
+  test('maybeEnableClientLightTraceFromLocation stays off without the query', () => {
+    maybeEnableClientLightTraceFromLocation({ search: '?clientLight=1' })
+    expect(isClientLightTraceEnabled()).toBe(false)
+  })
+
+  test('maybeEnableClientLightTraceFromLocation turns on with clientLightTrace=1', () => {
+    maybeEnableClientLightTraceFromLocation({ search: '?clientLight=1&clientLightTrace=1' })
+    expect(isClientLightTraceEnabled()).toBe(true)
+    expect(isClientLightTraceArmed()).toBe(false)
+  })
+})
+
+describe('clientLightTrace arm window', () => {
+  test('stays disarmed when enabled', () => {
+    enableClientLightTrace(true)
+    expect(isClientLightTraceEnabled()).toBe(true)
+    expect(isClientLightTraceArmed()).toBe(false)
+  })
+
+  test('exposes arm and dump on the window host when enabled', () => {
+    enableClientLightTrace(true)
+    const host = globalThis as typeof globalThis & {
+      clientLightTraceArm?: (on?: boolean) => void
+      clientLightTraceDump?: () => unknown
+    }
+    expect(typeof host.clientLightTraceArm).toBe('function')
+    expect(typeof host.clientLightTraceDump).toBe('function')
+    host.clientLightTraceArm?.()
+    expect(isClientLightTraceArmed()).toBe(true)
+    recordClientLightTrace({ phase: 'blockChange', sectionKey: '0,64,0' })
+    const dumped = host.clientLightTraceDump?.() as { events: unknown[]; aggregates: { count: number } }
+    expect(dumped.events).toHaveLength(1)
+    expect(dumped.aggregates.count).toBe(1)
+  })
+
+  test('disabling also disarms', () => {
+    enableClientLightTrace(true)
+    armClientLightTrace(true)
+    enableClientLightTrace(false)
+    expect(isClientLightTraceArmed()).toBe(false)
+  })
+})
+
+describe('clientLightTrace worker post batching', () => {
+  test('bulk events without arm send zero inter-thread messages', () => {
+    enableClientLightTrace(true)
+    const posts: unknown[] = []
+    for (let i = 0; i < 50; i++) {
+      postClientLightTrace(message => posts.push(message), { phase: 'mesherEnqueue', requestId: i })
+    }
+    flushClientLightTracePosts()
+    expect(posts).toEqual([])
+    expect(getClientLightTraceEvents()).toHaveLength(50)
+  })
+
+  test('armed posts batch so messages are far fewer than events and every event is delivered', () => {
+    vi.useFakeTimers()
+    enableClientLightTrace(true)
+    armClientLightTrace(true)
+    const posts: Array<{ type?: string; events?: Array<{ requestId?: number }> }> = []
+    const eventCount = 50
+    for (let i = 0; i < eventCount; i++) {
+      postClientLightTrace(message => posts.push(message), { phase: 'mesherEnqueue', requestId: i })
+    }
+    expect(posts).toEqual([])
+    vi.advanceTimersByTime(CLIENT_LIGHT_TRACE_BATCH_MS)
+    expect(posts).toHaveLength(1)
+    expect(posts[0]!.events).toHaveLength(eventCount)
+    expect(posts[0]!.events!.map(event => event.requestId)).toEqual([...Array(eventCount).keys()])
+    expect(isClientLightTraceMessage(posts[0])).toBe(true)
+
+    enableClientLightTrace(false)
+    clearClientLightTrace()
+    enableClientLightTrace(true)
+    for (const post of posts) ingestRemoteClientLightTraceMessage(post)
+    expect(getClientLightTraceEvents()).toHaveLength(eventCount)
+  })
+
+  test('armed posts flush immediately at the batch size', () => {
+    enableClientLightTrace(true)
+    armClientLightTrace(true)
+    const posts: Array<{ events?: unknown[] }> = []
+    for (let i = 0; i < CLIENT_LIGHT_TRACE_BATCH_SIZE + 3; i++) {
+      postClientLightTrace(message => posts.push(message), { phase: 'ownerAdmit', requestId: i })
+    }
+    expect(posts).toHaveLength(1)
+    expect(posts[0]!.events).toHaveLength(CLIENT_LIGHT_TRACE_BATCH_SIZE)
+    flushClientLightTracePosts()
+    expect(posts).toHaveLength(2)
+    expect(posts[1]!.events).toHaveLength(3)
+  })
+})
+
+describe('clientLightTrace gpu sampling', () => {
+  test('1000 unchanged gpuDrawn frames record at most one event until a sample is requested', () => {
+    enableClientLightTrace(true)
+    for (let i = 0; i < 1000; i++) {
+      recordClientLightTraceGpuSample('gpuDrawn', 8000, { phase: 'gpuDrawn', drawableFaces: 8000 })
+    }
+    expect(getClientLightTraceEvents().filter(event => event.phase === 'gpuDrawn')).toHaveLength(1)
+    requestClientLightTraceSample()
+    recordClientLightTraceGpuSample('gpuDrawn', 8000, { phase: 'gpuDrawn', drawableFaces: 8000 })
+    expect(getClientLightTraceEvents().filter(event => event.phase === 'gpuDrawn')).toHaveLength(2)
+    recordClientLightTraceGpuSample('gpuDrawn', 9000, { phase: 'gpuDrawn', drawableFaces: 9000 })
+    expect(getClientLightTraceEvents().filter(event => event.phase === 'gpuDrawn')).toHaveLength(3)
+  })
+
+  test('gpuUploaded records only when the sampled metric changes', () => {
+    enableClientLightTrace(true)
+    recordClientLightTraceGpuSample('gpuUploaded', 128, { phase: 'gpuUploaded', unuploadedRanges: 4, drawableFaces: 128 })
+    recordClientLightTraceGpuSample('gpuUploaded', 128, { phase: 'gpuUploaded', unuploadedRanges: 3, drawableFaces: 128 })
+    recordClientLightTraceGpuSample('gpuUploaded', 256, { phase: 'gpuUploaded', unuploadedRanges: 2, drawableFaces: 256 })
+    const uploaded = getClientLightTraceEvents().filter(event => event.phase === 'gpuUploaded')
+    expect(uploaded).toHaveLength(2)
+    expect(uploaded[0]!.drawableFaces).toBe(128)
+    expect(uploaded[1]!.drawableFaces).toBe(256)
+  })
+})
+
+test('dumpClientLightTrace requests a gpu sample for the next draw', () => {
+  enableClientLightTrace(true)
+  recordClientLightTraceGpuSample('gpuDrawn', 10, { phase: 'gpuDrawn', drawableFaces: 10 })
+  dumpClientLightTrace()
+  recordClientLightTraceGpuSample('gpuDrawn', 10, { phase: 'gpuDrawn', drawableFaces: 10 })
+  expect(getClientLightTraceEvents().filter(event => event.phase === 'gpuDrawn')).toHaveLength(2)
+})

package/src/lighting/debug/clientLightTrace.ts

@@ -0,0 +1,335 @@
+//@ts-nocheck
+/**
+ * Bounded causal trace for client lighting delivery.
+ * Off by default. Records metadata and aggregates only — never meshes, chunks, or raw packets.
+ */
+
+export const CLIENT_LIGHT_TRACE_CAPACITY = 2048
+export const CLIENT_LIGHT_TRACE_MESSAGE = '__clientLightTrace' as const
+export const CLIENT_LIGHT_TRACE_BATCH_MS = 250
+export const CLIENT_LIGHT_TRACE_BATCH_SIZE = 200
+
+export type ClientLightTracePhase =
+  | 'inputClick'
+  | 'inputHand'
+  | 'blockChange'
+  | 'ownerEnqueue'
+  | 'ownerAdmit'
+  | 'ownerComplete'
+  | 'mesherEnqueue'
+  | 'mesherStart'
+  | 'mesherEnd'
+  | 'mesherFlush'
+  | 'receive'
+  | 'reject'
+  | 'pending'
+  | 'flush'
+  | 'gpuStaged'
+  | 'gpuUploaded'
+  | 'gpuCommitted'
+  | 'gpuDrawn'
+
+export type ClientLightTraceEvent = {
+  t: number
+  tLocal: number
+  timeOrigin: number
+  phase: ClientLightTracePhase
+  sessionEpoch?: number
+  editSeq?: number
+  requestId?: number
+  sectionKey?: string
+  blockVersion?: number
+  lightVersion?: number
+  worldGeneration?: number
+  eventAgeMs?: number
+  currentColumn?: string
+  queueDepth?: number
+  fallbackRelights?: number
+  txnMs?: number
+  displayedStart?: number
+  displayedCount?: number
+  candidateStart?: number
+  candidateCount?: number
+  pendingReplace?: boolean
+  pendingMove?: boolean
+  unuploadedRanges?: number
+  drawableFaces?: number
+  cullReason?: string
+  flushReason?: string
+  workerIndex?: number
+}
+
+export type ClientLightTracePartial = Omit<ClientLightTraceEvent, 't' | 'tLocal' | 'timeOrigin'> &
+  Partial<Pick<ClientLightTraceEvent, 't' | 'tLocal' | 'timeOrigin'>>
+
+export type ClientLightTraceMessage = {
+  type: typeof CLIENT_LIGHT_TRACE_MESSAGE
+  event?: ClientLightTraceEvent
+  events?: ClientLightTraceEvent[]
+}
+
+export type ClientLightTraceConfig = {
+  enabled: boolean
+  armed: boolean
+}
+
+type ClientLightTraceConfigListener = (config: ClientLightTraceConfig) => void
+
+let enabled = false
+let armed = false
+let sessionEpoch = 0
+let editSeq = 0
+let requestId = 0
+let dropped = 0
+let start = 0
+let count = 0
+let sampleRequested = false
+let lastGpuDrawnMetric: number | undefined
+let lastGpuUploadedMetric: number | undefined
+let pendingPost: ((message: ClientLightTraceMessage) => void) | null = null
+let pendingEvents: ClientLightTraceEvent[] = []
+let pendingTimer: ReturnType<typeof setTimeout> | null = null
+let configListener: ClientLightTraceConfigListener | undefined
+const ring: Array<ClientLightTraceEvent | undefined> = new Array(CLIENT_LIGHT_TRACE_CAPACITY)
+
+export function isClientLightTraceEnabled(): boolean {
+  return enabled
+}
+
+export function isClientLightTraceArmed(): boolean {
+  return armed
+}
+
+export function enableClientLightTrace(on: boolean): void {
+  enabled = on
+  if (!on) {
+    armed = false
+    dropPendingPosts()
+    resetGpuSampleState()
+  }
+  attachDebugDump(on)
+  notifyConfig()
+}
+
+export function armClientLightTrace(on = true): void {
+  armed = on
+  if (!armed) dropPendingPosts()
+  notifyConfig()
+}
+
+export function setClientLightTraceConfigListener(listener: ClientLightTraceConfigListener | undefined): void {
+  configListener = listener
+}
+
+export function maybeEnableClientLightTraceFromLocation(loc: { search?: string } | undefined = typeof location === 'undefined' ? undefined : location): void {
+  try {
+    if (!loc) return
+    if (new URLSearchParams(loc.search ?? '').get('clientLightTrace') === '1') {
+      enableClientLightTrace(true)
+    }
+  } catch {
+    // ignore malformed URL in non-browser runtimes
+  }
+}
+
+export function comparableNow(): number {
+  return performance.timeOrigin + performance.now()
+}
+
+export function getClientLightTraceSessionEpoch(): number {
+  return sessionEpoch
+}
+
+export function bumpClientLightTraceSessionEpoch(): number {
+  sessionEpoch++
+  return sessionEpoch
+}
+
+export function nextClientLightEditSeq(): number {
+  editSeq++
+  return editSeq
+}
+
+export function nextClientLightRequestId(): number {
+  requestId++
+  return requestId
+}
+
+export function currentClientLightTraceIds(): { sessionEpoch: number; editSeq: number } {
+  return { sessionEpoch, editSeq }
+}
+
+export function clearClientLightTrace(): void {
+  start = 0
+  count = 0
+  dropped = 0
+  ring.fill(undefined)
+  resetGpuSampleState()
+}
+
+export function recordClientLightTrace(partial: ClientLightTracePartial): ClientLightTraceEvent | undefined {
+  if (!enabled) return undefined
+  const tLocal = partial.tLocal ?? performance.now()
+  const timeOrigin = partial.timeOrigin ?? performance.timeOrigin
+  const event: ClientLightTraceEvent = {
+    ...partial,
+    t: partial.t ?? timeOrigin + tLocal,
+    tLocal,
+    timeOrigin,
+    sessionEpoch: partial.sessionEpoch ?? sessionEpoch
+  }
+  pushEvent(event)
+  return event
+}
+
+export function requestClientLightTraceSample(): void {
+  sampleRequested = true
+}
+
+export function recordClientLightTraceGpuSample(
+  phase: 'gpuDrawn' | 'gpuUploaded',
+  metric: number,
+  partial: ClientLightTracePartial | (() => ClientLightTracePartial)
+): ClientLightTraceEvent | undefined {
+  if (!enabled) return undefined
+  const last = phase === 'gpuDrawn' ? lastGpuDrawnMetric : lastGpuUploadedMetric
+  if (last === metric && !sampleRequested) return undefined
+  if (phase === 'gpuDrawn') lastGpuDrawnMetric = metric
+  else lastGpuUploadedMetric = metric
+  sampleRequested = false
+  return recordClientLightTrace(typeof partial === 'function' ? partial() : partial)
+}
+
+export function ingestRemoteClientLightTrace(event: ClientLightTraceEvent | undefined): void {
+  if (!enabled || !event || typeof event.t !== 'number' || !event.phase) return
+  pushEvent(event)
+}
+
+export function ingestRemoteClientLightTraceMessage(message: ClientLightTraceMessage | { type?: unknown; event?: unknown; events?: unknown }): void {
+  if (!isClientLightTraceMessage(message)) return
+  const events = message.events ?? (message.event ? [message.event] : [])
+  for (const event of events) ingestRemoteClientLightTrace(event)
+}
+
+export function postClientLightTrace(post: (message: ClientLightTraceMessage) => void, partial: ClientLightTracePartial): void {
+  const event = recordClientLightTrace(partial)
+  if (!event || !armed) return
+  pendingPost = post
+  pendingEvents.push(event)
+  if (pendingEvents.length >= CLIENT_LIGHT_TRACE_BATCH_SIZE) {
+    flushClientLightTracePosts()
+    return
+  }
+  if (pendingTimer == null) {
+    pendingTimer = setTimeout(() => {
+      pendingTimer = null
+      flushClientLightTracePosts()
+    }, CLIENT_LIGHT_TRACE_BATCH_MS)
+  }
+}
+
+export function flushClientLightTracePosts(): void {
+  if (pendingTimer != null) {
+    clearTimeout(pendingTimer)
+    pendingTimer = null
+  }
+  if (!pendingPost || pendingEvents.length === 0) {
+    pendingEvents = []
+    pendingPost = null
+    return
+  }
+  const events = pendingEvents
+  const post = pendingPost
+  pendingEvents = []
+  pendingPost = null
+  post({ type: CLIENT_LIGHT_TRACE_MESSAGE, events })
+}
+
+export function isClientLightTraceMessage(data: unknown): data is ClientLightTraceMessage {
+  if (!data || typeof data !== 'object') return false
+  const message = data as { type?: unknown; event?: unknown; events?: unknown }
+  if (message.type !== CLIENT_LIGHT_TRACE_MESSAGE) return false
+  if (Array.isArray(message.events)) return true
+  return !!message.event && typeof message.event === 'object'
+}
+
+export function getClientLightTraceEvents(): ClientLightTraceEvent[] {
+  const out: ClientLightTraceEvent[] = []
+  for (let i = 0; i < count; i++) {
+    const event = ring[(start + i) % CLIENT_LIGHT_TRACE_CAPACITY]
+    if (event) out.push(event)
+  }
+  return out
+}
+
+export function getClientLightTraceAggregates(): { count: number; dropped: number; byPhase: Partial<Record<ClientLightTracePhase, number>> } {
+  const byPhase: Partial<Record<ClientLightTracePhase, number>> = {}
+  for (const event of getClientLightTraceEvents()) {
+    byPhase[event.phase] = (byPhase[event.phase] ?? 0) + 1
+  }
+  return { count: count, dropped, byPhase }
+}
+
+export function dumpClientLightTrace(): {
+  events: ClientLightTraceEvent[]
+  aggregates: ReturnType<typeof getClientLightTraceAggregates>
+} {
+  requestClientLightTraceSample()
+  return {
+    events: getClientLightTraceEvents(),
+    aggregates: getClientLightTraceAggregates()
+  }
+}
+
+function dropPendingPosts(): void {
+  if (pendingTimer != null) {
+    clearTimeout(pendingTimer)
+    pendingTimer = null
+  }
+  pendingEvents = []
+  pendingPost = null
+}
+
+function resetGpuSampleState(): void {
+  sampleRequested = false
+  lastGpuDrawnMetric = undefined
+  lastGpuUploadedMetric = undefined
+}
+
+function notifyConfig(): void {
+  configListener?.({ enabled, armed })
+}
+
+function pushEvent(event: ClientLightTraceEvent): void {
+  if (count === CLIENT_LIGHT_TRACE_CAPACITY) {
+    ring[start] = event
+    start = (start + 1) % CLIENT_LIGHT_TRACE_CAPACITY
+    dropped++
+    return
+  }
+  ring[(start + count) % CLIENT_LIGHT_TRACE_CAPACITY] = event
+  count++
+}
+
+function attachDebugDump(on: boolean): void {
+  if (typeof globalThis === 'undefined') return
+  const host = globalThis as typeof globalThis & {
+    getClientLightTrace?: typeof getClientLightTraceEvents
+    getClientLightTraceAggregates?: typeof getClientLightTraceAggregates
+    clientLightTraceArm?: (on?: boolean) => void
+    clientLightTraceDump?: typeof dumpClientLightTrace
+  }
+  if (on) {
+    host.getClientLightTrace = getClientLightTraceEvents
+    host.getClientLightTraceAggregates = getClientLightTraceAggregates
+    host.clientLightTraceArm = (next = true) => {
+      armClientLightTrace(next !== false)
+    }
+    host.clientLightTraceDump = dumpClientLightTrace
+  } else {
+    delete host.getClientLightTrace
+    delete host.getClientLightTraceAggregates
+    delete host.clientLightTraceArm
+    delete host.clientLightTraceDump
+  }
+}