Group Target Configurations

Step-by-step recipes for GroupTargetComponent — two-player party cam, combat encounter framing, and collapse-to-single-view triggers.
Categories:
Tags:

A Group Target is an entity whose world transform is the weighted centroid of a runtime-editable subject list. You point a camera at it like any other target, and the cam frames “where the group is” rather than chasing any single subject.

For the concept, centroid modes, subject-management API, and pitfalls, see The Basics: Group Targets. For the full per-field reference and the registry bus, see Group Targets (Framework API).

 

Contents

Recipe: Two-Player Party Cam

A single cam that frames both players, sliding smoothly as they spread apart and converge.

Steps

  1. Create a Group Target entity in your level (a plain entity with TransformComponent is fine).

  2. Add GroupTargetComponent to it. Configure:

    • Name → "Party" (or any string — this is your registry key).
    • Centroid Mode → WeightedMean.
    • Smoothing Halflife → 0.2 (gentle smoothing so the centroid doesn’t jitter when players move).

  3. Add Subjects at level start (or whenever players spawn):

    GS_PhantomCam::GroupTargetRequestBus::Event(
    groupEntityId,
    &GS_PhantomCam::GroupTargetRequests::AddSubject,
    player1EntityId, 1.0f);    // equal weight

GS_PhantomCam::GroupTargetRequestBus::Event(
    groupEntityId,
    &GS_PhantomCam::GroupTargetRequests::AddSubject,
    player2EntityId, 1.0f);

  4. On the Phantom Camera: Set the Body and Aim stages’ Target Mode to GroupTarget and Group Target Name to "Party". The stages will resolve the group entity through the Cam Manager registry at runtime.

The cam now points at the weighted midpoint of both players. As they move, the centroid follows.

Tip — pull the cam back as the spread grows. Pair this group cam with a DynamicOrbitBody and adjust the orbit shape’s radius at runtime based on subject spread. The group’s centroid is the pivot; the cam stays a healthy distance back so both subjects stay in frame. See the Group-Framing Cam recipe for the stage composition side.

Recipe: Combat Encounter Frame

The cam frames an evolving encounter. Subjects are added when combatants engage and removed when they disengage or die.

Steps

  1. Create a Group Target named "CurrentCombat" (or similar).

  2. On combat start, add the player and the engaged enemies:

    AddSubject(player, weight: 2.0);          // weight player higher
for (each enemy in encounter):
    AddSubject(enemy, weight: 1.0);

  3. On enemy death or disengage, remove the subject:

    RemoveSubject(deadEnemy);

  4. On combat end, clear:

    ClearSubjects();

  5. Set the cam’s Body and Aim to GroupTarget mode with name "CurrentCombat".

Why weight the player higher? Pure equal-weighting means a single enemy at long range drags the cam half-way to them. Weighting the player higher keeps framing centered on the player while still acknowledging the enemy’s presence.

When m_deactivateWhenEmpty is true (default), the cam falls back to hold-last-pose if the encounter clears completely — handy for the moment between encounters.

Recipe: Collapse to Single View

For multi-channel projects: when all players converge, switch from split-screen to a single shared cam, then receive a UI signal at the moment of collapse.

Steps

  1. Create a Group Target tracking all players (same as the party cam recipe).

  2. Author a shared cam outside any rig prefab. Set:

    • Channel Scope → TrueUnique.
    • Show Advanced → on.
    • All Channels Share → on.
    • Body / Aim Target Mode → GroupTarget, name → "Party".

  3. Tune priority so the shared cam wins arbitration when players are close enough (e.g. use a CameraInfluenceField volume around the players’ convergence point).

  4. Listen for the collapse signal in your UI controller:

    void OnAllChannelsActivatedSharedCam(AZ::EntityId sharedCam)
{
    // All channels selected the same shared cam — switch to single-view layout.
}

When players converge such that the shared cam wins in every channel simultaneously, the Cam Manager fires OnAllChannelsActivatedSharedCam once on the edge. UI hides split-screen dividers and shows the single shared view.

See Channel Tier Configurations for the surrounding multi-channel setup.

See Also

Related recipe collections:

Basics this builds on:

Framework API: