groups-and-containers

Groups and Containers

Logical grouping (Group), visual grouping with transform inheritance (Container), render-layer grouping (Layer), object pooling, and when to use each in Phaser 4.

Key source paths: src/gameobjects/group/, src/gameobjects/container/, src/gameobjects/layer/ Related skills: ../sprites-and-images/SKILL.md, ../physics-arcade/SKILL.md

Quick Start

// In a Scene's create() method:

// --- Group: logical collection, no transform, great for pooling ---
const enemies = this.add.group();
enemies.create(100, 200, 'enemy');       // creates Sprite at (100,200)
enemies.create(300, 200, 'enemy');

// --- Container: visual parent with inherited transform ---
const hud = this.add.container(10, 10);
const icon = this.add.image(0, 0, 'heart');
const label = this.add.text(20, 0, 'x3');
hud.add([icon, label]);                  // children move/scale/rotate with hud

// --- Layer: render-ordering bucket, no position/scale ---
const bgLayer = this.add.layer();
const fgLayer = this.add.layer();
bgLayer.add(this.add.image(400, 300, 'sky'));
fgLayer.add(this.add.sprite(400, 300, 'player'));

Core Concepts

Group vs Container vs Layer

Feature	Group	Container	Layer
Purpose	Logical collection / pool	Visual parent with transform	Render-order bucket
On display list	No (children are)	Yes (renders children)	Yes (renders children)
Position/rotation/scale	No	Yes (children inherit)	No
Children storage	children (Set)	list (Array)	List (Structs.List)
Physics	Via physics.add.group()	Limited (offsets if not at 0,0)	No
Input	No (children can)	Yes (needs hit area shape)	No
Object pooling	Yes (getFirstDead, kill)	No	No
Masks	No	Yes (not per-child in Canvas)	Yes
Alpha/blend/visible	No (batch via setVisible)	Yes	Yes
Nesting	N/A	Container in Container	Cannot go in Container
Extends	EventEmitter	GameObject	List
Factory	this.add.group()	this.add.container(x, y)	this.add.layer()

When to Use Each

Group: Managing collections of similar objects (enemies, bullets, coins), object pooling with active/inactive lifecycle, physics group collisions. No shared visual transform. Members can belong to multiple Groups simultaneously.

Container: Children inherit position, rotation, scale, alpha. Composite UI elements (health bars, inventory slots), moving/rotating clusters as one unit, nested transforms. By default exclusive -- a child can only belong to one Container (use setExclusive(false) to override).

Layer: Controlling render order of object batches, applying shared alpha/blend/mask. No position/scale/rotation. Lightweight render bucketing.

Container vs Group at a Glance

• Container has position, rotation, scale, alpha -- Group does not. If you need children to move/rotate as a unit, use Container.
• Container is exclusive by default -- adding a child removes it from its previous Container. Group is non-exclusive; a game object can be in many Groups.
• Container is on the display list -- it renders its children. Group is not on the display list; its children render individually on the Scene.
• Group supports object pooling -- getFirstDead, kill, killAndHide. Container does not.
• Container has performance cost -- each child requires matrix math per frame. Deeper nesting = more cost. Prefer Group or Layer when transforms are not needed.

Common Patterns

Creating and Populating Groups

// Empty group, add existing objects
const gems = this.add.group();
gems.add(existingSprite);
gems.addMultiple([sprite1, sprite2, sprite3]);

// Group with config -- creates children automatically
const coins = this.add.group({
    classType: Phaser.GameObjects.Sprite,
    key: 'coin',
    quantity: 10,           // overrides frameQuantity
    setXY: { x: 50, y: 300, stepX: 60 },
    setScale: { x: 0.5, y: 0.5 }
});

// Custom class type with pool limit
const bullets = this.add.group({
    classType: Bullet,       // must accept (scene, x, y, key, frame)
    maxSize: 30,
    defaultKey: 'bullet',
    runChildUpdate: true     // calls child.update() each frame
});

Object Pooling with getFirstDead

The core pooling pattern: deactivate objects instead of destroying them, then reuse inactive ones.

// Setup pool
const bullets = this.add.group({
    classType: Phaser.GameObjects.Sprite,
    defaultKey: 'bullet',
    maxSize: 30
});

// Fire a bullet -- get() finds first inactive member or creates one
function fireBullet(x, y) {
    const bullet = bullets.get(x, y);

    if (bullet) {
        bullet.setActive(true);
        bullet.setVisible(true);
        bullet.body.velocity.y = -300;   // if physics enabled
    }
}

// Deactivate when off-screen or on hit
function killBullet(bullet) {
    bullets.killAndHide(bullet);         // sets active=false, visible=false
    // If using physics, also reset the body:
    // bullet.body.stop();
}

// Alternative: manual getFirst
const inactive = bullets.getFirst(false);     // first where active===false
const active = bullets.getFirstAlive();       // first where active===true
const dead = bullets.getFirstDead(true, x, y); // first inactive, create if null

Pool helper methods on Group:

Method	Description
get(x, y, key, frame)	Shortcut: getFirst(false, true, ...) -- finds inactive or creates
getFirst(state, createIfNull, x, y, key, frame)	First member matching active state
getFirstAlive(createIfNull, x, y, key, frame)	First member where active===true
getFirstDead(createIfNull, x, y, key, frame)	First member where active===false
getLast(state, createIfNull, x, y, key, frame)	Like getFirst but searches back-to-front
kill(gameObject)	Sets active=false on a member
killAndHide(gameObject)	Sets active=false and visible=false
countActive(value)	Count members where active===value (default true)
getTotalUsed()	Count of active members
getTotalFree()	maxSize - active count (remaining pool capacity)
isFull()	True if children.size >= maxSize

Physics Groups

Physics groups extend Group with automatic body assignment. See ../physics-arcade/SKILL.md for full details.

// Arcade Physics group -- every member gets a dynamic body
const enemies = this.physics.add.group({
    key: 'enemy',
    quantity: 5,
    setXY: { x: 100, y: 100, stepX: 80 }
});

// Static physics group -- immovable bodies
const platforms = this.physics.add.staticGroup();
platforms.create(400, 568, 'ground');

// Collide physics groups with each other
this.physics.add.collider(player, platforms);
this.physics.add.overlap(bullets, enemies, onHit);

Containers with Nested Transforms

// HUD that follows camera
const hud = this.add.container(10, 10);
hud.setScrollFactor(0);     // pinned to camera

const healthBar = this.add.rectangle(0, 0, 200, 20, 0x00ff00);
const healthText = this.add.text(210, -5, '100 HP');
hud.add([healthBar, healthText]);

// Move everything at once
hud.setPosition(50, 50);

// Scale and rotate propagate to children
hud.setScale(1.5);
hud.setRotation(0.1);

// Alpha affects all children
hud.setAlpha(0.8);

// Nested containers
const inventory = this.add.container(300, 500);
for (let i = 0; i < 5; i++) {
    const slot = this.add.container(i * 55, 0);
    slot.add([
        this.add.rectangle(0, 0, 48, 48, 0x333333),
        this.add.image(0, 0, `item-${i}`)
    ]);
    inventory.add(slot);    // Container inside Container
}

Key Container methods:

Method	Description
add(child) / addAt(child, index)	Add Game Object(s); removes from display list
remove(child, destroyChild)	Remove; optionally destroy
getAt(index) / getIndex(child)	Access by index
getByName(name) / getFirst(prop, val)	Query children
getAll(prop, val) / count(prop, val)	Filtered access and counting
sort(property) / swap(a, b) / moveTo(child, idx)	Ordering
each(cb, ctx) / iterate(cb, ctx)	Iteration (iterate passes index)
setScrollFactor(x, y, updateChildren)	Pass true to also apply to children
getBounds(output)	Bounding rect of all children
pointToContainer(source, output)	World point to local space
setExclusive(value)	When false, children can exist in multiple places
replace(oldChild, newChild)	Swap one child for another
setSize(width, height)	Set hit area size (required for input)
length	Read-only child count

Layers for Render Ordering

const bgLayer = this.add.layer();
const entityLayer = this.add.layer();
const uiLayer = this.add.layer();

// Add objects -- they render in layer order, then by depth within layer
bgLayer.add(this.add.image(400, 300, 'sky'));
entityLayer.add(player);
entityLayer.add(enemy);
uiLayer.add(scoreText);

// Control depth of layers themselves
bgLayer.setDepth(0);
entityLayer.setDepth(1);
uiLayer.setDepth(2);

// Children set depth within their layer
enemy.setDepth(5);   // relative to entityLayer, not the Scene

// Apply shared effects to entire layer
entityLayer.setAlpha(0.5);
entityLayer.setVisible(false);
entityLayer.setBlendMode(Phaser.BlendModes.ADD);

Bulk Creation with createMultiple

// createMultiple accepts a GroupCreateConfig or array of them
const coins = this.add.group();

coins.createMultiple({
    key: 'coin',
    quantity: 20,
    setXY: { x: 50, y: 100, stepX: 40, stepY: 0 },
    setScale: { x: 0.5, y: 0.5 },
    setRotation: { value: 0, step: 0.1 },   // each rotated 0.1 more than previous
    setAlpha: { value: 1 },
    setOrigin: { x: 0.5, y: 0.5 },
    setDepth: { value: 5 },
    gridAlign: {
        width: 5,
        height: 4,
        cellWidth: 48,
        cellHeight: 48,
        x: 100,
        y: 200
    }
});

// Multiple configs at once (creates two different sets)
coins.createMultiple([
    { key: 'gold-coin', quantity: 10, setXY: { x: 50, y: 100, stepX: 30 } },
    { key: 'silver-coin', quantity: 10, setXY: { x: 50, y: 200, stepX: 30 } }
]);

Iterating and Batch Operations on Groups

const enemies = this.add.group();

// Get all children as array
const all = enemies.getChildren();
const active = enemies.getMatching('active', true);

// Batch property operations
enemies.setXY(200, 300);
enemies.incX(5);                    // add 5 to each member's x
enemies.setVisible(false);
enemies.propertyValueSet('tintTopLeft', 0xff0000);
enemies.playAnimation('walk');

// Stepping: apply incremental values across members
enemies.setX(100, 50);             // first at x=100, next at 150, then 200...
enemies.setY(200, 30);             // first at y=200, next at 230, then 260...
enemies.setXY(100, 200, 50, 30);   // combined X and Y stepping
enemies.incXY(10, 5);              // add 10 to each x, 5 to each y
enemies.angle(0, 15);              // first at 0 deg, next at 15, then 30...
enemies.setAlpha(1, -0.1);         // first at 1.0, next at 0.9, then 0.8...
enemies.setScale(1, 0, 0.1, 0);   // scaleX: 1.0, 1.1, 1.2... (stepX=0.1)
enemies.setDepth(0, 1);            // depth 0, 1, 2, 3...
enemies.setOrigin(0.5);
enemies.setBlendMode(Phaser.BlendModes.ADD);
enemies.setTint(0xff0000);
enemies.shuffle();                  // randomize order in the group

API Quick Reference

Group (Phaser.GameObjects.Group)

Factory:  this.add.group(children?, config?)

Config types:
  GroupConfig       -- classType, name, active, maxSize, defaultKey, defaultFrame,
                       runChildUpdate, createCallback, removeCallback
  GroupCreateConfig -- key (required), classType, frame, quantity, visible, active,
                       repeat, yoyo, frameQuantity, max, setXY, setRotation,
                       setScale, setOrigin, setAlpha, setDepth, setScrollFactor,
                       hitArea, gridAlign

Key members:  children (Set), classType, maxSize, defaultKey, defaultFrame,
              active, runChildUpdate
Lifecycle:    create, createMultiple, add, addMultiple, remove, clear, destroy
Queries:      getFirst, getFirstAlive, getFirstDead, getLast, get, getChildren,
              getLength, getMatching, contains, countActive, getTotalUsed,
              getTotalFree, isFull
Pool:         get, getFirstDead, kill, killAndHide
Bulk ops:     setX/Y/XY, incX/Y/XY, setAlpha, setVisible, toggleVisible,
              playAnimation, propertyValueSet, propertyValueInc, setOrigin,
              setDepth, shuffle, setBlendMode, setTint

Container (Phaser.GameObjects.Container)

Factory:  this.add.container(x?, y?, children?)

Extends:  GameObject
Mixins:   AlphaSingle, BlendMode, ComputedSize, Depth, Mask, Transform, Visible

Key members:  list (Array), exclusive, maxSize, scrollFactorX/Y
Children:     add, addAt, remove, removeAt, removeBetween, removeAll
Queries:      getAt, getIndex, getByName, getFirst, getAll, getRandom, count
Ordering:     sort, swap, moveTo, moveUp, moveDown, sendToBack, bringToTop,
              moveAbove, moveBelow, reverse
Transform:    pointToContainer, getBounds, getBoundsTransformMatrix
Iteration:    each(cb, ctx), iterate(cb, ctx, ...args)
Config:       setExclusive, setScrollFactor(x, y, updateChildren)
Property:     length (read-only child count)

Layer (Phaser.GameObjects.Layer)

Factory:  this.add.layer(children?)

Extends:  Phaser.Structs.List
Mixins:   AlphaSingle, BlendMode, Depth, Filters, Mask, RenderSteps, Visible

Key members:  scene, displayList, sortChildrenFlag
Children:     add, remove (inherited from List)
Settings:     setAlpha, setBlendMode, setDepth, setVisible, setMask, setName,
              setActive, setState, setData, getData

No position, rotation, scale, scroll factor, input, or physics.
Cannot be added to a Container. Containers can be added to Layers.

Gotchas

1. Group is NOT on the display list. Its children appear on the Scene display list individually. Moving a Group does nothing visually -- use Container for that.

2. Container has performance overhead. Every child requires extra matrix math per frame. Deep nesting multiplies this. Avoid Containers when a Group or Layer suffices.

3. Container origin is always 0,0. The transform point cannot be changed. Position children relative to (0,0).

4. Container children lose Scene-level depth control. A child's depth only orders within the Container. The Container's own depth positions it in the Scene.

5. Physics + Container is problematic. If a Container is not at (0,0), physics bodies on children will be offset. Avoid physics bodies on Container children.

6. Container children cannot be individually masked in Canvas rendering. Only the Container itself can have a mask. Masks do not stack for nested Containers. Masks do stack in WebGL rendering.

7. Group.get() vs Group.getFirst() differ. get(x, y) is shorthand for getFirst(false, true, x, y) -- finds first inactive member and creates if none found. getFirst(state) defaults to active===false without auto-creating.

8. Layer cannot go inside a Container. Containers can be added to Layers, but not the reverse.

9. Group children Set is unordered. No index-based access. Use getChildren() to get an array snapshot.

10. killAndHide does not remove from the group. It only sets active=false and visible=false. The object stays in the group for reuse.

11. Container.setScrollFactor does not auto-propagate. Pass true as the third argument to also update children: container.setScrollFactor(0, 0, true).

12. Group.create() adds to the Scene display list. But group.add() does NOT unless you pass true as the second argument.

13. Container needs setSize() for input. Containers have no implicit size. You must call container.setSize(width, height) before setInteractive() will work with a hit area.

Source File Map

File	Description
src/gameobjects/group/Group.js	Group class -- pooling, create, getFirst*, kill, batch ops
src/gameobjects/group/GroupFactory.js	this.add.group() factory registration
src/gameobjects/group/typedefs/GroupConfig.js	GroupConfig typedef (classType, maxSize, callbacks)
src/gameobjects/group/typedefs/GroupCreateConfig.js	GroupCreateConfig typedef (key, quantity, setXY, etc.)
src/gameobjects/container/Container.js	Container class -- list management, nested transforms
src/gameobjects/container/ContainerFactory.js	this.add.container() factory registration
src/gameobjects/container/ContainerRender.js	Container WebGL/Canvas render functions
src/gameobjects/layer/Layer.js	Layer class -- display list bucket with alpha/blend/mask
src/gameobjects/layer/LayerFactory.js	this.add.layer() factory registration
src/gameobjects/layer/LayerRender.js	Layer WebGL/Canvas render functions
src/physics/arcade/ArcadePhysics.js	this.physics.add.group() / staticGroup()