minecraft-renderer 0.1.106 → 0.1.108

package/src/three/entity/legWalkAnimation.test.ts

@@ -0,0 +1,154 @@
+//@ts-nocheck
+import * as THREE from 'three'
+import { expect, test } from 'vitest'
+import { applyLegRig, assignLegPhases, calculateLegSwing, createLegRig } from './legWalkAnimation'
+
+const close = (a: THREE.Vector3, b: THREE.Vector3) => a.distanceTo(b) < 1e-4
+
+/** Mirrors `getMesh`: bones carry absolute pivots even when parented, vertices are authored in mesh space. */
+// bound before scaling like `getMesh`, so skinned vertices come back in 1/16 block units
+function makeBedrockQuadruped() {
+  const legs = [
+    { name: 'leg0', pivot: [-4, 12, 7] },
+    { name: 'leg1', pivot: [4, 12, 7] },
+    { name: 'leg2', pivot: [-4, 12, -6] },
+    { name: 'leg3', pivot: [4, 12, -6] }
+  ]
+  const body = new THREE.Bone()
+  body.name = 'bone_body'
+  body.position.set(0, 5, 2)
+  const bones = [body]
+  const positions: number[] = []
+  const skinIndices: number[] = []
+  const skinWeights: number[] = []
+  for (const [i, leg] of legs.entries()) {
+    const bone = new THREE.Bone()
+    bone.name = `bone_${leg.name}`
+    bone.position.set(leg.pivot[0], leg.pivot[1], leg.pivot[2])
+    body.add(bone)
+    bones.push(bone)
+    // single foot vertex 12px under the pivot
+    positions.push(leg.pivot[0], leg.pivot[1] - 12, leg.pivot[2])
+    skinIndices.push(i + 1, 0, 0, 0)
+    skinWeights.push(1, 0, 0, 0)
+  }
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(skinIndices, 4))
+  geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(skinWeights, 4))
+  const mesh = new THREE.SkinnedMesh(geometry, new THREE.MeshBasicMaterial())
+  mesh.add(body)
+  mesh.bind(new THREE.Skeleton(bones))
+  mesh.scale.set(1 / 16, 1 / 16, 1 / 16)
+  const root = new THREE.Object3D()
+  root.add(mesh)
+  return { root, mesh, legs }
+}
+
+test('calculateLegSwing follows vanilla gait and is zero at rest', () => {
+  expect(calculateLegSwing(5, 0, 0)).toBe(0)
+  expect(calculateLegSwing(0, 1, 0)).toBeCloseTo(1.4)
+  expect(calculateLegSwing(0, 0.5, Math.PI)).toBeCloseTo(-0.7)
+  expect(calculateLegSwing(Number.NaN, 1, 0)).toBe(0)
+})
+
+test('assignLegPhases alternates bipeds and pairs quadruped diagonals', () => {
+  expect(
+    assignLegPhases([
+      { x: -1.9, z: 0 },
+      { x: 1.9, z: 0 }
+    ])
+  ).toEqual([Math.PI, 0])
+  // leg0..leg3 as hind-right, hind-left, front-right, front-left
+  const quad = assignLegPhases([
+    { x: -4, z: 7 },
+    { x: 4, z: 7 },
+    { x: -4, z: -6 },
+    { x: 4, z: -6 }
+  ])!
+  expect(quad[0]).toBe(quad[3])
+  expect(quad[1]).toBe(quad[2])
+  expect(quad[0]).not.toBe(quad[1])
+  expect(assignLegPhases([{ x: 0, z: 0 }])).toBeUndefined()
+  expect(assignLegPhases(Array.from({ length: 8 }, (_, i) => ({ x: i, z: i % 2 })))).toBeUndefined()
+})
+
+test('bedrock legs rotate about their own pivot even when parented to an offset body bone', () => {
+  const { root, mesh, legs } = makeBedrockQuadruped()
+  const rig = createLegRig(root, 'cow')!
+  expect(rig.legs).toHaveLength(4)
+
+  applyLegRig(rig, 0.4 * Math.PI, 1)
+  mesh.updateWorldMatrix(true, true)
+  mesh.skeleton.update()
+
+  const vertex = new THREE.Vector3()
+  for (const [i, leg] of legs.entries()) {
+    const pivot = new THREE.Vector3(...(leg.pivot as [number, number, number]))
+    const expectedAngle = calculateLegSwing(0.4 * Math.PI, 1, rig.legs[i].phase)
+    const foot = new THREE.Vector3(pivot.x, pivot.y - 12, pivot.z)
+    const expected = foot
+      .clone()
+      .sub(pivot)
+      .applyAxisAngle(new THREE.Vector3(1, 0, 0), expectedAngle)
+      .add(pivot)
+    mesh.getVertexPosition(i, vertex).multiplyScalar(16)
+    expect(close(vertex, expected), `leg ${i}`).toBe(true)
+    // the pivot itself never moves
+    expect(Math.abs(vertex.distanceTo(pivot) - 12)).toBeLessThan(1e-4)
+  }
+})
+
+test('legs settle back to the exact rest pose once the mob stops', () => {
+  const { root, mesh, legs } = makeBedrockQuadruped()
+  const rig = createLegRig(root, 'pig')!
+  applyLegRig(rig, 3, 0.8)
+  applyLegRig(rig, 3, 0)
+  mesh.updateWorldMatrix(true, true)
+  mesh.skeleton.update()
+  const vertex = new THREE.Vector3()
+  for (const [i, leg] of legs.entries()) {
+    mesh.getVertexPosition(i, vertex).multiplyScalar(16)
+    expect(close(vertex, new THREE.Vector3(leg.pivot[0], leg.pivot[1] - 12, leg.pivot[2]))).toBe(true)
+  }
+})
+
+function makeObjBiped() {
+  const root = new THREE.Object3D()
+  const makeLeg = (name: string, x: number) => {
+    const geometry = new THREE.BoxGeometry(0.25, 0.75, 0.25)
+    geometry.translate(x, 0.375, 0)
+    const mesh = new THREE.Mesh(geometry, new THREE.MeshBasicMaterial())
+    mesh.name = name
+    return mesh
+  }
+  const left = makeLeg('LeftLeg', 0.125)
+  const right = makeLeg('RightLeg', -0.125)
+  root.add(left, right)
+  return { root, left, right }
+}
+
+test('OBJ legs pivot at the top of their box without moving at rest', () => {
+  const { root, left, right } = makeObjBiped()
+  const rig = createLegRig(root, 'enderman')!
+  expect(rig.legs).toHaveLength(2)
+
+  left.updateMatrix()
+  left.geometry.computeBoundingBox()
+  const restBox = left.geometry.boundingBox!.clone().applyMatrix4(left.matrix)
+  expect(restBox.min.y).toBeCloseTo(0)
+  expect(restBox.max.y).toBeCloseTo(0.75)
+
+  applyLegRig(rig, 0, 1)
+  expect(left.rotation.x).toBeCloseTo(calculateLegSwing(0, 1, rig.legs.find(l => l.kind === 'mesh' && l.meshes[0] === left)!.phase))
+  expect(left.rotation.x).toBeCloseTo(-right.rotation.x)
+  // the hinge (original top centre of the leg) stays put while the leg rotates
+  left.updateMatrix()
+  const hinge = new THREE.Vector3(0, 0, 0).applyMatrix4(left.matrix)
+  expect(close(hinge, new THREE.Vector3(0.125, 0.75, 0))).toBe(true)
+})
+
+test('excluded and unrecognised models get no rig', () => {
+  expect(createLegRig(makeObjBiped().root, 'parrot')).toBeUndefined()
+  expect(createLegRig(new THREE.Object3D(), 'cow')).toBeUndefined()
+})

package/src/three/entity/legWalkAnimation.ts

@@ -0,0 +1,193 @@
+//@ts-nocheck
+import * as THREE from 'three'
+
+export const LEG_RIG_USER_DATA_KEY = '_legRig'
+export const LEG_ANIMATION_USER_DATA_KEY = '_legAnimation'
+
+/** Vanilla ModelBiped / ModelQuadruped constants. */
+export const LEG_SWING_FREQUENCY = 0.6662
+export const LEG_SWING_AMPLITUDE = 1.4
+
+/** Entities whose legs are not driven by ground walking (fly, hop, swim or use bespoke animations). */
+const LEG_ANIMATION_EXCLUDED = new Set(['armor_stand', 'axolotl', 'ender_dragon', 'frog', 'parrot', 'rabbit', 'turtle'])
+
+const LEG_NAME_PATTERN = /leg/i
+
+type BoneLeg = {
+  kind: 'bone'
+  bone: THREE.Bone
+  /** Pivot in mesh space, the point the vertices were authored around. */
+  pivot: THREE.Vector3
+  /** Parent bone matrix relative to the skinned mesh at bind time. */
+  parentMatrix: THREE.Matrix4
+  parentMatrixInverse: THREE.Matrix4
+  /** Local bone matrix at bind time. */
+  restMatrix: THREE.Matrix4
+}
+
+type MeshLeg = {
+  kind: 'mesh'
+  meshes: THREE.Mesh[]
+  restRotationX: number[]
+}
+
+export type LegRigLeg = (BoneLeg | MeshLeg) & { phase: number }
+
+export type LegRig = {
+  legs: LegRigLeg[]
+  /** True while legs are rotated away from rest, so settling back is written exactly once. */
+  posed: boolean
+}
+
+type LegCandidate = { name: string; pivot: THREE.Vector3; build: (phase: number) => LegRigLeg }
+
+/** Vanilla leg swing angle (radians around the model X axis). */
+export function calculateLegSwing(limbSwing: number, limbSwingAmount: number, phase: number): number {
+  const amount = Number.isFinite(limbSwingAmount) ? Math.max(0, limbSwingAmount) : 0
+  if (amount === 0 || !Number.isFinite(limbSwing)) return 0
+  return Math.cos(limbSwing * LEG_SWING_FREQUENCY + phase) * LEG_SWING_AMPLITUDE * amount
+}
+
+/**
+ * Diagonal pairs move together on four legged mobs and opposite legs alternate on bipeds.
+ * Derived from pivot positions so it works for any bone naming (leg0, rightLeg, left_hind_leg...).
+ * Returns the phase offset per candidate, or undefined if the leg layout isn't recognised.
+ */
+export function assignLegPhases(pivots: Array<{ x: number; z: number }>): number[] | undefined {
+  if (pivots.length !== 2 && pivots.length !== 4) return undefined
+
+  const meanX = pivots.reduce((sum, p) => sum + p.x, 0) / pivots.length
+  const meanZ = pivots.reduce((sum, p) => sum + p.z, 0) / pivots.length
+  const xs = pivots.map(p => p.x - meanX)
+  const zs = pivots.map(p => p.z - meanZ)
+  const xSpread = Math.max(...xs) - Math.min(...xs)
+  const zSpread = Math.max(...zs) - Math.min(...zs)
+
+  // Legs side by side: alternate left/right.
+  if (pivots.length === 2 || zSpread < xSpread * 0.5) {
+    if (xSpread === 0) return undefined
+    return xs.map(x => (x > 0 ? 0 : Math.PI))
+  }
+
+  if (xSpread === 0) return undefined
+  return xs.map((x, i) => (x > 0 === zs[i] > 0 ? 0 : Math.PI))
+}
+
+function collectBoneCandidates(skinned: THREE.SkinnedMesh): LegCandidate[] {
+  skinned.updateWorldMatrix(true, true)
+  const meshInverse = skinned.matrixWorld.clone().invert()
+  const candidates: LegCandidate[] = []
+  for (const bone of skinned.skeleton.bones) {
+    const name = bone.name.replace(/^bone_/, '')
+    if (!LEG_NAME_PATTERN.test(name)) continue
+    // Sub-bones such as `Leg1B` hang off the same pivot and would be double counted.
+    if (/^leg\d[b-z]$/i.test(name)) continue
+    const pivot = bone.position.clone()
+    const parentMatrix = bone.parent instanceof THREE.Bone ? meshInverse.clone().multiply(bone.parent.matrixWorld) : new THREE.Matrix4()
+    candidates.push({
+      name,
+      pivot,
+      build: phase => ({
+        kind: 'bone',
+        phase,
+        bone,
+        pivot,
+        parentMatrix,
+        parentMatrixInverse: parentMatrix.clone().invert(),
+        restMatrix: bone.matrix.clone()
+      })
+    })
+  }
+  return candidates
+}
+
+function collectMeshCandidates(root: THREE.Object3D): LegCandidate[] {
+  const groups = new Map<string, THREE.Mesh[]>()
+  for (const child of root.children) {
+    if (!(child instanceof THREE.Mesh) || child instanceof THREE.SkinnedMesh) continue
+    if (!LEG_NAME_PATTERN.test(child.name)) continue
+    const group = groups.get(child.name)
+    if (group) group.push(child)
+    else groups.set(child.name, [child])
+  }
+
+  const candidates: LegCandidate[] = []
+  for (const [name, meshes] of groups) {
+    // Overlay layers share a name, so the pivot is the union of them.
+    const box = new THREE.Box3()
+    for (const mesh of meshes) {
+      mesh.updateMatrix()
+      mesh.geometry.computeBoundingBox()
+      box.union(mesh.geometry.boundingBox!.clone().applyMatrix4(mesh.matrix))
+    }
+    // Legs hang from the top of their box and swing around it.
+    const pivot = new THREE.Vector3((box.min.x + box.max.x) / 2, box.max.y, (box.min.z + box.max.z) / 2)
+    candidates.push({
+      name,
+      pivot,
+      build: phase => {
+        for (const mesh of meshes) {
+          mesh.geometry.translate(-pivot.x, -pivot.y, -pivot.z)
+          mesh.position.add(pivot)
+        }
+        return { kind: 'mesh', phase, meshes, restRotationX: meshes.map(mesh => mesh.rotation.x) }
+      }
+    })
+  }
+  return candidates
+}
+
+function buildLegs(candidates: LegCandidate[]): LegRigLeg[] {
+  const phases = assignLegPhases(candidates.map(c => c.pivot))
+  if (!phases) return []
+  return candidates.map((candidate, i) => candidate.build(phases[i]))
+}
+
+/**
+ * Finds the legs of a mob model (bedrock bones or OBJ parts) and prepares them to be swung
+ * around their pivots. Returns undefined when the model has no recognisable 2 or 4 leg layout.
+ */
+export function createLegRig(root: THREE.Object3D, entityName?: string): LegRig | undefined {
+  if (entityName && LEG_ANIMATION_EXCLUDED.has(entityName)) return undefined
+
+  const legs: LegRigLeg[] = []
+  root.traverse(child => {
+    if (child instanceof THREE.SkinnedMesh) legs.push(...buildLegs(collectBoneCandidates(child)))
+  })
+  legs.push(...buildLegs(collectMeshCandidates(root)))
+
+  if (legs.length === 0) return undefined
+  return { legs, posed: false }
+}
+
+const tmpPivotMatrix = new THREE.Matrix4()
+const tmpRotation = new THREE.Matrix4()
+const tmpDeform = new THREE.Matrix4()
+const tmpLocal = new THREE.Matrix4()
+
+function applyBoneLeg(leg: BoneLeg, angle: number): void {
+  // Skinning deforms vertices by D = T(pivot) * Rx * T(-pivot) in mesh space. Bones are parented with absolute
+  // pivots, so the local rotation is conjugated by the parent bind matrix to produce exactly that deformation.
+  tmpDeform.makeTranslation(leg.pivot.x, leg.pivot.y, leg.pivot.z)
+  tmpDeform.multiply(tmpRotation.makeRotationX(angle))
+  tmpDeform.multiply(tmpPivotMatrix.makeTranslation(-leg.pivot.x, -leg.pivot.y, -leg.pivot.z))
+
+  tmpLocal.copy(leg.parentMatrixInverse).multiply(tmpDeform).multiply(leg.parentMatrix).multiply(leg.restMatrix)
+  tmpLocal.decompose(leg.bone.position, leg.bone.quaternion, leg.bone.scale)
+}
+
+/** Poses all legs of the rig. Cheap no-op while the mob stays still. */
+export function applyLegRig(rig: LegRig, limbSwing: number, limbSwingAmount: number): void {
+  const moving = Number.isFinite(limbSwingAmount) && limbSwingAmount >= 1e-4
+  if (!moving && !rig.posed) return
+  rig.posed = moving
+
+  for (const leg of rig.legs) {
+    const angle = moving ? calculateLegSwing(limbSwing, limbSwingAmount, leg.phase) : 0
+    if (leg.kind === 'bone') {
+      applyBoneLeg(leg, angle)
+    } else {
+      for (const [i, mesh] of leg.meshes.entries()) mesh.rotation.x = leg.restRotationX[i] + angle
+    }
+  }
+}

package/src/three/globalBlockBuffer.ts

@@ -12,6 +12,7 @@ import {
 import { VERTICES_PER_FACE, computeSectionOriginRel } from './shaders/cubeBlockShader'
 import { computeCameraRelativeUniforms, type RenderOrigin } from './shaders/legacyBlockShader'
 import { packWord2Empty } from '../wasm-mesher/bridge/shaderCubeBridge'
+import { isClientLightTraceEnabled, recordClientLightTrace, recordClientLightTraceGpuSample } from '../lighting/debug/clientLightTrace'
 
 type WebGLRendererInternals = THREE.WebGLRenderer & {
   properties: {
@@ -162,9 +163,9 @@ export class GlobalBlockBuffer {
   getSectionDrawStart(sectionKey: string): number | undefined {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return undefined
-    if (this.pendingMove?.key === sectionKey) return this.pendingMove.oldStart
     const replace = this.pendingReplace.get(sectionKey)
     if (replace) return replace.oldStart
+    if (this.pendingMove?.key === sectionKey) return this.pendingMove.oldStart
     if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return undefined
     return slot.start
   }
@@ -172,13 +173,37 @@ export class GlobalBlockBuffer {
   getSectionDrawCount(sectionKey: string): number | undefined {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return undefined
-    if (this.pendingMove?.key === sectionKey) return this.pendingMove.count
     const replace = this.pendingReplace.get(sectionKey)
     if (replace) return replace.oldCount
+    if (this.pendingMove?.key === sectionKey) return this.pendingMove.count
     if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return undefined
     return slot.count
   }
 
+  getGpuSlotTrace(sectionKey: string):
+    | {
+        displayedStart?: number
+        displayedCount?: number
+        candidateStart: number
+        candidateCount: number
+        pendingReplace: boolean
+        pendingMove: boolean
+        unuploadedRanges: number
+      }
+    | undefined {
+    const slot = this.sectionSlots.get(sectionKey)
+    if (!slot) return undefined
+    return {
+      displayedStart: this.getSectionDrawStart(sectionKey),
+      displayedCount: this.getSectionDrawCount(sectionKey),
+      candidateStart: slot.start,
+      candidateCount: slot.count,
+      pendingReplace: this.pendingReplace.has(sectionKey),
+      pendingMove: this.pendingMove?.key === sectionKey,
+      unuploadedRanges: this.pendingRanges.length
+    }
+  }
+
   getUploadEpoch(): number {
     return this.uploadEpoch
   }
@@ -282,6 +307,20 @@ export class GlobalBlockBuffer {
     this.markDirty(slot.start, slot.start + faceCount - 1)
     this.mesh.geometry.instanceCount = this.highWatermark
     this.layoutVersion++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(sectionKey)
+      recordClientLightTrace({
+        phase: 'gpuStaged',
+        sectionKey,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: gpu?.pendingReplace,
+        pendingMove: gpu?.pendingMove,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   getLayoutVersion(): number {
@@ -388,6 +427,20 @@ export class GlobalBlockBuffer {
     this.markDirty(newStart, newStart + section.count - 1)
     this.pendingMove = { key: section.key, oldStart, newStart, count: section.count }
     this.layoutVersion++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(section.key)
+      recordClientLightTrace({
+        phase: 'gpuStaged',
+        sectionKey: section.key,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: gpu?.pendingReplace,
+        pendingMove: true,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   uploadDirtyRange(): void {
@@ -411,6 +464,13 @@ export class GlobalBlockBuffer {
       r.start = offset + count
     }
     this.uploadEpoch++
+    if (isClientLightTraceEnabled()) {
+      recordClientLightTraceGpuSample('gpuUploaded', this.highWatermark, () => ({
+        phase: 'gpuUploaded',
+        unuploadedRanges: this.pendingRanges.length,
+        drawableFaces: this.highWatermark
+      }))
+    }
   }
 
   setCameraOrigin(renderOrigin: RenderOrigin, x: number, y: number, z: number): void {
@@ -608,6 +668,9 @@ export class GlobalBlockBuffer {
   private findMovableSection(maxCount: number): { key: string; start: number; count: number } | undefined {
     const sections: Array<{ key: string; start: number; count: number }> = []
     for (const [key, slot] of this.sectionSlots) {
+      if (this.pendingReplace.has(key)) continue
+      if (this.pendingMove?.key === key) continue
+      if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) continue
       sections.push({ key, start: slot.start, count: slot.count })
     }
     if (sections.length === 0) return undefined
@@ -684,11 +747,26 @@ export class GlobalBlockBuffer {
     this.mesh.geometry.instanceCount = this.highWatermark
     this.layoutVersion++
     this.uploadEpoch++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(key)
+      recordClientLightTrace({
+        phase: 'gpuCommitted',
+        sectionKey: key,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: false,
+        pendingMove: gpu?.pendingMove,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   private finalizePendingMove(): void {
     const move = this.pendingMove
     if (!move) return
+    const movedKey = move.key
 
     const { oldStart, count } = move
     this.zeroAndFreeSlot(oldStart, count)
@@ -697,6 +775,20 @@ export class GlobalBlockBuffer {
     this.pendingMove = null
     this.layoutVersion++
     this.uploadEpoch++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(movedKey)
+      recordClientLightTrace({
+        phase: 'gpuCommitted',
+        sectionKey: movedKey,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: gpu?.pendingReplace,
+        pendingMove: false,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   private shrinkHighWatermark(): void {

package/src/three/globalLegacyBuffer.ts

@@ -10,6 +10,7 @@ import {
   type LegacyMultiDrawScratch
 } from './legacyMultiDraw'
 import { computeCameraRelativeUniforms, type RenderOrigin } from './shaders/legacyBlockShader'
+import { isClientLightTraceEnabled, recordClientLightTrace, recordClientLightTraceGpuSample } from '../lighting/debug/clientLightTrace'
 
 const VERTS_PER_QUAD = 4
 const INDICES_PER_QUAD = 6
@@ -337,6 +338,20 @@ export class GlobalLegacyBuffer {
     this.markDirty(slot.start, slot.start + quadCount - 1)
     this.syncDefaultDrawGroups()
     this.layoutVersion++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(sectionKey)
+      recordClientLightTrace({
+        phase: 'gpuStaged',
+        sectionKey,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: gpu?.pendingReplace,
+        pendingMove: gpu?.pendingMove,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
     return true
   }
 
@@ -367,9 +382,9 @@ export class GlobalLegacyBuffer {
   getSectionDrawStart(sectionKey: string): number | undefined {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return undefined
-    if (this.pendingMove?.key === sectionKey) return this.pendingMove.oldStart
     const replace = this.pendingReplace.get(sectionKey)
     if (replace) return replace.oldStart
+    if (this.pendingMove?.key === sectionKey) return this.pendingMove.oldStart
     if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return undefined
     return slot.start
   }
@@ -377,13 +392,37 @@ export class GlobalLegacyBuffer {
   getSectionDrawCount(sectionKey: string): number | undefined {
     const slot = this.sectionSlots.get(sectionKey)
     if (!slot) return undefined
-    if (this.pendingMove?.key === sectionKey) return this.pendingMove.count
     const replace = this.pendingReplace.get(sectionKey)
     if (replace) return replace.oldCount
+    if (this.pendingMove?.key === sectionKey) return this.pendingMove.count
     if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) return undefined
     return slot.count
   }
 
+  getGpuSlotTrace(sectionKey: string):
+    | {
+        displayedStart?: number
+        displayedCount?: number
+        candidateStart: number
+        candidateCount: number
+        pendingReplace: boolean
+        pendingMove: boolean
+        unuploadedRanges: number
+      }
+    | undefined {
+    const slot = this.sectionSlots.get(sectionKey)
+    if (!slot) return undefined
+    return {
+      displayedStart: this.getSectionDrawStart(sectionKey),
+      displayedCount: this.getSectionDrawCount(sectionKey),
+      candidateStart: slot.start,
+      candidateCount: slot.count,
+      pendingReplace: this.pendingReplace.has(sectionKey),
+      pendingMove: this.pendingMove?.key === sectionKey,
+      unuploadedRanges: this.pendingRanges.length
+    }
+  }
+
   getPendingMove(): PendingMove | null {
     return this.pendingMove
   }
@@ -425,6 +464,20 @@ export class GlobalLegacyBuffer {
     this.markDirty(newStart, newStart + section.count - 1)
     this.pendingMove = { key: section.key, oldStart, newStart, count: section.count }
     this.layoutVersion++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(section.key)
+      recordClientLightTrace({
+        phase: 'gpuStaged',
+        sectionKey: section.key,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: gpu?.pendingReplace,
+        pendingMove: true,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   updateDrawSpans(visible: VisibleSectionSpan[], mode: 'opaque' | 'sortedBlend'): void {
@@ -696,6 +749,13 @@ export class GlobalLegacyBuffer {
       r.start = quadOffset + quadCount
     }
     this.uploadEpoch++
+    if (isClientLightTraceEnabled()) {
+      recordClientLightTraceGpuSample('gpuUploaded', this.highWatermark, () => ({
+        phase: 'gpuUploaded',
+        unuploadedRanges: this.pendingRanges.length,
+        drawableFaces: this.highWatermark
+      }))
+    }
   }
 
   uploadDirtyIndexRange(): void {
@@ -898,6 +958,9 @@ export class GlobalLegacyBuffer {
   private findMovableSection(maxCount: number): { key: string; start: number; count: number } | undefined {
     const sections: Array<{ key: string; start: number; count: number }> = []
     for (const [key, slot] of this.sectionSlots) {
+      if (this.pendingReplace.has(key)) continue
+      if (this.pendingMove?.key === key) continue
+      if (!this.rangeFullyUploaded(slot.start, slot.start + slot.count - 1)) continue
       sections.push({ key, start: slot.start, count: slot.count })
     }
     if (sections.length === 0) return undefined
@@ -1006,11 +1069,26 @@ export class GlobalLegacyBuffer {
     this.syncDefaultDrawGroups()
     this.layoutVersion++
     this.uploadEpoch++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(key)
+      recordClientLightTrace({
+        phase: 'gpuCommitted',
+        sectionKey: key,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: false,
+        pendingMove: gpu?.pendingMove,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   private finalizePendingMove(): void {
     const move = this.pendingMove
     if (!move) return
+    const movedKey = move.key
 
     const { oldStart, count } = move
     this.zeroAndFreeSlot(oldStart, count)
@@ -1019,6 +1097,20 @@ export class GlobalLegacyBuffer {
     this.pendingMove = null
     this.layoutVersion++
     this.uploadEpoch++
+    if (isClientLightTraceEnabled()) {
+      const gpu = this.getGpuSlotTrace(movedKey)
+      recordClientLightTrace({
+        phase: 'gpuCommitted',
+        sectionKey: movedKey,
+        displayedStart: gpu?.displayedStart,
+        displayedCount: gpu?.displayedCount,
+        candidateStart: gpu?.candidateStart,
+        candidateCount: gpu?.candidateCount,
+        pendingReplace: gpu?.pendingReplace,
+        pendingMove: false,
+        unuploadedRanges: gpu?.unuploadedRanges
+      })
+    }
   }
 
   private growCapacity(minQuads: number): void {