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.
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.
| name | performance-at-scale |
|---|---|
| description | 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. |
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 distributionscripts/octree.js- Adaptive queries for clustered objectsscripts/chunk-manager.js- World streaming for large mapsscripts/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 |