Cam Manager

OnStartupComplete:
  if m_enableInstancedChannels == false:
    Tier 1: if m_primaryRigPrefab valid → spawn one rig for channel 0
    Tier 2: no spawn (assumes level-placed CamCore)
  else:
    Tier 3: iterate m_channelConfigs[0 .. min(size, m_activeChannelCount)]
      for each PerChannelInstance config with valid prefab and m_enabledByDefault:
        SpawnChannelRig(channelId, GetEffectiveRigPrefab(channelId))

#pragma once
#include <GS_PhantomCam/GS_CamManagerBus.h>
#include <Source/GS_CamManagerComponent.h>

namespace MyProject
{
    class MyCamManager : public GS_PhantomCam::GS_CamManagerComponent
    {
    public:
        AZ_COMPONENT_DECL(MyCamManager);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        void EvaluatePriority() override;
        AZ::EntityId EvaluatePriorityForChannel(GS_PhantomCam::ChannelId channelId) override;
    };
}

#include "MyCamManager.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(MyCamManager, "MyCamManager", "{YOUR-UUID-HERE}");

    void MyCamManager::Reflect(AZ::ReflectContext* context)
    {
        if (auto serializeContext = azrtti_cast<AZ::SerializeContext*>(context))
        {
            serializeContext->Class<MyCamManager, GS_PhantomCam::GS_CamManagerComponent>()
                ->Version(0);

            if (AZ::EditContext* editContext = serializeContext->GetEditContext())
            {
                editContext->Class<MyCamManager>("My Cam Manager", "Custom camera manager")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"));
            }
        }
    }

    void MyCamManager::EvaluatePriority()
    {
        // Call base to run standard per-channel arbitration.
        GS_CamManagerComponent::EvaluatePriority();

        // Custom system-wide logic here.
    }

    AZ::EntityId MyCamManager::EvaluatePriorityForChannel(GS_PhantomCam::ChannelId channelId)
    {
        // Apply per-channel rules before falling back to base arbitration.
        // Example: lock to a specific cam during a scripted sequence.
        // if (m_lockedCam.IsValid()) return m_lockedCam;
        return GS_CamManagerComponent::EvaluatePriorityForChannel(channelId);
    }
}

1 - Channels & Instancing

A channel is one player viewpoint slot. Each channel owns its own rig (spawned from a prefab), its own Cam Core, zero or more Phantom Cameras registered to it, a bound target, and its own priority table. Channel 0 (DefaultChannelId) is the implicit default for all legacy / single-player flows.

The channel system progressively discloses across three authoring tiers — Tier 1 single-cam, Tier 2 single-player rig, Tier 3 multi-channel. The per-cam authoring surface is identical across tiers; only the Cam Manager configuration changes.

Pending — multi-view rendering (I.9b). The channel system architecturally supports per-channel render targets via AttachmentImage assets, but the Atom RPI binding has not landed yet. Until it does, the engine renders one channel at a time even when multiple are arbitrating internally. The active main-view selector decides which channel reaches the engine framebuffer; see Active Main View.

Contents

• Three Authoring Tiers
• ChannelId
• Cam Channel Scope
• ChannelStampComponent
• Rig Prefab Resolution
• Spawn Pipeline
• Stamp-Walk Registration
• Shared Cams and Collapse Detection
• Cross-Channel Dispatch
• Active Main View
• Runtime Channel API
• Notifications
• Tier 3 Author Workflow
• Naming Collision Callout
• See Also

Three Authoring Tiers

The Cam Manager exposes three top-level inspector fields that control the system tier. See Cam Manager — Authoring Tiers for the full author surface.

The Master Gate is m_enableInstancedChannels. When OFF, channel-aware fields are hidden in the inspector and only the legacy bus signatures (SetTarget, SettingNewCam) route through. When ON, the full channel surface is live and channel-aware notifications (SettingNewCamOnChannel) replace the legacy ones.

ChannelId

using ChannelId = AZ::u32;
static constexpr ChannelId InvalidChannelId = static_cast<ChannelId>(-1);
static constexpr ChannelId DefaultChannelId = 0;

Channel ids are integers (0 … max − 1). The default channel id is 0. Legacy single-arg bus calls (SetTarget(target), RegisterPhantomCam(cam)) forward to channel 0.

Logical cam names — the entity names of phantom cameras inside a rig prefab — are scoped within their channel. The same name can appear in all four channels’ rigs without collision. Authors never type _i1 / _i2 suffixes.

Cam Channel Scope

Each Phantom Camera authors a CamChannelScope that decides how it participates in the channel system:

enum class CamChannelScope : AZ::u8 {
    Local       = 0,  // Default. Lives in its owning channel's scope.
    AllChannels = 1,  // In-rig natural duplicate — every rig instance carries one.
    TrueUnique  = 2,  // Exactly one instance total; bound or shared.
};

TrueUnique sub-fields (visible only when scope is TrueUnique):

Author recipes:

• Cam inside a rig prefab — leave as Local.
• Per-player tailored broadcast cam in the level — AllChannels (in-rig); deferred for out-of-rig.
• Hero-perspective cam for a specific player — TrueUnique + m_boundChannelId = N.
• Shared cinematic collapse cam — TrueUnique + advanced + m_allChannelsShare = true. Pair with a Group Target to trigger OnAllChannelsActivatedSharedCam.

ChannelStampComponent

Pure runtime plumbing. Marks an entity (typically a rig root) with a (ChannelId, stampToken) pair. Phantom Camera and Cam Core components walk transform ancestors looking for this stamp at activate time to determine which channel they belong to.

Authored visibility: none. The stamp is reflected for serialization only — no EditContext block. The author never sees or sets it; the Cam Manager auto-attaches one during the spawn pre-insertion callback and calls StampChannel(channelId) to bump the token.

Why the token

m_stampToken bumps on every StampChannel(id) call (including idempotent re-stamps). The Cam Manager validates the supplied (channelId, token) against the live stamp on every registration call — mismatched tokens are rejected with a warning. This prevents stale messages from a previous stamp generation overwriting fresh bindings.

Buses

Static helper

static AZ::EntityId ChannelStampComponent::FindStampAncestor(AZ::EntityId start);

Walks transform ancestors via the request bus and returns the closest stamped entity (or invalid id if no stamp ancestor).

Rig Prefab Resolution

Three inspector fields on the Cam Manager control where each channel’s rig comes from:

The Cam Manager’s GetEffectiveRigPrefab(channelId) returns:

1. m_channelConfigs[channelId].m_rigPrefab if set.
2. Else m_primaryRigPrefab.
3. Else invalid (the channel emits a warning at spawn time and stays inert).

Symmetric multi-channel co-op (all players use the same rig) sets the primary once; every channel inherits. Asymmetric setups (e.g. P1 third-person, P2 top-down) set per-channel overrides.

Spawn Pipeline

The Cam Manager spawns configured rigs on startup (driven by OnStartupComplete) and re-spawns them on stage transitions.

OnStartupComplete:
  if m_enableInstancedChannels == false:
    Tier 1: m_primaryRigPrefab valid → SpawnChannelRig(DefaultChannelId, m_primaryRigPrefab)
    Tier 2: no spawn (assumes level-placed CamCore)
  else:
    Tier 3: iterate m_channelConfigs[0 .. min(size, m_activeChannelCount)]
      for each PerChannelInstance config with m_enabledByDefault and valid prefab:
        SpawnChannelRig(channelId, GetEffectiveRigPrefab(channelId))

SpawnChannelRig uses an EntitySpawnTicket with two callbacks:

1. Pre-insertion callback (entities created, not yet activated):
   • Cam Manager identifies the spawn root (first entity in the spawn container).
   • Attaches a ChannelStampComponent to it.
   • Calls StampChannel(channelId) — bumps the token, fires OnStamped to any subscribers.
2. Completion callback (entities activated):
   • Cam Manager walks activated entities into channel.m_rigSpawnedEntities.
   • Marks the channel m_active = true.
   • Folds any TrueUnique-shared cams into the new channel’s priority table.
   • Validates that a Cam Core registered (warns if not).
   • Broadcasts ChannelSpawned(channelId, camCoreEntity).
   • Re-runs EvaluatePriority(channelId) so the channel’s arbitration result reaches its Cam Core.

Stage transitions

BeginLoadStage    → DespawnAllChannelRigs (lock arbitration first)
LoadStageComplete → SpawnAllConfiguredRigs BEFORE broadcasting HandleStartup
                    so fresh-stage cams come up in the startup wave.

Stamp-Walk Registration

When a Phantom Camera (or Cam Core) activates, it walks ancestors for a ChannelStampComponent and branches:

RegisterWithCamManager:
   branch on m_channelScope (PhantomCam only — CamCore is always Local-equivalent):

   ┌── Local:
   │      stamp = FindStampAncestor(myEntity)
   │      if stamp valid:
   │         RegisterPhantomCamForChannel(myEntity, stamp, channelId, token)
   │         registrationMode = StampAware
   │      else:
   │         RegisterPhantomCam(myEntity)             // legacy channel 0
   │         registrationMode = LegacyChan0
   │
   ├── AllChannels:
   │      stamp = FindStampAncestor(myEntity)
   │      if stamp valid:
   │         RegisterPhantomCamForChannel(myEntity, stamp, channelId, token)
   │         registrationMode = StampAware
   │      else:
   │         warn (out-of-rig cloning deferred)
   │         fall back to legacy channel 0
   │         registrationMode = LegacyChan0
   │
   └── TrueUnique:
          if m_boundChannelId valid AND !m_allChannelsShare:
             RegisterPhantomCamDirect(myEntity, m_boundChannelId)
             registrationMode = Direct
          elif !m_boundChannelId AND m_allChannelsShare:
             RegisterPhantomCamShared(myEntity)
             registrationMode = (Shared, stored as Direct for unregister routing)
          else:
             warn (fragile manual-control mode)
             stay unregistered
             registrationMode = None

registrationMode is cached on the component so UnregisterFromCamManager can route symmetrically.

OnStamped — mid-session re-stamp handling

If a rig is re-stamped mid-session (rare; typically only during stage transitions or hot-reload), the cam handles it:

OnStamped(newChannelId, newToken):
   Only acts in StampAware or None modes.
   In Direct or LegacyChan0 modes, the signal is ignored — author intent
   takes precedence over stamps.

   UnregisterFromCamManager (old binding)
   m_resolvedChannelId  = newChannelId
   m_resolvedStampToken = newToken
   RegisterWithCamManager (new binding)

The Cam Core mirrors the same pattern.

Shared Cams and Collapse Detection

RegisterPhantomCamShared(cam) adds the cam to every active channel’s priority table. The Cam Manager tracks the list in m_sharedCams. A shared cam:

• Wins arbitration in every channel where it has the highest priority.
• Gains focus from any channel selecting it.
• Never DROPS focus via channel notifications — a shared cam losing in channel N doesn’t preclude winning in channel M.

Collapse detection

EvaluatePriority collects per-channel winners. If every active channel picked the same cam AND that cam is in m_sharedCams, the Cam Manager edge-triggers OnAllChannelsActivatedSharedCam(sharedCam) via m_lastSharedCollapsedCam — fires once on entry into the condition, and once on cam-A → cam-B shared-cam transitions.

Typical use case: a shared cinematic cam paired with a Group Target tracking all players. When players converge such that the shared cam wins in every channel, UI receives the collapse signal and can switch from split-screen layout to single-view layout.

No counterpart “uncollapsed” event exists — listeners dedupe locally if they care about exit.

Cross-Channel Dispatch

For cinematic / cross-channel scenarios — e.g. player 3’s wide cam should temporarily render on player 1’s Cam Core — the Cam Manager exposes a dispatch override.

Channel arbitration still runs internally during dispatch. SettingNewCamOnChannel continues to fire with the arbitrated winner — only the physical Cam Core route is overridden. This means downstream listeners still see what “would have” arbitrated, useful for HUD or AI behavior that shouldn’t follow the cinematic override.

Active Main View

Wraps O3DE’s AzFramework::Camera::CameraRequests::MakeActiveView so the channel system can orchestrate “this player’s view is on main right now” without callers reaching into camera bus plumbing. Orthogonal to dispatch (what cam) and render-target binding (where pixels go).

Listeners receive OnActiveCameraChanged(channelId, camCoreEntity). channelId == InvalidChannelId when the active cam isn’t channel-bound (e.g. a direct SetActiveCamCore to an external entity). External MakeActiveView calls made outside this API are not observed — subscribe to AzFramework::Camera::CameraNotificationBus directly if you need to detect engine-level changes.

Runtime Channel API

Intended lobby flow: author sets m_channelConfigs to N (primed max), pre-startup the lobby calls SetActiveChannelCount(actualPlayerCount), then OnStartupComplete spawns just actualPlayerCount rigs. Mid-session join / drop uses EnableChannel / DisableChannel.

Notifications

Channel-related events on CamManagerNotificationBus. See Cam Manager — Notifications for the full notification surface.

Tier 3 Author Workflow

1. On the Cam Manager: toggle m_enableInstancedChannels = true.
2. Set m_primaryRigPrefab to the project’s default rig (used as universal fallback).
3. Populate m_channelConfigs with one entry per supported player slot:
   • Set m_channelName for inspector readability (“P1”, “P2”, …).
   • Optionally set m_rigPrefab (the “Rig Override Prefab”) — leave empty to inherit the primary.
   • Set m_enabledByDefault = true for slots that should spawn on startup.
4. Optionally set m_activeChannelCount for the lobby cap, or call SetActiveChannelCount at runtime before startup.
5. Per-player cams placed inside the rig prefab will auto-stamp on spawn — no per-cam authoring required for normal Local-scope cams.
6. For shared cinematic cams (one cam to rule them all), set the cam’s m_channelScope = TrueUnique + m_showAdvanced = true + m_allChannelsShare = true.
7. For author-explicit per-channel cams (rare), use m_channelScope = TrueUnique + m_boundChannelId = N + m_allChannelsShare = false.

For the basics-side walkthrough with screenshots and step-by-step recipes, see The Basics: Channels & Instancing.

Naming Collision Callout

Tug-field m_channels ≠ instancing ChannelId. Tug-field channels are arbitrary string tags (“Cinematic”, “Combat”) that match tug volumes to listeners — see Tug Fields. Instancing channels documented on this page are integer ChannelIds for per-player viewpoint routing. The two systems are unrelated despite the shared word. The system uses the same identifier name in the codebase for both; the docs make the distinction prominent here and in the tug-fields page.

See Also

For related PhantomCam pages:

• Cam Manager — the owning component.
• Phantom Cameras — CamChannelScope is authored on each cam.
• Cam Core — one Cam Core per channel.
• Group Targets — pair with shared TrueUnique cams for collapse-to-single-view scenarios.
• Tug Fields — note the channel naming disambiguation above.

For the basics-side walkthrough:

• The Basics: Channels & Instancing

Get GS_PhantomCam

GS_PhantomCam — Explore this gem on the product page and add it to your project.