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 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, visuals, and stats. The controller provides the brain: player input or AI logic.

For usage guides and setup examples, see The Basics: GS_Unit.

Contents

• How It Works
• GS_UnitComponent Reference
• Setup
• See Also

How It Works

Registration

When a GS_UnitComponent activates, it registers itself with the Unit Manager. This allows the manager to track all active units and respond to CheckIsUnit queries. When the component deactivates, it unregisters.

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 issue commands to the unit’s subsystems (movement, actions, etc.).
4. Calling DePossess() clears the controller reference.

Standby

Units receive standby signals from the Unit Manager. When entering standby, the unit broadcasts UnitEnteringStandby on its notification bus. Child components (movers, input reactors, etc.) listen for this and pause their processing. UnitExitingStandby reverses the process.

GS_UnitComponent Reference

Request Bus: UnitRequestBus

Commands sent to a specific unit. ById bus — addressed by the unit’s entity ID, multiple handlers.

Notification Bus: UnitNotificationBus

Events broadcast by a unit. ById bus — addressed by the unit’s entity ID.

Virtual Methods

Setup

Unit 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.

A fully featured unit entity typically includes:

• GS_UnitComponent
• GS_MoverContextComponent – Aggregates movement input from movers
• A mover component (e.g., GS_3DFreeMoverComponent, GS_3DSlideMoverComponent, or GS_PhysicsMoverComponent)
• A grounder component (e.g., GS_PhysicsRayGrounderComponent) for surface detection
• PhysX Rigid Body and Collider components
• Mesh or Actor component for visuals

Unit Collider Configuration

Collision layers used for a unit collider, as seen in the Entity Inspector.

Units require properly configured PhysX collision layers to interact with the environment and other units. If you have not set up your PhysX Collision Layers or Groups yet, refer to the Setting Up Your Project Environment guide.

Typical collision layer assignments:

• Unit layer – The unit’s own collider. Collides with environment and other units.
• Ground detection layer – Used by grounder raycasts. Collides with terrain and walkable surfaces only.

See Also

For component references:

• Unit Manager – Spawning and lifecycle management
• Unit Controllers – Controllers that possess and drive units
• Movement – Movement, grounding, and influence components
• Input Data – Input state and reaction components

Get GS_Unit

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