Object Pooling API Documentation

Overview

Hyperscape implements comprehensive object pooling to eliminate garbage collection pressure in high-frequency event loops. The combat system alone fires events every 600ms tick per combatant, which would cause significant memory churn without pooling.

Core Modules

EventPayloadPool

Location: packages/shared/src/utils/pools/EventPayloadPool.ts Factory for creating type-safe event payload pools that eliminate per-event allocations.

Types

interface PooledPayload {
  /** Internal pool index - do not modify */
  _poolIndex: number;
}

interface EventPayloadPoolStats {
  name: string;
  total: number;
  available: number;
  inUse: number;
  peakUsage: number;
  acquireCount: number;
  releaseCount: number;
  leakWarnings: number;
}

interface EventPayloadPool<T extends PooledPayload> {
  acquire(): T;
  release(payload: T): void;
  withPayload<R>(fn: (payload: T) => R): R;
  getStats(): EventPayloadPoolStats;
  reset(): void;
  checkLeaks(): number;
}

interface EventPayloadPoolConfig<T extends PooledPayload> {
  factory: () => Omit<T, "_poolIndex">;
  reset: (payload: T) => void;
  name: string;
  initialSize?: number;      // default: 64
  growthSize?: number;        // default: 32
  warnOnLeaks?: boolean;      // default: true
}

Functions

`createEventPayloadPool<T>(config: EventPayloadPoolConfig<T>): EventPayloadPool<T>`

Creates a type-safe event payload pool. Parameters:

config.factory - Function to create a new payload object
config.reset - Function to reset payload state before returning to pool
config.name - Pool name for debugging and monitoring
config.initialSize - Initial pool size (default: 64)
config.growthSize - Growth size when exhausted (default: 32)
config.warnOnLeaks - Enable leak detection warnings (default: true)

Returns: Pool instance for acquiring/releasing payloads Example:

interface MyEventPayload extends PooledPayload {
  entityId: string;
  value: number;
}

const myEventPool = createEventPayloadPool<MyEventPayload>({
  name: 'MyEvent',
  factory: () => ({ entityId: '', value: 0 }),
  reset: (p) => { p.entityId = ''; p.value = 0; },
  initialSize: 32,
  growthSize: 16,
});

// Register for monitoring
eventPayloadPoolRegistry.register(myEventPool);

Pool Methods

`acquire(): T`

Acquires a payload from the pool. Automatically grows pool if exhausted. Returns: Payload object ready for use Example:

const payload = myEventPool.acquire();
payload.entityId = 'player-123';
payload.value = 42;

`release(payload: T): void`

Releases a payload back to the pool. Resets payload state before returning. Parameters:

payload - The payload to release

CRITICAL: Event listeners MUST call release() after processing. Failure to release causes pool exhaustion and memory leaks. Example:

myEventPool.release(payload);

`withPayload<R>(fn: (payload: T) => R): R`

Acquires, uses, and automatically releases a payload. Convenience method for short-lived usage. Parameters:

fn - Callback function that receives the payload

Returns: Return value of callback function Example:

const result = myEventPool.withPayload((payload) => {
  payload.entityId = 'player-123';
  return processPayload(payload);
});

`getStats(): EventPayloadPoolStats`

Returns pool statistics for monitoring and debugging. Returns: Statistics object with usage metrics Example:

const stats = myEventPool.getStats();
console.log(`Pool ${stats.name}: ${stats.inUse}/${stats.total} in use, peak: ${stats.peakUsage}`);

`reset(): void`

Resets pool to initial state. Use with caution - invalidates all acquired payloads. Example:

myEventPool.reset();

`checkLeaks(): number`

Checks for unreleased payloads. Should be called at end of tick. Returns: Number of payloads still in use Example:

const leakCount = myEventPool.checkLeaks();
if (leakCount > 0) {
  console.warn(`${leakCount} payloads not released!`);
}

Registry

`eventPayloadPoolRegistry`

Global registry of all event payload pools for monitoring. Methods:

register<T>(pool: EventPayloadPool<T>): void - Register a pool
unregister(name: string): void - Unregister a pool
getAllStats(): EventPayloadPoolStats[] - Get stats for all pools
checkAllLeaks(): Map<string, number> - Check all pools for leaks
resetAll(): void - Reset all pools

Example:

// Register pool
eventPayloadPoolRegistry.register(myEventPool);

// Get all stats
const allStats = eventPayloadPoolRegistry.getAllStats();

// Check for leaks across all pools
const leaks = eventPayloadPoolRegistry.checkAllLeaks();

CombatEventPools

Location: packages/shared/src/utils/pools/CombatEventPools.ts Pre-configured pools for high-frequency combat events.

Available Pools

const CombatEventPools = {
  damageDealt: EventPayloadPool<PooledCombatDamageDealtPayload>,
  projectileLaunched: EventPayloadPool<PooledCombatProjectileLaunchedPayload>,
  faceTarget: EventPayloadPool<PooledCombatFaceTargetPayload>,
  clearFaceTarget: EventPayloadPool<PooledCombatClearFaceTargetPayload>,
  attackFailed: EventPayloadPool<PooledCombatAttackFailedPayload>,
  followTarget: EventPayloadPool<PooledCombatFollowTargetPayload>,
  combatStarted: EventPayloadPool<PooledCombatStartedPayload>,
  combatEnded: EventPayloadPool<PooledCombatEndedPayload>,
  projectileHit: EventPayloadPool<PooledCombatProjectileHitPayload>,
  combatKill: EventPayloadPool<PooledCombatKillPayload>,
};

Payload Types

`PooledCombatDamageDealtPayload`

interface PooledCombatDamageDealtPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
  damage: number;
  attackType: string;
  targetType: string;
  positionX: number;
  positionY: number;
  positionZ: number;
  hasPosition: boolean;
  isCritical: boolean;
}

`PooledCombatProjectileLaunchedPayload`

interface PooledCombatProjectileLaunchedPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
  projectileType: string;
  sourceX: number;
  sourceY: number;
  sourceZ: number;
  targetX: number;
  targetY: number;
  targetZ: number;
  spellId: string;
  arrowId: string;
  delayMs: number;
  flightTimeMs: number;
}

`PooledCombatFaceTargetPayload`

interface PooledCombatFaceTargetPayload extends PooledPayload {
  playerId: string;
  targetId: string;
}

`PooledCombatClearFaceTargetPayload`

interface PooledCombatClearFaceTargetPayload extends PooledPayload {
  playerId: string;
}

`PooledCombatAttackFailedPayload`

interface PooledCombatAttackFailedPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
  reason: string;
}

`PooledCombatFollowTargetPayload`

interface PooledCombatFollowTargetPayload extends PooledPayload {
  playerId: string;
  targetId: string;
  targetX: number;
  targetY: number;
  targetZ: number;
  attackRange: number;
  attackType: string;
}

`PooledCombatStartedPayload`

interface PooledCombatStartedPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
}

`PooledCombatEndedPayload`

interface PooledCombatEndedPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
}

`PooledCombatProjectileHitPayload`

interface PooledCombatProjectileHitPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
  damage: number;
  projectileType: string;
}

`PooledCombatKillPayload`

interface PooledCombatKillPayload extends PooledPayload {
  attackerId: string;
  targetId: string;
  damageDealt: number;
  attackStyle: string;
}

Utility Methods

`getAllStats()`

Returns statistics for all combat pools. Returns: Object with stats for each pool Example:

const stats = CombatEventPools.getAllStats();
console.log('Damage dealt pool:', stats.damageDealt);

`checkAllLeaks(): number`

Checks all combat pools for unreleased payloads. Returns: Total number of leaked payloads across all pools Example:

const totalLeaks = CombatEventPools.checkAllLeaks();

`resetAll(): void`

Resets all combat pools to initial state. Example:

CombatEventPools.resetAll();

Usage Example

// In event emitter (CombatSystem, etc.)
const payload = CombatEventPools.damageDealt.acquire();
payload.attackerId = attacker.id;
payload.targetId = target.id;
payload.damage = 15;
payload.attackType = 'melee';
payload.targetType = 'mob';
this.emitTypedEvent(EventType.COMBAT_DAMAGE_DEALT, payload);

// In event listener - MUST call release()
world.on(EventType.COMBAT_DAMAGE_DEALT, (payload) => {
  // Process damage...
  updateHealthBar(payload.targetId, payload.damage);
  
  // CRITICAL: Release payload back to pool
  CombatEventPools.damageDealt.release(payload);
});

PositionPool

Location: packages/shared/src/utils/pools/PositionPool.ts Object pool for {x, y, z} position objects. Eliminates allocations in hot paths like position updates, movement, and combat.

Types

interface PooledPosition {
  x: number;
  y: number;
  z: number;
  /** Internal pool index - do not modify */
  _poolIndex: number;
}

Global Instance

export const positionPool: PositionPoolImpl;

Methods

`acquire(x = 0, y = 0, z = 0): PooledPosition`

Acquires a position from the pool, initialized to the given values. Parameters:

x - X coordinate (default: 0)
y - Y coordinate (default: 0)
z - Z coordinate (default: 0)

Returns: Position object ready for use IMPORTANT: Must call release() when done to return to pool. Example:

const pos = positionPool.acquire(10, 0, 20);
// ... use pos ...
positionPool.release(pos);

`release(pos: PooledPosition): void`

Releases a position back to the pool. Resets position to origin before returning. Parameters:

pos - The position to release

Example:

positionPool.release(pos);

`withPosition<T>(x: number, y: number, z: number, fn: (pos: PooledPosition) => T): T`

Acquires, uses, and automatically releases a position. Parameters:

x - X coordinate
y - Y coordinate
z - Z coordinate
fn - Callback function that receives the position

Returns: Return value of callback function Example:

const distance = positionPool.withPosition(10, 0, 20, (pos) => {
  return calculateDistance(playerPos, pos);
});

`set(pos: PooledPosition, x: number, y: number, z: number): void`

Sets position values in-place. Parameters:

pos - Position to modify
x - New X coordinate
y - New Y coordinate
z - New Z coordinate

Example:

positionPool.set(pos, 15, 5, 25);

`copy(target: PooledPosition, source: { x: number; y: number; z: number }): void`

Copies values from another position-like object. Parameters:

target - Position to modify
source - Source position to copy from

Example:

positionPool.copy(pos, entity.position);

`distanceSquared(a: PooledPosition, b: { x: number; y: number; z: number }): number`

Calculates distance squared between two positions (avoids sqrt for performance). Parameters:

a - First position
b - Second position

Returns: Distance squared Example:

const distSq = positionPool.distanceSquared(pos1, pos2);
if (distSq < 100) { // Within 10 units
  // ...
}

`getStats()`

Returns pool statistics for monitoring. Returns: Statistics object Example:

const stats = positionPool.getStats();
console.log(`Position pool: ${stats.inUse}/${stats.total} in use`);

`reset(): void`

Resets pool to initial state. Use with caution - invalidates all acquired positions. Example:

positionPool.reset();

Performance Characteristics

EventPayloadPool

Acquire: O(1) - Pop from available array
Release: O(1) - Push to available array
Memory: Fixed after warmup (unless pool exhausted)
Growth: Automatic when exhausted, warns once per minute

PositionPool

Acquire: O(1) - Pop from available array
Release: O(1) - Push to available array
Memory: Fixed after warmup (unless pool exhausted)
Initial Size: 128 positions
Growth Size: 64 positions

CombatEventPools

Pool Sizes: 16-64 objects (varies by event frequency)
Growth Sizes: 8-32 objects
Memory Impact: Eliminates per-tick allocations in combat hot paths
Verified: Memory stays flat during 60s stress test with agents in combat

Best Practices

1. Always Release Payloads

CRITICAL: Event listeners MUST call release() after processing.

// ❌ BAD - Payload never released
world.on(EventType.COMBAT_DAMAGE_DEALT, (payload) => {
  updateHealthBar(payload.targetId, payload.damage);
  // Missing release() - causes memory leak!
});

// ✅ GOOD - Payload properly released
world.on(EventType.COMBAT_DAMAGE_DEALT, (payload) => {
  updateHealthBar(payload.targetId, payload.damage);
  CombatEventPools.damageDealt.release(payload);
});

2. Use withPayload for Short-Lived Usage

// ✅ GOOD - Automatic release
const result = myEventPool.withPayload((payload) => {
  payload.entityId = 'player-123';
  return processPayload(payload);
});

3. Monitor Pool Statistics

// Check pool health periodically
setInterval(() => {
  const stats = CombatEventPools.getAllStats();
  for (const [name, poolStats] of Object.entries(stats)) {
    if (poolStats.inUse > poolStats.total * 0.8) {
      console.warn(`Pool ${name} is ${(poolStats.inUse / poolStats.total * 100).toFixed(1)}% full`);
    }
  }
}, 60000);

4. Check for Leaks at End of Tick

// In game tick processor
onTickEnd() {
  const leakCount = CombatEventPools.checkAllLeaks();
  if (leakCount > 0) {
    console.error(`${leakCount} combat event payloads not released!`);
  }
}

5. Register Custom Pools

// Always register custom pools for monitoring
const myPool = createEventPayloadPool({ ... });
eventPayloadPoolRegistry.register(myPool);

Migration Guide

Before (Without Pooling)

// Event emitter
this.emitTypedEvent(EventType.COMBAT_DAMAGE_DEALT, {
  attackerId: attacker.id,
  targetId: target.id,
  damage: 15,
  attackType: 'melee',
  targetType: 'mob',
  positionX: 0,
  positionY: 0,
  positionZ: 0,
  hasPosition: false,
  isCritical: false,
});

// Event listener
world.on(EventType.COMBAT_DAMAGE_DEALT, (payload) => {
  updateHealthBar(payload.targetId, payload.damage);
});

After (With Pooling)

// Event emitter
const payload = CombatEventPools.damageDealt.acquire();
payload.attackerId = attacker.id;
payload.targetId = target.id;
payload.damage = 15;
payload.attackType = 'melee';
payload.targetType = 'mob';
payload.hasPosition = false;
payload.isCritical = false;
this.emitTypedEvent(EventType.COMBAT_DAMAGE_DEALT, payload);

// Event listener - MUST release!
world.on(EventType.COMBAT_DAMAGE_DEALT, (payload) => {
  updateHealthBar(payload.targetId, payload.damage);
  CombatEventPools.damageDealt.release(payload);
});

Troubleshooting

Pool Exhaustion Warnings

Symptom: Console warnings about pool exhaustion Cause: High event frequency or payloads not being released Solution:

Check that all event listeners call release()
Increase initial pool size if legitimate high frequency
Use checkLeaks() to identify unreleased payloads

Memory Leaks

Symptom: Memory usage grows over time Cause: Payloads not being released back to pool Solution:

Call CombatEventPools.checkAllLeaks() at end of tick
Review event listeners for missing release() calls
Use Chrome DevTools Memory Profiler to identify leaking objects

Performance Degradation

Symptom: Frame drops or tick slowdowns Cause: Pool growth causing allocations Solution:

Check pool statistics with getStats()
Increase initial pool size to avoid growth
Verify payloads are being released promptly

​Object Pooling API Documentation

​Overview

​Core Modules

​EventPayloadPool

​Types

​Functions

createEventPayloadPool<T>(config: EventPayloadPoolConfig<T>): EventPayloadPool<T>

​Pool Methods

acquire(): T

release(payload: T): void

withPayload<R>(fn: (payload: T) => R): R

getStats(): EventPayloadPoolStats

reset(): void

checkLeaks(): number

​Registry

eventPayloadPoolRegistry

​CombatEventPools

​Available Pools

​Payload Types

PooledCombatDamageDealtPayload

PooledCombatProjectileLaunchedPayload

PooledCombatFaceTargetPayload

PooledCombatClearFaceTargetPayload

PooledCombatAttackFailedPayload

PooledCombatFollowTargetPayload

PooledCombatStartedPayload

PooledCombatEndedPayload

PooledCombatProjectileHitPayload

PooledCombatKillPayload

​Utility Methods

getAllStats()

checkAllLeaks(): number

resetAll(): void

​Usage Example

​PositionPool

​Types

​Global Instance

​Methods

acquire(x = 0, y = 0, z = 0): PooledPosition

release(pos: PooledPosition): void

withPosition<T>(x: number, y: number, z: number, fn: (pos: PooledPosition) => T): T

set(pos: PooledPosition, x: number, y: number, z: number): void

copy(target: PooledPosition, source: { x: number; y: number; z: number }): void

distanceSquared(a: PooledPosition, b: { x: number; y: number; z: number }): number

getStats()

reset(): void

​Performance Characteristics

​EventPayloadPool

​PositionPool

​CombatEventPools

​Best Practices

​1. Always Release Payloads

​2. Use withPayload for Short-Lived Usage

​3. Monitor Pool Statistics

​4. Check for Leaks at End of Tick

​5. Register Custom Pools

​Migration Guide

​Before (Without Pooling)

​After (With Pooling)

​Troubleshooting

​Pool Exhaustion Warnings

​Memory Leaks

​Performance Degradation

​See Also

Object Pooling API Documentation

Overview

Core Modules

EventPayloadPool

Types

Functions

`createEventPayloadPool<T>(config: EventPayloadPoolConfig<T>): EventPayloadPool<T>`

Pool Methods

`acquire(): T`

`release(payload: T): void`

`withPayload<R>(fn: (payload: T) => R): R`

`getStats(): EventPayloadPoolStats`

`reset(): void`

`checkLeaks(): number`

Registry

`eventPayloadPoolRegistry`

CombatEventPools

Available Pools

Payload Types

`PooledCombatDamageDealtPayload`

`PooledCombatProjectileLaunchedPayload`

`PooledCombatFaceTargetPayload`

`PooledCombatClearFaceTargetPayload`

`PooledCombatAttackFailedPayload`

`PooledCombatFollowTargetPayload`

`PooledCombatStartedPayload`

`PooledCombatEndedPayload`

`PooledCombatProjectileHitPayload`

`PooledCombatKillPayload`

Utility Methods

`getAllStats()`

`checkAllLeaks(): number`

`resetAll(): void`

Usage Example

PositionPool

Types

Global Instance

Methods

`acquire(x = 0, y = 0, z = 0): PooledPosition`

`release(pos: PooledPosition): void`

`withPosition<T>(x: number, y: number, z: number, fn: (pos: PooledPosition) => T): T`

`set(pos: PooledPosition, x: number, y: number, z: number): void`

`copy(target: PooledPosition, source: { x: number; y: number; z: number }): void`

`distanceSquared(a: PooledPosition, b: { x: number; y: number; z: number }): number`

`getStats()`

`reset(): void`

Performance Characteristics

EventPayloadPool

PositionPool

CombatEventPools

Best Practices

1. Always Release Payloads

2. Use withPayload for Short-Lived Usage

3. Monitor Pool Statistics

4. Check for Leaks at End of Tick

5. Register Custom Pools

Migration Guide

Before (Without Pooling)

After (With Pooling)

Troubleshooting

Pool Exhaustion Warnings

Memory Leaks

Performance Degradation

See Also