CharacterController

Add this component to a node to enable moving it like a game character.

Characters in games are usually not physical: they stop and start moving instantly, without acceleration. This component can be used for such non-physical characters. It can:

  • Slide along walls

  • Climb up and down stairs and ramps

  • Stick to moving surfaces

  • Push other physical objects

The user just needs to set the velocity value every frame. Note that gravity and jumps are also handled by the user, as every game requires unique movement handling.

Note

Don’t forget to add a collider, e.g., CapsuleCollider. Otherwise, the character will not move.

Note

To be registered by scene queries, raycasts, and other characters, the node with the CharacterController should also have a RigidBody component.

This is because character movement is done by performing a series of shape-casts and applying impulses to colliding bodies, but the character itself does not exist in the physical world.

Adding the RigidBody will include it in the physical world. No other behavior is changed by this.

Classes

CharacterController : NativeComponent

The component that represents the character movement. Don’t forget to add a capsule collider.

Example:

add_component(node, new CharacterController())
add_component(node, new Collider(shape = capsule_shape()))
get_component(node, type<CharacterController>).velocity = inputDirection * movementSpeed
Properties:

CharacterController.velocity: float3
CharacterController.velocity =(value: float3)

Set this value to the desired character velocity.

At the next frame the character will try to move there. It will automatically handle walls and stairs.

If the character is in air then include the gravity in the velocity. To know is it in the air use state property.

Arguments:

  • value : float3

CharacterController.maxSlopeAngle: float
CharacterController.maxSlopeAngle =(value: float)

The maximum angle (radians) of the ground that the character could walk on. Use the state property to know if the ground has an angle that is too steep.

Arguments:

  • value : float

CharacterController.stepHeight: float
CharacterController.stepHeight =(value: float)

The maximum height of the stair step that the character could climb to. Any bigger heights will be considered as walls.

Arguments:

  • value : float

CharacterController.upDirection: float3
CharacterController.upDirection =(value: float3)

The up direction vector for the character. Default is (0, 1, 0).

Arguments:

  • value : float3

CharacterController.gravityScale: float
CharacterController.gravityScale =(value: float)

The scale factor for gravity applied to the character. Default is 1.0f. For Moon gravity use approximately 0.16f, for Mars gravity use approximately 0.38f.

Arguments:

  • value : float

CharacterController.state: CharacterState

Returns whether the character is standing on something, or is it falling.

Use it to decide whether to apply the gravity and/or whether the character should be able to jump.

The result is calculated between on_update calls, then it is cached.

Usage example:

match characterController.state {
    if (CharacterState.OnGround) {
        // The character is standing firmly on the ground. Consider to allow jumping in this state only.
    }
    if (CharacterState.OnSteepGround) {
        // The character is standing on a steep slope, or touching a wall. The character cannot stay still and should slide down by adding the gravity to the character's velocity.
    }
    if (CharacterState.NotSupported) {
        // The character is touching something, but not standing on it (hence "not supported by the ground"). Most likely it's touching a ceiling. For most uses, it is like InAir.
    }
    if (CharacterState.InAir) {
        // The character is not touching anything.
    }
}
Returns:

  • CharacterState - current character state (use it to decide if the character is on ground, in air, etc.)

CharacterController.groundNormal: float3

Returns the normal of the ground that the character is standing on.

Note

If the state returns something other than OnGround or OnSteepGround, then the return value would be zero.

Returns:

  • float3 - vector of the normal; zero vector if no ground

CharacterController.groundNode: NodeId

Reads the ground node of the character controller.

Returns:

  • NodeId - returns active ground node or invalid node if there is no ground (i.e. character is in air)

CharacterController.gravity: float3

Reads the gravity vector applied to the character. Takes into account the gravity scale and up direction. Result formula is : -upDirection * gravityScale * global gravity vector magnitude.

Returns:

  • float3 - returns the gravity vector applied to the character