#game #gamedev #physics #collision #bevy

heron

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

30 releases (11 stable)

Uses new Rust 2021

3.0.0 Apr 17, 2022
2.4.1 Apr 15, 2022
2.3.0 Mar 23, 2022
1.2.0 Feb 19, 2022
0.3.0 Mar 21, 2021

#16 in Game dev

Download history 182/week @ 2022-01-25 127/week @ 2022-02-01 108/week @ 2022-02-08 237/week @ 2022-02-15 263/week @ 2022-02-22 445/week @ 2022-03-01 213/week @ 2022-03-08 223/week @ 2022-03-15 315/week @ 2022-03-22 179/week @ 2022-03-29 280/week @ 2022-04-05 358/week @ 2022-04-12 267/week @ 2022-04-19 408/week @ 2022-04-26 335/week @ 2022-05-03 200/week @ 2022-05-10

1,293 downloads per month
Used in 3 crates (2 directly)

MIT license

190KB
3.5K SLoC

Heron

License Crates.io Docs dependency status Bevy tracking Build Zenhub

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

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.
  • Data oriented. Using this library should feel like its a 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 worry about.
    • But, allow advanced users to access the underlying rapier resources, so the user is never blocked by a missing element in the API of heron.

What it looks like

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

fn main() {
  App::new()
    .add_plugins(DefaultPlugins)
    .add_plugin(PhysicsPlugin::default()) // Add the plugin
    .insert_resource(Gravity::from(Vec3::new(0.0, -9.81, 0.0))) // Optionally define gravity
    .add_startup_system(spawn)
    .run();
}

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())
        .insert(CollisionLayers::none().with_group(Layer::Player).with_mask(Layer::World));
}

// Define your physics layers
#[derive(PhysicsLayer)]
enum Layer {
    World,
    Player,
    Enemies,
}

Documentation

MSRV

The minimum supported rust version is currently: 1.60

It may be increased to a newer stable version in a minor release. (but only if needed)

It will be increased to the latest stable version in a major release. (even if not needed)

Supported Bevy Versions

bevy heron
0.7 3
0.6 1 - 2
0.5 0.4 - 0.13
0.4 0.1 - 0.3

How does this project compare to bevy_rapier?

bevy_rapier plugin is an excellent option and should definitely be considered.

Here are some key differences between the two projects:

  • heron tries to provide a smaller, simpler API that is easier to use. bevy_rapier is more complete and powerful, but a bit more complex.
  • heron mostly hides the underlying physics engine, so you don't have to use rapier directly nor nalgebra. bevy_rapier asks the user to deal directly with rapier and nalgebra.
  • heron is focused on games only. bevy_rapier targets all kind of physics simulation applications (incl. games).
  • bevy_rapier is actively maintained by dimforge, the developer of rapier. heron is also active, but cannot evolve as fast as bevy_rapier can.

heron is probably more suited for simple games and game-jams, where the ease of learn/use is especially valuable and where the lack of advanced feature isn't problematic.

bevy_rapier is probably more suited for bigger/complex games and other types of physics simulations, where it may be better to learn/use a more exhaustive/complex API.

Contribute / Contact

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

See how to contribute

Dependencies

~20–27MB
~349K SLoC