Crate bevy_falling_sand

Expand description

bevy_falling_sand is a plugin for adding falling sand physics to your Bevy project.

§Bevy versions

`bevy_falling_sand`	`bevy`
0.3.x	0.14.x
0.1.x	0.13.x

§Example

If you clone this repository, there is an example available that provides a full GUI interface for a “sandbox” like experience. I recommend running the example with the --release flag to maximize performance:

cargo run --example sandbox --release

§How to use

Spawning a particle is easy, just insert a ParticleType variant on an entity with a Transform component and it will be added to the simulation:

commands.spawn((
    ParticleType::Water,
    SpatialBundle::from_transform(Transform::from_xyz(0., 0., 0.)),
    ));

§Current limitations

§ChunkMap size

For optimization reasons, the underlying mapping mechanism for particles utilizes a sequence of chunks, each of which will induce a “hibernating” state on itself and the particles it contains if no movement is detected in a given frame. Because of this, the total map size is limited (the default is 1024x1024 spanning from transform (-512, 512) through (512, -512)). Any particle processed outside of this region will cause a panic.

This will be resolved in a future release, which will modify the ChunkMap to “follow” and entity with an arbitrary specified component (for example, a main camera), loading and unloading chunks as it moves. This will emulate an “infinite” space in which particles can reside.

§Single-threaded simulation

Currently, the particle simulation is single threaded. An multi-threaded simulation is planned for a future release.

If you want to tweak CPU thread allocation in the meantime to experiment with performance, you might try adjusting the default task pool thread assignment policy that bevy provides. I’ve found differing results in performance based on CPU manufacturer/architecture (sorry, no benchmarks available)

use bevy::{
    core::TaskPoolThreadAssignmentPolicy, prelude::*, tasks::available_parallelism,
};

fn main() {
    let mut app = App::new();
    app.add_plugins(DefaultPlugins
        .set(TaskPoolPlugin {
            task_pool_options: TaskPoolOptions {
                compute: TaskPoolThreadAssignmentPolicy {
                    min_threads: available_parallelism(),
                    max_threads: std::usize::MAX,
                    percent: 1.0,
                },
                ..default()
            },
        }));
}

§Visualizing chunk behavior

If you want to visualize how chunks behave, insert the DebugParticles resource:

app.init_resource::<DebugParticles>()

Structs§

Anchored: Indicates whether a particle should be considered for movement or not. Examples of anchored particles might be the ground, or walls. We want anchored particles to be considered as impenetrable neighbors (excluding their ability to be destroyed), but without uninstigated movement.
Chunk
ChunkMap: Generic resource for mapping IVec2 to entities. This resource uses underlying “chunks” which can optimize performance when processing large numbers of entities that may be inactive for some time. Chunks will enter a “sleeping” status if none of their contents are processed in a given frame.
Coordinates: Coordinates component for particles.
DebugGizmos: Indicates a gizmo used for debugging purposes
DebugParticles: Indicates whether built-in debugging should be enabled.
DenseRockWallBundle: Bundle of common particle components for dense rock wall
Density: The density of a particle.
DirtWallBundle: Bundle of common particle components for dirt wall
FallingSandPlugin
GrassWallBundle: Bundle of common particle components for grass wall
Momentum: Momentum component for particles. If a particle possesses this component, it will dynamically attempt to move in the same direction it moved in the previous frame.
Neighbors: A particle’s neighbors, represented as a nested vector of IVec2. The outer vectors represent tiered “groups” of priority, whereas the inner vectors are representative of relative coordinates a particle might move to. See the handle_particles system.
OilBundle: Bundle of common particle components for oil
Particle: Marker component for particles.
ParticleColor: Provides an individual particle with a particular color, usually selected from an existing entity with the ParticleColors component.
ParticleColors: Provides a range of possible colors for a particle. Child particles will access this component from their parent particle when spawning to select a color for themselves at random.
ParticleDebugSet
ParticleParent: Marker component for particle parents.
ParticleParentMap: Map of all parent particle types to their corresponding entity. Used to map child particles to their corresponding parent data.
ParticleSimulationSet
PhysicsRng: RNG to use when dealing with any entity that needs random movement behaviors.
RockWallBundle: Bundle of common particle components for rock wall
SandBundle: Bundle of common particle components for sand
SimulationBatch: Resource to insert for parallel queries and batching
SimulationPause: Resource to insert for pausing the simulation
Sleeping: Provides a flag for indicating whether a Particle is in a hibernated state. This is used to indicate whether a particle should be included in any kind of movements for the frame.
SteamBundle: Bundle of common particle components for steam
Velocity: A particle’s velocity.
WallBundle: Bundle of common particle components for wall
WaterBundle: Bundle of common particle components for water
WhiskeyBundle: Bundle of common particle components for whiskey

Enums§

ParticleType: Possible particle types. Add a variant of this enum to an entity to spawn the corresponding type into the world.

Functions§

color_chunks: Provides gizmos rendering for visualizing dead/alive chunks
color_particles: Colors newly added or changed particles
handle_new_particles: Map all particles to their respective parent when added/changed within the simulation
handle_particles: Moves all qualifying particles ‘v’ times equal to their current velocity
reset_chunks: Resets all chunks in preparation for the next frame
setup_particles: Setup all particle parent types on startup
swap_particle_positions

Crate bevy_falling_sandCopy item path