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.8.0"
If you are creating a 2d game, change the default features:
heron = { version = "0.8.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.
See also
- How to define a
RigidBody
- How to choose a
CollisionShape
- How to define the world’s
Gravity
- How to define the world’s
PhysicsTime
- How to define the
PhysicMaterial
- How to listen to
CollisionEvent
- How to define
RotationConstraints
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 |
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 |
Traits
PhysicsLayer | Describes a collision layer |
Functions
should_run | Run criteria system that decides if the physics systems should run. |
Derive Macros
PhysicsLayer |