Crate heron

Source
Expand description

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

§Get started

§Add the dependency and choose to work with either 2d or 3d

Add the library to Cargo.toml.

For a 3d game:

heron = { version = "3", features = ["3d"] }

For as 2d game:

heron = { version = "3", features = ["2d"] }

§Feature flags

One must choose to use either 2d or 3d. If none of theses two features is enabled, the plugin won’t be available.

  • 3d Enable simulation on the 3 axes x, y, and z. Incompatible with the feature 2d.
  • 2d Enable simulation only on the first 2 axes x and y. Incompatible with the feature 3d, therefore require to disable the default features.
  • debug-2d Render 2d collision shapes
  • debug-3d Render 3d collision shapes
  • collision-from-mesh Add the PendingConvexCollision component to generate convex hull collision shapes from a mesh
  • enhanced-determinism Enable rapier’s enhanced-determinism

§Install the plugin

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

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

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

§Create rigid bodies

To create a rigid body, add the RigidBody 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 positional kinematic bodies (RigidBody::KinematicPositionBased), 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::KinematicVelocityBased 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

Modules§

prelude
Re-exports of the most commons/useful types
rapier_plugin
Physics behavior powered by rapier
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.
Collisions
Component which will be filled (if present) with a list of entities with which the current entity is currently in contact.
CorePlugin
Plugin that registers stage resources and components.
CustomCollisionShape
An opaque type representing a custom collision shape.
Damping
Component that defines the linear and angular damping.
Gravity
Resource that defines world’s gravity.
PendingConvexCollision
Component which indicates that this entity or its children contains meshes which waiting for collision generation.
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
PhysicsStepDuration
The duration of time that this physics step should advance the simulation time
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