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

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:

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:

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