This is the multi-page printable view of this section. Click here to print.
Lessons around the various features. Installation. And extended tutorials on deeper usage, or project creation.
Video Tutorials are one or a playlist of videos covering a targeted topic.
Lessons are guide documents that describe in step by step ways, with informational detail, on how to accomplish the targeted goal. Lessons tied to a video tutorial will have a link to the Video Page for use.
GS_Play is an intermediate to advanced game development and production framework. Because of this it can rapidly create prototypes and prove out gameplay, but is deeply extensible and customizable — allowing the project to grow, and the game to become exactly what you want to make. This does mean the tools are not as “out of the box” as more beginner-friendly options. You should already know how to make videogames, or be actively studying how to develop features, to get the most out of this framework. Check out the library of lessons and guides to get embedded in any GS_Play feature you’d like to explore.
Due to its modularity, your project should only need to target the features most relevant to your intended gameplay and genre, then build on and around the framework to satisfy any additional needs.
GS_Play is built on the idea of simple, intuitive patterns for every feature — patterns that let you think about how to deploy the functionality, not how it works under the hood. Because of this core tenet, you should be able to reason about what the premade functionality can do, and what custom features you want to contribute to that pool, to author your project rapidly and precisely.
The core functionality is oriented around character-centric, live-action gameplay. This can be slow and subtle — a point-and-click adventure or survival horror where the action revolves around exploration, investigation, and choosing your own path. It can also be extended to high-paced action: character-driven unit gameplay, supported by cinematic performer visuals, where you attack, roll, jump, dodge, and traverse a complex world. Enter and exit game-time cinematics, or transition into rich, fully authored sequences. The PhantomCam system can keep pace with anything you throw at it.
That is not to say other styles and genres are off the table. Many GS_Play feature sets are genre-agnostic and simply complete the needs of a full production. GS_UI can serve as straightforward menus and indicators, but with the dynamic animation system, wealth of widgets, and precise control of input focus, it can anchor heavily UI-reliant gameplay. With deeply extensible unit control, AI, and input handling, you can pursue the group formation and pathing an RTS requires. Any genre, supported by Audio, VFX, Cinematics, and gameplay systems working together.
The ultimate goal for GS_Play is to get you from a blank canvas to the end credits, and everything in between.
Focus on learning the patterns of each feature set. There are many base elements ready to use from the start, but as you work, keep asking: “What would I do if I needed X for my game?” That question is the right lens for every feature — it keeps you thinking about your game’s needs, not the framework’s internals.
Target only what your game requires. GS_Play’s modularity means you are not obligated to use every gem. Start with the features that directly serve your genre and core loop, then expand from there as the project demands it.
Lean on the EBus pattern. Most systems communicate through request and notification buses. Understanding how to listen for state changes and issue requests is the skill that unlocks the entire framework.
Review Best Practices for full coverage.
15+ gems, with 30+ feature sets across them.
A guide to get everything propped up rapidly
Embed youtube guide.
Link to video_tutorials.
<ProjectGemName>.Private.Object STATIC
BUILD_DEPENDENCIES
PUBLIC
Gem:GS_Play_Core.API
Gem:GS_<your desired module>.API
Check out the Project Setup Video Tutorial (Links to video_tutorial tag for setup video)
These are the necessary details to create your project and have it run reliably with all GS_Play featuresets.
Image showing the standard PhysX Configuration necessary to support all GS_Play features.
Image showing the standard PhysX Collision Layers necessary to support all GS_Play features.
Image showing the standard PhysX Collision Groups necessary to support all GS_Play features.
In order to properly introduce a GS_Unit to the default scene you need to create an object with the “Environment” collision layer to stand on.
The easist way to start is to change the collision layer of the default “Ground” entity in the level.
Check out the Project Setup Video Tutorial (Links to video_tutorial tag for setup video)
Check out the Project Setup Video Tutorial (Links to video_tutorial tag for setup video)
Check out the Project Setup Video Tutorial (Links to video_tutorial tag for setup video)
The parent page — Agentic Guidelines — is not a documentation page in the normal sense. It contains no prose meant for a human to read comfortably. It is a structured seed document, intended to be pasted or loaded into an AI agent session before any GS_Play framework work begins.
Think of it as a mission briefing card. It is dense, compressed, and declarative. Every line exists to be parsed and acted on by a machine — not to be understood leisurely by a person.
Why it exists: Agents working without this document make predictable, repeatable errors. They guess EBus names incorrectly, place EnableForAssetEditor in the wrong reflection context, write polymorphic containers with the wrong pointer type, or generate C++ where a scripting answer was needed. The agentic guidelines page is the countermeasure for all of those failures.
What it is not: It is not a tutorial, an overview, or a feature summary. Those documents live elsewhere in the framework documentation. This page exists only to give an agent precise, actionable constraints and lookup data before it starts working.
The framework has two distinct user groups. This distinction determines what kind of guidance an agent should give, and it is the single most important thing to keep in mind when editing this document.
This user works entirely inside the O3DE editor. They configure components in the entity inspector, connect logic with Script Canvas or Lua, set up prefabs, and tweak exposed properties. They never write C++. For this user, an agent should provide guidance about:
This user writes C++ to extend the framework. They inherit from GS_Play base classes, create new gems or project-level systems, write new components, and build on top of the existing architecture. For this user, an agent should provide guidance about:
Engineers have full freedom to combine gems. GS_Complete is the framework’s reference integration layer — it demonstrates cross-gem patterns but is not a restriction on what engineers can do in their own projects. An engineer may freely include headers from multiple gems in their project code.
The page uses three tiers of information. Understanding these tiers is the most important thing before contributing.
Hard rules with no exceptions. These live at the very top of the document in the INVARIANTS section. An agent that reads only the first 600 tokens of the document will encounter all of them.
Invariants are:
BaseT*”, not “use the right container type”)Do not add to the Invariants section unless a rule is a hard technical constraint that has no contextual exceptions and causes a silent failure or editor malfunction when violated.
This is the structural description of what the system is: the SYSTEM ONTOLOGY paragraph, the GEM INDEX table, the EBUS DISPATCH REFERENCE, and the HOT PATHS section. This tier answers the question: what is this system and how do I operate it?
This tier is:
This tier does not provide information directly. It tells the agent when to stop and go deeper. The CONTEXT ANCHORS, CONFIDENCE THRESHOLDS, and CLARIFICATION TRIGGERS sections all belong here. They point the agent toward more information and define the exact conditions under which to seek it.
The document uses a small, fixed vocabulary of bracketed tokens. These act as machine-readable instruction labels. Agents across all backends pick them up reliably through pattern matching.
| Token | Meaning | Location |
|---|---|---|
[INVARIANT] | Hard constraint. Never violate. No exceptions. | INVARIANTS section |
[ANCHOR] | Stop and read the linked documentation before proceeding. | CONTEXT ANCHORS, inline in HOT PATHS |
[MEMORY] | Persist this content if a memory system is available. | MEMORY PROTOCOL section |
[ASK] | Do not infer. Pause and ask the user before proceeding. | CLARIFICATION TRIGGERS, inline in HOT PATHS |
[ANTIPATTERN] | What not to do and briefly why. | ANTIPATTERN CATALOG section |
Use only these tokens. Do not invent new ones. Tokens work because they are stable — an agent learns to treat [INVARIANT] as a certain category of instruction. A new, undiscussed token may be ignored or misinterpreted.
If you genuinely believe a new token category is needed, document the reasoning and discuss it before adding it. The bar is high: the existing five tokens cover almost every instruction type needed.
Before opening the file, answer these questions:
If none of these are true, you probably do not need to edit the parent document. Editing it without a concrete reason adds noise.
Use this map to find where your change belongs:
| Type of change | Target section |
|---|---|
| A rule that must never be broken | INVARIANTS |
| A new gem or renamed manager | GEM INDEX |
| A new or renamed EBus or method | EBUS DISPATCH REFERENCE |
| A new common code task | HOT PATHS |
| A mistake agents keep making | ANTIPATTERN CATALOG |
| A decision that needs user input | CLARIFICATION TRIGGERS |
| A documentation page that gives deep context | CONTEXT ANCHORS |
| Something agents can safely assume | CONFIDENCE THRESHOLDS |
| A memory entry agents should persist | MEMORY PROTOCOL |
If your change doesn’t fit any of these cleanly, it is probably better expressed in the framework’s technical documentation pages rather than here.
Do not add surrounding context, explanations, or improvements to adjacent content. The agentic document is optimized for token density — adding prose that an agent does not need to act on degrades its quality.
Apply the minimum correct change:
[INVARIANT] entryResist the impulse to expand.
Before saving, verify every name, method, and path in your change against the source:
GS_{Name}TypeIds.h.Read only the section you changed and ask: does an agent reading only this section know what to do, or does it still need to infer?
If it still needs to infer, the entry is incomplete. If it specifies exact names, exact locations, exact conditions, and exact patterns — it is ready.
If you added a new section to the parent document, added a new token type, changed the tier structure, or changed any guidance about how to contribute — update this page to match. The two documents must stay in sync. See the section below: When to Update This Page.
Edit when: The loading order or session re-entry behavior of the document should change.
Rules:
Edit when: A new silent-failure rule has been discovered through a real agent error, or an existing invariant is no longer accurate.
Qualifying test for a new invariant — all must be true:
Format:
`[INVARIANT]` **Short title.** One or two sentences of exact, actionable constraint.
Optionally: a code block showing the correct pattern.
Do not add O3DE general best practices here. They do not belong in the invariants list — agents already know them.
Edit when: A new section is added to the parent document that should be persisted to memory, or a memory key is renamed.
Rules:
gs_play_invariants, not GS Play Invariants.Edit when: The engine version changes, the build toolchain changes, or the platform target changes.
Rules:
Edit when: A new gem is added, a gem is renamed, a manager component is added or renamed, a primary bus is renamed, or a documentation path changes.
Rules:
GS_Complete remains in the index as the integration layer reference — it documents a real gem. Its description should clarify it is Genome Studios’ reference layer, not a restriction on user code.Edit when: A new EBus is added to any gem, a method is renamed, or the dispatch policy of a bus changes.
Rules:
ById. If it is a singleton broadcast, the column says Broadcast. If it is a listener-only bus, say Listen.### {GemName} buses subsection.Edit when: A new common task emerges that agents are regularly asked to perform, or an existing hot path’s steps become inaccurate.
Qualifying test for a new hot path — all must be true:
Format:
### HOT PATH N — Short task description
1. First discrete action.
2. Second discrete action.
3. Third discrete action.
`[ANCHOR]` Condition requiring deeper reading → /docs/path/to/page/
Rules:
[ANCHOR] at the end if there is a documentation page that provides necessary deeper detail.Edit when: A real agent error is identified that this document should prevent, or an existing antipattern is no longer relevant.
Qualifying test — all must be true:
Format:
`[ANTIPATTERN]` **Short title.** One sentence describing the failure. One sentence pointing to the correct behavior or its location in this document.
Do not add antipatterns that are just general bad practices. Every entry here should represent a failure mode specific to GS_Play or to O3DE patterns that agents commonly get wrong.
Edit when: A GS_Play-specific assumption has been confirmed safe (add to “proceed” list) or a pattern that agents incorrectly assume they know turns out to need verification (add to “stop” list).
Rules:
Edit when: A new documentation page is added that meaningfully fills a knowledge gap an agent would otherwise have to guess around, or an anchor’s target path changes.
Qualifying test for a new anchor:
Format:
`[ANCHOR]` **Before doing [specific task]:**
→ Read /docs/path/to/page/ for [what the agent needs from it — be specific].
→ `[ASK]` Optional inline clarification prompt if a user decision is required here.
Note on GS_Complete anchors: GS_Complete is a valid reference target. An anchor pointing to it as a reference (“review GS_Complete for examples”) is appropriate. An anchor that frames it as a restriction (“you must implement this there”) is not — that is a framework-internal structural convention, not a rule that applies to user project code.
Edit when: A new category of user decision is identified where agents predictably infer the wrong answer, or an existing trigger is too broad to fire usefully.
Qualifying test:
The USER CONTEXT trigger at the top of this section must never be removed. It is the most important clarification in the document — it gates all subsequent behavior between designer/scripter guidance and engineer guidance.
The two documentation sections referenced in USER CONTEXT are:
/docs/the_basics/) — Scripter and designer documentation. Covers component usage, property configuration, and scripting for all gems./docs/framework/) — Engineer documentation. Covers C++ interfaces, EBus signatures, base class architecture, and reflection patterns for all gems.Both sections cover the same featureset across the same gem set: core, cinematics, environment, interaction, performer, phantomcam, ui, unit, ai, item, rpstats. Update the USER CONTEXT doc links if any gem is added, renamed, or its documentation path changes in either section.
Understanding what to avoid is as important as understanding what to write.
Prose explanations. The parent document must never read like a tutorial. “The EBus system in O3DE works by…” is wasted tokens. An agent already knows what EBus is. It needs the specific name and specific dispatch syntax.
Vague headings. “Common Patterns”, “Unique Details” — these tell neither a human nor a machine what type of instruction to expect. Every section heading in the parent document is also a category of instruction.
Soft language. “You should consider”, “it is generally recommended” — agents do not weight soft language correctly. If something must be done a specific way, say so directly. Preferences belong in other documentation pages, not here.
Information without a trigger condition. Raw information with no instruction about when to use it adds cognitive load without adding value. Every fact in the parent document is attached to a pattern, a constraint, a lookup trigger, or a warning.
Framework-internal conventions framed as user-facing rules. Conventions about how the framework’s own gem structure is organized (like where cross-gem components live within the framework itself) should not appear as [INVARIANT] or [ANTIPATTERN] entries. Engineers extending the framework in their own projects have full freedom to organize code as their project requires.
Outdated EBus names or method signatures. This is the most damaging type of error in the document. An agent trusting a wrong bus name fails silently, and the diagnosis will be non-obvious. Before adding or updating anything in the EBus section, verify against the current source header.
When any of the following changes in the codebase, update the corresponding section:
| Codebase change | Section to update |
|---|---|
| New EBus added | EBUS DISPATCH REFERENCE — add table row |
| EBus method renamed | EBUS DISPATCH REFERENCE — update row; scan HOT PATHS for any direct references |
| New gem added | GEM INDEX — new row; update dependency graph |
| New Manager Component added or renamed | GEM INDEX — update Manager column and Primary Bus column |
| New documentation page published | CONTEXT ANCHORS — add anchor if it fills a knowledge gap |
| Documentation page moved or renamed | CONTEXT ANCHORS — update the path; if it is a gem root page in The Basics or Framework, also check CLARIFICATION TRIGGERS USER CONTEXT links |
| New gem added to the framework | GEM INDEX, EBUS DISPATCH REFERENCE, CLARIFICATION TRIGGERS USER CONTEXT gem list (both /docs/the_basics/ and /docs/framework/ paths) |
| O3DE API change affecting Reflect() patterns | INVARIANTS and HOT PATH 1, 5 — verify code blocks still compile |
| New common agent task identified | HOT PATHS — add new numbered path |
| New silent-failure pattern discovered | ANTIPATTERN CATALOG — add entry |
| GS_Play base class API changes | CONFIDENCE THRESHOLDS — verify the “stop” list is still accurate |
This contributing page should stay in sync with the parent document’s structure. Update it when:
This page is allowed to have prose. It is written for humans. Explanations, reasoning, and examples are all appropriate here. The parent document is the one that must remain dense and machine-optimized.
Before saving any change to the parent document, apply this test:
Read only the section you changed. Ask: does an agent reading only this section know exactly what to do, or does it still need to infer?
If it still needs to infer, the entry is incomplete. It is ready when it specifies:
A strong contribution eliminates a whole class of agent errors. A weak contribution adds words without eliminating uncertainty. When in doubt, add nothing and write the knowledge into the relevant framework documentation page instead. Let a [ANCHOR] point to it.
A guide to get everything propped up rapidly
Embed youtube guide.
Link to video_tutorials.