performance-at-scale_skill

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.