bevy-tnua

Starting with Tnua 0.27, you must statically define a control scheme using the TnuaScheme macro. This scheme defines the available basis and actions for the controller.

Both TnuaController and TnuaControllerPlugin are now parameterized by this scheme. The macro automatically generates a configuration struct named [YourSchemeName]Config. You can load this configuration from an asset or inject it directly into Assets.

#[derive(TnuaScheme)]
#[scheme(basis = TnuaBuiltinWalk)]
enum ControlScheme {
    Jump(TnuaBuiltinJump),
    Crouch(TnuaBuiltinCrouch),
    DifferentKindOfJump(TnuaBuiltinJump),
}

// Injecting configuration manually:
cmd.insert(TnuaController::<ControlScheme>::new(
    control_scheme_configs.add(ControlSchemeConfig {
        basis: TnuaBuiltinWalkConfig { ..Default::default() },
        jump: TnuaBuiltinJumpConfig { ..Default::default() },
        crouch: TnuaBuiltinCrouchConfig { ..Default::default() },
        different_kind_of_jump: TnuaBuiltinJumpConfig { ..Default::default() },
    })
));

In Tnua 0.30, TnuaSimpleAirActionsCounter is deprecated. It has been replaced by TnuaActionsCounter, which uses a slot-based system. Instead of one counter for all air actions, you define a slots struct where each slot can track specific actions separately.

To implement this:

1. Define a slots struct using #[derive(TnuaActionSlots)] and #[slots(scheme = YourScheme)].
2. Assign specific actions to slots using #[slots(ActionName)].
3. Register the actions using TnuaAirActionsPlugin::<YourSlotsStruct>::new(Schedule).

This plugin automatically adds TnuaActionsCounter<YourSlotsStruct> as a dependency to your TnuaController and handles the update loop automatically in the specified schedule.

#[derive(TnuaActionSlots)]
#[slots(scheme = ControlScheme)]
struct AirActionSlots {
    #[slots(Jump)]
    jump: usize,
    #[slots(Dash)]
    dash: usize,
}

// In your app setup:
app.add_plugins(TnuaAirActionsPlugin::<AirActionSlots>::new(FixedUpdate));

Tnua requires both the main bevy-tnua crate and a specific integration crate for your chosen physics backend. You must add the main plugin from both crates to your Bevy app.

Choose the integration crate based on your physics engine and dimensionality:

• Rapier 2D: Add bevy-tnua-rapier2d
• Rapier 3D: Add bevy-tnua-rapier3d
• Avian 2D: Add bevy-tnua-avian2d
• Avian 3D: Add bevy-tnua-avian3d

Important Notes:

• Double Precision: If using a physics backend with double precision (e.g., Avian with the f64 flag), you must also add the f64 flag to all Tnua crates. This ensures data consistency for physics-defined values, though Bevy will still use single precision for position and rotation.
• Third-party Integrations: If you are building a new integration crate, it should depend on bevy-tnua-physics-integration-layer rather than the main bevy-tnua crate.

In Tnua 0.30, TnuaPlatformerAnimatingOutput is removed. Animation data must be retrieved directly from the TnuaController using concrete_basis or concrete_action.

Accessing Basis State

To get the current state of a basis (e.g., for calculating running velocity), use controller.concrete_basis::<T>(). This returns a tuple of (basis_input, basis_state).

Identifying Current Basis or Action

If your game uses multiple bases (e.g., walking vs. swimming) or actions, you can use controller.basis_name() or controller.action_name() to get a string identifier. For matching, it is best practice to use the NAME constant provided by the basis/action type rather than string literals.

// Get basis state for animation
let Some((_basis_input, basis_state)) = controller.concrete_basis::<TnuaBuiltinWalk>()
else {
    continue;
};
let speed = basis_state.running_velocity.length();

// Match on action name using NAME constants
match controller.action_name() {
    Some(TnuaBuiltinJump::NAME) => { /* ... */ }
    Some(TnuaBuiltinCrouch::NAME) => { /* ... */ }
    Some(other) => panic!("Unknown action {other}"),
    None => { /* ... */ }
}

Since TnuaPlatformerConfig has been removed, the recommended way to store character movement configuration in the ECS is to create a custom component that holds the basis and action templates. You can then clone these templates into the TnuaController during your control system execution.

Because TnuaBuiltinWalk::desired_velocity is a vector (direction + speed), it is often better to store a scalar speed in your config component and multiply it by a direction vector at runtime.

#[derive(Component)]
pub struct CharacterMotionConfigForPlatformerDemo {
    pub speed: f32,
    pub walk: TnuaBuiltinWalk,
    pub jump: TnuaBuiltinJump,
    pub crouch: TnuaBuiltinCrouch,
}

// In your control system:
controller.basis(TnuaBuiltinWalk {
    desired_velocity: direction * config.speed,
    ..config.walk.clone()
});

if crouch {
    controller.action(config.crouch.clone());
}

if jump {
    controller.action(config.jump.clone());
}

In Tnua 0.30, character controls have moved from the TnuaPlatformerControls component to the TnuaController component. Controls should be passed every frame, preferably within the TnuaUserControlsSystemSet system set.

Base Movement

Instead of modifying TnuaPlatformerControls::desired_velocity, you must now pass a basis (such as TnuaBuiltinWalk) to the TnuaController. Note that TnuaBuiltinWalk::desired_velocity now represents both speed and direction, and float_height must be explicitly provided.

Jumping

Use the TnuaBuiltinJump action via the controller. The jump height is controlled by TnuaBuiltinJump::height. The jump is active as long as the action is being fed; once you stop passing the action, the jump stops automatically (no manual nullification required).

Crouching

Use the TnuaBuiltinCrouch action via the controller. Set the float_offset within the action. For enforcing crouching behavior under obstacles, use TnuaCrouchEnforcer instead of the deprecated TnuaKeepCrouchingBelowObstacles.

// Base movement
controller.basis(TnuaBuiltinWalk {
    desired_velocity: the_desired_velocity,
    float_height: 2.0, // must be passed
    ..Default::default()
});

// Jumping
if should_jump {
    controller.action(TnuaBuiltinJump {
        height: 4.0,
        ..Default::default()
    });
}

// Crouching
if should_crouch {
    controller.action(TnuaBuiltinCrouch {
        float_offset: -0.9,
        ..Default::default()
    });
}