GS_Unit

1 - Unit Manager

The Unit Manager is the global coordinator for all units in a GS_Play project. It maintains a registry of every active unit entity, provides the interface for spawning new units at runtime, tracks which player controllers are currently active, and participates in the GS_Core standby system so that all controlled characters pause cleanly during level transitions.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• What the Unit Manager Does
• Spawning Units
• Registering Player Controllers
• Checking Unit Identity
• Standby Mode
• Quick Reference
• Glossary
• See Also

What the Unit Manager Does

The Unit Manager runs as a singleton that all other unit systems report to. When a unit entity activates, it registers itself so the manager can track it by name and ID. When gameplay code needs a new unit spawned, it asks the manager — not the spawning system directly — so the manager can assign a unique name and fire the appropriate notification.

Spawning Units

How Spawning Works

Spawning a unit is a two-step async operation. Your script calls RequestSpawnNewUnit, the manager creates the entity using the prefab spawner, and when the unit is fully initialized the manager fires ReturnNewUnit on UnitManagerNotificationBus with the new entity ID and its assigned unique name.

You should always listen for ReturnNewUnit rather than attempting to use the entity immediately after the request, because spawning can take one or more frames.

ScriptCanvas — Spawning a Unit

Registering Player Controllers

Player controllers must register themselves with the Unit Manager on activation so the game always knows which controllers are active. This is handled automatically by GS_PlayerControllerComponent, but if you are building a custom controller, call RegisterPlayerController in your activation logic.

[On Entity Activated (custom controller)]
    └─► [UnitManagerRequestBus → RegisterPlayerController(selfEntityId)]

This registration matters most for split-screen or multi-player setups where the manager needs to route input correctly across multiple simultaneous controllers.

Checking Unit Identity

Any system can confirm whether an arbitrary entity is a registered unit without holding a direct reference to the Unit Manager:

ScriptCanvas

[UnitManagerRequestBus → CheckIsUnit(targetEntityId)]
    └─► bool
            ├─► true  — proceed with unit-specific logic
            └─► false — entity is not a unit, skip

Standby Mode

The Unit Manager participates in GS_Core’s global standby system. During level transitions or other blocking operations, the Game Manager signals standby and the Unit Manager relays that signal to all units. Units should pause movement, suspend input processing, and halt any tick-driven logic while in standby.

Listen on UnitManagerNotificationBus to coordinate your own logic with unit standby:

ScriptCanvas

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Unit Manager
• Framework API: GS_Unit

For related systems:

• The Basics: Controllers
• The Basics: GS_Managers

Get GS_Unit

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

2 - Controllers

Controllers are the possession layer of GS_Unit. A controller is the intelligence — human input or AI logic — that owns and drives a unit at any given moment. Because both player and AI controllers share the same possession interface, your unit entities do not need to know what is controlling them, and swapping control at runtime requires no special-casing.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• The Possession Model
• Controller Types
• Player Controller
• AI Controller
• Switching Controllers at Runtime
• Querying Controller State
• Standby and Controllers
• Quick Reference
• Glossary
• See Also

The Possession Model

Breakdown

Every unit has exactly one controller at a time, or no controller at all. Possession is established by calling Possess on the unit and released by calling DePossess. The unit fires UnitPossessed on UnitNotificationBus whenever ownership changes so other systems can react.

Concept	Description
Possession	A controller attaches to a unit. The unit accepts input and movement commands from that controller only.
DePossession	The controller releases the unit. The unit halts input processing and enters a neutral state.
UnitPossessed event	Fires on UnitNotificationBus (addressed by entity ID) whenever a unit’s controller changes.
GetController	Returns the entity ID of the current controller, or an invalid ID if none.
GetUniqueName	Returns the string name assigned by the Unit Manager when this unit was spawned.

• The Basics: Controllers — Possession, input routing, and controller assignment.
• Framework API: Unit Controllers — Controller components, possession API, and C++ extension.

Controller Types

GS_Unit ships three controller components that cover the full range of typical game use:

Both GS_PlayerControllerComponent and GS_AIControllerComponent extend the base controller, meaning any code that works with the base controller interface works transparently with either type.

Player Controller

GS_PlayerControllerComponent registers itself with the Unit Manager on activation, making it visible to the game’s controller tracking system. It connects to the Input Data pipeline on the possessed unit so that raw input events are routed correctly as soon as possession is established.

Setup

1. Add GS_PlayerControllerComponent to a controller entity (not the unit entity itself).
2. Ensure GS_InputDataComponent and GS_PlayerControllerInputReaderComponent are on the unit entity.
3. Call Possess to attach the controller to the target unit.

ScriptCanvas — Possessing a Unit

AI Controller

GS_AIControllerComponent gives AI logic the same possession interface as the player controller. An AI behavior system possesses a unit, then issues movement commands through UnitRequestBus or directly drives the unit’s Input Data component to simulate input. The unit processes those commands through the same mover stack it would use for player input.

ScriptCanvas — Handing a Unit to AI

// Called from your behavior tree or AI activation event when the NPC starts acting
[AI behavior activates]
    └─► [UnitRequestBus(unitEntityId) → Possess(aiControllerEntityId)]

[UnitNotificationBus(unitEntityId) → UnitPossessed(aiControllerEntityId)]
    └─► [AI logic begins issuing movement / action commands]

Switching Controllers at Runtime

Because possession is a simple attach/detach operation on the unit, switching from player to AI control (or back) is two calls:

[Trigger: cutscene starts, character incapacitated, etc.]
    └─► [UnitRequestBus(unitEntityId) → DePossess]
            └─► [UnitRequestBus(unitEntityId) → Possess(aiControllerEntityId)]

[Trigger: cutscene ends, character recovers, etc.]
    └─► [UnitRequestBus(unitEntityId) → DePossess]
            └─► [UnitRequestBus(unitEntityId) → Possess(playerControllerEntityId)]

The DePossess call ensures the previous controller’s input pipeline is disconnected before the new controller attaches, preventing stale input state from leaking between ownership changes.

Querying Controller State

ScriptCanvas

Standby and Controllers

When the Unit Manager broadcasts EnterStandby, both player and AI controllers should stop issuing commands. Player controllers automatically halt input reading. AI controllers must be suspended by whatever behavior system drives them. On ExitStandby, normal command flow resumes.

Both events fire on UnitNotificationBus addressed by unit entity ID.

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Unit Controllers
• Framework API: GS_Unit

For related systems:

• The Basics: Unit Manager
• The Basics: Input Data

Get GS_Unit

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

3 - Input Data

The Input Data system is the pipeline that converts raw hardware signals into structured intent your movement code can consume. It sits between the active input profile and the mover stack, so controllers, movement components, and action systems all read from a single consistent source rather than polling hardware directly. Swapping input profiles at runtime — for remapping, controller switching, or accessibility options — requires no change to any downstream component.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• Pipeline Overview
• Input Data Component
• Input Reader
• Input Reactors
• Keyboard Movement Reactor
• Joystick Axis Reactor
• Adding Custom Reactors
• Quick Reference
• Glossary
• See Also

Pipeline Overview

Breakdown

The input pipeline has three stages. Each stage is a separate component on the unit entity, and they run in order every frame:

Stage	Component	What It Does
1 — Read	GS_PlayerControllerInputReaderComponent	Reads raw input events from the active input profile and writes them into GS_InputDataComponent.
2 — Store	GS_InputDataComponent	Holds the current frame’s input state — button presses, axis values — as structured data.
3 — React	Reactor components	Read from GS_InputDataComponent and produce intent: movement vectors, action triggers, etc.

All reactor components downstream of the store stage read from the same GS_InputDataComponent, so there is no duplicated hardware polling and no risk of two reactors seeing different input states for the same frame.

• The Basics: Controllers — Possession, input routing, and controller assignment.
• The Basics: Core Input — Input profiles, action mappings, and options setup.
• The Basics: Unit Input — Input readers, axis configuration, and ScriptCanvas usage.
• Framework API: Unit Controllers — Controller components, possession API, and C++ extension.
• Framework API: Input Reader — Profile binding, action event reading, and C++ extension.
• Framework API: Input Reactor — InputDataComponent schema, reactor base class, and C++ extension.
• Framework API: Mover Context — Context state, mode authority, and C++ extension.

Input Data Component

GS_InputDataComponent is the shared state store. It does not read hardware — it only holds the values written by the Reader and consumed by Reactors.

Add it to any unit entity that needs to process input. A unit should have exactly one GS_InputDataComponent. All input reactors on the same entity read from it automatically.

Input Reader

GS_PlayerControllerInputReaderComponent connects the unit to the game’s active input profile. It receives input events from the profile and writes the resulting state into the unit’s GS_InputDataComponent each frame.

When the player controller possesses the unit, the reader activates. When the unit is depossessed or control is handed to an AI controller, the reader goes silent and the Input Data component retains its last-written state until overwritten.

Setup

Add GS_PlayerControllerInputReaderComponent to the unit entity alongside GS_InputDataComponent. No additional configuration is required — it picks up the active input profile automatically.

Script Canvas - Enabling and Disabling Input Groups

Input Reactors

Reactors are the components that transform stored input state into useful intent values. Each reactor handles one concern:

Add as many reactors as your unit needs. A typical ground character has both KeyboardMovement_InputReactorComponent and JoyAxisMovement_AxisReactorComponent active so it responds to either keyboard or gamepad input without requiring separate prefabs.

Keyboard Movement Reactor

KeyboardMovement_InputReactorComponent reads the four directional button states from GS_InputDataComponent and produces a normalized movement vector. The vector direction is relative to the unit’s forward axis, so rotating the unit automatically adjusts the movement direction without any additional calculation.

The reactor writes the resulting vector into a movement data field that the active mover reads each frame.

ScriptCanvas — Reading the Movement Vector

You generally do not need to read the movement vector directly — the mover components consume it automatically. However, if you need to inspect or override it:

// Use only if you need to inspect or override the movement vector — movers consume it automatically
[On Tick]
    └─► [GS_InputDataComponent → GetMovementVector]
            └─► Vector3 — current frame's movement intent

Joystick Axis Reactor

JoyAxisMovement_AxisReactorComponent reads a pair of axis values (horizontal and vertical) from GS_InputDataComponent and applies deadzone filtering and magnitude scaling before writing the resulting vector. This prevents stick drift at rest and allows variable-speed movement when the stick is partially deflected.

Adding Custom Reactors

To handle input not covered by the built-in reactors — jumping, sprinting, interaction, ability activation — extend GS_InputReactorComponent or GS_InputAxisReactorComponent in C++. Your reactor reads from GS_InputDataComponent the same way the built-in ones do, so it automatically benefits from any input profile that writes to those fields.

For the C++ extension guide, see the Framework API reference.

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Input Data
• Framework API: Input Reactor
• Framework API: Player Input Reader

For related systems:

• The Basics: Controllers
• The Basics: Movement

Get GS_Unit

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

4 - Units

A “unit” in GS_Play is any entity that can be possessed by a controller and driven through gameplay. The GS_UnitComponent is the marker that transforms an ordinary entity into a unit — it provides the possession interface, unique naming, standby awareness, and automatic registration with the Unit Manager.

Units are the characters, vehicles, creatures, or any other controllable actors in your game. They do not contain decision-making logic themselves — that comes from the controller that possesses them. A unit provides the body: movement, collision, and visuals. The controller provides the brain: player input or AI logic.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• How Units Work
• Entity Configuration
• Collision Setup
• Movement
• Quick Reference
• Glossary
• See Also

How Units Work

Registration

When a GS_UnitComponent activates, it registers itself with the Unit Manager. The manager tracks all active units and responds to CheckIsUnit queries. When the component deactivates, it unregisters automatically.

Possession

Units are possessed by controllers through the UnitRequestBus:

1. A controller calls Possess(controllerEntityId) on the unit.
2. The unit stores the controller reference and broadcasts UnitPossessed on UnitNotificationBus.
3. The controller can now drive the unit’s subsystems (movement, actions, etc.).
4. Calling DePossess() clears the controller reference and releases the unit.

Standby

Units participate in the standby system for clean level transitions. When the Unit Manager signals standby, the unit broadcasts UnitEnteringStandby on its notification bus. Child components — movers, input reactors, and others — listen for this signal and pause their processing. UnitExitingStandby reverses the process.

Entity Configuration

A minimal unit entity requires:

1. GS_UnitComponent — Registers the entity as a unit and provides the possession interface.
2. Movement components — At least a mover and optionally a grounder for ground detection.
3. PhysX collider — For physics interaction and ground detection raycasts.

A fully featured unit entity typically includes:

Entity Arrangement

Entity arrangement

Collision Setup

Units require properly configured PhysX collision layers to interact with the environment and other units. If you have not set up collision layers yet, refer to the Simple Project Setup guide.

Typical collision layer assignments:

Movement

The Movement feature set is a composable stack where each component handles one concern of character locomotion. Movers define core behavior (free, strafe, grid, slide), the MoverContext manages movement state and selects the active mover, Grounders report ground state, and Influence components apply external forces like wind or currents.

Movement API

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Units

For related systems:

• The Basics: Unit Manager
• The Basics: Controllers
• The Basics: Input Data
• The Basics: Movement

Get GS_Unit

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

4.1 - Mover Context

GS_MoverContextComponent is the coordinator that sits above the movers and owns the movement state for a unit. It does not move the character itself — it decides which mover runs, transforms input into the correct movement vector, and exposes state to every other system that needs to know what the character is doing.

Add exactly one GS_MoverContextComponent to any unit that uses movers.

For architecture details, component properties, and extending the system in C++, see the Framework API: Mover Context.

Contents

• Movement Modes
• Context States
• Input Axis Transformation
• Movement Profile Priority
• Script Canvas Examples
• Quick Reference
• Glossary
• See Also

Movement Modes

The Mover Context uses three independent mode tracks — movement, rotation, and grounding — each holding a named string. Only the mover or grounder whose assigned mode name matches the active mode on that track will run. All others stay dormant.

The three tracks are independent — changing the movement mode does not reset rotation or grounding.

Reverting Modes

Every mode change stores the previous value. Calling RevertToLastMovementMode, RevertToLastRotationMode, or RevertToLastGroundingMode restores it. This is how the Slide mover hands control back to Free movement after a slope is cleared — without needing to know what mode was active before.

Context States

Context states are named key/value pairs stored on the Mover Context. Any component can write or read them via MoverContextRequestBus. They provide a lightweight shared blackboard for movement systems to coordinate without direct dependencies.

The grounder writes "grounding" each frame. The Slide mover writes it back to 0 or 1 when the slope clears. Your own companion components can write custom states in the same way.

Input Axis Transformation

The Mover Context processes raw input through two transformations before handing it to the active mover.

Movers read the ground-projected axis. Both intermediate values are available via bus if a component needs an earlier stage.

Movement Profile Priority

The Mover Context resolves which GS_UnitMovementProfile governs the unit’s locomotion parameters at runtime using a priority stack:

1. Influence fields — Any MovementInfluenceFieldComponent or GlobalMovementInfluenceComponent that has added a profile to the unit. Highest priority. Multiple influences are stacked additively.
2. Global profile — The scene-level default from GlobalMovementRequestBus. Applied when no influence overrides are active.
3. Default profile — The profile assigned directly to the GS_MoverContextComponent. Used as the final fallback.

To change a unit’s movement feel in a specific area, place a MovementInfluenceFieldComponent with a volume shape and assign an alternate profile to it. The unit’s own component property does not need to change.

Script Canvas Examples

Changing movement mode:

Reverting to the previous movement mode:

Setting a context state flag:

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Mover Context
• Framework API: Movers
• Framework API: Grounders

For related systems:

• The Basics: Movement
• The Basics: Input Data
• The Basics: Controllers

Get GS_Unit

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

4.2 - Movement

The Movement system is a composable stack of components that each handle one concern of character locomotion. Movers define the core behavior, grounders report surface contact, the Mover Context manages which mover is active and what movement state the character is in, influence fields apply external forces, and Movement Profiles store the parameters that govern all of it. You assemble what you need — most characters use two or three components — and replace individual pieces without touching anything else.

For architecture details, component properties, and extending the system in C++, see the Framework API reference.

Contents

• How it Works
• Mover Types
• Mover Context
• Grounders
• Movement Profiles
• Influence Fields
• Assembly Guide
• Quick Reference
• Glossary
• See Also

How it Works

Breakdown

Movers and Grounders are multiple components on a Unit that are constantly changing activation based on the units state. When a mover is active, it freely processes the unit’s movement based on it’s functionality. At any moment, through internal or external forces, the Movement, Rotation, or Grounding state can change, which disables the old movers, and activates the new one to continue controlling the Unit.

Input
    ↓  InputDataNotificationBus::InputStateChanged
Input Reactor Components
    ↓  MoverContextRequestBus::SetMoveInputAxis
GS_MoverContextComponent
    ↓  ModifyInputAxis() → camera-relative
    ↓  GroundInputAxis() → ground-projected
    ↓  MoverContextNotificationBus::MovementModeChanged("Free")
GS_3DFreeMoverComponent  [active when mode == "Free"]
    ↓  AccelerationSpringDamper → rigidBody->SetLinearVelocity
GS_PhysicsRayGrounderComponent  [active when grounding mode == "Free"]
    ↓  MoverContextRequestBus::SetGroundNormal / SetContextState("grounding", ...)
    ↓  MoverContextRequestBus::ChangeMovementMode("Slide")  ← when slope too steep
GS_3DSlideMoverComponent  [active when mode == "Slide"]

The Slide mover activates when the Unit is walking on too steep an angle. It takes control over the unit, slides down the hill, then restores the previous movement behaviour.

• The Basics: Mover Context — Movement modes, grounding states, and configuration.
• The Basics: Movement — Mover types, grounder types, and ScriptCanvas usage.
• Framework API: Input Reactor — InputDataComponent schema, reactor base class, and C++ extension.
• Framework API: Mover Context — Context state, mode authority, and C++ extension.
• Framework API: Movers — Mover and grounder components, movement APIs, and C++ extension.

Mover Types

Each mover defines one locomotion behavior. A unit has one active mover at a time, selected by the Mover Context. All movers read from the unit’s movement vector (produced by the input pipeline) and translate it into entity movement each frame.

Choosing a Mover

• Use GS_3DFreeMoverComponent for any character that needs to move through air or water without ground contact.
• Use GS_3DSlideMoverComponent for most ground-bound characters. It handles slopes and steps without requiring physics simulation.
• Use GS_PhysicsMoverComponent when the character must interact physically with the world — pushing objects, being knocked back by forces, or responding to physics joints.

Mover Context

GS_MoverContextComponent sits above the movers and coordinates everything: it selects which mover runs each frame, owns the movement mode tracks, transforms raw input into camera-relative and ground-projected vectors, and manages the movement profile priority stack.

Add exactly one to any unit that uses movers.

Mover Context →

Grounders

Grounders detect whether the character has contact with a surface and report that information to the Mover Context. Without a grounder, the Context cannot distinguish ground-bound from airborne states.

Add one grounder to a unit that uses GS_3DSlideMoverComponent or any mover that needs ground awareness. GS_3DFreeMoverComponent does not require a grounder because it never needs ground contact.

Movement Profiles

GS_UnitMovementProfile is a data asset that stores all locomotion parameters for a unit configuration: walk speed, run speed, acceleration, deceleration, air control, jump force, and any mover-specific values. The Mover Context component holds a reference to a profile asset, so multiple prefabs can share the same profile or each have their own without duplicating inline values.

Creating a Profile

1. In the O3DE Asset Browser, right-click and select Create Asset → GS_UnitMovementProfile.
2. Configure the parameters in the asset editor.
3. Assign the asset to the Movement Profile slot on GS_MoverContextComponent.

Changing a profile asset at runtime allows you to alter all locomotion parameters at once — for example, switching a character between normal and encumbered movement profiles without touching individual component properties.

Reading Movement Profile Data - ScriptCanvas

Influence Fields

Influence components dynamically apply priority that change a units dominant movement profile. Priority values are additive — a unit accumulates priority values from all active sources and evaluate the final priority to determine the acting movement profile.

GlobalMovementInfluenceComponent is placed once in the level, usually on the Stage Data entity. MovementInfluenceFieldComponent uses a shape component to define its volume — place one wherever you need to change movement priority.

Assembly Guide

A typical ground-bound player character uses this component combination:

A flying or swimming character replaces the grounder and slide mover with GS_3DFreeMoverComponent and removes the grounder entirely.

Quick Reference

Glossary

For full definitions, see the Glossary.

See Also

For the full API, component properties, and C++ extension guide:

• Framework API: Movement
• Framework API: Movers
• Framework API: Mover Context
• Framework API: Grounders

For related systems:

• The Basics: Input Data
• The Basics: Controllers
• The Basics: Stage Data

Get GS_Unit

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