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.