[−][src]Struct amethyst_physics::PhysicsBundle

pub struct PhysicsBundle<'a, 'b, N: PtReal, B: PhysicsBackend<N>> { /* fields omitted */ }

To use the amethyst_physics crate is necessary to register the PhysicsBundle as show below.

use amethyst_physics::PhysicsBundle;
use amethyst::amethyst_nphysics::NPhysicsBackend;

let game_data = GameDataBuilder::default()
    .with_bundle(PhysicsBundle::<f32, NPhysicsBackend>::new()).unwrap()

Is it possible to define the Physics Engine floating point precision and the PhysicsBackend; additionally, the physics frame rate can be specified using the function with_frames_per_seconds.

Dispatcher pipeline

Behind the scenes

To have a stable execution, the physics stepping is executed with a constant frame rate; and to be frame rate agnostic it keep tracks of the elapsed time. But don't worry, the above statement means that a physics step can occur multiple times per each frame. So, when you have a System that interact with the physics, you have to register it using the API provided by the PhysicsBundle; amethyst_physics will take care to execute your Systems at the right time.

Pipeline

The physics pipeline is composed by three sections:

Pre physics with_pre_physics

Executed just before any physics step. In this section of the pipeline you want to register any System that will alter the simulation (like add a force or change a transform).
In physics with_in_physics

The Systems in this stage are executed in parallel with the physics stepping, and this section is meant for all the Systems that have to be executed each physics frame but doesn't depend on its state.
Post physics with_post_physics

The last section of the physics pipeline, is simply executed just after the physics stepping. In this section, you want to register the Systems that collects the physics states, (like checking for volumes overlaps, or collision events).

Parallel physics dispatching

amethyst_physics is designed to dispatch the physics in parallel with everything else, by default. When you start to interact with it, you have to approach it correctly to maintain this property.

Some internal parts are being explained, and if the physics of your game is not so heavy, or you are not yet confortable with amethyst_physics, you can just skip this section.

The physics pipeline, just explained above, groups all the Systems that interact with the physics. We can consider all these Systems, a single group; let's call it PhysicsBatch.

Like any other System in Amethyst, the PhysicsBatch is dispatched by shred, this mean that if we make sure that its resources are not used by any other System, registered after it, them will run in parallel.

Synchronization

The main concept is easy, but let's see what it mean in practice.

When nothing is registered in the PhysicsBatch, the only resource that can potentially cause problems is the Transform Component. To avoid using the Transform Component inside the PhysicsBatch; amethyst_physics defines the PhysicsSyncSystem, that executed at the begining of each frame, it will take care to copy the transforms from the physics to Amethyst. Leaving the physics and the rendering untied and free to be executed in parallel.

The dispatcher looks like this:

|--Sync--||-------------PhysicsBatch------------|
          |--Any other System--||-- Rendering --|

Taking as example a race game, you may want to display a scratch on the car when it hits something. To ensure that the physics runs in parallel, you want to register the System that checks for the collision, before the PhysicsBatch (similarly as was explained above).

The dispatcher looks like this:

|--Sync--|         |-------------PhysicsBatch------------|
|--CollisionSync--||--Any other System--||-- Rendering --|

That's it.

Following this small trick, the physics will run in parallel with anything else!.

Small TODO to highlight

I'm confident that this section will be removed ASAP, but for the sake of completeness I've to mention a problem.

The above section, which explains how to make the physics runs in parallel, due to a small Amethyst's design problem, is lying. Indeed, is not possible to run the physics and the rendering in parallel, because they are in two different pipelines.

So the dispatcher looks like:

|--Sync--|         |-------------PhysicsBatch------------|
|--CollisionSync--||--Any other System--|
                                                           |-- Rendering --|

To know more about it, check this: https://github.com/AndreaCatania/amethyst/issues/2

However, I'm confident that this will be solved soon, and for this reason the above section is written as if this problem doesn't exist.

Methods

`impl<'a, 'b, N: PtReal, B: PhysicsBackend<N>> PhysicsBundle<'a, 'b, N, B>`[src]

`pub fn new() -> Self`[src]

Creates new PhysicsBundle

`pub fn with_frames_per_seconds(self, frames_per_seconds: u32) -> Self`[src]

Set the physics frames per seconds.

This is just an helper function, and you can modify it later in the game.

Check the PhysicsTime

`pub fn set_frames_per_seconds(self, frames_per_seconds: u32)`[src]

Set the physics frames per seconds.

This is just an helper function, and you can modify it later in the game.

Check the PhysicsTime

`pub fn with_max_sub_steps(self, max_sub_steps: u32) -> Self`[src]

Set the physics max sub steps.

This controls how much physics step can be executed in a single frame. It's used to avoid spiral performance degradation. Set it to an too high value, will make this mechanism ineffective, and a too low value will make the physics unstable. Is advised to keep the default

This is just an helper function, and you can modify it later in the game. Check the PhysicsTime

`pub fn set_max_sub_steps(self, max_sub_steps: u32)`[src]

Set the physics max sub steps.

This controls how much physics step can be executed in a single frame. It's used to avoid spiral performance degradation. Set it to an too high value, will make this mechanism ineffective, and a too low value will make the physics unstable. Is advised to keep the default

This is just an helper function, and you can modify it later in the game. Check the PhysicsTime

`pub fn with_pre_physics<S>( self, system: S, name: String, dependencies: Vec<String> ) -> Self where S: for<'c> System<'c> + 'static + Send,` [src]

Add a System to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn add_pre_physics<S>( &mut self, system: S, name: String, dependencies: Vec<String> ) where S: for<'c> System<'c> + 'static + Send,` [src]

Add a System to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn with_system_desc_pre_physics<SD, S>( self, system_desc: SD, name: String, dependencies: Vec<String> ) -> Self where SD: SystemDesc<'a, 'b, S> + 'static, S: for<'s> System<'s> + 'static + Send,` [src]

Add a SystemDesc to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn add_system_desc_pre_physics<SD, S>( &mut self, system_desc: SD, name: String, dependencies: Vec<String> ) where SD: SystemDesc<'a, 'b, S> + 'static, S: for<'s> System<'s> + 'static + Send,` [src]

Add a SystemDesc to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn with_bundle_pre_physics<BUND>(self, bundle: BUND) -> Self where BUND: SystemBundle<'a, 'b> + 'static + Send,` [src]

Add a Bundle to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn add_bundle_pre_physics<BUND>(&mut self, bundle: BUND) where BUND: SystemBundle<'a, 'b> + 'static + Send,` [src]

Add a Bundle to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn with_barrier_pre_physics(self) -> Self`[src]

Add a Barrier to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).

`pub fn add_barrier_pre_physics(&mut self)`[src]

Add a Barrier to the Pre physics pipeline.

This pipeline is executed before the physics step. Register here all the Systems that want to control the physics (like add force, set transform).