Object Pooling

This guide covers one performance pattern: reusing objects instead of creating and destroying them repeatedly.

When Pooling Helps

Pooling is useful for short-lived objects such as:

bullets
enemies
pickups
particles

Key Engine Behaviors

GameObject::pool($template, $size) clones a template object
pooled clones are not automatically added to scene
GameObject::instantiate(...) creates a live object and adds it to active scene
inactive objects are skipped by collision checks and update traversal

Pool Setup Example

<?php

use Sendama\Engine\Core\GameObject;

$bulletTemplate = GameObject::find('Bullet Template');

if (!$bulletTemplate instanceof GameObject) {
    return;
}

$pool = GameObject::pool($bulletTemplate, 32);

foreach ($pool as $bullet) {
    $bullet->deactivate();
    $this->activeScene->addGameObject($bullet);
}

Firing From Pool

Typical fire sequence:

find an inactive pooled bullet
set its position and rotation
activate it
when lifetime ends or hit occurs, deactivate it instead of destroying

Why This Feels Better In Practice

Pooling reduces frame spikes when many objects spawn at once.

That matters most in:

bullet-heavy games
wave spawners
rapid-fire effects

Common Mistakes

forgetting to add pooled clones to the scene
leaving pooled objects active when unused
destroying pooled objects instead of deactivating them
mixing pooled and non-pooled versions of the same gameplay object