.. _stdlib_character_controller_component: =================== 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 +++++++ .. _struct-character_controller_component-CharacterController: .. das:attribute:: 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).velocity = inputDirection * movementSpeed :Properties: .. _function-character_controller_component__dot__rq_velocity_CharacterController: .. das:operator:: CharacterController.velocity() : float3 .. _function-character_controller_component__dot__rq_velocity_rq_clone_CharacterController_float3: .. das:operator:: 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 .. _function-character_controller_component__dot__rq_maxSlopeAngle_CharacterController: .. das:operator:: CharacterController.maxSlopeAngle() : float .. _function-character_controller_component__dot__rq_maxSlopeAngle_rq_clone_CharacterController_float: .. das:operator:: 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 .. _function-character_controller_component__dot__rq_stepHeight_CharacterController: .. das:operator:: CharacterController.stepHeight() : float .. _function-character_controller_component__dot__rq_stepHeight_rq_clone_CharacterController_float: .. das:operator:: 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 .. _function-character_controller_component__dot__rq_upDirection_CharacterController: .. das:operator:: CharacterController.upDirection() : float3 .. _function-character_controller_component__dot__rq_upDirection_rq_clone_CharacterController_float3: .. das:operator:: CharacterController.upDirection =(value: float3) The up direction vector for the character. Default is (0, 1, 0). :Arguments: * **value** : float3 .. _function-character_controller_component__dot__rq_gravityScale_CharacterController: .. das:operator:: CharacterController.gravityScale() : float .. _function-character_controller_component__dot__rq_gravityScale_rq_clone_CharacterController_float: .. das:operator:: 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 .. _function-character_controller_component__dot__rq_state_CharacterController: .. das:operator:: 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: * :ref:`CharacterState ` - current character state (use it to decide if the character is on ground, in air, etc.) .. _function-character_controller_component__dot__rq_groundNormal_CharacterController: .. das:operator:: 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 .. _function-character_controller_component__dot__rq_groundNode_CharacterController: .. das:operator:: CharacterController.groundNode() : NodeId Reads the ground node of the character controller. :Returns: * :ref:`NodeId ` - returns active ground node or invalid node if there is no ground (i.e. character is in air) .. _function-character_controller_component__dot__rq_gravity_CharacterController: .. das:operator:: 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