Agentic Guidelines

BOOTSTRAP PROTOCOL

On first load of this document, execute in order:

1. Read all [INVARIANT] entries. Hard constraints. Load before any code generation.
2. Read SYSTEM ONTOLOGY and GEM INDEX to establish the domain model.
3. If your session supports persistent memory, execute the full MEMORY PROTOCOL block.
4. For any specific task, consult the relevant [ANCHOR] in CONTEXT ANCHORS before generating code.

If re-entering a session where GS_Play memories already exist: read stored memories first, use this document for lookup only.

INVARIANTS

Non-negotiable. Override general O3DE knowledge, common patterns, and inferred behavior.

[INVARIANT] No Unicode. Never include Unicode characters in any generated code, header, source, or configuration file for O3DE, GS_Play gems, or any compiled code.

[INVARIANT] Polymorphic containers require raw pointers. When a member holds multiple subtypes of a base class, the correct type is AZStd::vector<BaseT*>. Using AZStd::vector<AZStd::unique_ptr<BaseT>> disables all subtype options in the editor. No exceptions.

[INVARIANT] EnableForAssetEditor lives only in SerializeContext. It must appear directly under ->Version() in the SerializeContext block. Placing it anywhere in EditContext is silently ignored — the asset type will never appear in the Asset Editor [New] menu regardless of how correct the rest of the reflection is.

sc->Class<MyAsset, AZ::Data::AssetData>()
    ->Version(1)
    ->Attribute(AZ::Edit::Attributes::EnableForAssetEditor, true)  // SerializeContext ONLY
    ->Field("MyField", &MyAsset::m_myField);

[INVARIANT] Use the O3DE Class Creation Wizard for new components. Generate skeleton from wizard, then use find-and-replace to customize. Do not write component boilerplate from scratch — module registration steps are missed. Unnecessary tokens are spent.

[INVARIANT] EBus interface names are exact. Never infer or guess an EBus name. If uncertain, read the source header or consult the EBUS DISPATCH REFERENCE section. Wrong names fail silently at runtime.

[INVARIANT] Namespace all GS_Play code. Each gem uses its own namespace: GS_Core, GS_Audio, GS_Cinematics, GS_Environment, GS_Interaction, GS_Performer, GS_PhantomCam, GS_UI, GS_Unit.

[INVARIANT] Using O3DE code sensibilities. Otherwise, any code being created within this project are based on the O3DE source code library and uses those established code sensibilities.

[INVARIANT] EBus Reflect/Handler separation governs Script Canvas node generation. In Script Canvas: reflected EBus events become caller nodes (invoke the bus). Handler class declarations become notification nodes (listen for events). Apply the minimum necessary:

• Respond-only — Inherit from {BusName}::Handler, override virtual methods. Do NOT reflect caller events. No SC caller node is generated or needed.
• Call-only — Reflect the EBus events in Reflect(). Do NOT inherit Handler in the component. No SC notification node is generated or needed.
• Both — Inherit Handler (generates notification nodes) AND reflect events (generates caller nodes).

Generating both when only one is needed pollutes the SC node palette and signals incorrect intent to maintainers.

MEMORY PROTOCOL

[MEMORY] If your system supports persistent memory, create or verify these entries at session start:

At session end: If you discovered or confirmed any EBus method signatures, component property names, or TypeIds, ask the user: “Should I save what I learned about [topic] to memory?”

Memory freshness rule: If a stored memory conflicts with source code you have read during a session, source code is authoritative. Update the memory.

If no memory system is available: Re-read this document at the start of every new GS_Play session before generating any code.

SYSTEM ONTOLOGY

What this system is: gs_play_gems is a modular O3DE gameplay framework in C++17. It provides game systems as base classes for developer extension. It is a framework, not a library — the expected pattern is: extend base classes, override virtual methods, communicate exclusively via EBus.

Core architectural rules:

• Each Gem is a self-contained feature module. GS_Complete is the framework’s reference integration layer demonstrating cross-gem patterns — it is not a required home for your project code.
• Runtime cross-gem communication between GS_Play framework components uses EBus. Your own project code may include and combine gem headers as needed.
• All game systems are singleton Manager Components responding to GameManagerNotificationBus lifecycle events.
• Extensible type systems (dialogue effects, pulse types, motion tracks) use polymorphic base classes. Extend the base class and reflect it — types are discovered automatically through O3DE serialization at startup.
• All user-facing data must be reflected via SerializeContext + EditContext.

CLASS WIZARD PROTOCOL

[INVARIANT] Always use the Class Creation Wizard CLI for new component, asset, and system class generation. The wizard handles file scaffolding, CMake registration, module descriptor insertion, and system component wiring. Manual boilerplate misses registration steps and wastes tokens.

CLI invocation (agents use CLI mode only)

python ClassWizard.py \
  --engine-path  <engine-path> \
  --project-path <project-path> \
  --template     <template_name> \
  --component-name <Name> \
  --namespace      <GemNamespace> \
  --automatic-register \
  [<template-specific flags>]

--automatic-register is required for build integration (CMake file lists, module descriptors, system component entries). Omitting it generates files only.

Available templates — O3DE base

Available templates — GS_Play extensions

GS_Play provides gem-specific templates that extend the above. These handle GS_ base class wiring, EBus interface generation, and framework-specific registration steps automatically. Full reference: Templates List.

[ANCHOR] Registration requirements per template (some require a manual Reflect() call after generation) → Templates List: Registration Quick Reference

What the wizard generates

The wizard output for --template default_component --component-name PlayerHealth --namespace GS_Core produces:

• Source/PlayerHealthComponent.h / .cpp — component with Reflect(), Activate(), Deactivate(), AZ_COMPONENT_IMPL
• Include/GS_Core/PlayerHealthInterface.h — EBus interface header (unless --skip-interface)
• CMake file list entries, module descriptor registration (with --automatic-register)

Post-wizard agent workflow

After the wizard runs:

1. Add GS_ base class to the inheritance list alongside AZ::Component.
2. Add EBus handler inheritance for any buses this component listens to.
3. Wire BusConnect() / BusDisconnect() in Activate() / Deactivate().
4. Override virtual methods from the GS_ base class.
5. Add reflected fields in SerializeContext → EditContext.
6. Add gem dependency if the component depends on another GS_ gem: add_gem_dependency is automatic for some templates (e.g., LyShine), but cross-GS-gem dependencies must be added manually to CMake.

[ANCHOR] Before customizing wizard output → read the target base class API at /docs/framework/{gem}/.

Discovery commands

--list-templates                   # Print all available templates
--template-help <template_name>    # Print full command shape, all flags, and command list

Use --template-help to discover template-specific flags before invoking.

GEM INDEX

EBUS DISPATCH REFERENCE

Dispatch syntax

// Broadcast (no address, singleton bus)
GS_Core::GameManagerRequestBus::Broadcast(
    &GS_Core::GameManagerRequestBus::Events::NewGame);

// Entity-addressed
GS_Unit::UnitRequestBus::Event(
    entityId, &GS_Unit::UnitRequestBus::Events::Possess, controllerEntityId);

// Broadcast with return value
bool isStarted = false;
GS_Core::GameManagerRequestBus::BroadcastResult(
    isStarted, &GS_Core::GameManagerRequestBus::Events::IsStarted);

Bus naming convention

GS_Core buses

GS_Cinematics buses

GS_Interaction buses

GS_PhantomCam buses

GS_UI buses

Removed / Deprecated (do not use): GS_UIHubComponent, GS_UIHubBus, GS_UIWindowComponent — these were part of a removed three-tier Hub/Window/Page hierarchy. The current architecture is single-tier: Manager → Page.

GS_Unit buses

GS_Environment buses

GS_Audio buses

HOT PATHS

Canonical patterns for the most common agent tasks. Follow exactly.

HOT PATH 1 — Create a component extending a GS_ base

(Incorrect - Templates satisfy much of this.)

1. Identify target gem namespace and base class.
2. Generate skeleton via O3DE Class Creation Wizard.
3. Replace generated names. Add GS_ base class alongside AZ::Component in inheritance list.
4. In Activate(): call BusConnect() for all buses this component handles.
5. In Deactivate(): call BusDisconnect() for all buses.
6. In Reflect(): SerializeContext first, EditContext nested inside it. EnableForAssetEditor in SerializeContext only, directly under ->Version().

[ANCHOR] For any specific gem’s base class API → read /docs/framework/{gem}/ before writing the override body.

HOT PATH 2 — Dispatch an EBus command

(Incorrect - BusInterfaceName)

// Fire and forget, singleton bus
GS_{Gem}::{BusName}::Broadcast(
    &GS_{Gem}::{BusName}::Events::{MethodName},
    arg1, arg2);

// Entity-addressed bus
GS_{Gem}::{BusName}::Event(
    targetEntityId, &GS_{Gem}::{BusName}::Events::{MethodName}, arg1);

// With return value
ReturnType result{};
GS_{Gem}::{BusName}::BroadcastResult(
    result, &GS_{Gem}::{BusName}::Events::{MethodName});

HOT PATH 3 — Listen to an EBus notification

1. Inherit from {BusName}::Handler (protected inheritance).
2. In Activate(): {BusName}::Handler::BusConnect();
   • For entity-addressed buses: {BusName}::Handler::BusConnect(GetEntityId());
3. In Deactivate(): {BusName}::Handler::BusDisconnect();
4. Override the virtual notification methods.

HOT PATH 4 — Create a new Manager Component

1. Inherit from GS_Core::GS_ManagerComponent.
2. Connect to GameManagerNotificationBus in Activate().
3. Implement lifecycle hooks: OnSetupManagers, OnShutdownManagers, OnEnterStandby, OnExitStandby.
4. Define {Name}RequestBus (Single/Single policy) for commands.
5. Define {Name}NotificationBus (Multiple policy) for notifications.
6. Register descriptor in your gem’s module constructor.

[ANCHOR] Manager lifecycle and initialization order → /docs/framework/core/gs_managers/manager/

HOT PATH 5 — Create a Generic Data Asset

1. Inherit from AZ::Data::AssetData.
2. Include GS_Core Utility: GS_AssetReflectionIncludes.h
3. In Reflect(), SerializeContext block:

   sc->Class<MyAsset, AZ::Data::AssetData>()
       ->Version(1)
       ->Attribute(AZ::Edit::Attributes::EnableForAssetEditor, true)
       ->Field("Field", &MyAsset::m_field);
   

4. Register asset type in a system component’s Reflect().
5. EnableForAssetEditor goes only in SerializeContext. Never in EditContext.

HOT PATH 6 — Polymorphic container of subtypes

// CORRECT — all subtypes selectable in editor
AZStd::vector<BaseClass*> m_items;

// WRONG — disables all subtype options in editor
AZStd::vector<AZStd::unique_ptr<BaseClass>> m_items;

Reflect with ->Field("Items", &MyClass::m_items). O3DE handles subtype selection automatically with raw pointers.

HOT PATH 7 — Create a custom Trigger Sensor or World Trigger

Two distinct extension points. Choose the correct base:

Custom Trigger Sensor (condition side — detects when to fire):

1. Inherit from GS_Interaction::TriggerSensorComponent.
2. Override EvaluateSensor() — call Trigger() on all WorldTriggerRequestBus handlers on the same entity when your condition is met.
3. Reflect with SerializeContext and EditContext.
4. Register descriptor in your gem’s module.

Custom World Trigger (response side — what happens when fired):

1. Inherit from GS_Interaction::WorldTriggerComponent.
2. Override DoTrigger() — implement the response behavior.
3. Override DoReset() if the trigger should re-arm.
4. Reflect with SerializeContext and EditContext.
5. Register descriptor in your gem’s module.

[ANCHOR] Full WorldTrigger architecture → /docs/framework/interaction/world_triggers/

HOT PATH 8 — Add a custom Dialogue type (effect, condition, performance)

1. Inherit from the appropriate base: DialogueEffect, DialogueCondition, or DialoguePerformance.
2. Reflect the class using SerializeContext and EditContext. The system discovers it automatically at startup — no manual registration step.
3. GS_Complete demonstrates this pattern for cross-gem types (e.g., a dialogue effect controlling a PhantomCam). Use it as a reference, not a required location.

[ANCHOR] Dialogue type system → /docs/framework/cinematics/dialogue_system/

ANTIPATTERN CATALOG

[ANTIPATTERN] EnableForAssetEditor in EditContext. Silent failure — asset never appears in Asset Editor [New] menu. See INVARIANTS.

[ANTIPATTERN] unique_ptr in polymorphic AZStd containers. Disables all subtype selection in the editor. Use BaseT*. See INVARIANTS.

[ANTIPATTERN] Guessing EBus method names. O3DE EBus dispatches fail silently on wrong method names. Always verify against source headers or the EBUS DISPATCH REFERENCE in this document.

[ANTIPATTERN] Dispatching to entity-addressed buses before target entity is active. Buses are not connected before Activate() or after Deactivate(). Sending events before activation is silently dropped.

[ANTIPATTERN] Omitting AZ_COMPONENT_IMPL in the .cpp file. Component will not be reflectable. Causes subtle reflection failures that appear unrelated to the missing macro.

[ANTIPATTERN] Using "Editor" service in AppearsInAddComponentMenu. GS_Play components use AZ_CRC_CE("Game"). The "Editor" category makes components invisible in standard game entity contexts.

[ANTIPATTERN] Writing component boilerplate manually. Module registration steps are reliably missed. Always start from the O3DE Class Creation Wizard output.

CONFIDENCE THRESHOLDS

Proceed without reading source or docs:

• Standard O3DE component lifecycle: Init, Activate, Deactivate, BusConnect, BusDisconnect
• AZStd container usage (with the raw pointer rule applied for polymorphic types)
• CMake target aliases: Gem::{Name}.API, Gem::{Name}.Private.Object, Gem::{Name}.Clients
• SerializeContext → EditContext nesting order in Reflect()
• AZ_CRC_CE() for compile-time CRC values
• azrtti_cast<> for safe type casting in reflection code

Stop and read documentation or ask the user before proceeding:

• Any EBus method signature you are not 100% certain of
• Any virtual method signature on a GS_ base class
• Whether a specific GS_ gem is present in the target project
• Initialization order requirements for a new Manager component
• Any TypeId UUID value — never generate a UUID, ask the user or read the TypeIds header

CONTEXT ANCHORS

Conditions that require reading deeper documentation before generating code.

[ANCHOR] Before writing any unit movement or controller code: → Read /docs/framework/unit/ for mover types (3DFree, Strafe, Grid, SideScroller, Slide, Physics), grounder types, and controller hierarchy (Player vs AI). → [ASK] Which mover type does this movement context require?

[ANCHOR] Before configuring any virtual camera: → Read /docs/framework/phantomcam/ for camera types (PhantomCamera, StaticOrbit, Track, ClampedLook) and influence field setup.

[ANCHOR] Before wiring any dialogue sequence: → Read /docs/framework/cinematics/dialogue_system/ for the full chain: Sequencer → UIBridge → DialogueUI component.

[ANCHOR] Before implementing targeting or interaction: → Read /docs/framework/interaction/targeting/ for the TargetingHandler, Target, TargetField setup order and registration timing.

[ANCHOR] Before building any UI screen or menu: → Read /docs/framework/ui/ for the Manager → Page architecture, navigation return policies, companion component pattern, and UIManager registration sequence. The Hub/Window layer has been removed — do not use GS_UIHubComponent or GS_UIWindowComponent.

[ANCHOR] Before integrating save or persistence: → Read /docs/framework/core/gs_save/ for the SaveManager, RecordKeeper, and Saver component chain.

[ANCHOR] Before setting up project physics layers or collision groups: → Read /docs/get_started/configure_project/setup_environment/ for required engine-level physics configuration.

[ANCHOR] Before implementing behavior that combines two or more GS_ gems: → Review GS_Complete — it provides reference implementations of common cross-gem patterns. Reuse or adapt them rather than reimplementing from scratch.

CLARIFICATION TRIGGERS

[ASK] At the start of any GS_Play session, identify the user context:

• Designer / Scripter — Working in the O3DE editor with components, Script Canvas, or Lua. No C++ generation needed.

  • Guidance: component configuration, property setup, EBus Script Canvas nodes.
  • Documentation: The Basics → /docs/the_basics/
  • Gem-specific: /docs/the_basics/{gem}/ (e.g., /docs/the_basics/unit/ for unit questions)

• Engineer — Writing C++ to extend the framework with new components, gems, or systems.

  • Guidance: follows HOT PATHS and code patterns in this document.
  • Documentation: Framework API → /docs/framework/
  • Gem-specific: /docs/framework/{gem}/ (e.g., /docs/framework/unit/ for unit questions)

Both sections cover identical gem featuresets. The Basics covers component usage and scripting; Framework API covers C++ interfaces, EBus signatures, and base class architecture. Available gems in both: core, audio, cinematics, environment, interaction, juice, performer, phantomcam, ui, unit.

When answering any gem-specific question, include a link to the appropriate documentation section alongside your response. If the context is not stated, ask before generating any code or providing documentation links.

[ASK] Before creating any new component: Confirm which gem’s namespace and base class this component should use.

[ASK] Before generating any TypeId UUID: Always request the UUID from the user or confirm they want one generated. Never silently generate a UUID.

[ASK] If the task references a system with no memory or documentation coverage: Ask before inferring behavior. GS_Play base class APIs are not reliably guessable from generic O3DE patterns.

[ASK] If a Manager initialization order is being modified: The sequence of OnSetupManagers calls is load-order dependent. Confirm the intended position in the sequence before writing.

[ASK] If asked to implement a new Dialogue type: Extend the appropriate base class (DialogueEffect, DialogueCondition, or DialoguePerformance) and reflect it. Confirm which gem or module owns the new class before writing.

UPCOMING: AGENTIC SITE FEATURES (Post v1)

The GS_Play documentation site will implement formal agent-friendly features after the v1 documentation release. These are not yet live.

Planned additions follow the emerging specifications at:

• Making a Hugo Site Agent-Friendly — structured metadata, machine-readable page indexes, and LLM-optimized content formatting for Hugo-based docs sites.
• Agent Docs Spec — emerging open specification for agent-accessible documentation.

What this means for agents using this document now:

Until those features are live, this bootstrap document (/docs/get_started/agentic_guidelines/) is the primary machine-readable entry point. Treat it as authoritative. Do not rely on inferred site structure or navigated page discovery — navigate the docs via explicit paths from the GEM INDEX and CONTEXT ANCHORS sections above.

When the agent-friendly site features are released, this section will be updated with the new entry points and structured access patterns.