Groupes et conteneurs

--- name: groups-and-containers description: "Use this skill when using Groups or Containers in Phaser 4. Covers organizing game objects, object pooling, batch operations, and nested transforms with Containers. Triggers on: Group, Container, object pool, getFirstDead, children." --- # 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 ``js // 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 `js // 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. ``js // 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);