GS_Unit

Character and entity control — unit lifecycle, player and AI controllers, input processing, movement, and grounding.
Categories:
Tags:

GS_Unit is the gem that gives entities agency. It provides a unit lifecycle system for spawning and possessing controllable entities, a controller layer that separates player and AI concerns, an input pipeline that converts raw device input into movement vectors, a family of mover components covering free 3D, surface-sliding, and physics-driven movement, and grounding components for stable surface contact. The gem depends only on GS_Core and introduces one data asset, GS_UnitMovementProfile, for authoring movement parameters outside of code.

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

 

Contents

Unit Manager

The lifecycle system for spawnable, possessable units. The Unit Manager is a singleton that handles unit spawn requests and tracks the active player controller. Individual Unit components identify an entity as a game unit and manage possession state.

ComponentPurpose
GS_UnitManagerComponentSingleton manager. Handles unit spawn requests and player controller registration.
GS_UnitComponentMarks an entity as a unit. Manages possession, controller access, and standby state.

Unit Manager API

Controllers

The controller layer separates how a unit is driven from what the unit is. A base controller handles possession handshake. The player controller adds input-driven behavior. The AI controller provides a hook for script or code-driven NPC logic.

ComponentPurpose
GS_UnitControllerComponentBase controller. Manages unit possession and depossession.
GS_PlayerControllerComponentPlayer-specific controller. Routes player input to the possessed unit.
GS_AIControllerComponentAI controller. Provides the hook point for NPC logic.

Unit Controllers API

Input Data

The input pipeline converts raw device events into a normalised input state that movement and interaction systems can read. Input Reactor components handle discrete button events. Axis Reactor components handle analogue axes. Concrete implementations cover keyboard WASD and joystick movement.

ComponentPurpose
GS_InputDataComponentHolds the current normalised input state for a unit.
GS_InputReactorComponentBase component for reacting to discrete input events.
GS_InputAxisReactorComponentBase component for reacting to analogue axis input.
GS_PlayerControllerInputReaderComponentReads player device input and writes it into GS_InputDataComponent.
KeyboardMovement_InputReactorComponentConverts WASD keyboard input into a movement vector.
JoyAxisMovement_AxisReactorComponentConverts joystick axis input into a movement vector.

Input Data API

Movement

The mover stack translates input vectors and influences into entity motion. The Mover Context component tracks current movement state. Concrete movers cover three locomotion modes. Grounder components maintain stable surface contact and feed grounded state back to the mover. Influence components apply persistent or volume-scoped forces on top of any mover.

ComponentPurpose
GS_MoverComponentBase movement component. All concrete movers extend this.
GS_MoverContextComponentTracks contextual movement state shared across the mover stack.
GS_3DFreeMoverComponentFree 3D movement — suitable for flying or swimming characters.
GS_3DSlideMoverComponentSurface-sliding 3D movement — suitable for ground characters.
GS_PhysicsMoverComponentPhysics-driven movement via rigid body integration.
GS_GrounderComponentBase ground detection component.
GS_PhysicsRayGrounderComponentRaycast-based ground detection.
GlobalMovementInfluenceComponentApplies a global movement modifier (e.g., wind, current) to all units.
MovementInfluenceFieldComponentApplies a movement modifier inside a spatial volume.

Movement API

Installation

GS_Unit requires only GS_Core. It is one of the lightest gems in the framework to add.

  1. Enable GS_Unit in Project Manager or project.json.
  2. Add GS_UnitManagerComponent to the Game Manager entity and register it in the Startup Managers list.
  3. Build your unit prefab: add GS_UnitComponent, the appropriate Controller, GS_InputDataComponent, and a Mover for the locomotion type you need.
  4. Add GS_PlayerControllerInputReaderComponent and the relevant input reactor components to the player unit prefab.
  5. Refer to the Unit Set Up Guide for a full walkthrough.

See Also

For conceptual overviews and usage guides:

For related resources:

Get GS_Unit

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