https://github.com/idanarye/bevy-tnua
A floating character controller for Bevy
https://github.com/idanarye/bevy-tnua
bevy-plugin character-controller locomotion rapier2d rapier3d rust xpbd
Last synced: 3 months ago
JSON representation
A floating character controller for Bevy
- Host: GitHub
- URL: https://github.com/idanarye/bevy-tnua
- Owner: idanarye
- License: apache-2.0
- Created: 2022-09-18T12:47:54.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-04T22:54:13.000Z (about 1 year ago)
- Last Synced: 2025-04-06T21:03:43.086Z (about 1 year ago)
- Topics: bevy-plugin, character-controller, locomotion, rapier2d, rapier3d, rust, xpbd
- Language: Rust
- Homepage: https://crates.io/crates/bevy-tnua
- Size: 1.33 MB
- Stars: 302
- Watchers: 5
- Forks: 29
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
[](https://github.com/idanarye/bevy-tnua/actions)
[](https://crates.io/crates/bevy-tnua)
[](https://idanarye.github.io/bevy-tnua/)
[](https://docs.rs/bevy-tnua/)
# Tnua - A Character Controller for [Bevy](https://bevyengine.org/).
Tnua ("motion" in Hebrew) is a floating character controller, which means that instead of constantly touching the ground the character floats above it, which makes many aspects of the motion control simpler.
Tnua can use [Rapier](https://rapier.rs/) or [Avian](https://github.com/Jondolf/avian) (formerly XPBD), and supports both the 2D and 3D versions of both with integration crates:
* For Rapier 2D, add the [bevy-tnua-rapier2d](https://crates.io/crates/bevy-tnua-rapier2d) crate.
* For Rapier 3D, add the [bevy-tnua-rapier3d](https://crates.io/crates/bevy-tnua-rapier3d) crate.
* For Avian 2D, add the [bevy-tnua-avian2d](https://crates.io/crates/bevy-tnua-avian2d) crate.
* For Avian 3D, add the [bevy-tnua-avian3d](https://crates.io/crates/bevy-tnua-avian3d) crate.
* XPBD is still supported with [bevy-tnua-xpbd2d](https://crates.io/crates/bevy-tnua-xpbd2d) and [bevy-tnua-xpbd3d](https://crates.io/crates/bevy-tnua-xpbd3d), but users are encouraged to migrate to Avian
* Third party integration crates. Such crates should depend on [bevy-tnua-physics-integration-layer](https://crates.io/crates/bevy-tnua-physics-integration-layer) and not the main bevy-tnua crate.
Note that:
* **Both** integration crate (`bevy-tnua-`) and the main `bevy-tnua` crate are required, and that the main plugin from both crates should be added.
* If you use a physics backend with double precision (like Avian with the `f64` flag), you need to add the `f64` flag to all the Tnua crates. This applies to double precision data that gets defined by the physics backend - Bevy itself will still use single precision, and this is the precision the position and rotation will use.
## Features
* Supports both 2D and 3D versions of [Rapier](https://rapier.rs/) and [Avian](https://github.com/Jondolf/avian)
* Running
* Jumping
* Crouching
* Variable height jumping
* Coyote time
* Jump buffer
* Running up/down slopes/stairs
* Tilt correction
* Moving platforms
* Rotating platforms
* Animation helpers (not the animation itself, but Tnua has facilities that help deciding which animation to play)
* [Jump/fall through platforms](https://github.com/idanarye/bevy-tnua/wiki/Jump-fall-Through-Platforms)
* Air actions
* [Obstacle actions](https://github.com/idanarye/bevy-tnua/wiki/Using-the-obstacle-radar):
* Wall sliding (and jumping)
* Climbing
## Demos:
* 2D Platformer:
[Rapier](https://idanarye.github.io/bevy-tnua/demos/platformer_2d-rapier),
[Avian](https://idanarye.github.io/bevy-tnua/demos/platformer_2d-avian),
[Avian (f64 version)](https://idanarye.github.io/bevy-tnua/demos/platformer_2d-avian-64)
* 3D Platformer:
[Rapier](https://idanarye.github.io/bevy-tnua/demos/platformer_3d-rapier),
[Avian](https://idanarye.github.io/bevy-tnua/demos/platformer_3d-avian),
[Avian (f64 version)](https://idanarye.github.io/bevy-tnua/demos/platformer_3d-avian-64)
* 3D Shooter:
[Rapier](https://idanarye.github.io/bevy-tnua/demos/shooter_like-rapier),
[Avian](https://idanarye.github.io/bevy-tnua/demos/shooter_like-avian),
[Avian (f64 version)](https://idanarye.github.io/bevy-tnua/demos/shooter_like-avian-64)
The basis and actions in the demos can be tweaked with a GUI. They are initialized to the `Default::default()` provided in Tnua, with the following exceptions:
* `TnuaBuiltinWalkConfig::float_height` is set to 2.0 even though it defaults to 0.0. User code should always set the float height based on the model's geometrics.
* `TnuaBuiltinWalkConfig::max_slope` is set to $\frac{\pi}{4}$ even though it defaults to $\frac{\pi}{2}$ (which disables the slipping behavior, since this is the slope angle of a wall)
* `TnuaBuiltinJumpConfig::height` is set to 4.0 even though it defaults to 0.0. User code should always set the jump height based on the game's requirements (a jump action of zero height is useless)
* `TnuaBuiltinCrouchConfig::float_offset` is set to -0.9 even though it defaults to 0.0. Just like `float_height`, this value should always be set by user code based on the model's geometric.
* `TnuaBuiltinDashConfig::horizontal_distance` is set to 10.0 even though it defaults to 1.0.
* `TnuaBuiltinDashConfig::vertical_distance` is set to 0.0 even though it defaults to 1.0. This means that the vertical component added to it when Shift is pressed in the demo gets zeroed (and the character does not lift to air while dashing) unless that value is changed in the settings UI.
### Running the Demos Locally
```sh
$ cargo run --bin --features
```
Where `` is the name of the demo and `` is either `rapier2d`, `rapier3d`, `avian2d` or `avian3d`. Make sure to match the dimensionality of the backend (2D or 3D) to that of the demo. For example, to run the 3D platformer with Avian, use this:
```sh
$ cargo run --bin platformer_3d --features avian3d
```
### Interesting Parts of the Demo Code
(**NOTE**: [the examples](examples/) are simpler than the demos, so if there is an example that shows something it'll be easier to read that)
* Check out [the demos' entry points](demos/src/bin/) to see how the plugins and the player character entities are being set.
* Check out [the character control systems](demos/src/character_control_systems/) to see how to control the character's motion and special movement actions. Specifically:
* [The control scheme definition](demos/src/character_control_systems/platformer_control_scheme.rs) which defines the various movements the character can do.
* [The actual control systems](demos/src/character_control_systems/platformer_control_systems.rs) which read player input and environmental data and translate it to Tnua's motion commands.
* Check out [the character animating systems](demos/src/character_animating_systems/) to see how to use information from Tnua for character animation.
## Versions
Tnua is broken into different crates that update separately, so this is broken into multiple tables. The version of bevy-tnua-physics-integration-layer must be the same for both the main bevy-tnua crate and the integration crates.
### Main
| bevy | bevy-tnua-physics-integration-layer | bevy-tnua |
|------|-------------------------------------|-------------|
| 0.18 | 0.12 | 0.29, 0.30 |
| 0.17 | 0.11 | 0.27, 0.28 |
| 0.17 | 0.10 | 0.26 |
| 0.16 | 0.9 | 0.25 |
| 0.16 | 0.8 | 0.24 |
| 0.15 | 0.7 | 0.23 |
| 0.15 | 0.6 | 0.22 |
| 0.15 | 0.5 | 0.21 |
| 0.14 | 0.4 | 0.19, 0.20 |
| 0.13 | 0.3 | 0.16 - 0.18 |
| 0.13 | 0.2 | 0.15 |
| 0.12 | 0.1 | 0.13, 0.14 |
### Rapier integration
| bevy | bevy-tnua-physics-integration-layer | bevy-tnua-rapier | bevy_rapier |
|------|-------------------------------------|------------------|-------------|
| 0.17 | 0.11 | 0.15 | 0.32 |
| 0.16 | 0.9 | 0.14 | 0.31 |
| 0.16 | 0.9 | 0.13 | 0.30 |
| 0.16 | 0.8 | 0.12 | 0.30 |
| 0.15 | 0.7 | 0.11 | 0.29 |
| 0.15 | 0.6 | 0.10 | 0.29 |
| 0.15 | 0.5 | 0.8, 0.9 | 0.28 |
| 0.14 | 0.4 | 0.7 | 0.27 |
| 0.13 | 0.3 | 0.6 | 0.26 |
| 0.13 | 0.3 | 0.4, 0.5 | 0.25 |
| 0.13 | 0.2 | 0.3 | 0.25 |
| 0.12 | 0.1 | 0.2 | 0.24 |
| 0.12 | 0.1 | 0.1 | 0.23 |
### Avian integration
| bevy | bevy-tnua-physics-integration-layer | bevy-tnua-avian | avian |
|------|-------------------------------------|-----------------|-------|
| 0.18 | 0.12 | 0.11 | 0.6 |
| 0.18 | 0.12 | 0.10 | 0.5 |
| 0.17 | 0.11 | 0.9 | 0.4 |
| 0.17 | 0.10 | 0.7, 0.8 | 0.4 |
| 0.16 | 0.9 | 0.6 | 0.3 |
| 0.16 | 0.8 | 0.5 | 0.3 |
| 0.15 | 0.7 | 0.4 | 0.2 |
| 0.15 | 0.6 | 0.3 | 0.2 |
| 0.15 | 0.5 | 0.2 | 0.2 |
| 0.14 | 0.4 | 0.1 | 0.1 |
### XPBD integration
Will not receive any more updates since the bevy_xpbd project has been rebranded as "Avian".
| bevy | bevy-tnua-physics-integration-layer | bevy-tnua-xpbd | bevy_xpbd |
|------|-------------------------------------|----------------|-----------|
| 0.14 | 0.4 | 0.5 | 0.5 |
| 0.13 | 0.3 | 0.3, 0.4 | 0.4 |
| 0.13 | 0.2 | 0.2 | 0.4 |
| 0.12 | 0.1 | 0.1 | 0.3 |
### Pre-split
| bevy | bevy-tnua | bevy_rapier |
|------|------------|-------------|
| 0.12 | 0.12 | 0.23 |
| 0.11 | 0.8 - 0.11 | 0.22 |
| 0.10 | 0.1 - 0.7 | 0.21 |
## Reference Material
The following were used for coding the math and physics of Tnua:
* "Floating capsule" and running mechanics:
* https://youtu.be/qdskE8PJy6Q
* Jumping mechanics:
* https://youtu.be/hG9SzQxaCm8
* https://youtu.be/eeLPL3Y9jjA
## Alternatives
* [bevy_mod_wanderlust](https://github.com/PROMETHIA-27/bevy_mod_wanderlust) - the original inspiration for this mod, and where I got the floating capsule video from. I ended up creating my own plugin because bevy_mod_wanderlust does not support 2D.
* [Rapier itself has a character controller](https://rapier.rs/docs/user_guides/bevy_plugin/character_controller). It's not a floating character controller, but it's integrated with the physics engine itself and uses that privilege to work out some of the problems the floating model is used to address.
* [Bevy Ahoy!](https://github.com/janhohenheim/bevy_ahoy) - a kinematic character controller for Avian 3D.
## License
Licensed under either of
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.