performance-at-scale

Spatial indexing and world streaming for Three.js building games with thousands of pieces. Use when optimizing building games, implementing spatial queries, chunk loading, or profiling performance. Includes spatial hash grids, octrees, chunk managers, and benchmarking tools.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025

When & Why to Use This Skill

This Claude skill provides a comprehensive toolkit for optimizing Three.js building games through advanced spatial indexing and world streaming. It enables developers to handle thousands of entities efficiently using spatial hash grids, octrees, and chunk management, ensuring high-performance rendering and smooth gameplay in large-scale 3D environments by implementing industry-standard spatial partitioning patterns.

Use Cases

  • Optimizing 3D Building Games: Maintain high frame rates in Three.js applications by using spatial hash grids to manage and query thousands of individual building components efficiently.
  • Implementing Large-Scale World Streaming: Use the ChunkManager to dynamically load and unload game sections based on camera position, significantly reducing memory overhead and initial load times.
  • Efficient Proximity and Collision Queries: Implement octrees for clustered object distributions to perform lightning-fast 'find nearby' queries or collision detection in complex 3D scenes.
  • Performance Profiling and Benchmarking: Utilize built-in benchmarking tools to compare different spatial partitioning strategies (Grid vs. Octree) and select the optimal architecture for specific game distributions.
nameperformance-at-scale
descriptionSpatial indexing and world streaming for Three.js building games with thousands of pieces. Use when optimizing building games, implementing spatial queries, chunk loading, or profiling performance. Includes spatial hash grids, octrees, chunk managers, and benchmarking tools.

Performance at Scale

Spatial indexing and world streaming for large-scale building systems.

Quick Start

import { SpatialHashGrid } from './scripts/spatial-hash-grid.js';
import { Octree } from './scripts/octree.js';

// Uniform distribution - use hash grid
const grid = new SpatialHashGrid(10);
grid.insert(piece, piece.position);
const nearby = grid.queryRadius(position, 15);

// Clustered bases - use octree
const octree = new Octree(bounds, { maxDepth: 8 });
octree.insert(piece);
const inBox = octree.queryBox(min, max);

Reference

See references/performance-at-scale.md for detailed guidance on:

  • Spatial partitioning selection (when to use grid vs octree)
  • Chunk loading strategies
  • Instancing and LOD
  • Memory management

Scripts

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

Selection Guide

Pieces Distribution Use
<1,000 Any Array
1-5k Uniform SpatialHashGrid
1-5k Clustered Octree
5k+ Any ChunkManager + Octree per chunk