Terrain LOD API

new TerrainQuadTree(config?: Partial<QuadTreeConfig>)

const quadTree = new TerrainQuadTree({
  minSize: 100,
  maxDepth: 4,
  splitRatio: 1.5,
  unsplitMultiplier: 1.2,
  resolution: 32,
  skirtDrop: 15,
});

setListener(listener: QuadTreeListener): void

quadTree.setListener({
  onNodeNeedsGeometry(node: TerrainQuadNode) {
    generateTerrainChunk(node);
  },
  onNodeDestroyGeometry(node: TerrainQuadNode) {
    destroyTerrainChunk(node);
  },
});

update(playerX: number, playerZ: number): boolean

const camera = world.camera;
const structureChanged = quadTree.update(camera.position.x, camera.position.z);

if (structureChanged) {
  console.log('Terrain LOD updated');
}

getFinalNodes(): TerrainQuadNode[]

const finalNodes = quadTree.getFinalNodes();
console.log(`Active chunks: ${finalNodes.length}`);

for (const node of finalNodes) {
  console.log(`Chunk at (${node.centerX}, ${node.centerZ}), size: ${node.size}m`);
}

dispose(): void

// Cleanup on world shutdown
quadTree.dispose();

get totalNodeCount(): number

console.log(`Total nodes: ${quadTree.totalNodeCount}`);

get visualChunkCount(): number

console.log(`Visual chunks: ${quadTree.visualChunkCount}`);

readonly id: number;                    // Unique node ID
readonly tree: TerrainQuadTree;         // Parent tree reference
readonly parent: TerrainQuadNode | null; // Parent node (null for root)
readonly quadPosition: QuadPosition | null; // Position in parent (ne/nw/sw/se)
readonly size: number;                  // Chunk size in meters
readonly halfSize: number;              // size * 0.5
readonly quarterSize: number;           // halfSize * 0.5
readonly centerX: number;               // World X coordinate
readonly centerZ: number;               // World Z coordinate
readonly depth: number;                 // Depth in tree (0 = root)
readonly precision: number;             // Normalized LOD: 0 at root → 1 at max depth
readonly isMaxDepth: boolean;           // True when at maximum subdivision depth

children: Map<QuadPosition, TerrainQuadNode>; // Child nodes (when split)
neighbours: Map<CardinalDirection, TerrainQuadNode | null>; // Adjacent nodes
splitted: boolean;                      // True when node has children
splitting: boolean;                     // True during split operation
unsplitting: boolean;                   // True during unsplit operation
ready: boolean;                         // True when geometry is ready
needsCheck: boolean;                    // True when split/unsplit check needed
isFinal: boolean;                       // True when leaf node with geometry
terrainNeedsUpdate: boolean;            // True when geometry needs generation
visualChunkKey: string | null;          // Assigned by TerrainVisualManager

readonly boundingBox: {
  xMin: number;
  xMax: number;
  zMin: number;
  zMax: number;
};

check(): void

update(): void

setNeighbours(
  n: TerrainQuadNode | null,
  e: TerrainQuadNode | null,
  s: TerrainQuadNode | null,
  w: TerrainQuadNode | null
): void

isInside(x: number, z: number): boolean

getDeepestNodeAt(x: number, z: number): TerrainQuadNode | null

interface QuadTreeListener {
  onNodeNeedsGeometry(node: TerrainQuadNode): void;
  onNodeDestroyGeometry(node: TerrainQuadNode): void;
}

onNodeNeedsGeometry(node: TerrainQuadNode): void {
  // Generate terrain mesh
  const geometry = new THREE.PlaneGeometry(
    node.size,
    node.size,
    node.resolution,
    node.resolution
  );
  
  // Apply height data
  applyHeightData(geometry, node);
  
  // Add skirts
  addSkirtGeometry(geometry, node.tree.config.skirtDrop);
  
  // Create mesh
  const mesh = new THREE.Mesh(geometry, terrainMaterial);
  mesh.position.set(node.centerX, 0, node.centerZ);
  mesh.rotation.x = -Math.PI / 2;
  
  // Store reference
  node.visualChunkKey = `chunk_${node.id}`;
  this.chunks.set(node.visualChunkKey, mesh);
  
  // Add to scene
  this.scene.add(mesh);
  
  // Mark ready
  node.testReady();
}

onNodeDestroyGeometry(node: TerrainQuadNode): void {
  const mesh = this.chunks.get(node.visualChunkKey);
  if (mesh) {
    this.scene.remove(mesh);
    mesh.geometry.dispose();
    this.chunks.delete(node.visualChunkKey);
  }
}

interface QuadTreeConfig {
  minSize: number;
  maxDepth: number;
  splitRatio: number;
  unsplitMultiplier: number;
  resolution: number;
  skirtDrop: number;
}

const config: QuadTreeConfig = {
  minSize: 100,           // 100m leaf chunks
  maxDepth: 4,            // 5 LOD levels (0-4)
  splitRatio: 1.5,        // Split at 150m for 100m chunk
  unsplitMultiplier: 1.2, // Unsplit at 180m (prevents thrashing)
  resolution: 32,         // 32×32 vertices per chunk
  skirtDrop: 15,          // 15m skirt depth
};

type QuadPosition = "ne" | "nw" | "sw" | "se";

type CardinalDirection = "n" | "e" | "s" | "w";