Character Controller

A character controller is a special type of physics body that uses its own collision resolution which is geared for user-controlled characters. Use a character controller for an entity that you can consider kinematic (i.e. controlled by user inputs, not affected by forces like gravity), but is also your main playable character. A character controller will benefit from continuous collision detection and its own collision resolution algorithm that has been tweaked to provide a good feeling while controlling the player.

To make your entity a character controller it needs the following components:

  • character controller
  • one geometry component from this list: box geometry, capsule geometry

Between the two, the capsule geometry is the recommended default choice.

Character controller component

Step OffsetStep offset. If the height of a step is greater than stepOffset, the controller cannot climb automatically and gets stuck.
Slope LimitSlope limit in degrees. A slope steeper than the slopeLimit will not be walkable by the controller.
Skin WidthThe character's collision skin width.
DisplacementDisplacement vector for current frame. See How to move a character controller.

Orientation of character controllers

There’s a slight caveat with the box character controller. Unlike other bodies, the box geometry of a character controller will NOT be affected by the orientation of your entity. The box always has a fixed rotation even when the player is (visually) rotating.

However, the capsule character controller will be impacted by the orientation of your entity. The orientation of your entity will be multiplied to the axis vector of your capsule, which will decide the capsule’s orientation.

How to move a character controller

The character controller is moved by affecting its displacement in the character controller component. The physics engine will try to move the character controller by the displacement, and do any collision resolution if necessary. The displacement you input will be used to move the character only for that frame; you need to keep updating the displacement each frame you want to keep moving it.

For best results you should affect the displacement server-side, as in a script, but it can also be done in client-side JS code with setComponent. The first-person and third-person template projects both modify the displacement of the character controller in their respective scripts.

Rigidbody Physics