View on GitHub

ezEngine Documentation

The documentation for ezEngine

Character Controller

A character controller is a special object in the physics engine that is used to move a character throughout a scene and make it collide with other geometry. A character controller is typically an upright capsule that abstractly represents the space that a character occupies.

The character controller provides the following functionality:

On top of these basic features, the character controller implements many details of movement. For example, while jumping or falling, a game may allow the player some degree of control. Such details are very game specific, though, and there is no one-size-fits-all solution.

Consequently, the character controller functionality is split up into multiple classes, and you are encouraged to implement your own logic:

  1. ezCharacterControllerComponent: An abstract base class for all character controllers, with a minimal interface. Other (script) code typically uses this interface to instruct the character to move, according to the player’s input or the decision of an AI controlled character. This class is not actually specific to the PhysX plugin.
  2. ezPxCharacterShapeComponent: A base class for exposing the raw functionality of the PhysX character controllers. Specifically ezPxCharacterCapsuleShapeComponent provides an implementation for the most commonly used capsule controller. If you implement a custom character controller, you can still save some work by reusing this, instead of calling the PhysX code yourself. On the other hand, you may want to write a custom implementation for this, if you need to adjust the very low level PhysX behavior for colliding and interacting with other bodies.
  3. ezPxCharacterControllerComponent: An implementation of ezCharacterControllerComponent that is provided as an example and as a decent starting point. It implements behavior similar to old-school first-person shooter games, such as Half-Life 2. Depending on how significantly different behavior you want, you can either derive from this class and override some parts, or copy the entire code and rewrite everything as desired. The latter approach may be the better solution, as ezPxCharacterControllerComponent may get changes over time that you don’t desire for your game.


The player object is often the most complicated object in a game. The character controller only provides the locomotion aspect, but this is often coupled tightly to the overall game logic. For example, the player may move slower or be disallowed to jump while carrying an object. Many of these aspects can be handled by an overall player logic script. Other aspects, like the details of the characters velocity while sliding down a slope or jumping through the air, have to be implemented directly inside a character controller component.

The Testing Chambers sample contains a prefab called Player.ezPrefab, which demonstrates how to build your own player object. The top level node contains both a PhysX Character Capsule Shape component (for the raw movement functionality), as well as a PhysX Character Controller component. You could replace the latter with a custom character controller component, to test out entirely different movement behavior.

Note that the player object also uses an input component to funnel input into a script, which implements high level game logic, like weapon selection.

ezPxCharacterShapeComponent Component Properties

ezPxCharacterCapsuleShapeComponent Component Properties

This component inherits the properties of ezPxCharacterShapeComponent and adds these properties:

ezPxCharacterControllerComponent Component Properties

The ezPxCharacterControllerComponent expects to find a ezPxCharacterShapeComponent attached to the very same game object. Note that this class is mainly intended for demonstration purposes and may not have all the features and behavior that you need in your game.

See Also