Dev Patterns Object Pooling

Object Pooling Pattern

"Pre-allocate, reuse, recycle – eliminate runtime GC pauses."

When to Use This Skill

Use when:

• Creating/destroying objects every frame (bullets, particles, decals)
• Targeting 60 FPS with many transient objects
• Seeing GC pauses in Chrome DevTools Performance tab
• Objects have identical initialization (can be pre-created)
• Maximum simultaneous objects is bounded (~500 or less)

Quick Start

// Basic object pool pattern
const POOL_SIZE = 500;
const MAX_ACTIVE = 200;

interface PoolSlot<T> {
  obj: T;
  active: boolean;
  lastUsed: number;
}

function useObjectPool<T>(
  create: () => T,
  activate: (obj: T) => void,
  deactivate: (obj: T) => void
) {
  const poolRef = useRef<PoolSlot<T>[]>([]);

  // Initialize pool on mount
  useEffect(() => {
    poolRef.current = Array.from({ length: POOL_SIZE }, () => ({
      obj: create(),
      active: false,
      lastUsed: 0,
    }));
    return () => {
      // Cleanup
      poolRef.current.forEach(slot => {
        if (slot.obj?.dispose) slot.obj.dispose();
      });
    };
  }, []);

  const acquire = useCallback(() => {
    const pool = poolRef.current;
    // Find inactive slot
    let slot = pool.find(s => !s.active);
    // If pool full, recycle LRU
    if (!slot) {
      slot = pool.reduce((oldest, s) =>
        s.lastUsed < oldest.lastUsed ? s : oldest
      );
      deactivate(slot.obj);
    }
    slot.active = true;
    slot.lastUsed = performance.now();
    activate(slot.obj);
    return slot.obj;
  }, [activate]);

  const release = useCallback((obj: T) => {
    const slot = poolRef.current.find(s => s.obj === obj);
    if (slot) slot.active = false;
  }, []);

  return { acquire, release };
}

Decision Framework

LRU Eviction Pattern

When the pool is full, evict the Least Recently Used item:

// LRU recycling
let slot = pool.find(s => !s.active);
if (!slot) {
  // Pool exhausted - recycle oldest decal
  slot = pool.reduce((oldest, s) =>
    s.lastUsed < oldest.lastUsed ? s : oldest
  );
  // Fade out before recycling
  fadeOutDecal(slot.obj);
}

Why LRU?

• Predictable: older content fades first (less noticeable)
• Fair: no single hot-spot gets preferential treatment
• Simple: O(n) scan is fine for pools < 1000

GC-Avoidance: Temp Vector Reuse

// BAD: Creates new objects every frame
useFrame(() => {
  const position = new Vector3();
  const quaternion = new Quaternion();
  // ... do work
});

// GOOD: Reuse temp objects
const _tempVec = useRef(new Vector3()).current;
const _tempQuat = useRef(new Quaternion()).current;

useFrame(() => {
  _tempVec.set(0, 0, 0);  // Reset, don't reallocate
  _tempQuat.identity();
  // ... do work
});

Pool Size Guidelines

Rule of thumb: poolSize = maxActive * 2 to maxActive * 3

Implementation Checklist

• Pre-create all objects on mount (useEffect)
• Use active flag to track in-use slots
• Use lastUsed timestamp for LRU eviction
• Properly dispose geometries/materials in cleanup
• Reuse temp vectors with useRef or class fields
• Initialize materials per-slot (not shared) when needed
• Consider frustumCulled={false} for small objects

Common Pitfalls

Reference Implementation

See: src/components/game/effects/PaintDecalManager.tsx

Key sections:

• Pool initialization: lines 68-118
• Acquire/activate: lines 120-141
• LRU recycling: lines 142-153
• Release/deactivate: lines 155-162
• Temp vector reuse: lines 35-37