perf
game/perf provides deterministic, zero-steady-state-allocation primitives for hot game loops: reusable object pools (Pool, Arena, SlicePool), 2D broad-phase spatial indices (SpatialHash, Quadtree), and viewport sprite culling (CullBatch, BatchCuller, Cull).
import "github.com/nsgo-dev/game/packages/game/perf"
Deterministic object pools (Pool, Arena, SlicePool)
Unlike sync.Pool, perf pools never drop entries on garbage collection, keeping frame times predictable across desktop, mobile, and WebAssembly targets:
// Pointer pool with explicit reset callback:
bullets := perf.NewPool(128, func(b *Bullet) { *b = Bullet{} })
b := bullets.Acquire()
b.X, b.Y = playerX, playerY
bullets.Release(b)
// Dense, cache-friendly Arena with generational Handles (stale handles safely return false):
enemies := perf.NewArena[Enemy](64, nil)
h, e := enemies.Alloc()
e.HP = 100
for handle, item := range enemies.All() {
stepEnemy(handle, item, dt)
}
enemies.Remove(h)
// Reusable scratch slices:
scratch := perf.NewSlicePool[uint32](16)
ids := scratch.Acquire(64)
defer scratch.Release(ids)
| Type | Best for | Key methods |
|---|---|---|
Pool[T] |
Stable pointers to pooled structs (particles, projectiles) | Acquire, Release, Prewarm, Active, Free, Cap, Reset |
Arena[T] |
Dense iteration + O(1) swap-remove with generational Handles |
Add, Alloc, Get, Has, Remove, Slice, ForEach, All, Reset |
SlicePool[T] |
Per-frame temporary query or sorting buffers | Acquire(minCap), Release(s), Free, Reset |
2D spatial indices (SpatialHash, Quadtree)
Replace O(n²) scans with O(k) area queries, point queries, and collision pair generation. Both indices reuse internal buckets/nodes and accept caller-owned output slices so steady-state queries allocate zero bytes:
grid := perf.NewSpatialHash[uint32](64) // cell size ~1-2x typical entity size
grid.Insert(id, entityBounds)
grid.Update(id, movedBounds)
// Zero-alloc area query reusing caller slice:
hits = grid.Query(cameraView, hits[:0])
// Deduplicated overlapping broad-phase pairs:
grid.QueryPairs(func(a, b uint32) {
resolveNarrowPhase(a, b)
})
Use SpatialHash[ID] for uniform entity sizes and unbounded or scrolling worlds; use NewQuadtree[ID](worldBounds, maxItems, maxDepth) when entities vary widely in size or cluster densely inside a known world rectangle. Both expose Insert, Update, Remove, Clear, Len, Query, and QueryPoint.
Viewport culling (CullBatch, BatchCuller, Cull)
Skip drawing off-screen sprites before submitting draw commands to core.Drawing:
var culler perf.BatchCuller
// Inside Canvas.Draw:
culler.Draw(spriteBatch, cameraViewBounds, d)
BatchCuller.Draw(batch, view, d)reuses an internal scratchsprite.Batchfor zero per-frame allocations (use the one-linerperf.CullBatch(batch, view, d)when convenience matters more than reusing scratch memory).- Use
perf.CullSprites(view, src, dst[:0]),perf.SpriteBounds(s),perf.Intersects(a, b), or genericperf.Cull(view, items, boundsOf, dst[:0])to cull arbitrary world objects.