playbooks

home / skills / bbeierle12 / skill-mcp-claude / performance-at-scale

performance-at-scale skill

/skills/performance-at-scale

This skill helps you optimize large-scale building games by applying spatial indexing, chunking, and benchmarking to improve rendering and world loading.

npx playbooks add skill bbeierle12/skill-mcp-claude --skill performance-at-scale

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
1.5 KB
---
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

```javascript
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 |

Overview

This skill provides spatial indexing and world streaming utilities for Three.js building games that need to manage thousands of pieces. It bundles spatial hash grids, octrees, chunk managers, and benchmarking tools to help you scale queries, streaming, and performance profiling. Use it to pick the right partitioning, stream chunks, and measure bottlenecks quickly.

How this skill works

The package exposes a SpatialHashGrid for near-constant-time queries when objects are uniformly distributed and an Octree for adaptive queries in clustered scenes. A ChunkManager coordinates world streaming by dividing the world into loadable regions and attaching an Octree per chunk for local spatial queries. The performance-profiler benchmarks insertion, query, and streaming operations so you can validate trade-offs.

When to use it

  • When your scene has 1k–5k objects and distribution is uniform, use SpatialHashGrid for O(1) radius queries.
  • When objects are clustered or have deep spatial hierarchy, use Octree for efficient box and range queries.
  • When the world exceeds ~5k pieces, use ChunkManager with per-chunk octrees to stream and cull content.
  • When you need to measure insertion/query latency or compare partitioning strategies, use the profiler.
  • When implementing LOD, instancing, or memory budgets alongside streaming to maintain frame-rate.

Best practices

  • Choose the simplest structure that satisfies distribution: arrays for <1k, grid for uniform, octree for clustered.
  • Partition by logical chunks for large worlds and keep per-chunk spatial indices to limit query scope.
  • Tune grid cell size and octree maxDepth to balance query cost and memory overhead; benchmark changes.
  • Batch inserts/removals and use instancing for many identical meshes to reduce CPU/GPU overhead.
  • Profile under realistic conditions (player position, spawn patterns) before finalizing streaming heuristics.

Example use cases

  • A sandbox building game with thousands of player-placed pieces using SpatialHashGrid for fast neighbor checks.
  • A base-building game with dense clusters using an Octree to quickly find collisions and nearby structures.
  • An open-world builder that streams terrain and constructions with ChunkManager and per-chunk octrees.
  • Comparing grid vs octree performance with the performance-profiler to choose the right strategy.
  • Implementing LOD and instancing while streaming to keep memory and draw calls under control.

FAQ

Which index should I start with for new projects?

Start with arrays for small scenes (<1k). For 1–5k choose SpatialHashGrid if distribution is uniform, otherwise Octree.

How do I limit memory when using octrees per chunk?

Limit octree maxDepth, unload inactive chunks with ChunkManager, and combine low-detail objects into instanced meshes.