bevy_feronia

Environment scattering tools and shaders/materials that prioritize visual fidelity/artistic freedom, a declarative API and modularity.

[!CAUTION] This package is in early development and in an experimentation stage.

Getting started

cargo add bevy_feronia

The possible use-cases are demonstrated in the examples

Setup

The setup depends on the use-case, but a typical setup would look like something like this:

app.add_plugins((
    ExtendedWindAffectedScatterPlugin
));

The Scatter system needs to know when it can setup since it can depend on height mapping. You need to insert the setup state at some point.

[!NOTE]
In complex setups that load assets and bake a height map this can be after the Startup.

app.insert_state(ScatterState::Setup)

or

ns_height_map.set(HeightMapState::Setup);
ns_scatter.set(ScatterState::Setup);

Defining layers

A ScatterItem's LOD's are grouped by Name.

[!CAUTION] When defining multiple ScatterItems per ScatterLayer without names, a different asset will render when LODs are changing, leading to visual bugs.

// Landscape
cmd.spawn((
    MeshMaterial3d(materials.add(StandardMaterial {
    base_color: GRAY_500.into(),
        ..default()
    })),
    Mesh3d(meshes.add(PlaneMeshBuilder::from_length(80.).build())),
    ScatterRoot::default(),
    // Scatter layers
    children![(
            // Make sure you use the correct `ScatterLayer` with the desired `ScatterLayerType`, e.g.,
            // Standard, Extended or Instanced Material/Layer.
            extension::scatter_layer("Wind Affected Layer"),
            // Scatter Options
            DistributionDensity(50.),
            InstanceJitter::default(),
            // You can define material options on the full layer here
            WindAffected,
            children![
                (
                    // Or overwrite on the item, e.g., 
                    // WindAffected,
                    //
                    // CAUTION: If you have multiple assets, all lods that belong to each other need to have the same name!
                    //
                    // You can have multiple assets in each layer; as long as all LODs have the same name, they will be matched correctly.
                    Name::new("Wind Affected Example Item"),
                    MeshMaterial3d(materials.add(StandardMaterial::default())),
                    Mesh3d(mesh.clone()),
                ),
                (
                    Name::new("Wind Affected Example Item"),
                    // We need to specify the LOD Level if it is not 0 (Highest level)
                    LevelOfDetail(1),
                    MeshMaterial3d(materials.add(StandardMaterial {
                        base_color: RED_500.into(),
                        ..default()
                    })),
                    Mesh3d(mesh.clone()),
                ),

            ]
        )]
));

Scattering

Now you can start scattering! 🌱 🍃 🌿 🍀 🌳 🌲 🌴 🌺

cmd.trigger(Scatter::<ExtendedWindAffectedMaterial>::new(*root));

[!NOTE] ScatterLayers and their ScatterItems of the same ScatterType are always scattered in order, but layers of different ScatterTypes can be scattered at the same time.

Ordered Scattering

In complex scenes it is often required to scatter a complete hierarchy in order (rocks → trees/foliage → grass).

[!TIP] If a ordered scatter is still required and you can't or don't want to scatter in parallel, observers need to be used to chain the scattering of ScatterTypes in order.

fn scatter_on_keypress(
    mut cmd: Commands,
    keyboard_input: Res<ButtonInput<KeyCode>>,
    root: Single<Entity, With<ScatterRoot>>
) {
    if !keyboard_input.just_pressed(KeyCode::Space) {
        return;
    };

    // Scatter the rocks.
    cmd.trigger(Scatter::<StandardMaterial>::new(q_root));
}

fn scatter_extended(
    _: On<ScatterFinished<StandardMaterial>>,
    mut cmd: Commands,
    root: Single<Entity, With<ScatterRoot>>,
) {
    // Scatter the foliage after the rocks.
    cmd.trigger(Scatter::<ExtendedWindAffectedMaterial>::new(*root));
}

fn scatter_instanced(
    _: On<ScatterFinished<ExtendedWindAffectedMaterial>>,
    mut cmd: Commands,
    root: Single<Entity, With<ScatterRoot>>,
) {
    // Scatter the grass last so it doesn't grow on occupied areas.
    cmd.trigger(Scatter::<InstancedWindAffectedMaterial>::new(*root));
}

Credits/Inspirations/References

Feel free to copy the grass assets. All the other assets used in the examples are licensed assets.

[!IMPORTANT] If you intend to use them, make sure you comply with the license.

• Graswald for their amazing assets and GScatter, which served as inspiration for the scatter tools.
• Sucker Punch Productions for their Procedural Grass and Wind simulation in 'Ghost of Tsushima' and GDC Talks.
• bevy_procedural_grass by jadedbay
• warbler_grass by EmiOnGit
• GDC 2011 "Approximating Translucency"
• Blinn–Phong reflection model
• All the other assets

Roadmap

A bunch of issues are already open, but some of the larger milestones could be:

• Allow physics-based and other entities to impact the displacement/wind.
• Make use of compute shaders (Allow scattering on CPU and GPU, improve culling).