Crate heron

An ergonomic physics API for 2d and 3d bevy games. (powered by rapier)

Get started

Add the dependency

Add the library to Cargo.toml

heron = "0.2.0"

If you are creating a 2d game, change the default features:

heron = { version = "0.2.0", default-features = false, features = ["2d"] }

Note: when debugging you may consider enabling the debug feature, to render the collision shapes (works only for 2d, at the moment).

Install the plugin

To enable physics and collision detection, the PhysicsPlugin should be installed

use bevy::prelude::*;
use heron::prelude::*;

fn main() {
  App::build()
    .add_plugins(DefaultPlugins)
    .add_plugin(PhysicsPlugin::default())
    // ... Add your resources and systems
    .run();
}

Create rigid bodies

To create a rigid body, add the component Body to the entity, choosing a collision shape. It will turn the entity into a dynamic rigid body affected by physics.

The position, and rotation is defined by the bevy GlobalTransform component.

fn spawn(commands: &mut Commands) {
    commands

        // Spawn any bundle of your choice. Only make sure there is a `GlobalTransform`
        .spawn(SpriteBundle::default())

        // Make it a physics body, by attaching a collision shape
        .with(Body::Sphere { radius: 10.0 })

        // Optionally define a type (if absent, the body will be *dynamic*)
        .with(BodyType::Kinematic)
         
        // Optionally define the velocity (works only with dynamic and kinematic bodies)
        .with(Velocity::from(Vec2::unit_x() * 2.0));
}

Run systems synchronously with the physics step

The physics step runs at fixed rate (60 times per second by default) and is out of sync of the bevy frame.

But modifying any physics component (such as the transform or velocity) must be done synchronously with the physics step.

The simplest way is to add these systems with add_physics_system:

App::build()
    .add_plugins(DefaultPlugins)
    .add_plugin(PhysicsPlugin::default())

    // This system should NOT update transforms, velocities and other physics components
    // In other game engines this would be the "update" function
    .add_system(cannot_update_physics.system())

    // This system can update transforms, velocities and other physics components
    // In other game engines this would be the "physics update" function
    .add_physics_system(update_velocities.system())

Move rigid bodies programatically

When creating games, it is often useful to interact with the physics engine and move bodies programatically. For this, you have two options: Updating the Transform or applying a Velocity.

Option 1: Update the Transform

For kinematic bodies (BodyType::Kinematic), if the transform is udpated, the body is moved and get an automatically calculated velocity. Physics rules will be applied normally. Updating the transform is a good way to move a kinematic body.

For other type of bodies, if the transform is updated, the rigid body will be teleported to the new position/rotation, ignoring physic rules.

Option 2: Use the Velocity component

For BodyType::Dynamic and BodyType::Kinematic bodies only, one can add a Velocity component to the entity, that will move the body over time. Physics rules will be applied normally.

Note that the velocity component is updated by heron to always reflects the current velocity.

Defining/updating the velocity is a good way to interact with dynamic bodies.

See also

• The different BodyType (dynamic, static, kinematic or sensor)
• How to define the world’s Gravity
• How to define the PhysicMaterial
• How to listen to CollisionEvent

Modules

ext	Extensions to bevy API
prelude	Re-exports of the most commons/useful types
rapier_plugin	Physics behavior powered by rapier
stage	Physics stages for user systems. These stages are executed once per physics step.
utils	Utility traits and extensions

Structs

AxisAngle	An axis-angle representation
CorePlugin	Plugin that register stage resources and components.
Gravity	Resource that defines world’s gravity.
PhysicMaterial	Component that defines the physics properties of the rigid body
PhysicsPlugin	Plugin to install in order to enable collision detection and physics behavior.
Velocity	Component that defines the linear and angular velocity.

Enums

Body	Components that defines a body subject to physics and collision
BodyType	Component that defines the type of rigid body.
CollisionEvent	An event fired when the collision state between two entities changed

Traits

AppBuilderExt

Extensions for the app builder