Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-25 22:20:20 +00:00
Code Issues Projects Releases Packages Wiki Activity
bevy/examples/README.md
James O'Brien ea42d14344
Dynamic queries and builder API (#9774) 
# Objective
Expand the existing `Query` API to support more dynamic use cases i.e.
scripting.

## Prior Art
 - #6390 
 - #8308 
- #10037

## Solution
- Create a `QueryBuilder` with runtime methods to define the set of
component accesses for a built query.
- Create new `WorldQueryData` implementations `FilteredEntityMut` and
`FilteredEntityRef` as variants of `EntityMut` and `EntityRef` that
provide run time checked access to the components included in a given
query.
- Add new methods to `Query` to create "query lens" with a subset of the
access of the initial query.

### Query Builder
The `QueryBuilder` API allows you to define a query at runtime. At it's
most basic use it will simply create a query with the corresponding type
signature:
```rust
let query = QueryBuilder::<Entity, With<A>>::new(&mut world).build();
// is equivalent to
let query = QueryState::<Entity, With<A>>::new(&mut world);
```
Before calling `.build()` you also have the opportunity to add
additional accesses and filters. Here is a simple example where we add
additional filter terms:
```rust
let entity_a = world.spawn((A(0), B(0))).id();
let entity_b = world.spawn((A(0), C(0))).id();

let mut query_a = QueryBuilder::<Entity>::new(&mut world)
    .with::<A>()
    .without::<C>()
    .build();
            
assert_eq!(entity_a, query_a.single(&world));
```
This alone is useful in that allows you to decide which archetypes your
query will match at runtime. However it is also very limited, consider a
case like the following:
```rust
let query_a = QueryBuilder::<&A>::new(&mut world)
// Add an additional access
    .data::<&B>()
    .build();
```
This will grant the query an additional read access to component B
however we have no way of accessing the data while iterating as the type
signature still only includes &A. For an even more concrete example of
this consider dynamic components:
```rust
let query_a = QueryBuilder::<Entity>::new(&mut world)
// Adding a filter is easy since it doesn't need be read later
    .with_id(component_id_a)
// How do I access the data of this component?
    .ref_id(component_id_b)
    .build();
```
With this in mind the `QueryBuilder` API seems somewhat incomplete by
itself, we need some way method of accessing the components dynamically.
So here's one:
### Query Transmutation
If the problem is not having the component in the type signature why not
just add it? This PR also adds transmute methods to `QueryBuilder` and
`QueryState`. Here's a simple example:
```rust
world.spawn(A(0));
world.spawn((A(1), B(0)));
let mut query = QueryBuilder::<()>::new(&mut world)
    .with::<B>()
    .transmute::<&A>()
    .build();

query.iter(&world).for_each(|a| assert_eq!(a.0, 1));
```
The `QueryState` and `QueryBuilder` transmute methods look quite similar
but are different in one respect. Transmuting a builder will always
succeed as it will just add the additional accesses needed for the new
terms if they weren't already included. Transmuting a `QueryState` will
panic in the case that the new type signature would give it access it
didn't already have, for example:
```rust
let query = QueryState::<&A, Option<&B>>::new(&mut world);
/// This is fine, the access for Option<&A> is less restrictive than &A
query.transmute::<Option<&A>>(&world);
/// Oh no, this would allow access to &B on entities that might not have it, so it panics
query.transmute::<&B>(&world);
/// This is right out
query.transmute::<&C>(&world);
```
This is quite an appealing API to also have available on `Query` however
it does pose one additional wrinkle: In order to to change the iterator
we need to create a new `QueryState` to back it. `Query` doesn't own
it's own state though, it just borrows it, so we need a place to borrow
it from. This is why `QueryLens` exists, it is a place to store the new
state so it can be borrowed when you call `.query()` leaving you with an
API like this:
```rust
fn function_that_takes_a_query(query: &Query<&A>) {
    // ...
}

fn system(query: Query<(&A, &B)>) {
    let lens = query.transmute_lens::<&A>();
    let q = lens.query();
    function_that_takes_a_query(&q);
}
```
Now you may be thinking: Hey, wait a second, you introduced the problem
with dynamic components and then described a solution that only works
for static components! Ok, you got me, I guess we need a bit more:
### Filtered Entity References
Currently the only way you can access dynamic components on entities
through a query is with either `EntityMut` or `EntityRef`, however these
can access all components and so conflict with all other accesses. This
PR introduces `FilteredEntityMut` and `FilteredEntityRef` as
alternatives that have additional runtime checking to prevent accessing
components that you shouldn't. This way you can build a query with a
`QueryBuilder` and actually access the components you asked for:
```rust
let mut query = QueryBuilder::<FilteredEntityRef>::new(&mut world)
    .ref_id(component_id_a)
    .with(component_id_b)
    .build();

let entity_ref = query.single(&world);

// Returns Some(Ptr) as we have that component and are allowed to read it
let a = entity_ref.get_by_id(component_id_a);
// Will return None even though the entity does have the component, as we are not allowed to read it
let b = entity_ref.get_by_id(component_id_b);
```
For the most part these new structs have the exact same methods as their
non-filtered equivalents.

Putting all of this together we can do some truly dynamic ECS queries,
check out the `dynamic` example to see it in action:
```
Commands:
    comp, c   Create new components
    spawn, s  Spawn entities
    query, q  Query for entities
Enter a command with no parameters for usage.

> c A, B, C, Data 4  
Component A created with id: 0
Component B created with id: 1
Component C created with id: 2
Component Data created with id: 3

> s A, B, Data 1
Entity spawned with id: 0v0

> s A, C, Data 0
Entity spawned with id: 1v0

> q &Data
0v0: Data: [1, 0, 0, 0]
1v0: Data: [0, 0, 0, 0]

> q B, &mut Data                                                                                     
0v0: Data: [2, 1, 1, 1]

> q B || C, &Data 
0v0: Data: [2, 1, 1, 1]
1v0: Data: [0, 0, 0, 0]
```
## Changelog
 - Add new `transmute_lens` methods to `Query`.
- Add new types `QueryBuilder`, `FilteredEntityMut`, `FilteredEntityRef`
and `QueryLens`
- `update_archetype_component_access` has been removed, archetype
component accesses are now determined by the accesses set in
`update_component_access`
- Added method `set_access` to `WorldQuery`, this is called before
`update_component_access` for queries that have a restricted set of
accesses, such as those built by `QueryBuilder` or `QueryLens`. This is
primarily used by the `FilteredEntity*` variants and has an empty trait
implementation.
- Added method `get_state` to `WorldQuery` as a fallible version of
`init_state` when you don't have `&mut World` access.

## Future Work
Improve performance of `FilteredEntityMut` and `FilteredEntityRef`,
currently they have to determine the accesses a query has in a given
archetype during iteration which is far from ideal, especially since we
already did the work when matching the archetype in the first place. To
avoid making more internal API changes I have left it out of this PR.

---------

Co-authored-by: Mike Hsu <mike.hsu@gmail.com>
2024-01-16 19:16:49 +00:00

35 KiB
Raw Blame History

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 Bloom Illustrates bloom post-processing in 2d
2D Gizmos A scene showcasing 2D gizmos
2D Rotation Demonstrates rotating entities in 2D with quaternions
2D Shapes Renders a rectangle, circle, and hexagon
2D Viewport To World Demonstrates how to use the Camera::viewport_to_world_2d method
Custom glTF vertex attribute 2D Renders a glTF mesh in 2D with a custom vertex attribute
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
Pixel Grid Snapping Shows how to create graphics that snap to the pixel grid by rendering to a texture in 2D
Sprite Renders a sprite
Sprite Flipping Renders a sprite flipped along an axis
Sprite Sheet Renders an animated sprite
Sprite Slice Showcases slicing sprites into sections that can be scaled independently via the 9-patch technique
Sprite Tile Renders a sprite tiled in a grid
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 Bloom Illustrates bloom configuration using HDR and emissive materials
3D Gizmos A scene showcasing 3D gizmos
3D Scene Simple 3D scene with basic shapes and lighting
3D Shapes A scene showcasing the built-in 3D shapes
3D Viewport To World Demonstrates how to use the Camera::viewport_to_world method
Anti-aliasing Compares different anti-aliasing methods
Atmospheric Fog A scene showcasing the atmospheric fog effect
Blend Modes Showcases different blend modes
Deferred Rendering Renders meshes with both forward and deferred pipelines
Deterministic rendering Stop flickering from z-fighting at a performance cost
Fog A scene showcasing the distance fog effect
Generate Custom Mesh Simple showcase of how to generate a custom mesh with a custom texture
Lighting Illustrates various lighting options in a simple scene
Lightmaps Rendering a scene with baked lightmaps
Lines Create a custom material to draw 3d lines
Load glTF Loads and renders a glTF file as a scene
Orthographic View Shows how to create a 3D orthographic view (for isometric-look in games or CAD applications)
Parallax Mapping Demonstrates use of a normal map and depth map for parallax mapping
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
Screen Space Ambient Occlusion A scene showcasing screen space ambient occlusion
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
Skybox Load a cubemap texture onto a cube like a skybox and cycle through different compressed texture formats.
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"
Spotlight Illustrates spot lights
Texture Shows configuration of texture materials
Tonemapping Compares tonemapping options
Transmission Showcases light transmission in the PBR material
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
Cubic Curve Bezier curve example showing a cube following a cubic curve
Custom Skinned Mesh Skinned mesh example with mesh and joints data defined in code
Morph Targets Plays an animation from a glTF file with meshes with morph targets
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
Log layers Illustrate how to add custom log layers
Logs Illustrate how to use generate log output
No Renderer An application that runs with default plugins and displays an empty window, but without an actual renderer
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 Decompression Demonstrates loading a compressed asset
Asset Loading Demonstrates various methods to load assets
Asset Processing Demonstrates how to process and load custom assets
Custom Asset Implements a custom asset loader
Custom Asset IO Implements a custom AssetReader
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
Decodable Shows how to create and register a custom audio source by implementing the Decodable type.
Pitch Shows how to directly play a simple pitch
Spatial Audio 2D Shows how to play spatial audio, and moving the emitter in 2D
Spatial Audio 3D Shows how to play spatial audio, and moving the emitter in 3D

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
Dynamic ECS Dynamically create components, spawn entities with those components and query those components
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
Nondeterministic System Order Systems run in parallel, but their order isn't always deterministic. Here's how to detect and fix this.
One Shot Systems Shows how to flexibly run systems without scheduling them
Parallel Query Illustrates parallel queries with ParallelIterator
Removal Detection Query for entities that had a specific component removed earlier in the current frame
Run Conditions Run systems only when one or multiple conditions are met
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 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 Piping Pipe the output of one system into a second, allowing you to handle any errors gracefully

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
Gamepad Rumble Shows how to rumble a gamepad using force feedback
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.)
Text Input Simple text input with IME support
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
Extended Material A custom shader that builds on the standard material
Instancing A shader that renders a mesh multiple times in one draw call
Material A shader and a material that uses it
Material A shader and a material that uses it on a 2d mesh
Material - GLSL A shader that uses the GLSL shading language
Material - Screenspace Texture A shader that samples a texture with view-independent UV coordinates
Material Prepass A shader that uses the various textures generated by the prepass
Post Processing - Custom Render Pass A custom post processing effect, using a custom render pass that runs after the main pass
Shader Defs A shader that uses "shaders defs" (a bevy tool to selectively toggle parts of a shader)
Texture Binding Array (Bindless Textures) A shader that shows how to bind and sample multiple textures as a binding array (a.k.a. bindless textures).

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 Animated Sprites Displays many animated sprites in a grid arrangement with slight offsets to their animation timers. Used for performance testing.
Many Buttons Test rendering of many UI elements
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 Gizmos Test rendering of many gizmos
Many Glyphs Simple benchmark to test text rendering.
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 arrangement! Used for performance testing. Use --colored to enable color tinted sprites.
Text Pipeline Text Pipeline benchmark
Transform Hierarchy Various test cases for hierarchy and transform propagation performance

Time

Example Description
Time handling Explains how Time is handled in ECS
Timers Illustrates ticking Timer resources inside systems and handling their state
Virtual time Shows how Time<Virtual> can be used to pause, resume, slow down and speed up a game.

Tools

Example Description
Gamepad Viewer Shows a visualization of gamepad buttons, sticks, and triggers
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
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
Borders Demonstrates how to create a node with a border
Button Illustrates creating and updating a button
CSS Grid An example for CSS Grid layout
Display and Visibility Demonstrates how Display and Visibility work in the UI.
Flex Layout Demonstrates how the AlignItems and JustifyContent properties can be composed to layout nodes and position text
Font Atlas Debug Illustrates how FontAtlases are populated (used to optimize text rendering internally)
Overflow Simple example demonstrating overflow behavior
Overflow and Clipping Debug An example to debug overflow and clipping behavior
Relative Cursor Position Showcases the RelativeCursorPosition component
Render UI to Texture An example of rendering UI as a part of a 3D world
Size Constraints Demonstrates how the to use the size constraints to control the size of a UI node.
Text Illustrates creating and updating text
Text Debug An example for debugging text layout
Text Wrap Debug Demonstrates text wrapping
Transparency UI Demonstrates transparency for UI
UI Illustrates various features of Bevy UI
UI Material Demonstrates creating and using custom Ui materials
UI Scaling Illustrates how to scale the UI
UI Texture Atlas Illustrates how to use TextureAtlases in UI
UI Z-Index Demonstrates how to control the relative depth (z-position) of UI elements
Viewport Debug An example for debugging viewport coordinates
Window Fallthrough Illustrates how to access winit::window::Window's hittest functionality.

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 Override Illustrates how to customize the default window settings
Screenshot Shows how to save screenshots to disk
Transparent Window Illustrates making the window transparent and hiding the window decoration
Window Resizing Demonstrates resizing and responding to resizing a window
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 -p bevy_mobile_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 information.

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 mobile/src/lib.rs A 3d Scene with a button and playing sound

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/mobile
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_mobile_example.xcodeproj/

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

Example File Description
ios mobile/src/lib.rs A 3d Scene with a button and playing sound

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 in the output file examples/wasm/target/wasm_example.js, 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

WebGL2 and WebGPU

Bevy support for WebGPU is being worked on, but is currently experimental.

To build for WebGPU, you'll need to disable default features and add all those you need, making sure to omit the webgl2 feature.

WebGPU depends on unstable APIs so you will also need to pass the web_sys_unstable_apis flag to your builds. For example:

RUSTFLAGS=--cfg=web_sys_unstable_apis cargo build ...

Check wasm-bindgen docs on Unstable APIs for more details.

Bevy has an helper to build its examples:

  • Build for WebGL2: cargo run -p build-wasm-example -- --api webgl2 load_gltf
  • Build for WebGPU: cargo run -p build-wasm-example -- --api webgpu load_gltf

This helper will log the command used to build the examples.

Audio in the browsers

For the moment, everything is single threaded, this can lead to stuttering when playing audio in browsers. Not all browsers react the same way for all games, you will have to experiment for your game.

In browsers, audio is not authorized to start without being triggered by an user interaction. This is to avoid multiple tabs all starting to auto play some sounds. You can find more context and explanation for this on Google Chrome blog. This page also describes a JS workaround to resume audio as soon as the user interact with your game.

Optimizing

On the web, it's useful to reduce the size of the files that are distributed. With rust, there are many ways to improve your executable sizes. Here are some.

1. Tweak your Cargo.toml

Add a new profile to your Cargo.toml:

[profile.wasm-release]
# Use release profile as default values
inherits = "release"

# Optimize with size in mind, also try "s", sometimes it is better.
# This doesn't increase compilation times compared to -O3, great improvements
opt-level = "z"

# Do a second optimization pass removing duplicate or unused code from dependencies.
# Slows compile times, marginal improvements
lto = "fat"

# When building crates, optimize larger chunks at a time
# Slows compile times, marginal improvements
codegen-units = 1

Now, when building the final executable, use the wasm-release profile by replacing --release by --profile wasm-release in the cargo command.

cargo build --profile wasm-release --example lighting --target wasm32-unknown-unknown

Make sure your final executable size is smaller, some of those optimizations may not be worth keeping, due to compilation time increases.

2. Use wasm-opt from the binaryen package

Binaryen is a set of tools for working with wasm. It has a wasm-opt CLI tool.

First download the binaryen package, then locate the .wasm file generated by wasm-bindgen. It should be in the --out-dir you specified in the command line, the file name should end in _bg.wasm.

Then run wasm-opt with the -Oz flag. Note that wasm-opt is very slow.

Note that wasm-opt optimizations might not be as effective if you didn't apply the optimizations from the previous section.

wasm-opt -Oz --output optimized.wasm examples/wasm/target/lighting_bg.wasm
mv optimized.wasm examples/wasm/target/lighting_bg.wasm

For a small project with a basic 3d model and two lights, the generated file sizes are, as of July 2022, as follows:

profile wasm-opt no wasm-opt
Default 8.5M 13.0M
opt-level = "z" 6.1M 12.7M
"z" + lto = "thin" 5.9M 12M
"z" + lto = "fat" 5.1M 9.4M
"z" + "thin" + codegen-units = 1 5.3M 11M
"z" + "fat" + codegen-units = 1 4.8M 8.5M

There are more advanced optimization options available, check the following pages for more info:

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.