Struct TnuaBuiltinWalk

pub struct TnuaBuiltinWalk {

    pub desired_velocity: Vector3,
    pub desired_forward: Option<Dir3>,
    pub float_height: Float,
    pub cling_distance: Float,
    pub spring_strength: Float,
    pub spring_dampening: Float,
    pub acceleration: Float,
    pub air_acceleration: Float,
    pub coyote_time: Float,
    pub free_fall_extra_gravity: Float,
    pub tilt_offset_angvel: Float,
    pub tilt_offset_angacl: Float,
    pub turning_angvel: Float,
    pub max_slope: Float,
}

The most common basis - walk around as a floating capsule.

This basis implements the floating capsule character controller explained in https://youtu.be/qdskE8PJy6Q. It controls both the floating and the movement. Most of its fields have sane defaults, except:

• float_height - this field defaults to 0.0, which means the character will not float. Set it to be higher than the distance from the center of the entity to the bottom of the collider.

• desired_velocity - while leaving this as as the default Vector3::ZERO, doing so would mean that the character will not move.

• desired_forward - leaving this is the default None will mean that Tnua will not attempt to fix the character’s rotation along the up axis.

  This is fine if rotation along the up axis is locked (Rapier and Avian only support locking cardinal axes, but the up direction is based on the gravity which means it defaults to the Y axis so it usually works out).

  This is also fine for 2D games (or games with 3D graphics and 2D physics) played from side view where the physics engine cannot rotate the character along the up axis.

  But if the physics engine is free to rotate the character’s rigid body along the up axis, leaving desired_forward as the default Vector3::ZERO may cause the character to spin uncontrollably when it contacts other colliders. Unless, of course, some other mechanism prevents that.

Fields

desired_velocity: Vector3

The direction (in the world space) and speed to accelerate to.

Tnua assumes that this vector is orthogonal to the up dierction.

desired_forward: Option<Dir3>

If non-zero, Tnua will rotate the character so that its negative Z will face in that direction.

Tnua assumes that this vector is orthogonal to the up direction.

float_height: Float

The height at which the character will float above ground at rest.

Note that this is the height of the character’s center of mass - not the distance from its collision mesh.

To make a character crouch, instead of altering this field, prefer to use the TnuaBuiltinCrouch action.

cling_distance: Float

Extra distance above the float_height where the spring is still in effect.

When the character is at at most this distance above the float_height, the spring force will kick in and move it to the float height - even if that means pushing it down. If the character is above that distance above the float_height, Tnua will consider it to be in the air.

spring_strength: Float

The force that pushes the character to the float height.

The actual force applied is in direct linear relationship to the displacement from the float_height.

spring_dampening: Float

A force that slows down the characters vertical spring motion.

The actual dampening is in direct linear relationship to the vertical velocity it tries to dampen.

Note that as this approaches 2.0, the character starts to shake violently and eventually get launched upward at great speed.

acceleration: Float

The acceleration for horizontal movement.

Note that this is the acceleration for starting the horizontal motion and for reaching the top speed. When braking or changing direction the acceleration is greater, up to 2 times acceleration when doing a 180 turn.

air_acceleration: Float

The acceleration for horizontal movement while in the air.

Set to 0.0 to completely disable air movement.

coyote_time: Float

The time, in seconds, the character can still jump after losing their footing.

free_fall_extra_gravity: Float

Extra gravity for free fall (fall that’s not initiated by a jump or some other action that provides its own fall gravity)

NOTE: This force will be added to the normal gravity.

NOTE: If the parameter set to this option is too low, the character may be able to run up a slope and “jump” potentially even higher than a regular jump, even without pressing the jump button.

tilt_offset_angvel: Float

The maximum angular velocity used for keeping the character standing upright.

NOTE: The character’s rotation can also be locked to prevent it from being tilted, in which case this paramter is redundant and can be set to 0.0.

tilt_offset_angacl: Float

The maximum angular acceleration used for reaching tilt_offset_angvel.

NOTE: The character’s rotation can also be locked to prevent it from being tilted, in which case this paramter is redundant and can be set to 0.0.

turning_angvel: Float

The maximum angular velocity used for turning the character when the direction changes.

max_slope: Float

The maximum slope, in radians, that the character can stand on without slipping.

Implementations

impl TnuaBuiltinWalk

pub fn spring_force( &self, state: &TnuaBuiltinWalkState, ctx: &TnuaBasisContext<'_>, spring_offset: Float, ) -> TnuaVelChange

Calculate the vertical spring force that this basis would need to apply assuming its vertical distance from the vertical distance it needs to be at equals the spring_offset argument.

Note: this is exposed so that actions like TnuaBuiltinCrouch may rely on it.

Trait Implementations

impl Clone for TnuaBuiltinWalk

fn clone(&self) -> TnuaBuiltinWalk

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TnuaBuiltinWalk

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TnuaBuiltinWalk

fn default() -> Self

Returns the “default value” for a type.

impl TnuaBasis for TnuaBuiltinWalk

const NAME: &'static str = "TnuaBuiltinWalk"

The default name of the basis.

type State = TnuaBuiltinWalkState

Data that the basis can persist between frames.

fn apply( &self, state: &mut Self::State, ctx: TnuaBasisContext<'_>, motor: &mut TnuaMotor, )

This is where the basis affects the character’s motion.

fn proximity_sensor_cast_range(&self, _state: &Self::State) -> Float

A value to configure the range of the ground proximity sensor according to the basis’ needs.

fn displacement(&self, state: &Self::State) -> Option<Vector3>

The displacement of the character from where the basis wants it to be.

fn effective_velocity(&self, state: &Self::State) -> Vector3

The velocity of the character, relative the what the basis considers its frame of reference.

fn vertical_velocity(&self, state: &Self::State) -> Float

The vertical velocity the character requires to stay the same height if it wants to move in effective_velocity.

fn neutralize(&mut self)

Nullify the fields of the basis that represent user input.

fn is_airborne(&self, state: &Self::State) -> bool

Can be queried by an action to determine if the character should be considered “in the air”.

fn violate_coyote_time(&self, state: &mut Self::State)

If the basis is at coyote time - finish the coyote time.