superdump / bevy_prototype_character_controller

Character controllers for use with Bevy and any physics engine you like

bevy_prototype_character_controller

Implementations of character controllers that take common input events and map them to relative / absolute rotation and change in position (translation) / change in velocity (impulse) / change in acceleration (force).

This design is intended to allow use of these controller systems with whichever physics or camera setup you like. For example, you may use a kinematic rigid body in your physics engine and set its position based on the translation events, or a dynamic rigid body and apply the impulses or forces.

Features

• use_rapier - for bevy_rapier3d character controller support
• use_physx - for bevy_prototype_physx character controller support, using physx

Demos

First-Person Character Controller

cargo run --release --example first_person

Third-Person Character Controller

cargo run --release --example third_person

Third-Person Pseudo-Isometric Character Controller

cargo run --release --example pseudo_isometric

Rapier Third-Person Character Controller

You can choose between:

• DynamicImpulse - uses the ImpulseEvents to apply impulses to the body
• DynamicForce - uses the ForceEvents to apply forces to the body. This is the default.

Pitch and yaw are handled in the same way for both options.

cargo run --release --features use_rapier --example rapier3d -- DynamicImpulse

cargo run --release --features use_rapier --example rapier3d -- DynamicForce

PhysX Third-Person Character Controller

You can choose between:

• KinematicTranslation - uses the TranslationEvents to apply translations to the body
• DynamicImpulse - uses the ImpulseEvents to apply impulses to the body
• DynamicForce - uses the ForceEvents to apply forces to the body. This is the default.

Pitch and yaw are handled in the same way for both options.

cargo run --release --features use_physx --example physx -- KinematicTranslation

cargo run --release --features use_physx --example physx -- DynamicImpulse

cargo run --release --features use_physx --example physx -- DynamicForce

How-To

See the examples for the different types of controller to get a better idea of how to use this stuff. Below is a description of an approach to structuring the hierarchy of entities necessary to make this system work.

Entity structure

The structure of the Character is:

• body with Transform to set the position and yaw of the character, a CharacterController component and a tag so you can identify the body Transform for translating and yawing. Add rigid body and collider, or character controller components here.
  • body model
  • head with Transform offset upward to head position in y to give a point of reference for where the head / eyes are, and a tag so you can identify the head Transform for pitching. This design can be used for first- or third-person controllers.
    • head model
    • camera with Transform to offset for third person view like a camera boom arm stuck to the character's head, a LookDirection to get forward / right / up vectors, and a tag so you can identify the camera Transform

Handling events

• When translating, the position of the body should be manipulated.
• When yawing (rotating about the y axis), the orientation of the body should be manipulated.
• When pitching (rotating about the right axis relative to the character), the orientation of the head should be manipulated.
• When zooming in and out (TODO) or changing the focal point (TODO - defaults to look at the head position for third-person), the translation and orientation of the camera boom should be manipulated.

TODO

• use components rather than resources as appropriate to support multiple controllers in a scene (e.g. split-screen local co-op)
• add indirect third-person modes
  • the pseudo-isometric example should make the body face the direction of movement
  • the third-person indirect example would have the player control the character and the follow camera would lag, seek and follow after
  • allow temporary absolute orientation through pitch / yaw events
• avoid clipping the camera through obstacles
  • ray or box cast and adjust the camera position
• add juicy controllers that use Attack, Decay, Sustain, Release curves, with easing using bevy_easings

License

MIT. See the LICENSE file.