Tree Instancing API

Overview

The GLBTreeBatchedInstancer module provides BatchedMesh-based rendering for multi-variant trees with minimal draw calls.

Source: packages/shared/src/systems/shared/world/GLBTreeBatchedInstancer.tsAdded in commits 82a5365 and 6c14c8e (March 12, 2026).

Initialization

initGLBTreeBatchedInstancer

function initGLBTreeBatchedInstancer(scene: THREE.Scene, world: World): void

Initializes the tree instancing system. Parameters:

scene - Three.js scene for adding BatchedMesh instances
world - World instance for material setup

Example:

import { initGLBTreeBatchedInstancer } from '@hyperscape/shared';

// Initialize on world startup
initGLBTreeBatchedInstancer(world.stage.scene, world);

destroyGLBTreeBatchedInstancer

function destroyGLBTreeBatchedInstancer(): void

Destroys all tree instances and cleans up resources. Example:

import { destroyGLBTreeBatchedInstancer } from '@hyperscape/shared';

// Cleanup on world shutdown
destroyGLBTreeBatchedInstancer();

Instance Management

addInstance

async function addInstance(
  treeType: string,
  variantPaths: string[],
  variantIndex: number,
  entityId: string,
  position: THREE.Vector3,
  rotation: number,
  scale: number,
  depletedModelPath?: string | null,
  depletedScale?: number
): Promise<boolean>

Adds a tree instance to the rendering system. Parameters:

treeType - Tree type identifier (e.g., “oak”, “birch”)
variantPaths - Array of model paths for variants (e.g., [“oak_1.glb”, “oak_2.glb”])
variantIndex - Index of variant to use (0-based)
entityId - Unique entity ID
position - World position (THREE.Vector3)
rotation - Y-axis rotation in radians
scale - Uniform scale multiplier
depletedModelPath - Optional path to depleted model (stump)
depletedScale - Optional scale for depleted model

Returns: Promise<boolean> - true if successful, false if failed Example:

import { addInstance } from '@hyperscape/shared';

const success = await addInstance(
  'oak',                          // Tree type
  ['oak_1.glb', 'oak_2.glb', 'oak_3.glb'], // Variant paths
  0,                              // Use first variant
  'tree-123',                     // Entity ID
  new THREE.Vector3(100, 0, 200), // Position
  Math.PI / 4,                    // 45° rotation
  1.0,                            // Normal scale
  'oak_stump.glb',               // Depleted model
  0.8                             // Stump scale (80%)
);

if (success) {
  console.log('Tree instance added');
} else {
  console.error('Failed to add tree instance');
}

removeInstance

function removeInstance(entityId: string): void

Removes a tree instance from the rendering system. Parameters:

entityId - Entity ID of tree to remove

Example:

import { removeInstance } from '@hyperscape/shared';

// Remove tree instance
removeInstance('tree-123');

State Management

setDepleted

function setDepleted(entityId: string, depleted: boolean): void

Sets the depleted state of a tree (shows stump or normal tree). Parameters:

entityId - Entity ID of tree
depleted - true to show stump, false to show normal tree

Example:

import { setDepleted } from '@hyperscape/shared';

// Tree chopped down - show stump
setDepleted('tree-123', true);

// Tree respawned - show normal tree
setDepleted('tree-123', false);

Behavior:

Removes instance from current LOD pool
Adds instance to depleted pool (or normal pool)
Uses depletedScale for stump size
Preserves position and rotation

setHighlight

function setHighlight(entityId: string, on: boolean): void

Highlights a tree instance (1.15x color multiplier). Parameters:

entityId - Entity ID of tree
on - true to highlight, false to remove highlight

Example:

import { setHighlight } from '@hyperscape/shared';

// Highlight tree on hover
setHighlight('tree-123', true);

// Remove highlight
setHighlight('tree-123', false);

Behavior:

Only one tree can be highlighted at a time
Automatically removes previous highlight when highlighting new tree
Highlight persists across LOD transitions

clearHighlight

function clearHighlight(): void

Clears all tree highlights. Example:

import { clearHighlight } from '@hyperscape/shared';

// Clear all highlights
clearHighlight();

Utility Functions

hasInstance

function hasInstance(entityId: string): boolean

Checks if an entity has a tree instance. Parameters:

entityId - Entity ID to check

Returns: true if instance exists, false otherwise Example:

import { hasInstance } from '@hyperscape/shared';

if (hasInstance('tree-123')) {
  console.log('Tree instance exists');
}

hasDepleted

function hasDepleted(entityId: string): boolean

Checks if a tree has a depleted model available. Parameters:

entityId - Entity ID to check

Returns: true if depleted model available, false otherwise Example:

import { hasDepleted } from '@hyperscape/shared';

if (hasDepleted('tree-123')) {
  // Can show stump
  setDepleted('tree-123', true);
} else {
  console.warn('No depleted model for tree-123');
}

getModelDimensions

function getModelDimensions(entityId: string): { height: number; radius: number } | null

Gets the model dimensions for a tree instance. Parameters:

entityId - Entity ID to query

Returns: Object with height and radius in meters, or null if not found Example:

import { getModelDimensions } from '@hyperscape/shared';

const dims = getModelDimensions('tree-123');
if (dims) {
  console.log(`Tree height: ${dims.height}m, radius: ${dims.radius}m`);
  
  // Use for collision detection
  const collisionRadius = dims.radius * 1.1; // 10% buffer
}

Update Loop

updateGLBTreeBatchedInstancer

function updateGLBTreeBatchedInstancer(): void

Updates LOD levels and material uniforms. Call once per frame. Example:

import { updateGLBTreeBatchedInstancer } from '@hyperscape/shared';

// In render loop
function animate() {
  updateGLBTreeBatchedInstancer();
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

Behavior:

Switches LOD levels based on camera distance
Updates dissolve uniforms (camera pos, player pos, sun direction, wind)
Preserves highlight state across LOD transitions
Uses hysteresis (0.81x) to prevent flickering

Constants

MAX_INSTANCES

const MAX_INSTANCES = 512;

Maximum number of instances per BatchedMesh. Usage:

Limit instance count per tree type to 512
Split into multiple tree types if needed
Prevents BatchedMesh overflow

Type Definitions

TreeSlot

interface TreeSlot {
  entityId: string;
  position: THREE.Vector3;
  rotation: number;
  scale: number;
  depletedScale: number;
  yOffset: number;
  currentLOD: 0 | 1 | 2;
  depleted: boolean;
  variantIndex: number;
}

Internal slot tracking for tree instances.

BatchedLODPool

interface BatchedLODPool {
  batches: THREE.BatchedMesh[];
  materials: DissolveMaterial[];
  geometryIds: number[][];
  instanceIds: Map<string, number[]>;
}

Pool of BatchedMesh instances for a specific LOD level.

TreeTypePool

interface TreeTypePool {
  treeType: string;
  variantPaths: string[];
  lod0: BatchedLODPool | null;
  lod1: BatchedLODPool | null;
  lod2: BatchedLODPool | null;
  depleted: BatchedLODPool | null;
  instances: Map<string, TreeSlot>;
  yOffset: number;
  depletedYOffset: number;
  modelHeight: number;
  modelRadius: number;
}

Pool of all LOD levels for a specific tree type.

Error Handling

Model Load Failures

try {
  const success = await addInstance(/* ... */);
  if (!success) {
    console.warn('Failed to add tree instance');
  }
} catch (error) {
  console.error('Tree instancing error:', error);
}

Common Causes:

Model file not found
Invalid model format
Texture loading failure
Out of memory

Variant Matching Failures

// Console warnings when variants don't match
[GLBTreeBatchedInstancer] Variant oak_2.glb has 3 parts, expected 2!
[GLBTreeBatchedInstancer] Could not match parts for oak_3.glb — using original order

Causes:

Variants have different numbers of meshes
Material slot order differs between variants
Texture dimensions don’t match

Solution: Ensure all variants have identical mesh structure.

Best Practices

Use consistent material slots

Ensure all variants have materials in the same order (bark first, leaves second). This allows texture fingerprinting to work correctly.

Provide depleted models

Always provide a depleted model (stump) for harvestable trees. This improves visual feedback when trees are chopped.

Use LOD models

Provide LOD1 and LOD2 models for better performance at distance. Use inferLOD1Path() and inferLOD2Path() naming convention.

Limit instance count

Keep instance count below MAX_INSTANCES (512) per tree type. Split into multiple tree types if needed.

Call update every frame

Call updateGLBTreeBatchedInstancer() once per frame to update LOD levels and material uniforms.

Terrain LOD API

TerrainQuadTree and TerrainQuadNode API

Biome API

BiomeType enum and tree configuration

Resource System

Resource spawning and gathering

GPU Materials

TSL-based materials with dissolve effects

​Overview

​Initialization

​initGLBTreeBatchedInstancer

​destroyGLBTreeBatchedInstancer

​Instance Management

​addInstance

​removeInstance

​State Management

​setDepleted

​setHighlight

​clearHighlight

​Utility Functions

​hasInstance

​hasDepleted

​getModelDimensions

​Update Loop

​updateGLBTreeBatchedInstancer

​Constants

​MAX_INSTANCES

​Type Definitions

​TreeSlot

​BatchedLODPool

​TreeTypePool

​Error Handling

​Model Load Failures

​Variant Matching Failures

​Best Practices

​Related APIs

Terrain LOD API

Biome API

Resource System

GPU Materials

Overview

Initialization

initGLBTreeBatchedInstancer

destroyGLBTreeBatchedInstancer

Instance Management

addInstance

removeInstance

State Management

setDepleted

setHighlight

clearHighlight

Utility Functions

hasInstance

hasDepleted

getModelDimensions

Update Loop

updateGLBTreeBatchedInstancer

Constants

MAX_INSTANCES

Type Definitions

TreeSlot

BatchedLODPool

TreeTypePool

Error Handling

Model Load Failures

Variant Matching Failures

Best Practices

Related APIs