bevy/examples
Carter Anderson 747b0c69b0 Better Materials: AsBindGroup trait and derive, simpler Material trait (#5053)
# Objective

This PR reworks Bevy's Material system, making the user experience of defining Materials _much_ nicer. Bevy's previous material system leaves a lot to be desired:
* Materials require manually implementing the `RenderAsset` trait, which involves manually generating the bind group, handling gpu buffer data transfer, looking up image textures, etc. Even the simplest single-texture material involves writing ~80 unnecessary lines of code. This was never the long term plan.
* There are two material traits, which is confusing, hard to document, and often redundant: `Material` and `SpecializedMaterial`. `Material` implicitly implements `SpecializedMaterial`, and `SpecializedMaterial` is used in most high level apis to support both use cases. Most users shouldn't need to think about specialization at all (I consider it a "power-user tool"), so the fact that `SpecializedMaterial` is front-and-center in our apis is a miss.
* Implementing either material trait involves a lot of "type soup". The "prepared asset" parameter is particularly heinous: `&<Self as RenderAsset>::PreparedAsset`. Defining vertex and fragment shaders is also more verbose than it needs to be. 

## Solution

Say hello to the new `Material` system:

```rust
#[derive(AsBindGroup, TypeUuid, Debug, Clone)]
#[uuid = "f690fdae-d598-45ab-8225-97e2a3f056e0"]
pub struct CoolMaterial {
    #[uniform(0)]
    color: Color,
    #[texture(1)]
    #[sampler(2)]
    color_texture: Handle<Image>,
}
impl Material for CoolMaterial {
    fn fragment_shader() -> ShaderRef {
        "cool_material.wgsl".into()
    }
}
```

Thats it! This same material would have required [~80 lines of complicated "type heavy" code](https://github.com/bevyengine/bevy/blob/v0.7.0/examples/shader/shader_material.rs) in the old Material system. Now it is just 14 lines of simple, readable code.

This is thanks to a new consolidated `Material` trait and the new `AsBindGroup` trait / derive.

### The new `Material` trait

The old "split" `Material` and `SpecializedMaterial` traits have been removed in favor of a new consolidated `Material` trait. All of the functions on the trait are optional.

The difficulty of implementing `Material` has been reduced by simplifying dataflow and removing type complexity:

```rust
// Old
impl Material for CustomMaterial {
    fn fragment_shader(asset_server: &AssetServer) -> Option<Handle<Shader>> {
        Some(asset_server.load("custom_material.wgsl"))
    }

    fn alpha_mode(render_asset: &<Self as RenderAsset>::PreparedAsset) -> AlphaMode {
        render_asset.alpha_mode
    }
}

// New
impl Material for CustomMaterial {
    fn fragment_shader() -> ShaderRef {
        "custom_material.wgsl".into()
    }

    fn alpha_mode(&self) -> AlphaMode {
        self.alpha_mode
    }
}
```

Specialization is still supported, but it is hidden by default under the `specialize()` function (more on this later).

### The `AsBindGroup` trait / derive

The `Material` trait now requires the `AsBindGroup` derive. This can be implemented manually relatively easily, but deriving it will almost always be preferable. 

Field attributes like `uniform` and `texture` are used to define which fields should be bindings,
what their binding type is, and what index they should be bound at:

```rust
#[derive(AsBindGroup)]
struct CoolMaterial {
    #[uniform(0)]
    color: Color,
    #[texture(1)]
    #[sampler(2)]
    color_texture: Handle<Image>,
}
```

In WGSL shaders, the binding looks like this:

```wgsl
struct CoolMaterial {
    color: vec4<f32>;
};

[[group(1), binding(0)]]
var<uniform> material: CoolMaterial;
[[group(1), binding(1)]]
var color_texture: texture_2d<f32>;
[[group(1), binding(2)]]
var color_sampler: sampler;
```

Note that the "group" index is determined by the usage context. It is not defined in `AsBindGroup`. Bevy material bind groups are bound to group 1.

The following field-level attributes are supported:
* `uniform(BINDING_INDEX)`
    * The field will be converted to a shader-compatible type using the `ShaderType` trait, written to a `Buffer`, and bound as a uniform. It can also be derived for custom structs.
* `texture(BINDING_INDEX)`
    * This field's `Handle<Image>` will be used to look up the matching `Texture` gpu resource, which will be bound as a texture in shaders. The field will be assumed to implement `Into<Option<Handle<Image>>>`. In practice, most fields should be a `Handle<Image>` or `Option<Handle<Image>>`. If the value of an `Option<Handle<Image>>` is `None`, the new `FallbackImage` resource will be used instead. This attribute can be used in conjunction with a `sampler` binding attribute (with a different binding index).
* `sampler(BINDING_INDEX)`
    * Behaves exactly like the `texture` attribute, but sets the Image's sampler binding instead of the texture. 

Note that fields without field-level binding attributes will be ignored.
```rust
#[derive(AsBindGroup)]
struct CoolMaterial {
    #[uniform(0)]
    color: Color,
    this_field_is_ignored: String,
}
```

As mentioned above, `Option<Handle<Image>>` is also supported:
```rust
#[derive(AsBindGroup)]
struct CoolMaterial {
    #[uniform(0)]
    color: Color,
    #[texture(1)]
    #[sampler(2)]
    color_texture: Option<Handle<Image>>,
}
```
This is useful if you want a texture to be optional. When the value is `None`, the `FallbackImage` will be used for the binding instead, which defaults to "pure white".

Field uniforms with the same binding index will be combined into a single binding:
```rust
#[derive(AsBindGroup)]
struct CoolMaterial {
    #[uniform(0)]
    color: Color,
    #[uniform(0)]
    roughness: f32,
}
```

In WGSL shaders, the binding would look like this:
```wgsl
struct CoolMaterial {
    color: vec4<f32>;
    roughness: f32;
};

[[group(1), binding(0)]]
var<uniform> material: CoolMaterial;
```

Some less common scenarios will require "struct-level" attributes. These are the currently supported struct-level attributes:
* `uniform(BINDING_INDEX, ConvertedShaderType)`
    * Similar to the field-level `uniform` attribute, but instead the entire `AsBindGroup` value is converted to `ConvertedShaderType`, which must implement `ShaderType`. This is useful if more complicated conversion logic is required.
* `bind_group_data(DataType)`
    * The `AsBindGroup` type will be converted to some `DataType` using `Into<DataType>` and stored as `AsBindGroup::Data` as part of the `AsBindGroup::as_bind_group` call. This is useful if data needs to be stored alongside the generated bind group, such as a unique identifier for a material's bind group. The most common use case for this attribute is "shader pipeline specialization".

The previous `CoolMaterial` example illustrating "combining multiple field-level uniform attributes with the same binding index" can
also be equivalently represented with a single struct-level uniform attribute:
```rust
#[derive(AsBindGroup)]
#[uniform(0, CoolMaterialUniform)]
struct CoolMaterial {
    color: Color,
    roughness: f32,
}

#[derive(ShaderType)]
struct CoolMaterialUniform {
    color: Color,
    roughness: f32,
}

impl From<&CoolMaterial> for CoolMaterialUniform {
    fn from(material: &CoolMaterial) -> CoolMaterialUniform {
        CoolMaterialUniform {
            color: material.color,
            roughness: material.roughness,
        }
    }
}
```

### Material Specialization

Material shader specialization is now _much_ simpler:

```rust
#[derive(AsBindGroup, TypeUuid, Debug, Clone)]
#[uuid = "f690fdae-d598-45ab-8225-97e2a3f056e0"]
#[bind_group_data(CoolMaterialKey)]
struct CoolMaterial {
    #[uniform(0)]
    color: Color,
    is_red: bool,
}

#[derive(Copy, Clone, Hash, Eq, PartialEq)]
struct CoolMaterialKey {
    is_red: bool,
}

impl From<&CoolMaterial> for CoolMaterialKey {
    fn from(material: &CoolMaterial) -> CoolMaterialKey {
        CoolMaterialKey {
            is_red: material.is_red,
        }
    }
}

impl Material for CoolMaterial {
    fn fragment_shader() -> ShaderRef {
        "cool_material.wgsl".into()
    }

    fn specialize(
        pipeline: &MaterialPipeline<Self>,
        descriptor: &mut RenderPipelineDescriptor,
        layout: &MeshVertexBufferLayout,
        key: MaterialPipelineKey<Self>,
    ) -> Result<(), SpecializedMeshPipelineError> {
        if key.bind_group_data.is_red {
            let fragment = descriptor.fragment.as_mut().unwrap();
            fragment.shader_defs.push("IS_RED".to_string());
        }
        Ok(())
    }
}
```

Setting `bind_group_data` is not required for specialization (it defaults to `()`). Scenarios like "custom vertex attributes" also benefit from this system:
```rust
impl Material for CustomMaterial {
    fn vertex_shader() -> ShaderRef {
        "custom_material.wgsl".into()
    }

    fn fragment_shader() -> ShaderRef {
        "custom_material.wgsl".into()
    }

    fn specialize(
        pipeline: &MaterialPipeline<Self>,
        descriptor: &mut RenderPipelineDescriptor,
        layout: &MeshVertexBufferLayout,
        key: MaterialPipelineKey<Self>,
    ) -> Result<(), SpecializedMeshPipelineError> {
        let vertex_layout = layout.get_layout(&[
            Mesh::ATTRIBUTE_POSITION.at_shader_location(0),
            ATTRIBUTE_BLEND_COLOR.at_shader_location(1),
        ])?;
        descriptor.vertex.buffers = vec![vertex_layout];
        Ok(())
    }
}
```

### Ported `StandardMaterial` to the new `Material` system

Bevy's built-in PBR material uses the new Material system (including the AsBindGroup derive):

```rust
#[derive(AsBindGroup, Debug, Clone, TypeUuid)]
#[uuid = "7494888b-c082-457b-aacf-517228cc0c22"]
#[bind_group_data(StandardMaterialKey)]
#[uniform(0, StandardMaterialUniform)]
pub struct StandardMaterial {
    pub base_color: Color,
    #[texture(1)]
    #[sampler(2)]
    pub base_color_texture: Option<Handle<Image>>,
    /* other fields omitted for brevity */
```

### Ported Bevy examples to the new `Material` system

The overall complexity of Bevy's "custom shader examples" has gone down significantly. Take a look at the diffs if you want a dopamine spike.

Please note that while this PR has a net increase in "lines of code", most of those extra lines come from added documentation. There is a significant reduction
in the overall complexity of the code (even accounting for the new derive logic).

---

## Changelog

### Added

* `AsBindGroup` trait and derive, which make it much easier to transfer data to the gpu and generate bind groups for a given type.

### Changed

* The old `Material` and `SpecializedMaterial` traits have been replaced by a consolidated (much simpler) `Material` trait. Materials no longer implement `RenderAsset`.
* `StandardMaterial` was ported to the new material system. There are no user-facing api changes to the `StandardMaterial` struct api, but it now implements `AsBindGroup` and `Material` instead of `RenderAsset` and `SpecializedMaterial`.

## Migration Guide
The Material system has been reworked to be much simpler. We've removed a lot of boilerplate with the new `AsBindGroup` derive and the `Material` trait is simpler as well!

### Bevy 0.7 (old)

```rust
#[derive(Debug, Clone, TypeUuid)]
#[uuid = "f690fdae-d598-45ab-8225-97e2a3f056e0"]
pub struct CustomMaterial {
    color: Color,
    color_texture: Handle<Image>,
}

#[derive(Clone)]
pub struct GpuCustomMaterial {
    _buffer: Buffer,
    bind_group: BindGroup,
}

impl RenderAsset for CustomMaterial {
    type ExtractedAsset = CustomMaterial;
    type PreparedAsset = GpuCustomMaterial;
    type Param = (SRes<RenderDevice>, SRes<MaterialPipeline<Self>>);
    fn extract_asset(&self) -> Self::ExtractedAsset {
        self.clone()
    }

    fn prepare_asset(
        extracted_asset: Self::ExtractedAsset,
        (render_device, material_pipeline): &mut SystemParamItem<Self::Param>,
    ) -> Result<Self::PreparedAsset, PrepareAssetError<Self::ExtractedAsset>> {
        let color = Vec4::from_slice(&extracted_asset.color.as_linear_rgba_f32());

        let byte_buffer = [0u8; Vec4::SIZE.get() as usize];
        let mut buffer = encase::UniformBuffer::new(byte_buffer);
        buffer.write(&color).unwrap();

        let buffer = render_device.create_buffer_with_data(&BufferInitDescriptor {
            contents: buffer.as_ref(),
            label: None,
            usage: BufferUsages::UNIFORM | BufferUsages::COPY_DST,
        });

        let (texture_view, texture_sampler) = if let Some(result) = material_pipeline
            .mesh_pipeline
            .get_image_texture(gpu_images, &Some(extracted_asset.color_texture.clone()))
        {
            result
        } else {
            return Err(PrepareAssetError::RetryNextUpdate(extracted_asset));
        };
        let bind_group = render_device.create_bind_group(&BindGroupDescriptor {
            entries: &[
                BindGroupEntry {
                    binding: 0,
                    resource: buffer.as_entire_binding(),
                },
                BindGroupEntry {
                    binding: 0,
                    resource: BindingResource::TextureView(texture_view),
                },
                BindGroupEntry {
                    binding: 1,
                    resource: BindingResource::Sampler(texture_sampler),
                },
            ],
            label: None,
            layout: &material_pipeline.material_layout,
        });

        Ok(GpuCustomMaterial {
            _buffer: buffer,
            bind_group,
        })
    }
}

impl Material for CustomMaterial {
    fn fragment_shader(asset_server: &AssetServer) -> Option<Handle<Shader>> {
        Some(asset_server.load("custom_material.wgsl"))
    }

    fn bind_group(render_asset: &<Self as RenderAsset>::PreparedAsset) -> &BindGroup {
        &render_asset.bind_group
    }

    fn bind_group_layout(render_device: &RenderDevice) -> BindGroupLayout {
        render_device.create_bind_group_layout(&BindGroupLayoutDescriptor {
            entries: &[
                BindGroupLayoutEntry {
                    binding: 0,
                    visibility: ShaderStages::FRAGMENT,
                    ty: BindingType::Buffer {
                        ty: BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: Some(Vec4::min_size()),
                    },
                    count: None,
                },
                BindGroupLayoutEntry {
                    binding: 1,
                    visibility: ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        sample_type: TextureSampleType::Float { filterable: true },
                        view_dimension: TextureViewDimension::D2Array,
                    },
                    count: None,
                },
                BindGroupLayoutEntry {
                    binding: 2,
                    visibility: ShaderStages::FRAGMENT,
                    ty: BindingType::Sampler(SamplerBindingType::Filtering),
                    count: None,
                },
            ],
            label: None,
        })
    }
}
```

### Bevy 0.8 (new)

```rust
impl Material for CustomMaterial {
    fn fragment_shader() -> ShaderRef {
        "custom_material.wgsl".into()
    }
}

#[derive(AsBindGroup, TypeUuid, Debug, Clone)]
#[uuid = "f690fdae-d598-45ab-8225-97e2a3f056e0"]
pub struct CustomMaterial {
    #[uniform(0)]
    color: Color,
    #[texture(1)]
    #[sampler(2)]
    color_texture: Handle<Image>,
}
```

## Future Work

* Add support for more binding types (cubemaps, buffers, etc). This PR intentionally includes a bare minimum number of binding types to keep "reviewability" in check.
* Consider optionally eliding binding indices using binding names. `AsBindGroup` could pass in (optional?) reflection info as a "hint".
    * This would make it possible for the derive to do this:
        ```rust
        #[derive(AsBindGroup)]
        pub struct CustomMaterial {
            #[uniform]
            color: Color,
            #[texture]
            #[sampler]
            color_texture: Option<Handle<Image>>,
            alpha_mode: AlphaMode,
        }
        ```
    * Or this
        ```rust
        #[derive(AsBindGroup)]
        pub struct CustomMaterial {
            #[binding]
            color: Color,
            #[binding]
            color_texture: Option<Handle<Image>>,
            alpha_mode: AlphaMode,
        }
        ```
    * Or even this (if we flip to "include bindings by default")
        ```rust
        #[derive(AsBindGroup)]
        pub struct CustomMaterial {
            color: Color,
            color_texture: Option<Handle<Image>>,
            #[binding(ignore)]
            alpha_mode: AlphaMode,
        }
        ```
* If we add the option to define custom draw functions for materials (which could be done in a type-erased way), I think that would be enough to support extra non-material bindings. Worth considering!
2022-06-30 23:48:46 +00:00
..
2d Add reusable shader functions for transforming position/normal/tangent (#4901) 2022-06-14 00:32:33 +00:00
3d transparency_3d example tweaks (#4968) 2022-06-23 18:36:07 +00:00
android android - fix issues other than the rendering (#5130) 2022-06-30 19:42:45 +00:00
animation add a SceneBundle to spawn a scene (#2424) 2022-06-09 20:34:09 +00:00
app Camera Driven Rendering (#4745) 2022-06-02 00:12:17 +00:00
asset add a SceneBundle to spawn a scene (#2424) 2022-06-09 20:34:09 +00:00
async_tasks Add global init and get accessors for all newtyped TaskPools (#2250) 2022-06-09 02:43:24 +00:00
audio Clippy improvements (#4665) 2022-05-31 01:38:07 +00:00
diagnostics Cleanups in diagnostics (#3871) 2022-06-20 17:02:25 +00:00
ecs Fix player number in example game in the ecs_guide (#5098) 2022-06-26 13:58:56 +00:00
games Fix typo in game_menu.rs (#4977) 2022-06-09 20:57:43 +00:00
input Doc/module style doc blocks for examples (#4438) 2022-05-16 13:53:20 +00:00
ios Fixed bevy_ui touch input (#4099) 2022-06-20 20:32:19 +00:00
reflection Clippy improvements (#4665) 2022-05-31 01:38:07 +00:00
scene add a SceneBundle to spawn a scene (#2424) 2022-06-09 20:34:09 +00:00
shader Better Materials: AsBindGroup trait and derive, simpler Material trait (#5053) 2022-06-30 23:48:46 +00:00
stress_tests many foxes: only change animation once (#5076) 2022-06-23 02:00:45 +00:00
tools Camera Driven Rendering (#4745) 2022-06-02 00:12:17 +00:00
transforms use the default() method in examples instead of Default::default() (#4952) 2022-06-07 02:16:47 +00:00
ui use the default() method in examples instead of Default::default() (#4952) 2022-06-07 02:16:47 +00:00
wasm Remove wasm specific examples (#3705) 2022-01-17 22:38:05 +00:00
window add a SceneBundle to spawn a scene (#2424) 2022-06-09 20:34:09 +00:00
hello_world.rs Add upstream bevy_ecs and prepare for custom-shaders merge (#2815) 2021-09-14 06:14:19 +00:00
README.md android - fix issues other than the rendering (#5130) 2022-06-30 19:42:45 +00:00
README.md.tpl android - fix issues other than the rendering (#5130) 2022-06-30 19:42:45 +00:00

Examples

These examples demonstrate the main features of Bevy and how to use them. To run an example, use the command cargo run --example <Example>, and add the option --features x11 or --features wayland to force the example to run on a specific window compositor, e.g.

cargo run --features wayland --example hello_world

⚠️ Note: for users of releases on crates.io!

There are often large differences and incompatible API changes between the latest crates.io release and the development version of Bevy in the git main branch!

If you are using a released version of bevy, you need to make sure you are viewing the correct version of the examples!

When you clone the repo locally to run the examples, use git checkout to get the correct version:

# `latest` always points to the newest release
git checkout latest
# or use a specific version
git checkout v0.4.0

Table of Contents

The Bare Minimum

Hello, World!

Example Description
hello_world.rs Runs a minimal example that outputs "hello world"

Cross-Platform Examples

2D Rendering

Example Description
2D Rotation Demonstrates rotating entities in 2D with quaternions
Manual Mesh 2D Renders a custom mesh "manually" with "mid-level" renderer apis
Mesh 2D Renders a 2d mesh
Mesh 2D With Vertex Colors Renders a 2d mesh with vertex color attributes
Move Sprite Changes the transform of a sprite
Shapes Renders a rectangle, circle, and hexagon
Sprite Renders a sprite
Sprite Flipping Renders a sprite flipped along an axis
Sprite Sheet Renders an animated sprite
Text 2D Generates text in 2D
Texture Atlas Generates a texture atlas (sprite sheet) from individual sprites
Transparency in 2D Demonstrates transparency in 2d

3D Rendering

Example Description
3D Scene Simple 3D scene with basic shapes and lighting
3D Shapes A scene showcasing the built-in 3D shapes
Lighting Illustrates various lighting options in a simple scene
Load glTF Loads and renders a glTF file as a scene
MSAA Configures MSAA (Multi-Sample Anti-Aliasing) for smoother edges
Orthographic View Shows how to create a 3D orthographic view (for isometric-look in games or CAD applications)
Parenting Demonstrates parent->child relationships and relative transformations
Physically Based Rendering Demonstrates use of Physically Based Rendering (PBR) properties
Render to Texture Shows how to render to a texture, useful for mirrors, UI, or exporting images
Shadow Biases Demonstrates how shadow biases affect shadows in a 3d scene
Shadow Caster and Receiver Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene
Spherical Area Lights Demonstrates how point light radius values affect light behavior
Split Screen Demonstrates how to render two cameras to the same window to accomplish "split screen"
Texture Shows configuration of texture materials
Transparency in 3D Demonstrates transparency in 3d
Two Passes Renders two 3d passes to the same window from different perspectives
Update glTF Scene Update a scene from a glTF file, either by spawning the scene as a child of another entity, or by accessing the entities of the scene
Vertex Colors Shows the use of vertex colors
Wireframe Showcases wireframe rendering

Animation

Example Description
Animated Fox Plays an animation from a skinned glTF
Animated Transform Create and play an animation defined by code that operates on the Transform component
Custom Skinned Mesh Skinned mesh example with mesh and joints data defined in code
glTF Skinned Mesh Skinned mesh example with mesh and joints data loaded from a glTF file

Application

Example Description
Custom Loop Demonstrates how to create a custom runner (to update an app manually)
Drag and Drop An example that shows how to handle drag and drop in an app
Empty An empty application (does nothing)
Empty with Defaults An empty application with default plugins
Headless An application that runs without default plugins
Headless with Defaults An application that runs with default plugins, but without an actual renderer
Logs Illustrate how to use generate log output
Plugin Demonstrates the creation and registration of a custom plugin
Plugin Group Demonstrates the creation and registration of a custom plugin group
Return after Run Show how to return to main after the Bevy app has exited
Thread Pool Resources Creates and customizes the internal thread pool
Without Winit Create an application without winit (runs single time, no event loop)

Assets

Example Description
Asset Loading Demonstrates various methods to load assets
Custom Asset Implements a custom asset loader
Custom Asset IO Implements a custom asset io loader
Hot Reloading of Assets Demonstrates automatic reloading of assets when modified on disk

Async Tasks

Example Description
Async Compute How to use AsyncComputeTaskPool to complete longer running tasks
External Source of Data on an External Thread How to use an external thread to run an infinite task and communicate with a channel

Audio

Example Description
Audio Shows how to load and play an audio file
Audio Control Shows how to load and play an audio file, and control how it's played

Diagnostics

Example Description
Custom Diagnostic Shows how to create a custom diagnostic
Log Diagnostics Add a plugin that logs diagnostics, like frames per second (FPS), to the console

ECS (Entity Component System)

Example Description
Component Change Detection Change detection on components
Custom Query Parameters Groups commonly used compound queries and query filters into a single type
ECS Guide Full guide to Bevy's ECS
Event Illustrates event creation, activation, and reception
Fixed Timestep Shows how to create systems that run every fixed timestep, rather than every tick
Generic System Shows how to create systems that can be reused with different types
Hierarchy Creates a hierarchy of parents and children entities
Iter Combinations Shows how to iterate over combinations of query results
Parallel Query Illustrates parallel queries with ParallelIterator
Removal Detection Query for entities that had a specific component removed in a previous stage during the current frame
Startup System Demonstrates a startup system (one that runs once when the app starts up)
State Illustrates how to use States to control transitioning from a Menu state to an InGame state
System Chaining Chain two systems together, specifying a return type in a system (such as Result)
System Closure Show how to use closures as systems, and how to configure Local variables by capturing external state
System Parameter Illustrates creating custom system parameters with SystemParam
System Sets Shows SystemSet use along with run criterion
Timers Illustrates ticking Timer resources inside systems and handling their state

Games

Example Description
Alien Cake Addict Eat the cakes. Eat them all. An example 3D game
Breakout An implementation of the classic game "Breakout"
Contributors Displays each contributor as a bouncy bevy-ball!
Game Menu A simple game menu

Input

Example Description
Char Input Events Prints out all chars as they are inputted
Gamepad Input Shows handling of gamepad input, connections, and disconnections
Gamepad Input Events Iterates and prints gamepad input and connection events
Keyboard Input Demonstrates handling a key press/release
Keyboard Input Events Prints out all keyboard events
Keyboard Modifiers Demonstrates using key modifiers (ctrl, shift)
Mouse Grab Demonstrates how to grab the mouse, locking the cursor to the app's screen
Mouse Input Demonstrates handling a mouse button press/release
Mouse Input Events Prints out all mouse events (buttons, movement, etc.)
Touch Input Displays touch presses, releases, and cancels
Touch Input Events Prints out all touch inputs

Reflection

Example Description
Generic Reflection Registers concrete instances of generic types that may be used with reflection
Reflection Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types
Reflection Types Illustrates the various reflection types available
Trait Reflection Allows reflection with trait objects

Scene

Example Description
Scene Demonstrates loading from and saving scenes to files

Shaders

These examples demonstrate how to implement different shaders in user code.

A shader in its most common usage is a small program that is run by the GPU per-vertex in a mesh (a vertex shader) or per-affected-screen-fragment (a fragment shader.) The GPU executes these programs in a highly parallel way.

There are also compute shaders which are used for more general processing leveraging the GPU's parallelism.

Example Description
Animated A shader that uses dynamic data like the time since startup
Array Texture A shader that shows how to reuse the core bevy PBR shading functionality in a custom material that obtains the base color from an array texture.
Compute - Game of Life A compute shader that simulates Conway's Game of Life
Custom Vertex Attribute A shader that reads a mesh's custom vertex attribute
Instancing A shader that renders a mesh multiple times in one draw call
Material A shader and a material that uses it
Material - GLSL A shader that uses the GLSL shading language
Material - Screenspace Texture A shader that samples a texture with view-independent UV coordinates
Post Processing A custom post processing effect, using two cameras, with one reusing the render texture of the first one
Shader Defs A shader that uses "shaders defs" (a bevy tool to selectively toggle parts of a shader)

Stress Tests

These examples are used to test the performance and stability of various parts of the engine in an isolated way.

Due to the focus on performance it's recommended to run the stress tests in release mode:

cargo run --release --example <example name>
Example Description
Bevymark A heavy sprite rendering workload to benchmark your system with Bevy
Many Cubes Simple benchmark to test per-entity draw overhead. Run with the sphere argument to test frustum culling
Many Foxes Loads an animated fox model and spawns lots of them. Good for testing skinned mesh performance. Takes an unsigned integer argument for the number of foxes to spawn. Defaults to 1000
Many Lights Simple benchmark to test rendering many point lights. Run with WGPU_SETTINGS_PRIO=webgl2 to restrict to uniform buffers and max 256 lights
Many Sprites Displays many sprites in a grid arragement! Used for performance testing
Transform Hierarchy Various test cases for hierarchy and transform propagation performance

Tools

Example Description
Scene Viewer A simple way to view glTF models with Bevy. Just run cargo run --release --example scene_viewer /path/to/model.gltf#Scene0, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory

Transforms

Example Description
3D Rotation Illustrates how to (constantly) rotate an object around an axis
Global / Local Translation Illustrates the difference between direction of a translation in respect to local object or global object Transform
Scale Illustrates how to scale an object in each direction
Transform Shows multiple transformations of objects
Translation Illustrates how to move an object along an axis

UI (User Interface)

Example Description
Button Illustrates creating and updating a button
Font Atlas Debug Illustrates how FontAtlases are populated (used to optimize text rendering internally)
Text Illustrates creating and updating text
Text Debug An example for debugging text layout
Transparency UI Demonstrates transparency for UI
UI Illustrates various features of Bevy UI

Window

Example Description
Clear Color Creates a solid color window
Low Power Demonstrates settings to reduce power use for bevy applications
Multiple Windows Demonstrates creating multiple windows, and rendering to them
Scale Factor Iverride Illustrates how to customize the default window settings
Transparent Window Illustrates making the window transparent and hiding the window decoration
Window Settings Demonstrates customizing default window settings

Tests

Example Description
How to Test Systems How to test systems with commands, queries or resources

Platform-Specific Examples

Android

Setup

rustup target add aarch64-linux-android armv7-linux-androideabi
cargo install cargo-apk

The Android SDK must be installed, and the environment variable ANDROID_SDK_ROOT set to the root Android sdk folder.

When using NDK (Side by side), the environment variable ANDROID_NDK_ROOT must also be set to one of the NDKs in sdk\ndk\[NDK number].

Build & Run

To run on a device setup for Android development, run:

cargo apk run --example android_example

When using Bevy as a library, the following fields must be added to Cargo.toml:

[package.metadata.android]
build_targets = ["aarch64-linux-android", "armv7-linux-androideabi"]

[package.metadata.android.sdk]
target_sdk_version = 31

Please reference cargo-apk README for other Android Manifest fields.

Debugging

You can view the logs with the following command:

adb logcat | grep 'RustStdoutStderr\|bevy\|wgpu'

In case of an error getting a GPU or setting it up, you can try settings logs of wgpu_hal to DEBUG to get more informations.

Sometimes, running the app complains about an unknown activity. This may be fixed by uninstalling the application:

adb uninstall org.bevyengine.example

Old phones

Bevy by default targets Android API level 31 in its examples which is the Play Store's minimum API to upload or update apps. Users of older phones may want to use an older API when testing.

To use a different API, the following fields must be updated in Cargo.toml:

[package.metadata.android.sdk]
target_sdk_version = >>API<<
min_sdk_version = >>API or less<<
Example File Description
android android/android.rs The 3d/3d_scene.rs example for Android

iOS

Setup

You need to install the correct rust targets:

  • aarch64-apple-ios: iOS devices
  • x86_64-apple-ios: iOS simulator on x86 processors
  • aarch64-apple-ios-sim: iOS simulator on Apple processors
rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim

Build & Run

Using bash:

cd examples/ios
make run

In an ideal world, this will boot up, install and run the app for the first iOS simulator in your xcrun simctl devices list. If this fails, you can specify the simulator device UUID via:

DEVICE_ID=${YOUR_DEVICE_ID} make run

If you'd like to see xcode do stuff, you can run

open bevy_ios_example.xcodeproj/

which will open xcode. You then must push the zoom zoom play button and wait for the magic.

Example File Description
ios ios/src/lib.rs The 3d/3d_scene.rs example for iOS

WASM

Setup

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

Build & Run

Following is an example for lighting. For other examples, change the lighting in the following commands.

cargo build --release --example lighting --target wasm32-unknown-unknown
wasm-bindgen --out-name wasm_example --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/lighting.wasm

The first command will build the example for the wasm target, creating a binary. Then, wasm-bindgen-cli is used to create javascript bindings to this wasm file, which can be loaded using this example HTML file.

Then serve examples/wasm directory to browser. i.e.

# cargo install basic-http-server
basic-http-server examples/wasm

# with python
python3 -m http.server --directory examples/wasm

# with ruby
ruby -run -ehttpd examples/wasm

Loading Assets

To load assets, they need to be available in the folder examples/wasm/assets. Cloning this repository will set it up as a symlink on Linux and macOS, but you will need to manually move the assets on Windows.