
Object Pooling in Phaser 3: A Beginner's Bullet and Particle Pool
Object pooling in Phaser 3 means reusing a capped set of game objects instead of creating and destroying them as they come and go. Phaser’s own documentation frames a Group as “a way for you to create, manipulate, or recycle similar Game Objects,” and recycling is the whole point of the technique (Group concept guide).
In this tutorial you’ll build two pools from scratch: a bullet pool and a small spark “particle” pool, both from Phaser Groups and a handful of method calls — no physics engine, no plugins, no third-party libraries. Every API below comes from Phaser’s own documentation and reference pages, and we did not run the code hands-on.
Sourcing note
- Authoritativeness: Claims are limited to what the Group concept guide, the Game Objects concept guide and the Phaser.GameObjects.Group API reference actually say. Quoted lines are copied from those pages; where this tutorial reasons a step beyond them, the wording marks it as inference or as a rule of thumb. The API reference is the legacy Phaser 3 documentation, whose own banner points readers to newdocs.phaser.io.
- Trust: No frame-rate numbers and no benchmark claims — no speedup was measured, so none is quoted. Where a behaviour is a pattern rather than a documented guarantee, we say so.
What object pooling is
A pool is a Group created once with a fixed ceiling, then reused. Instead of spawning a new sprite and destroying it later, you ask the group for a member, switch it on, and switch it off again when it is done.
Two properties do the heavy lifting for pooling:
maxSize— “The maximum size of this group, if used as a pool. -1 is no limit,” and the default is-1(API reference). If you want an actual pool, set this deliberately.classType— “The class to create new group members from,” defaulting toPhaser.GameObjects.Sprite, so you can usually leave it out (API reference).
There is a third property you need in practice, and it is the one beginners miss: a texture key. Phaser is explicit about what happens without one (Game Objects concept guide):
Game objects can’t be created without a texture. Instead they will receive the “default” texture and frame (32 × 32 transparent)
A pool whose members all use that default texture renders nothing at all — the sprites exist, update, and recycle perfectly, and you see an empty screen.
// Load or generate a 'bullet' texture first, e.g. in preload():
// this.load.image('bullet', 'assets/bullet.png');
// A pool for bullets: created once, reused forever
const bullets = this.add.group({
classType: Phaser.GameObjects.Sprite, // this is the default classType
defaultKey: 'bullet', // texture key used for every new member
maxSize: 30 // hard ceiling for the pool
});
Note what maxSize does not do: nothing is created yet. The pool starts empty, and get() fills it lazily, creating a member on demand until the group reaches its ceiling.
How get() and isFull() actually behave
It is worth quoting the docs precisely here, because the two methods are easy to mix up.
get() is the documented way to pull a member out of a pool: it “scans the group for the first member that has an active state set to false, assigns x and y, and returns the member. If no inactive member is found and the group isn’t full then it will create a new Game Object using x, y, key, frame, and visible,” whose “active state set to true” (API reference). Its return value is documented as “the first inactive group member, or a newly created member, or null.”
That null is the whole exhaustion story: reuse first, create only while there is room, and hand back null when there is neither. So the check you actually need sits after get():
const bullet = bullets.get(x, y); // reuses a hidden bullet, or creates one while there is room
if (!bullet) return null; // every member is in use — skip this shot
One more documented detail makes the texture setup tidier: get()’s key parameter defaults to defaultKey, and “unless a new member is created, key, frame, and visible are ignored” (API reference). In other words, get() applies the group’s defaultKey to a newly created member, while a reused member keeps the texture it already has.
isFull() is a different signal, and this is the trap: its Returns line reads “True if the number of members equals maxSize” (API reference). isFull() counts members, not active members, and killAndHide only deactivates and hides — so a retired bullet stays in the group as a reusable member. So once your pool has grown to maxSize, isFull() stays true forever — and a spawn gate built on if (isFull()) return null would permanently block every shot after the pool filled up. Use isFull() to describe the pool’s cap, never as the spawn test.
For sizing, the API reference gives two purpose-built counters:
getTotalFree()— “The difference ofmaxSizeand the number of active group members… the number of group members that could be created or reactivated before reaching the size limit.”getTotalUsed()— “Counts the number of in-use (active) group members.”
getTotalFree() answers “how many more can I switch on?”, which is the question a spawn system is really asking.
Build it: a pooled bullet group
Three steps: create the group with a maxSize and a defaultKey, pull from it with get(), and retire each bullet with killAndHide once it leaves the screen. Define the bullet’s behaviour once and keep per-shot values on the bullet itself, so no allocation happens at spawn time.
// 1. Create the pool once, when your scene sets up
const bullets = this.add.group({
classType: Phaser.GameObjects.Sprite,
defaultKey: 'bullet',
maxSize: 30,
runChildUpdate: true, // each bullet's update() will be called
createCallback: (bullet) => { // runs when a member is created — attach the
bullet.update = updateBullet; // shared function, not a new one per shot
}
});
// 2. One behaviour for every bullet, defined once.
// Handler signature (time, delta); the member is `this`.
function updateBullet(time, delta) {
if (!this.active) return; // already recycled
this.x += this.speedX; // per-shot value, stored on the bullet
if (this.x > 800) bullets.killAndHide(this); // 800 is an example canvas width
}
// 3. Spawn: ask the pool for a member, and handle the null
function fireBullet(x, y) {
const bullet = bullets.get(x, y);
if (!bullet) return null; // pool exhausted — every bullet is in use
bullet.setActive(true); // revive it
bullet.setVisible(true);
bullet.speedX = 6; // reset the per-shot state
return bullet;
}
Two details matter here:
runChildUpdatedefaults tofalseand decides “whether to call the update method of any members” (API reference);createCallbackis “a function to be called when adding or creating group members” (API reference). Phaser’s own guide explains why the group is needed at all: “a game object’s update() method isn’t called automatically. You can call the update() method yourself; or add the game object to a group with runChildUpdate = true” (Game Objects concept guide). The group then updates its members frompreUpdate(time, delta)(API reference), and Phaser’s guide uses the matchingupdate(time, delta)signature in its own example. Binding the handler so the member isthisis the usual convention rather than a documented guarantee. The payoff is one shared function per pool instead of a new closure on every shot.killAndHide“deactivates and hides a member of this group”, whilekillonly deactivates it (API reference). Reach forkillAndHidewhenever the object should visibly disappear — exactly what a spent bullet should do. Since both only toggle state, the member stays in the group for the nextget()to reuse.
If you’d rather drive movement yourself in your own loop, set runChildUpdate: false (the default) and call killAndHide when a bullet leaves the screen — the pool logic stays identical.
Add particles
Here “particles” means a second, larger pool of tiny sprite sparks — the same Group pattern, with more of them and a shorter life, so the example stays one pattern instead of two.
const sparks = this.add.group({
classType: Phaser.GameObjects.Sprite,
defaultKey: 'spark',
maxSize: 120,
runChildUpdate: true,
createCallback: (spark) => { spark.update = updateSpark; }
});
// One behaviour for every spark — one shared handler, not a closure per spawn.
// Handler signature (time, delta); the member is `this`.
function updateSpark(time, delta) {
if (!this.active) return;
this.x += this.drift;
this.y += 1;
this.lifeLeft -= 1;
if (this.lifeLeft <= 0) sparks.killAndHide(this);
}
function burst(x, y) {
for (let i = 0; i < 8; i++) {
const spark = sparks.get(x, y);
if (!spark) return; // pool exhausted — stop spawning
spark.setActive(true);
spark.setVisible(true);
spark.lifeLeft = 30; // frames this spark lives — reset per spawn
spark.drift = (i % 3) - 1; // -1, 0, or 1
}
}
The null check sits inside the loop, which matters: a burst that runs out of sparks halfway simply stops, so the first few sparks still read as an impact and your ceiling of 120 is never breached.
Measure with the two counters
The useful measurement is counting, not guessing. Two documented counters do the work:
// A tiny diagnostic you can drop into your own code
function poolReport() {
console.log(
"bullets — free:", bullets.getTotalFree(), // can still be created or reactivated
"in use:", bullets.getTotalUsed() // active right now
);
console.log(
"sparks — free:", sparks.getTotalFree(),
"in use:", sparks.getTotalUsed()
);
}
Watch getTotalFree() during your busiest second. If it never approaches zero, the ceiling is generous; if it sits at zero, get() is returning null and shots are being skipped, which is your signal to raise maxSize.
There is also getLength(), “the number of members of the group” (API reference). It counts members whether they are active or hidden, so it reports how big the pool has grown, not how many objects are on screen. Treat it as a memory high-water mark, not a live object count.
No speedup percentage is quoted here, because none was measured — read the counters above and draw your own conclusion in your own project.
Common mistakes
The usual stumbles are small: forgetting maxSize so the pool grows without limit, treating isFull() as a spawn gate once the pool has grown, forgetting the texture key so every member is invisible, and removing pooled members from the group so the next get() has nothing to reuse. Each has a one-line fix.
// Fragile: no null check, and recycled members left invisible
const loosePool = this.add.group({ defaultKey: 'bullet', maxSize: 30 });
function spawnLoose(x, y) {
const item = loosePool.get(x, y); // null once every member is in use
item.setActive(true); // throws on that null; a recycled member stays invisible
return item;
}
// Robust: null check and both visibility calls
const safePool = this.add.group({ defaultKey: 'bullet', maxSize: 60 });
function spawnSafe(x, y) {
const item = safePool.get(x, y);
if (!item) return null;
item.setActive(true);
item.setVisible(true);
return item;
}
Checklist to keep nearby:
- Set
maxSizeon purpose. The default-1means no limit (API reference), which quietly defeats the point of pooling. - Give the pool a
defaultKey. Members created without a texture use the transparent 32 × 32 default, so your bullets exist but never appear (Game Objects concept guide). - Gate spawning on the
nullfromget(), not onisFull().isFull()describes the cap and stays true once the pool has grown. - Reused members need both
setActive(true)andsetVisible(true)—killAndHideturned both off. A memberget()creates is active and visible already, so an invisible sprite points at a missing texture key rather than a missingsetVisiblecall. - Don’t remove pooled members. Recycling works because retired members stay in the group, available to the next
get(). - Don’t read
getLength()as an on-screen count. It reports how many members the group holds, active or not; usegetTotalUsed()for the live number andgetTotalFree()for the headroom. - If you ever reach for
createMultiple, note thatdefaultKeyis used inGroup#createbut not inGroup#createMultiple(API reference), so a bulk-created batch needs its key passed in explicitly.
FAQ
How do I pick a size for maxSize?
Start from your busiest moment, then let the counters correct you. getTotalFree() tells you how many bullets could still be created or reactivated before the limit; if it never gets close to zero during a frantic second, you have slack, and if it sits at zero, raise the ceiling. As a rule of thumb — ours, not a documented one — a generous maxSize costs a few idle members, while a stingy one costs you skipped shots.
What happens when the pool is full?
get() reuses a retired member first, and only creates a new one “if no inactive member is found and the group isn’t full” — otherwise it returns null (API reference). So a full pool means no free member and no room for another: your spawn function gets null, returns, and the shot is skipped. Making that null an explicit branch up front is the beginner-safe habit; reaching for isFull() instead will block the pool permanently once it has grown to its cap.
Do bullets and sparks have to share one group?
No — and they shouldn’t. Separate pools give you separate ceilings, so a flood of sparks can never eat your bullets. Group membership is non-exclusive: “a Game Object can belong to several groups, one group, or none” (Group concept guide), so sharing is allowed, but the cleanest beginner setup is one pool per kind of object, each with its own maxSize, its own defaultKey and its own spawn/recycle pair.
What you learned
- A pool is a Group with a deliberately chosen
maxSizeand a texture key, created once and reused throughget()andkillAndHide(). maxSizedefaults to-1(no limit), andclassTypedefaults toPhaser.GameObjects.Sprite.- The recycle pattern is four calls:
get(),setActive(true),setVisible(true), andkillAndHide(). - The exhaustion signal is the
nullfromget(), notisFull()—isFull()compares the member count tomaxSizeand stays true once the pool has grown. getTotalFree()andgetTotalUsed()are the documented counters for sizing a pool;getLength()reports members held, not objects on screen.runChildUpdatedefaults tofalse; flipping it totruelets each pooled object run its ownupdate()logic, and a singlecreateCallbackcan attach that logic once.- Sizing comes from those counters, not from guessing at frame rates.
Next: the Phaser performance guide shows where pooling sits among the other beginner optimisation habits, and the collector game tutorial puts the same recycling idea to work in a full playable scene.