Crate heron[−][src]

Expand description

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.7.0"

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

heron = { version = "0.7.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

The PhysicsPlugin should be installed to enable physics and collision detection.

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 RigdBody to the entity and add a collision shapes with the CollisionShape component.

The position and rotation are defined by the bevy GlobalTransform component.

fn spawn(mut commands: Commands) {
commands

    // Spawn any bundle of your choice. Only make sure there is a `GlobalTransform`
    .spawn_bundle(SpriteBundle::default())
     
    // Make it a rigid body
    .insert(RigidBody::Dynamic)
     
    // Attach a collision shape
    .insert(CollisionShape::Sphere { radius: 10.0 })
     
    // Optionally add other useful components...
    .insert(Velocity::from_linear(Vec3::X * 2.0))
    .insert(Acceleration::from_linear(Vec3::X * 1.0))
    .insert(PhysicMaterial { friction: 1.0, density: 10.0, ..Default::default() })
    .insert(RotationConstraints::lock());
}

Move rigid bodies programmatically

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

Option 1: Update the Transform

For kinematic bodies (RigidBody::Kinematic), if the transform is updated, 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 types 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 RigidBody::Dynamic and RigidBody::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.

Modules

ext	Deprecated
prelude	Re-exports of the most commons/useful types
rapier_plugin	Physics behavior powered by rapier
stage	Deprecated
utils	Utility traits and extensions

Structs

Acceleration	Component that defines the linear and angular acceleration.
AxisAngle	An axis-angle representation
CollisionData	Collision data concerning one of the two entity that collided
CollisionLayers	Components that defines the collision layers of the collision shape.
CorePlugin	Plugin that registers 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 to enable collision detection and physics behavior.
PhysicsSteps	Resource to control how many physics steps are performed per second.
PhysicsTime	Resource that controls the physics time scale
RotationConstraints	Component that restrict what rotations can be caused by forces.
SensorShape	Mark the `CollisionShape` of the same entity as being a sensor.
Velocity	Component that defines the linear and angular velocity.

Enums

CollisionEvent	An event fired when the collision state between two entities changed
CollisionShape	Components that defines the collision shape of a rigid body
PhysicsSystem	Physics system labels
RigidBody	Component that mark the entity as being a rigid body