From 8581aab71070b397deab3355957766b1c756a044 Mon Sep 17 00:00:00 2001 From: Martijn Faassen Date: Tue, 16 Mar 2021 21:50:34 +0100 Subject: [PATCH 1/3] Add a quickstart to the guide. --- guide/src/SUMMARY.md | 2 +- guide/src/features.md | 16 +++++++++ guide/src/quickstart.md | 78 +++++++++++++++++++++++++++++++++++++++++ guide/src/setup.md | 30 ---------------- 4 files changed, 95 insertions(+), 31 deletions(-) create mode 100644 guide/src/features.md create mode 100644 guide/src/quickstart.md delete mode 100644 guide/src/setup.md diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 860f6af0..ba45582f 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -1,3 +1,3 @@ # Summary -- [Setup](setup.md) +- [Quickstart](quickstart.md) diff --git a/guide/src/features.md b/guide/src/features.md new file mode 100644 index 00000000..56d3d439 --- /dev/null +++ b/guide/src/features.md @@ -0,0 +1,16 @@ + +# Features, to be written + +* You can add BodyType Static, Kinematic and Dynamic + +* PhysicsMaterial + +* In order to rotate a transform, use `rotate` with a Quad. + +* collision detection + +* Rotation in 2d is around the z axis. + +* Modifying Velocity and Acceleration + +* How to acces Rapier directly diff --git a/guide/src/quickstart.md b/guide/src/quickstart.md new file mode 100644 index 00000000..567649d7 --- /dev/null +++ b/guide/src/quickstart.md @@ -0,0 +1,78 @@ +# Quickstart + +Here is a basic example of using Heron with 2d graphics. It draws a green box +that falls down due to gravity: + +```rust +use bevy::prelude::*; +use heron::*; + +#[bevy_main] +fn main() { + App::build() + .add_plugins(DefaultPlugins) + .add_plugin(PhysicsPlugin::default()) // Add the Heron plugin + .add_resource(Gravity::from(Vec3::new(0.0, -300.0, 0.0))) // Define gravity + .add_startup_system(spawn.system()) + .run(); +} + +fn spawn(commands: &mut Commands, mut materials: ResMut>) { + // Ensure we can see things + commands.spawn(Camera2dBundle::default()); + + // the size of our sprite + let size = Vec2::new(30.0, 30.0); + commands + // here we add a Sprite. We can add any bundle of our choice; the + // only required component is a GlobalTransform + .spawn(SpriteBundle { + sprite: Sprite::new(size), + material: materials.add(Color::GREEN.into()), + transform: Transform::from_translation(Vec3::new(0.0, 200.0, 0.0)), + ..Default::default() + }) + // Make it a physics body, by attaching a collision shape + .with(Body::Cuboid { + // let the size be consistent with our sprite + half_extends: size.extend(0.0) / 2.0, + }); +} +``` + +If you create a new project using `cargo init` you can replace `main.rs` +with this code. You should also add this to your projects's `Cargo.toml`: + +```toml +[dependencies] +bevy = { version = "0.4"} +heron = { version = "0.2.0", default-features = false, features = ["2d"] } +``` + +Heron defaults to 3d. To make sure we run it in 2d mode we have to configure it +in `Cargo.toml`; we need to turn off the default features and enable `2d`. + +If you then run `cargo run` you should see the green box fall. + +## Explanation + +We create a normal `Bevy` app. To enable Heron we must add the `PhysicsPlugin`. +Optionally you can add a `Gravity` resource, as we do here. + +We can spawn our physics entities in the startup system as we do here. + +We also need to set up the camera bundle to 2d so that we can see something. + +We then spawn a `SpriteBundle` in the normal Bevy style; here we generate a +very basic green `box` sprite and place it on `x` and `y` coordinates. Note +that we have to use `Vec3` even though we are in 2d space. In 2d we simply set +the `z` coordinate to zero always. + +To make it work with the physics engine, we must add a Heron `Body` component. +In this case we add a cuboid (rectangular in 2d) collision shape. + +And that's all there is to it! Heron, using the Rapier physics engine, makes +your sprite behave according to physics! + +You can do a lot more with Heron but this should get you started! + diff --git a/guide/src/setup.md b/guide/src/setup.md deleted file mode 100644 index 4954cd35..00000000 --- a/guide/src/setup.md +++ /dev/null @@ -1,30 +0,0 @@ -# Setup - -## Add the dependency in your `Cargo.toml` - -**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", default-features = false, features = ["2d"] } -``` - -## Add the plugin - -```rust,no_run -use bevy::prelude::*; -use heron::prelude::*; - -fn main() { - App::build() - .add_plugins(DefaultPlugins) - .add_plugin(PhysicsPlugin::default()) - // ... Add your resources and systems - .run(); -} -``` From a54d891cbe50057b5bcea1c29c43d171d3d738db Mon Sep 17 00:00:00 2001 From: Jonathan Cornaz Date: Wed, 17 Mar 2021 19:49:36 +0100 Subject: [PATCH 2/3] Don't run example that require graphics --- guide/src/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/src/quickstart.md b/guide/src/quickstart.md index 567649d7..24f8b845 100644 --- a/guide/src/quickstart.md +++ b/guide/src/quickstart.md @@ -3,7 +3,7 @@ Here is a basic example of using Heron with 2d graphics. It draws a green box that falls down due to gravity: -```rust +```rust,no_run use bevy::prelude::*; use heron::*; From 99ebffceb883794473842f1de390a0ecd14f5a41 Mon Sep 17 00:00:00 2001 From: Jonathan Cornaz Date: Wed, 17 Mar 2021 20:03:17 +0100 Subject: [PATCH 3/3] Delete features.md --- guide/src/features.md | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 guide/src/features.md diff --git a/guide/src/features.md b/guide/src/features.md deleted file mode 100644 index 56d3d439..00000000 --- a/guide/src/features.md +++ /dev/null @@ -1,16 +0,0 @@ - -# Features, to be written - -* You can add BodyType Static, Kinematic and Dynamic - -* PhysicsMaterial - -* In order to rotate a transform, use `rotate` with a Quad. - -* collision detection - -* Rotation in 2d is around the z axis. - -* Modifying Velocity and Acceleration - -* How to acces Rapier directly