Heron

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

How it looks like

```rust fn main() { App::build() .addplugins(DefaultPlugins) .addplugin(PhysicsPlugin::default()) // Add the plugin .addresource(Gravity::from(Vec3::new(0.0, -9.81, 0.0))) // Optionally define gravity .addstartup_system(spawn.system()) .run(); }

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));

} ```

Installation

For a 3d game: toml bevy = "^0.4.0" heron = "0.2.0"

For a 2d game: toml bevy = "^0.4.0" heron = { version = "0.2.0"] }

With the git version of bevy: ```toml bevy = { git = "https://github.com/bevyengine/bevy.git", branch = "main" }

ATTENTION: The code may not compile. And if it does compile, it may not work properly!

Be aware, that it might contains unreleased features and breaking changes too.

Checkout the changelog: https://github.com/jcornaz/heron/blob/next-bevy/CHANGELOG.md#unreleased

heron = { git = "https://github.com/jcornaz/heron.git", branch = "next-bevy" } ```

Design principles

• Use [bevy] types, resources and components when possible (Vec3, Quat, Transform, Events, etc.)
• Provide a single API that works for both 2d and 3d. (Like bevy does)
• Data oriented. Using this library should look like it is part of [bevy].
• Avoid asking the user to lookup in resources via handles. Data should be accessible and modifiable directly in components.
• Hide the actual physics engine. This is an implementation detail the user shouldn't have to care about.
  • But, allow advanced users to access the underlying [rapier] resources, so a user is never blocked by a missing element in the API of heron.

Feature flags

One must choose to use either 2d or 3d (but not both). If none of theses two features is enabled, the PhysicsPlugin won't be available.

Enabled by Default

• 3d Enable simulation on the 3 axes x, y, and z. Incompatible with the feature 2d.

Optional

• 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 Render collision shapes. Works only in 2d, support for 3d will be added later.

Motivation

I think [rapier] is very powerful as a physics engine. But using it directly or via [bevy_rapier] in a [bevy] game is not ergonomic enough for my taste.

Ideally I would like to have the power of [rapier] accessible behind an API focused on [bevy] games.

Contribute / Contact

You can open issues/discussions here or you can discuss with me (Jomag#2675) in the bevy discord

See how to contribute