Building Mechanics

3D Building Mechanics

Complete building system for Three.js games with performance optimization, structural physics, and multiplayer networking.

Quick Start

import { SpatialHashGrid } from './scripts/spatial-hash-grid.js';
import { HeuristicValidator } from './scripts/heuristic-validator.js';

// Spatial indexing for fast queries
const spatialIndex = new SpatialHashGrid(10);
spatialIndex.insert(piece, piece.position);
const nearby = spatialIndex.queryRadius(position, 15);

// Structural validation (Rust/Valheim style)
const validator = new HeuristicValidator({ mode: 'heuristic' });
validator.addPiece(piece);
const canPlace = validator.validatePlacement(newPiece);

Reference Files

Read these for detailed implementation guidance:

• references/performance-at-scale.md - Spatial partitioning, chunk loading, instancing, LOD
• references/structural-physics-advanced.md - Arcade vs heuristic vs realistic physics
• references/multiplayer-networking.md - Authority models, delta sync, conflict resolution

Scripts

Performance (references/performance-at-scale.md)

• scripts/spatial-hash-grid.js - O(1) queries for uniform distribution
• scripts/octree.js - Adaptive queries for clustered bases
• scripts/chunk-manager.js - World streaming for large maps
• scripts/performance-profiler.js - Benchmarking utilities

Structural Physics (references/structural-physics-advanced.md)

• scripts/heuristic-validator.js - Fast validation (Fortnite/Rust/Valheim modes)
• scripts/stability-optimizer.js - Caching and batch updates
• scripts/damage-propagation.js - Damage states, cascading collapse
• scripts/physics-engine-lite.js - Optional realistic physics

Multiplayer (references/multiplayer-networking.md)

• scripts/delta-compression.js - Only send changed state
• scripts/client-prediction.js - Optimistic placement with rollback
• scripts/conflict-resolver.js - Handle simultaneous builds
• scripts/building-network-manager.js - Complete server/client system

Key Patterns

Spatial Indexing Selection

Physics Mode Selection

• Arcade (Fortnite): Connectivity only, instant collapse, best for combat
• Heuristic (Rust/Valheim): Stability %, predictable, best for survival
• Realistic: Full stress/strain, expensive, best for engineering sims

Multiplayer Pattern

Server-authoritative with client prediction. Use delta compression for sync.

Multiplayer Networking for Building Systems

Networked building introduces challenges beyond typical game networking. Structures persist, players modify them simultaneously, and the combinatorial state space explodes. This reference covers authority models, synchronization strategies, and conflict resolution patterns used by production multiplayer building games.

The Networking Challenge

Building systems create unique networking problems:

1. State explosion: A base with 1,000 pieces has 1,000+ entities to sync, each with position, rotation, material, health, and relationships.

2. Simultaneous modification: Multiple players editing the same structure at once creates race conditions and conflicts.

3. Persistence: Unlike transient game state (player positions), buildings must survive server restarts and player disconnections.

4. Ownership complexity: Who can modify what? Rust's Tool Cupboard system exists specifically to solve building permission conflicts.

5. Bandwidth constraints: Fortnite runs at 30Hz tick rate (not 60Hz) specifically because building generates so much state change.

Authority Models

Server-Authoritative (Recommended)

The server is the single source of truth. Clients send requests; server validates and broadcasts results.

Flow:

Client: "I want to place a wall at (10, 0, 15)"
Server: Validates position, collision, permissions, resources
Server: "Wall placed with ID 4827 at (10, 0, 15)"
Server: Broadcasts to all clients
All Clients: Create wall locally

Advantages:

• Cheat-resistant (server validates everything)
• Consistent state across all clients
• Clear conflict resolution (server decides)

Disadvantages:

• Latency visible to placing player
• Server CPU load scales with player count
• Requires client prediction for responsiveness

When to use: Any competitive or persistent game. This is Rust's and Fortnite's model.

Client-Authoritative (Avoid for Building)

Clients make changes locally and inform server. Server trusts clients.

Why it fails for building:

• Trivial to cheat (spawn free resources, clip through walls)
• Conflict resolution becomes impossible
• State divergence across clients

Only viable for: Single-player with cloud save, or fully trusted clients (same-room co-op).

Hybrid Authority

Different systems use different authority. Common pattern:

• Server-authoritative: Building placement, destruction, permissions
• Client-authoritative: Camera, UI state, local preview
• Predicted: Movement, some interactions

This is the practical approach. Clients predict placement visually while server validates.

Client Prediction for Building

Players expect immediate feedback when placing. With 100ms latency, waiting for server confirmation feels sluggish. Solution: predict locally, reconcile with server.

Optimistic Placement

// Client-side
function onPlaceAttempt(piece, position, rotation) {
  // Generate temporary local ID
  const tempId = generateTempId();
  
  // Create ghost/preview immediately
  const localPiece = createLocalPiece(piece, position, rotation, tempId);
  localPiece.isPredicted = true;
  localPiece.confirmedByServer = false;
  
  // Send request to server
  sendToServer({
    type: 'place_request',
    tempId,
    pieceType: piece.type,
    position: serializeVector(position),
    rotation: serializeRotation(rotation),
    timestamp: Date.now()
  });
  
  // Add to pending predictions
  pendingPlacements.set(tempId, {
    localPiece,
    requestTime: Date.now(),
    timeout: 5000
  });
  
  return localPiece;
}

Server Confirmation

// Client receives server response
function onPlaceConfirmed(message) {
  const { tempId, serverId, success, position, rotation, reason } = message;
  
  const pending = pendingPlacements.get(tempId);
  if (!pending) return; // Already timed out
  
  pendingPlacements.delete(tempId);
  
  if (success) {
    // Replace predicted piece with confirmed
    const confirmedPiece = pending.localPiece;
    confirmedPiece.id = serverId;
    confirmedPiece.isPredicted = false;
    confirmedPiece.confirmedByServer = true;
    
    // Correct position if server adjusted it (snapping, etc.)
    if (position) {
      confirmedPiece.position.copy(deserializeVector(position));
    }
    
    buildingSystem.registerPiece(confirmedPiece);
  } else {
    // Rollback: remove predicted piece
    buildingSystem.removePiece(pending.localPiece);
    showError(reason); // "Cannot place: overlapping existing structure"
  }
}

Prediction Timeout

Predictions can't wait forever. Handle network issues gracefully.

function updatePredictions() {
  const now = Date.now();
  
  for (const [tempId, pending] of pendingPlacements) {
    if (now - pending.requestTime > pending.timeout) {
      // Assume failure after timeout
      buildingSystem.removePiece(pending.localPiece);
      pendingPlacements.delete(tempId);
      showError("Placement timed out - please try again");
    }
  }
}

Delta Compression

Sending full structure state every tick is prohibitive. Rust structures can have thousands of pieces. Solution: only send what changed.

The Source Engine Pattern

Valve's approach (used in CS, TF2, etc.):

1. Server tracks what state each client has acknowledged 2. Server computes delta (difference) from last acknowledged state 3. Server sends only the delta 4. If heavy packet loss detected, send full state to resync

class DeltaCompressor {
  constructor() {
    this.clientStates = new Map(); // clientId -> acknowledged state version
    this.stateHistory = [];        // Ring buffer of recent states
    this.maxHistory = 64;          // Keep ~1 second at 60Hz
  }
  
  recordState(state, version) {
    this.stateHistory.push({ state: this.cloneState(state), version });
    
    if (this.stateHistory.length > this.maxHistory) {
      this.stateHistory.shift();
    }
  }
  
  getDeltaForClient(clientId, currentState, currentVersion) {
    const lastAcked = this.clientStates.get(clientId) ?? 0;
    const baseState = this.findState(lastAcked);
    
    if (!baseState) {
      // Client too far behind, send full state
      return { full: true, state: currentState };
    }
    
    // Compute delta
    const delta = this.computeDelta(baseState, currentState);
    return { full: false, delta, baseVersion: lastAcked, version: currentVersion };
  }
  
  computeDelta(oldState, newState) {
    const delta = {
      added: [],
      removed: [],
      modified: []
    };
    
    // Find added pieces
    for (const [id, piece] of newState.pieces) {
      if (!oldState.pieces.has(id)) {
        delta.added.push(this.serializePiece(piece));
      } else {
        // Check for modifications
        const oldPiece = oldState.pieces.get(id);
        if (this.pieceChanged(oldPiece, piece)) {
          delta.modified.push(this.serializePieceChanges(oldPiece, piece));
        }
      }
    }
    
    // Find removed pieces
    for (const [id] of oldState.pieces) {
      if (!newState.pieces.has(id)) {
        delta.removed.push(id);
      }
    }
    
    return delta;
  }
  
  pieceChanged(oldPiece, newPiece) {
    // Quick checks for common changes
    if (oldPiece.health !== newPiece.health) return true;
    if (oldPiece.material !== newPiece.material) return true;
    if (!oldPiece.position.equals(newPiece.position)) return true;
    return false;
  }
}

Building-Specific Delta Optimization

Building pieces don't move often. Optimize for common cases:

function serializePieceChanges(oldPiece, newPiece) {
  const changes = { id: newPiece.id };
  
  // Only include changed fields
  if (oldPiece.health !== newPiece.health) {
    changes.health = newPiece.health;
  }
  if (oldPiece.material !== newPiece.material) {
    changes.material = newPiece.material;
  }
  // Position changes are rare for buildings - flag separately
  if (!oldPiece.position.equals(newPiece.position)) {
    changes.position = serializeVector(newPiece.position);
  }
  
  return changes;
}

Batching Updates

Group multiple changes into single packets:

class UpdateBatcher {
  constructor(maxBatchSize = 50, maxDelay = 50) {
    this.pending = [];
    this.maxBatchSize = maxBatchSize;
    this.maxDelay = maxDelay;
    this.lastFlush = Date.now();
  }
  
  add(update) {
    this.pending.push(update);
    
    if (this.pending.length >= this.maxBatchSize) {
      this.flush();
    }
  }
  
  update() {
    if (this.pending.length > 0 && Date.now() - this.lastFlush > this.maxDelay) {
      this.flush();
    }
  }
  
  flush() {
    if (this.pending.length === 0) return;
    
    const batch = {
      type: 'building_update_batch',
      updates: this.pending,
      timestamp: Date.now()
    };
    
    this.pending = [];
    this.lastFlush = Date.now();
    
    broadcast(batch);
  }
}

Conflict Resolution

Two players place at the same spot at the same time. Who wins?

First-Write-Wins

Simplest approach: first request to reach server succeeds.

// Server-side
function handlePlaceRequest(request, client) {
  const position = deserializeVector(request.position);
  
  // Check if position is already occupied
  if (buildingSystem.isOccupied(position)) {
    return { success: false, reason: 'Position occupied' };
  }
  
  // Atomically place and register
  const piece = buildingSystem.place(request.pieceType, position, request.rotation);
  
  return { success: true, serverId: piece.id };
}

Problem: With network latency, "first" is ambiguous. Player A clicks first but has higher latency; Player B's request arrives first.

Timestamp-Based Resolution

Include client timestamp, server decides based on who clicked first.

function handlePlaceRequest(request, client) {
  const position = deserializeVector(request.position);
  const clientTime = request.timestamp;
  
  // Check pending requests for same position
  const conflicting = pendingRequests.find(r => 
    vectorsEqual(r.position, position) &&
    r.clientTime < clientTime
  );
  
  if (conflicting) {
    // Earlier request wins
    return { success: false, reason: 'Position claimed by another player' };
  }
  
  // Hold request briefly to allow conflicts to arrive
  pendingRequests.push({
    request,
    client,
    position,
    clientTime,
    serverTime: Date.now()
  });
  
  // Process after conflict window
  setTimeout(() => processRequest(request, client), CONFLICT_WINDOW_MS);
}

Problem: Requires trusting client timestamps (cheatable) or complex clock synchronization.

Lock-Based Resolution (Rust's Tool Cupboard)

Players claim regions. Only the owner (or authorized players) can modify.

class BuildingPermissionSystem {
  constructor() {
    this.regions = new Map(); // regionId -> { owner, authorized: Set, bounds }
  }
  
  claimRegion(player, position, radius) {
    const regionId = this.generateRegionId();
    
    // Check for overlapping claims
    for (const [id, region] of this.regions) {
      if (this.regionsOverlap(region.bounds, position, radius)) {
        return { success: false, reason: 'Overlaps existing claim' };
      }
    }
    
    this.regions.set(regionId, {
      owner: player.id,
      authorized: new Set([player.id]),
      bounds: { center: position, radius }
    });
    
    return { success: true, regionId };
  }
  
  canModify(player, position) {
    for (const region of this.regions.values()) {
      if (this.isInRegion(position, region.bounds)) {
        return region.authorized.has(player.id);
      }
    }
    // Outside all regions - allow (or deny, depending on game rules)
    return true;
  }
  
  authorize(owner, playerToAuth, regionId) {
    const region = this.regions.get(regionId);
    if (!region || region.owner !== owner.id) {
      return { success: false, reason: 'Not region owner' };
    }
    
    region.authorized.add(playerToAuth.id);
    return { success: true };
  }
}

Optimistic Locking

Clients include version number. Server rejects if version is stale.

// Client request includes last known version
function placeRequest(piece, position, structureVersion) {
  return {
    type: 'place_request',
    pieceType: piece.type,
    position: serializeVector(position),
    structureVersion // Version of structure when client made decision
  };
}

// Server checks version
function handlePlaceRequest(request, client) {
  const structure = getStructureAt(request.position);
  
  if (structure && structure.version !== request.structureVersion) {
    // Structure changed since client's view - reject
    return { 
      success: false, 
      reason: 'Structure modified by another player',
      currentVersion: structure.version,
      resync: getStructureState(structure)
    };
  }
  
  // Proceed with placement, increment version
  structure.version++;
  // ... place piece ...
}

Large Structure Synchronization

A 500-piece base can't be sent every tick. Strategies for initial sync and ongoing updates.

Chunked Initial Sync

When player approaches a large structure, stream it in chunks:

class StructureStreamer {
  constructor() {
    this.chunkSize = 50; // Pieces per chunk
    this.streamDelay = 50; // ms between chunks
  }
  
  async streamStructureToClient(client, structure) {
    const pieces = Array.from(structure.pieces.values());
    const chunks = this.chunkArray(pieces, this.chunkSize);
    
    // Send metadata first
    client.send({
      type: 'structure_stream_start',
      structureId: structure.id,
      totalPieces: pieces.length,
      chunkCount: chunks.length
    });
    
    // Stream chunks
    for (let i = 0; i < chunks.length; i++) {
      await this.delay(this.streamDelay);
      
      client.send({
        type: 'structure_chunk',
        structureId: structure.id,
        chunkIndex: i,
        pieces: chunks[i].map(p => this.serializePiece(p))
      });
    }
    
    client.send({
      type: 'structure_stream_complete',
      structureId: structure.id
    });
  }
  
  chunkArray(array, size) {
    const chunks = [];
    for (let i = 0; i < array.length; i += size) {
      chunks.push(array.slice(i, i + size));
    }
    return chunks;
  }
}

Priority-Based Updates

Not all pieces are equally important. Prioritize visible/nearby pieces.

class PrioritySync {
  getPriority(piece, player) {
    let priority = 0;
    
    // Distance factor (closer = higher priority)
    const distance = piece.position.distanceTo(player.position);
    priority += Math.max(0, 100 - distance);
    
    // Visibility factor
    if (this.isInPlayerFOV(piece, player)) {
      priority += 50;
    }
    
    // Recent change factor
    const timeSinceChange = Date.now() - piece.lastModified;
    if (timeSinceChange < 1000) {
      priority += 100; // Recently changed pieces are critical
    }
    
    // Structural importance
    if (piece.type === 'foundation') {
      priority += 20;
    }
    
    return priority;
  }
  
  getUpdatesForClient(client, allUpdates, maxUpdates = 20) {
    return allUpdates
      .map(update => ({
        update,
        priority: this.getPriority(update.piece, client.player)
      }))
      .sort((a, b) => b.priority - a.priority)
      .slice(0, maxUpdates)
      .map(({ update }) => update);
  }
}

Structure IDs (Rust's Approach)

Group pieces by building. Query and sync at building level, not piece level.

class BuildingIdSystem {
  constructor() {
    this.buildings = new Map(); // buildingId -> { pieces: Set, bounds, version }
    this.pieceToBuilding = new Map(); // pieceId -> buildingId
  }
  
  addPiece(piece, nearbyPiece = null) {
    let buildingId;
    
    if (nearbyPiece) {
      // Join existing building
      buildingId = this.pieceToBuilding.get(nearbyPiece.id);
    }
    
    if (!buildingId) {
      // Create new building
      buildingId = this.generateBuildingId();
      this.buildings.set(buildingId, {
        pieces: new Set(),
        bounds: null,
        version: 1
      });
    }
    
    const building = this.buildings.get(buildingId);
    building.pieces.add(piece.id);
    building.version++;
    this.pieceToBuilding.set(piece.id, buildingId);
    this.updateBounds(building);
    
    return buildingId;
  }
  
  getBuildingPieces(buildingId) {
    const building = this.buildings.get(buildingId);
    return building ? Array.from(building.pieces) : [];
  }
  
  getBuildingsInRange(position, range) {
    const results = [];
    
    for (const [id, building] of this.buildings) {
      if (this.boundsInRange(building.bounds, position, range)) {
        results.push(id);
      }
    }
    
    return results;
  }
}

Server Performance

Building operations can strain servers. Patterns for scalability.

Rate Limiting

Prevent spam and DoS via excessive building:

class BuildingRateLimiter {
  constructor(options = {}) {
    this.maxPlacementsPerSecond = options.maxPlacementsPerSecond ?? 5;
    this.maxDestructionsPerSecond = options.maxDestructionsPerSecond ?? 10;
    this.clientBuckets = new Map();
  }
  
  checkLimit(clientId, action) {
    let bucket = this.clientBuckets.get(clientId);
    
    if (!bucket) {
      bucket = {
        placements: { count: 0, resetTime: Date.now() + 1000 },
        destructions: { count: 0, resetTime: Date.now() + 1000 }
      };
      this.clientBuckets.set(clientId, bucket);
    }
    
    const now = Date.now();
    const limit = action === 'place' 
      ? { bucket: bucket.placements, max: this.maxPlacementsPerSecond }
      : { bucket: bucket.destructions, max: this.maxDestructionsPerSecond };
    
    // Reset bucket if window passed
    if (now > limit.bucket.resetTime) {
      limit.bucket.count = 0;
      limit.bucket.resetTime = now + 1000;
    }
    
    if (limit.bucket.count >= limit.max) {
      return { allowed: false, retryAfter: limit.bucket.resetTime - now };
    }
    
    limit.bucket.count++;
    return { allowed: true };
  }
}

Async Processing

Don't block the main tick for building operations:

class AsyncBuildingProcessor {
  constructor() {
    this.queue = [];
    this.processing = false;
    this.maxProcessTimePerTick = 5; // ms
  }
  
  enqueue(operation) {
    return new Promise((resolve, reject) => {
      this.queue.push({ operation, resolve, reject });
    });
  }
  
  processTick() {
    if (this.queue.length === 0) return;
    
    const startTime = performance.now();
    
    while (this.queue.length > 0) {
      if (performance.now() - startTime > this.maxProcessTimePerTick) {
        break; // Yield to other systems
      }
      
      const { operation, resolve, reject } = this.queue.shift();
      
      try {
        const result = operation();
        resolve(result);
      } catch (error) {
        reject(error);
      }
    }
  }
}

Spatial Partitioning for Network

Only send updates to clients who can see them:

class NetworkSpatialPartition {
  constructor(cellSize = 100) {
    this.cellSize = cellSize;
    this.clientCells = new Map(); // clientId -> Set of cell keys
    this.cellClients = new Map(); // cellKey -> Set of clientIds
  }
  
  updateClientPosition(clientId, position) {
    // Remove from old cells
    const oldCells = this.clientCells.get(clientId) || new Set();
    for (const cell of oldCells) {
      this.cellClients.get(cell)?.delete(clientId);
    }
    
    // Add to new cells (with some range)
    const newCells = this.getCellsInRange(position, 200);
    this.clientCells.set(clientId, newCells);
    
    for (const cell of newCells) {
      if (!this.cellClients.has(cell)) {
        this.cellClients.set(cell, new Set());
      }
      this.cellClients.get(cell).add(clientId);
    }
  }
  
  getClientsForPosition(position) {
    const cell = this.getCellKey(position);
    return Array.from(this.cellClients.get(cell) || []);
  }
  
  broadcastToNearby(position, message, excludeClient = null) {
    const clients = this.getClientsForPosition(position);
    
    for (const clientId of clients) {
      if (clientId !== excludeClient) {
        sendToClient(clientId, message);
      }
    }
  }
}

Message Protocol

Efficient wire format for building messages.

Message Types

const BuildingMessageType = {
  // Client -> Server
  PLACE_REQUEST: 0x01,
  DESTROY_REQUEST: 0x02,
  UPGRADE_REQUEST: 0x03,
  ROTATE_REQUEST: 0x04,
  
  // Server -> Client
  PLACE_CONFIRMED: 0x10,
  PLACE_REJECTED: 0x11,
  PIECE_DESTROYED: 0x12,
  PIECE_UPDATED: 0x13,
  STRUCTURE_SYNC: 0x14,
  DELTA_UPDATE: 0x15,
  
  // Bidirectional
  PING: 0xF0,
  PONG: 0xF1
};

Binary Encoding

JSON is convenient but verbose. For high-frequency updates, binary is better:

class BuildingMessageEncoder {
  encodePlace(tempId, pieceType, position, rotation) {
    const buffer = new ArrayBuffer(26);
    const view = new DataView(buffer);
    
    let offset = 0;
    view.setUint8(offset++, BuildingMessageType.PLACE_REQUEST);
    view.setUint32(offset, tempId); offset += 4;
    view.setUint8(offset++, pieceType);
    view.setFloat32(offset, position.x); offset += 4;
    view.setFloat32(offset, position.y); offset += 4;
    view.setFloat32(offset, position.z); offset += 4;
    view.setFloat32(offset, rotation.y); offset += 4; // Only Y rotation usually needed
    
    return buffer;
  }
  
  decodePlace(buffer) {
    const view = new DataView(buffer);
    let offset = 1; // Skip type byte
    
    return {
      tempId: view.getUint32(offset), offset += 4,
      pieceType: view.getUint8(offset++),
      position: {
        x: view.getFloat32(offset), offset += 4,
        y: view.getFloat32(offset), offset += 4,
        z: view.getFloat32(offset), offset += 4
      },
      rotation: view.getFloat32(offset)
    };
  }
}

Integration Checklist

When implementing networked building:

• [ ] Choose authority model (server-authoritative recommended)
• [ ] Implement client prediction with rollback
• [ ] Add delta compression for ongoing updates
• [ ] Handle conflicts (first-write, timestamp, or lock-based)
• [ ] Implement chunked sync for large structures
• [ ] Add rate limiting to prevent abuse
• [ ] Use spatial partitioning for targeted broadcasts
• [ ] Add permission system if needed (tool cupboard style)
• [ ] Test with simulated latency and packet loss
• [ ] Profile server CPU usage under load

Related References

• building-network-manager.js - Complete networking system
• client-prediction.js - Optimistic placement and rollback
• delta-compression.js - State delta computation
• conflict-resolver.js - Conflict detection and resolution
• performance-at-scale.md - Spatial partitioning for network queries

Performance at Scale

Building systems face exponential complexity as component counts grow. A naive approach that works for 100 pieces will collapse at 1,000 and become unplayable at 10,000. This reference covers the spatial data structures, chunking strategies, and optimization patterns used by production games to handle massive player-built structures.

The Scale Problem

Every building operation involves spatial queries: "What's near this position?", "Does this overlap anything?", "What supports this piece?" Without optimization, these queries scan every object—O(n) per query. With n queries per frame, you get O(n²) complexity.

Real-world limits from production games:

• Rust: ~150,000-200,000 colliders practical limit (Unity physics "goes nuts" beyond ~150k)
• Fortnite: 30Hz server tick to manage build/destruction load for 100 players
• Minecraft: 16×16×256 chunk system enabling effectively infinite worlds
• Valheim: New terrain system in patch 0.150.3 specifically to reduce network instances

The solution is spatial partitioning—organizing objects by location so queries only examine nearby candidates.

Spatial Data Structures

Spatial Hash Grid

The simplest spatial structure. Divide world space into a uniform grid of cells. Each cell stores references to objects within it. Query time becomes O(1) for cell lookup plus O(k) for objects in that cell.

Best for:

• Uniform object distribution
• 2D or 2.5D games (terrain-based building)
• Simple implementation needs
• Component counts under 5,000

Implementation pattern:

class SpatialHashGrid {
  constructor(cellSize = 10) {
    this.cellSize = cellSize;
    this.cells = new Map();
  }

  _hash(x, y, z) {
    const cx = Math.floor(x / this.cellSize);
    const cy = Math.floor(y / this.cellSize);
    const cz = Math.floor(z / this.cellSize);
    return `${cx},${cy},${cz}`;
  }

  insert(object, position) {
    const key = this._hash(position.x, position.y, position.z);
    if (!this.cells.has(key)) {
      this.cells.set(key, new Set());
    }
    this.cells.get(key).add(object);
    object._spatialKey = key;
  }

  query(position, radius) {
    const results = [];
    const cellRadius = Math.ceil(radius / this.cellSize);
    const cx = Math.floor(position.x / this.cellSize);
    const cy = Math.floor(position.y / this.cellSize);
    const cz = Math.floor(position.z / this.cellSize);

    for (let dx = -cellRadius; dx <= cellRadius; dx++) {
      for (let dy = -cellRadius; dy <= cellRadius; dy++) {
        for (let dz = -cellRadius; dz <= cellRadius; dz++) {
          const key = `${cx + dx},${cy + dy},${cz + dz}`;
          const cell = this.cells.get(key);
          if (cell) {
            results.push(...cell);
          }
        }
      }
    }
    return results;
  }
}

Tradeoffs:

• Fixed cell size means wasted memory in sparse areas, overcrowded cells in dense areas
• Cell size tuning is critical: too small = many cells to check, too large = many objects per cell
• Rule of thumb: cell size ≈ 2-4× typical object size

Octree

A tree structure that recursively subdivides 3D space into eight octants. Adapts to object density—sparse regions stay as large nodes while dense regions subdivide further.

Best for:

• Non-uniform object distribution (bases clustered in certain areas)
• True 3D queries (tall structures, flying/underwater building)
• Component counts 5,000-10,000+
• When memory efficiency matters

Key insight from research: Octrees are "more performant for large differences in spatial density" due to adaptive scaling.

Implementation pattern:

class OctreeNode {
  constructor(bounds, depth = 0, maxDepth = 8, maxObjects = 8) {
    this.bounds = bounds; // { min: Vector3, max: Vector3 }
    this.depth = depth;
    this.maxDepth = maxDepth;
    this.maxObjects = maxObjects;
    this.objects = [];
    this.children = null; // Array of 8 OctreeNodes when subdivided
  }

  insert(object, position) {
    if (!this._containsPoint(position)) return false;

    if (this.children) {
      for (const child of this.children) {
        if (child.insert(object, position)) return true;
      }
      return false;
    }

    this.objects.push({ object, position });

    if (this.objects.length > this.maxObjects && this.depth < this.maxDepth) {
      this._subdivide();
    }
    return true;
  }

  queryRadius(center, radius, results = []) {
    if (!this._intersectsSphere(center, radius)) return results;

    for (const { object, position } of this.objects) {
      if (center.distanceTo(position) <= radius) {
        results.push(object);
      }
    }

    if (this.children) {
      for (const child of this.children) {
        child.queryRadius(center, radius, results);
      }
    }
    return results;
  }

  _subdivide() {
    const { min, max } = this.bounds;
    const mid = new THREE.Vector3().addVectors(min, max).multiplyScalar(0.5);
    
    this.children = [];
    const corners = [
      [min.x, min.y, min.z], [mid.x, min.y, min.z],
      [min.x, mid.y, min.z], [mid.x, mid.y, min.z],
      [min.x, min.y, mid.z], [mid.x, min.y, mid.z],
      [min.x, mid.y, mid.z], [mid.x, mid.y, mid.z]
    ];

    for (let i = 0; i < 8; i++) {
      const [x, y, z] = corners[i];
      const childMin = new THREE.Vector3(x, y, z);
      const childMax = new THREE.Vector3(
        x + (max.x - min.x) / 2,
        y + (max.y - min.y) / 2,
        z + (max.z - min.z) / 2
      );
      this.children.push(new OctreeNode(
        { min: childMin, max: childMax },
        this.depth + 1,
        this.maxDepth,
        this.maxObjects
      ));
    }

    // Redistribute existing objects
    for (const { object, position } of this.objects) {
      for (const child of this.children) {
        if (child.insert(object, position)) break;
      }
    }
    this.objects = [];
  }
}

Decision Framework

Chunk-Based Loading

For open worlds, keep the entire structure in memory is impossible. Chunk systems divide the world into discrete regions that load/unload based on player proximity.

Minecraft's approach: 16×16×256 block chunks. Only chunks within render distance are loaded. This enables infinite horizontal worlds while keeping memory bounded.

Key implementation concerns:

1. Chunk boundaries: Objects spanning multiple chunks need special handling. Either assign to primary chunk or duplicate references.

2. Loading priority: Not all chunks are equal. Prioritize:

• Chunks player is moving toward
• Chunks containing player-owned structures
• Chunks with recent activity

3. Async loading: Never block the main thread. Load chunk data in workers, then integrate on main thread.

class ChunkManager {
  constructor(chunkSize = 64, loadDistance = 3) {
    this.chunkSize = chunkSize;
    this.loadDistance = loadDistance;
    this.chunks = new Map();
    this.loadQueue = [];
  }

  update(playerPosition) {
    const playerChunk = this._worldToChunk(playerPosition);
    
    // Queue chunks that should be loaded
    for (let dx = -this.loadDistance; dx <= this.loadDistance; dx++) {
      for (let dz = -this.loadDistance; dz <= this.loadDistance; dz++) {
        const key = `${playerChunk.x + dx},${playerChunk.z + dz}`;
        if (!this.chunks.has(key) && !this.loadQueue.includes(key)) {
          this.loadQueue.push(key);
        }
      }
    }

    // Unload distant chunks
    for (const [key, chunk] of this.chunks) {
      const [cx, cz] = key.split(',').map(Number);
      const dist = Math.max(
        Math.abs(cx - playerChunk.x),
        Math.abs(cz - playerChunk.z)
      );
      if (dist > this.loadDistance + 1) {
        this._unloadChunk(key);
      }
    }

    // Process load queue (limit per frame)
    this._processLoadQueue(2);
  }
}

GPU Instancing

When thousands of building pieces use the same mesh (walls, floors, etc.), GPU instancing renders them in a single draw call. Instead of sending geometry repeatedly, send it once with a list of transformation matrices.

Three.js implementation:

class InstancedBuildingRenderer {
  constructor(maxInstances = 10000) {
    this.maxInstances = maxInstances;
    this.instancedMeshes = new Map(); // meshType -> InstancedMesh
  }

  createInstancedMesh(type, geometry, material) {
    const mesh = new THREE.InstancedMesh(geometry, material, this.maxInstances);
    mesh.count = 0;
    mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
    this.instancedMeshes.set(type, mesh);
    return mesh;
  }

  addInstance(type, position, rotation, scale) {
    const mesh = this.instancedMeshes.get(type);
    if (!mesh || mesh.count >= this.maxInstances) return -1;

    const matrix = new THREE.Matrix4();
    matrix.compose(position, rotation, scale);
    mesh.setMatrixAt(mesh.count, matrix);
    mesh.instanceMatrix.needsUpdate = true;
    return mesh.count++;
  }

  updateInstance(type, index, position, rotation, scale) {
    const mesh = this.instancedMeshes.get(type);
    if (!mesh || index >= mesh.count) return;

    const matrix = new THREE.Matrix4();
    matrix.compose(position, rotation, scale);
    mesh.setMatrixAt(index, matrix);
    mesh.instanceMatrix.needsUpdate = true;
  }
}

Performance impact: Fortnite's "Performance Mode" uses ultra-simplified "bubble wrap" meshes combined with aggressive instancing to maintain framerate during intense build battles.

Occlusion Culling

Don't render what the camera can't see. For building interiors, this is critical—a large base might have 1,000 pieces but only 50 visible from inside a room.

Rust's approach: Dynamic occlusion system treating all world geometry as potential occluders. Trades one frame of latency for significant CPU savings on visibility calculations. The developers noted it cut a "good chunk of CPU-side overhead."

Implementation strategies:

1. Frustum culling: Built into Three.js. Objects outside camera view aren't rendered.

2. Distance culling: Simple but effective. Don't render objects beyond a threshold.

3. Portal-based: Define portals (doorways, windows) between rooms. Only render rooms visible through portals from camera position.

class OcclusionSystem {
  constructor(camera) {
    this.camera = camera;
    this.frustum = new THREE.Frustum();
    this.projMatrix = new THREE.Matrix4();
  }

  update() {
    this.projMatrix.multiplyMatrices(
      this.camera.projectionMatrix,
      this.camera.matrixWorldInverse
    );
    this.frustum.setFromProjectionMatrix(this.projMatrix);
  }

  isVisible(object, maxDistance = 500) {
    // Distance check
    const distance = this.camera.position.distanceTo(object.position);
    if (distance > maxDistance) return false;

    // Frustum check
    if (object.geometry?.boundingSphere) {
      const sphere = object.geometry.boundingSphere.clone();
      sphere.applyMatrix4(object.matrixWorld);
      return this.frustum.intersectsSphere(sphere);
    }

    return this.frustum.containsPoint(object.position);
  }
}

Level of Detail (LOD)

Replace detailed meshes with simpler versions at distance. A wall might have 500 triangles up close, 50 at medium range, and 8 at far range.

Three.js LOD setup:

function createBuildingLOD(detailedGeo, mediumGeo, simpleGeo, material) {
  const lod = new THREE.LOD();
  
  lod.addLevel(new THREE.Mesh(detailedGeo, material), 0);    // 0-20 units
  lod.addLevel(new THREE.Mesh(mediumGeo, material), 20);     // 20-50 units
  lod.addLevel(new THREE.Mesh(simpleGeo, material), 50);     // 50+ units
  
  return lod;
}

Combining with instancing: At distance, switch from individual LOD objects to instanced batches of the simplest mesh. This gives you the best of both worlds—detail up close, massive throughput at distance.

Memory Management

Building systems can consume gigabytes if not careful. Key strategies:

1. Object pooling: Reuse removed pieces instead of garbage collecting them.

2. Geometry sharing: Never duplicate geometry. Store one copy per piece type.

3. Lazy loading: Don't load textures/materials until a piece type is actually placed.

4. Building IDs: Rust uses building IDs for fast queries—all pieces in a structure share an ID, enabling efficient ownership checks and grouped operations.

class BuildingPool {
  constructor() {
    this.pools = new Map(); // type -> array of inactive objects
  }

  acquire(type, createFn) {
    const pool = this.pools.get(type);
    if (pool && pool.length > 0) {
      const obj = pool.pop();
      obj.visible = true;
      return obj;
    }
    return createFn();
  }

  release(type, object) {
    object.visible = false;
    if (!this.pools.has(type)) {
      this.pools.set(type, []);
    }
    this.pools.get(type).push(object);
  }
}

Performance Targets

Based on industry benchmarks:

Measuring in Three.js:

const stats = new Stats();
document.body.appendChild(stats.dom);

// In render loop
stats.begin();
renderer.render(scene, camera);
stats.end();

// Log renderer info periodically
console.log('Draw calls:', renderer.info.render.calls);
console.log('Triangles:', renderer.info.render.triangles);
console.log('Geometries:', renderer.info.memory.geometries);

Integration Checklist

When implementing performance systems in your building mechanics:

• [ ] Choose spatial structure based on expected component count and distribution
• [ ] Implement chunk loading for open-world games
• [ ] Use instancing for repeated building pieces (walls, floors, etc.)
• [ ] Add distance-based culling as minimum optimization
• [ ] Pool frequently created/destroyed objects
• [ ] Profile regularly with target hardware
• [ ] Set hard limits and degrade gracefully when exceeded

Related References

• octree.js - Complete octree implementation
• spatial-hash-grid.js - Spatial hash grid implementation
• chunk-manager.js - Chunk loading/unloading system
• performance-profiler.js - Benchmarking utilities
• structural-validation.md - How spatial queries support structural checks

Structural Physics Advanced

Building games face a fundamental tension: realistic physics create satisfying, believable structures but demand enormous computation and frustrate players with unexpected collapses. This reference covers the spectrum from arcade simplicity to full simulation, with focus on the heuristic middle ground used by most successful building games.

The Physics Spectrum

Arcade Style (Fortnite, Minecraft)

No structural simulation at all. Pieces exist or don't exist. The only physics rule: if a structure becomes disconnected from any grounded piece, it collapses entirely.

Characteristics:

• Binary stability: connected = stable, disconnected = collapse
• No stress, no load distribution, no material strength
• Pieces can float if connected to something grounded
• Collapse is instant and total

Why it works: Speed. Fortnite players build during combat—checking "is this connected?" is O(1) with proper data structures. Full physics would make build battles impossible.

Implementation:

// Arcade: Just check connectivity to ground
function isStable(piece, buildingGraph) {
  return buildingGraph.hasPathToGround(piece);
}

function onPieceDestroyed(piece, buildingGraph) {
  buildingGraph.remove(piece);
  
  // Find all pieces no longer connected to ground
  const disconnected = buildingGraph.findDisconnected();
  
  // Instant collapse - no physics, just removal
  for (const p of disconnected) {
    destroyPiece(p);
  }
}

Heuristic Style (Rust, Valheim, 7 Days to Die)

Simplified stability rules that feel physics-like without simulating actual forces. Each piece has a "stability value" based on its support chain, not real stress calculations.

Rust's approach: Every piece has stability 0-100%. Ground pieces = 100%. Each piece above inherits stability minus a penalty. When stability hits 0%, the piece can't be placed or collapses.

Valheim's insight: The developers explicitly stated their system "does not work like real materials – it's more like pressure in a plumbing system, a magic force from the ground." This framing helps players build mental models.

Why it works:

• Predictable: players learn the rules and plan around them
• Fast: O(n) worst case for stability recalculation, usually O(log n) with caching
• Tunable: designers control exactly how tall/wide structures can be

The stability formula:

// Heuristic stability calculation
function calculateStability(piece, graph) {
  // Ground pieces are always 100%
  if (piece.isFoundation && piece.touchesGround) {
    return 1.0;
  }

  // Find supporting pieces
  const supports = graph.getSupports(piece);
  if (supports.length === 0) {
    return 0; // No support = unstable
  }

  // Inherit best supporter's stability minus decay
  let maxSupportStability = 0;
  for (const support of supports) {
    const supportStability = support.cachedStability ?? calculateStability(support, graph);
    maxSupportStability = Math.max(maxSupportStability, supportStability);
  }

  // Apply material-specific decay
  const decay = piece.material.stabilityDecay; // e.g., wood: 0.15, stone: 0.10
  return Math.max(0, maxSupportStability - decay);
}

Realistic Style (Medieval Engineers, Space Engineers)

Full physics simulation with stress propagation, material deformation, and dynamic fracture. Every piece has mass, every connection has strength limits.

Characteristics:

• Real load distribution through structures
• Material fatigue and breaking points
• Dynamic collapse with pieces falling realistically
• Computationally expensive

Why it's rare: The Medieval Engineers developers found players spent more time fighting physics than building. Structures collapsed unexpectedly. The "fun" ceiling was low despite technical impressiveness.

When to use: Engineering sandboxes, educational simulations, or games where structural failure IS the gameplay (bridge builders, demolition games).

Choosing Your Approach

Rule of thumb: If building happens during combat or time pressure, use arcade. If building is a primary activity players spend hours on, use heuristic. Only use realistic if structural engineering IS your game.

Implementing Heuristic Physics

The Support Graph

Model structures as directed graphs where edges represent "supports" relationships.

class SupportGraph {
  constructor() {
    this.nodes = new Map();      // pieceId -> piece
    this.supports = new Map();   // pieceId -> Set of pieces this supports
    this.supportedBy = new Map(); // pieceId -> Set of pieces supporting this
  }

  addPiece(piece) {
    this.nodes.set(piece.id, piece);
    this.supports.set(piece.id, new Set());
    this.supportedBy.set(piece.id, new Set());
  }

  addSupport(supporter, supported) {
    this.supports.get(supporter.id).add(supported);
    this.supportedBy.get(supported.id).add(supporter);
  }

  getSupports(piece) {
    return Array.from(this.supportedBy.get(piece.id) || []);
  }

  getSupportedPieces(piece) {
    return Array.from(this.supports.get(piece.id) || []);
  }

  removePiece(piece) {
    // Remove all support relationships
    for (const supported of this.supports.get(piece.id) || []) {
      this.supportedBy.get(supported.id)?.delete(piece);
    }
    for (const supporter of this.supportedBy.get(piece.id) || []) {
      this.supports.get(supporter.id)?.delete(piece);
    }
    
    this.nodes.delete(piece.id);
    this.supports.delete(piece.id);
    this.supportedBy.delete(piece.id);
  }
}

Stability Propagation

When a piece is destroyed, stability changes ripple upward through dependent pieces.

class StabilitySystem {
  constructor(graph) {
    this.graph = graph;
    this.stabilityCache = new Map();
    this.minStability = 0.05; // Below this = collapse
  }

  /**
   * Recalculate stability for affected pieces after destruction
   */
  onPieceDestroyed(piece) {
    const affected = this.getAffectedPieces(piece);
    this.graph.removePiece(piece);
    
    // Clear cache for affected pieces
    for (const p of affected) {
      this.stabilityCache.delete(p.id);
    }

    // Recalculate and find collapses
    const toCollapse = [];
    for (const p of affected) {
      const stability = this.calculateStability(p);
      if (stability < this.minStability) {
        toCollapse.push(p);
      }
    }

    return toCollapse;
  }

  /**
   * Get all pieces that depend on this piece for support
   */
  getAffectedPieces(piece) {
    const affected = new Set();
    const queue = [piece];

    while (queue.length > 0) {
      const current = queue.shift();
      const supported = this.graph.getSupportedPieces(current);
      
      for (const p of supported) {
        if (!affected.has(p)) {
          affected.add(p);
          queue.push(p);
        }
      }
    }

    return affected;
  }

  /**
   * Calculate stability with caching
   */
  calculateStability(piece) {
    if (this.stabilityCache.has(piece.id)) {
      return this.stabilityCache.get(piece.id);
    }

    const stability = this._computeStability(piece);
    this.stabilityCache.set(piece.id, stability);
    return stability;
  }

  _computeStability(piece) {
    // Foundations touching ground are 100% stable
    if (piece.type === 'foundation' && piece.onGround) {
      return 1.0;
    }

    const supports = this.graph.getSupports(piece);
    if (supports.length === 0) {
      return 0;
    }

    // Find maximum stability from supporters
    let maxStability = 0;
    for (const supporter of supports) {
      const supporterStability = this.calculateStability(supporter);
      maxStability = Math.max(maxStability, supporterStability);
    }

    // Apply decay based on piece type and material
    const decay = this.getDecayRate(piece);
    return Math.max(0, maxStability - decay);
  }

  getDecayRate(piece) {
    // Vertical pieces (walls, pillars) decay less than horizontal (floors, roofs)
    const baseDecay = piece.material?.stabilityDecay ?? 0.1;
    const orientationMultiplier = piece.isVertical ? 0.5 : 1.0;
    return baseDecay * orientationMultiplier;
  }
}

Support Detection

Determining which pieces support which requires geometric analysis.

class SupportDetector {
  constructor(options = {}) {
    this.snapTolerance = options.snapTolerance ?? 0.1;
  }

  /**
   * Find all support relationships for a piece
   */
  findSupports(piece, allPieces) {
    const supports = [];

    for (const other of allPieces) {
      if (other === piece) continue;

      if (this.canSupport(other, piece)) {
        supports.push(other);
      }
    }

    return supports;
  }

  /**
   * Check if 'supporter' can support 'piece'
   */
  canSupport(supporter, piece) {
    // Supporter must be below or at same level
    if (supporter.bounds.max.y < piece.bounds.min.y - this.snapTolerance) {
      return false;
    }

    // Must be within snap tolerance vertically
    const verticalGap = piece.bounds.min.y - supporter.bounds.max.y;
    if (verticalGap > this.snapTolerance) {
      return false;
    }

    // Check horizontal overlap
    return this.hasHorizontalOverlap(supporter, piece);
  }

  hasHorizontalOverlap(a, b) {
    const overlapX = a.bounds.max.x > b.bounds.min.x && a.bounds.min.x < b.bounds.max.x;
    const overlapZ = a.bounds.max.z > b.bounds.min.z && a.bounds.min.z < b.bounds.max.z;
    return overlapX && overlapZ;
  }

  /**
   * Determine support type for visual feedback
   */
  getSupportType(supporter, piece) {
    const centerDist = Math.abs(supporter.position.x - piece.position.x) +
                       Math.abs(supporter.position.z - piece.position.z);
    
    if (supporter.type === 'foundation' && supporter.onGround) {
      return 'ground';
    } else if (supporter.type === 'pillar' || supporter.type === 'wall') {
      return 'vertical';
    } else if (centerDist < 0.5) {
      return 'direct'; // Directly above
    } else {
      return 'cantilever'; // Offset support
    }
  }
}

Damage and Partial Destruction

Real structures don't collapse all at once. Implement damage states for more interesting gameplay.

Damage States

const DamageState = {
  PRISTINE: 'pristine',     // Full health
  DAMAGED: 'damaged',       // Visible damage, reduced stability
  CRITICAL: 'critical',     // Near collapse, major stability penalty
  DESTROYED: 'destroyed'    // Gone
};

class DamageableBuilding {
  constructor(piece) {
    this.piece = piece;
    this.maxHealth = piece.material.health;
    this.health = this.maxHealth;
    this.damageState = DamageState.PRISTINE;
  }

  takeDamage(amount) {
    this.health = Math.max(0, this.health - amount);
    this.updateDamageState();
    return this.damageState;
  }

  updateDamageState() {
    const healthPercent = this.health / this.maxHealth;

    if (healthPercent <= 0) {
      this.damageState = DamageState.DESTROYED;
    } else if (healthPercent <= 0.25) {
      this.damageState = DamageState.CRITICAL;
    } else if (healthPercent <= 0.6) {
      this.damageState = DamageState.DAMAGED;
    } else {
      this.damageState = DamageState.PRISTINE;
    }
  }

  getStabilityModifier() {
    switch (this.damageState) {
      case DamageState.PRISTINE: return 1.0;
      case DamageState.DAMAGED: return 0.8;
      case DamageState.CRITICAL: return 0.5;
      default: return 0;
    }
  }
}

Cascading Damage

When a piece is destroyed, adjacent pieces may take damage from the collapse.

class DamageSystem {
  constructor(stabilitySystem) {
    this.stability = stabilitySystem;
    this.damagePropagation = 0.3; // Collapse does 30% damage to neighbors
  }

  destroyPiece(piece) {
    const results = {
      destroyed: [piece],
      damaged: [],
      collapsed: []
    };

    // Find pieces that will collapse due to stability loss
    const unstable = this.stability.onPieceDestroyed(piece);
    
    // Process collapses in order (bottom to top)
    unstable.sort((a, b) => a.position.y - b.position.y);
    
    for (const p of unstable) {
      results.collapsed.push(p);
      
      // Propagate damage to neighbors
      const neighbors = this.getAdjacentPieces(p);
      for (const neighbor of neighbors) {
        if (!results.destroyed.includes(neighbor) && 
            !results.collapsed.includes(neighbor)) {
          const damage = p.mass * this.damagePropagation;
          const newState = neighbor.takeDamage(damage);
          
          if (newState === DamageState.DESTROYED) {
            results.destroyed.push(neighbor);
          } else if (newState !== DamageState.PRISTINE) {
            results.damaged.push(neighbor);
          }
        }
      }
    }

    return results;
  }
}

Visual Feedback

Players need to understand stability without studying numbers.

Stability Visualization (Valheim Style)

Valheim uses color coding: blue/green = strong, yellow = moderate, red = weak.

class StabilityVisualizer {
  constructor() {
    this.colors = {
      excellent: new THREE.Color(0x4488ff), // Blue - grounded
      good: new THREE.Color(0x44ff44),      // Green - stable
      moderate: new THREE.Color(0xffff44),  // Yellow - getting weak
      weak: new THREE.Color(0xff8844),      // Orange - danger
      critical: new THREE.Color(0xff4444)   // Red - about to collapse
    };
  }

  getStabilityColor(stability) {
    if (stability >= 0.9) return this.colors.excellent;
    if (stability >= 0.7) return this.colors.good;
    if (stability >= 0.5) return this.colors.moderate;
    if (stability >= 0.25) return this.colors.weak;
    return this.colors.critical;
  }

  /**
   * Apply stability coloring to building pieces
   */
  visualizeStability(pieces, stabilitySystem, enabled = true) {
    for (const piece of pieces) {
      if (!enabled) {
        piece.mesh.material.color.setHex(piece.originalColor);
        continue;
      }

      const stability = stabilitySystem.calculateStability(piece);
      const color = this.getStabilityColor(stability);
      piece.mesh.material.color.copy(color);
    }
  }

  /**
   * Create stability indicator UI element
   */
  createStabilityIndicator(piece, stabilitySystem) {
    const stability = stabilitySystem.calculateStability(piece);
    const percent = Math.round(stability * 100);
    const color = this.getStabilityColor(stability);

    return {
      text: `${percent}%`,
      color: `#${color.getHexString()}`,
      position: piece.position.clone().add(new THREE.Vector3(0, 2, 0))
    };
  }
}

Collapse Animation

Instant disappearance feels wrong. Animate collapses for feedback.

class CollapseAnimator {
  constructor(scene) {
    this.scene = scene;
    this.activeCollapses = [];
  }

  /**
   * Animate a piece collapsing
   */
  collapse(piece, delay = 0) {
    const animation = {
      piece,
      startTime: performance.now() + delay,
      duration: 800 + Math.random() * 400,
      startPosition: piece.position.clone(),
      startRotation: piece.rotation.clone(),
      velocity: new THREE.Vector3(
        (Math.random() - 0.5) * 2,
        -5,
        (Math.random() - 0.5) * 2
      ),
      angularVelocity: new THREE.Vector3(
        (Math.random() - 0.5) * 3,
        (Math.random() - 0.5) * 3,
        (Math.random() - 0.5) * 3
      ),
      phase: 'waiting'
    };

    this.activeCollapses.push(animation);
    return animation;
  }

  /**
   * Animate multiple pieces with cascading delay
   */
  collapseMultiple(pieces) {
    // Sort by height (top pieces fall last for visual effect)
    pieces.sort((a, b) => b.position.y - a.position.y);

    pieces.forEach((piece, index) => {
      this.collapse(piece, index * 50); // 50ms stagger
    });
  }

  /**
   * Update all active collapse animations
   */
  update(deltaTime) {
    const now = performance.now();
    const gravity = -20;

    for (let i = this.activeCollapses.length - 1; i >= 0; i--) {
      const anim = this.activeCollapses[i];

      if (anim.phase === 'waiting') {
        if (now >= anim.startTime) {
          anim.phase = 'falling';
          anim.fallStart = now;
        }
        continue;
      }

      const elapsed = now - anim.fallStart;
      const t = Math.min(elapsed / anim.duration, 1);

      // Apply physics
      const piece = anim.piece;
      piece.position.x = anim.startPosition.x + anim.velocity.x * t;
      piece.position.y = anim.startPosition.y + anim.velocity.y * t + 0.5 * gravity * t * t;
      piece.position.z = anim.startPosition.z + anim.velocity.z * t;

      piece.rotation.x = anim.startRotation.x + anim.angularVelocity.x * t;
      piece.rotation.y = anim.startRotation.y + anim.angularVelocity.y * t;
      piece.rotation.z = anim.startRotation.z + anim.angularVelocity.z * t;

      // Fade out
      if (piece.mesh.material.opacity !== undefined) {
        piece.mesh.material.transparent = true;
        piece.mesh.material.opacity = 1 - t;
      }

      // Remove when done
      if (t >= 1) {
        this.scene.remove(piece.mesh);
        this.activeCollapses.splice(i, 1);
      }
    }
  }
}

Performance Considerations

Caching Strategy

Stability calculations can be expensive. Cache aggressively.

class CachedStabilitySystem {
  constructor(graph) {
    this.graph = graph;
    this.cache = new Map();
    this.dirty = new Set(); // Pieces needing recalculation
  }

  invalidate(piece) {
    // Mark this piece and all dependent pieces as dirty
    this.dirty.add(piece.id);
    
    const dependents = this.graph.getAffectedPieces(piece);
    for (const dep of dependents) {
      this.dirty.add(dep.id);
      this.cache.delete(dep.id);
    }
  }

  getStability(piece) {
    if (!this.dirty.has(piece.id) && this.cache.has(piece.id)) {
      return this.cache.get(piece.id);
    }

    const stability = this.calculateStability(piece);
    this.cache.set(piece.id, stability);
    this.dirty.delete(piece.id);
    return stability;
  }

  /**
   * Batch recalculate all dirty pieces
   * Call this once per frame, not per piece
   */
  recalculateDirty() {
    // Sort dirty pieces by support order (bottom to top)
    const sorted = Array.from(this.dirty)
      .map(id => this.graph.nodes.get(id))
      .filter(p => p)
      .sort((a, b) => a.position.y - b.position.y);

    for (const piece of sorted) {
      this.getStability(piece);
    }

    this.dirty.clear();
  }
}

Event-Driven Updates

Only recalculate when something changes.

class EventDrivenStability {
  constructor() {
    this.listeners = new Set();
  }

  // Called when piece is placed
  onPiecePlaced(piece) {
    this.invalidateAffected(piece);
    this.scheduleRecalculation();
  }

  // Called when piece is destroyed
  onPieceDestroyed(piece) {
    this.invalidateAffected(piece);
    this.scheduleRecalculation();
  }

  // Debounce recalculations
  scheduleRecalculation() {
    if (this.recalcTimer) return;
    
    this.recalcTimer = requestAnimationFrame(() => {
      this.recalcTimer = null;
      this.recalculateAll();
      this.notifyListeners();
    });
  }
}

Material Properties

Different materials create different building constraints.

const Materials = {
  WOOD: {
    name: 'Wood',
    health: 100,
    stabilityDecay: 0.15,      // Loses 15% per piece
    maxStackHeight: 6,          // Can stack ~6 pieces high
    buildTime: 1.0,
    upgradeTo: 'STONE'
  },
  STONE: {
    name: 'Stone',
    health: 300,
    stabilityDecay: 0.10,      // Loses 10% per piece
    maxStackHeight: 10,
    buildTime: 2.0,
    upgradeTo: 'METAL'
  },
  METAL: {
    name: 'Metal',
    health: 500,
    stabilityDecay: 0.05,      // Loses 5% per piece
    maxStackHeight: 20,
    buildTime: 3.0,
    upgradeTo: null
  },
  THATCH: {
    name: 'Thatch',
    health: 50,
    stabilityDecay: 0.20,
    maxStackHeight: 4,
    buildTime: 0.5,
    upgradeTo: 'WOOD'
  }
};

// Helper to check if placement is valid
function canPlace(piece, stabilitySystem) {
  const stability = stabilitySystem.calculateStability(piece);
  return stability >= 0.05; // Minimum 5% to place
}

Integration Checklist

When implementing structural physics in your building system:

• [ ] Choose physics approach based on game type (arcade/heuristic/realistic)
• [ ] Implement support graph for tracking piece relationships
• [ ] Add stability calculation with appropriate decay rates
• [ ] Cache stability values and invalidate on changes
• [ ] Implement visual feedback (colors, indicators)
• [ ] Add collapse animations for destroyed pieces
• [ ] Handle cascading damage for connected pieces
• [ ] Tune material properties for desired building limits
• [ ] Test with maximum expected structure sizes
• [ ] Profile stability recalculation performance

Related References

• heuristic-validator.js - Fast arcade/heuristic stability checking
• stability-optimizer.js - Caching and batch recalculation
• damage-propagation.js - Damage states and cascading destruction
• physics-engine-lite.js - Optional realistic physics mode
• structural-validation.md - Original structural validation reference