2022-06-25 20:23:24 +00:00
<!-- MD024 - The Headers from the Platform-Specific Examples should be identical -->
2023-04-17 16:13:24 +00:00
<!-- Use 'cargo run -p build-templated-pages -- build-example-page' to generate the final example README.md -->
2022-06-25 20:23:24 +00:00
<!-- markdownlint-disable-file MD024 -->
# 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.
```sh
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](https://crates.io/crates/bevy) 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!
- Latest release: [https://github.com/bevyengine/bevy/tree/latest/examples](https://github.com/bevyengine/bevy/tree/latest/examples)
- Specific version, such as `0.4`: [https://github.com/bevyengine/bevy/tree/v0.4.0/examples](https://github.com/bevyengine/bevy/tree/v0.4.0/examples)
When you clone the repo locally to run the examples, use `git checkout` to get the correct version:
```bash
# `latest` always points to the newest release
git checkout latest
# or use a specific version
git checkout v0.4.0
```
---
## Table of Contents
- [Examples](#examples)
- [Table of Contents](#table-of-contents)
- [The Bare Minimum](#the-bare-minimum)
- [Hello, World!](#hello-world)
- [Cross-Platform Examples](#cross-platform-examples)
{ % for category , _ in all_examples % } - [ { { category } } ](# { { category | slugify } } )
{ % endfor % }
- [Tests](#tests)
- [Platform-Specific Examples](#platform-specific-examples)
- [Android](#android)
- [Setup](#setup)
- [Build & Run](#build--run)
2024-10-01 22:23:48 +00:00
- [About `libc++_shared.so`](#about-libc_sharedso)
2022-06-25 20:23:24 +00:00
- [Old phones](#old-phones)
2024-10-01 22:23:48 +00:00
- [About `cargo-apk`](#about-cargo-apk)
2022-06-25 20:23:24 +00:00
- [iOS](#ios)
- [Setup](#setup-1)
- [Build & Run](#build--run-1)
2024-07-31 21:16:05 +00:00
- [Wasm](#wasm)
2022-06-25 20:23:24 +00:00
- [Setup](#setup-2)
- [Build & Run](#build--run-2)
2023-05-17 23:54:35 +00:00
- [WebGL2 and WebGPU](#webgl2-and-webgpu)
- [Audio in the browsers](#audio-in-the-browsers)
- [Optimizing](#optimizing)
2022-06-25 20:23:24 +00:00
- [Loading Assets](#loading-assets)
# The Bare Minimum
<!-- MD026 - Hello, World! looks better with the ! -->
<!-- markdownlint-disable-next-line MD026 -->
## Hello, World!
Example | Description
--- | ---
[`hello_world.rs`](./hello_world.rs) | Runs a minimal example that outputs "hello world"
# Cross-Platform Examples
{ % for category , details in all_examples % }
## { { category } }
{ % if details . description is string % } { { details . description } }
{ % endif % } Example | Description
--- | ---
{ % for example in details . examples % } [ { { example . name } } ](../ { { example . path } } ) | { { example . description } }
{ % endfor % } { % endfor % }
# Tests
Example | Description
--- | ---
[How to Test Systems](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources
# Platform-Specific Examples
## Android
### Setup
```sh
2024-10-01 22:23:48 +00:00
rustup target add aarch64-linux-android
cargo install cargo-ndk
2022-06-25 20:23:24 +00:00
```
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]`.
2024-10-01 22:23:48 +00:00
Alternatively, you can install Android Studio.
2022-06-25 20:23:24 +00:00
### Build & Run
2024-10-01 22:23:48 +00:00
To build an Android app, you first need to build shared object files for the target architecture with `cargo-ndk`:
2022-06-25 20:23:24 +00:00
```sh
2024-10-04 19:20:25 +00:00
cargo ndk -t <target_name> -o <project_name>/app/src/main/jniLibs build
2022-06-25 20:23:24 +00:00
```
2024-10-01 22:23:48 +00:00
For example, to compile to a 64-bit ARM platform:
2022-06-25 20:23:24 +00:00
2024-10-01 22:23:48 +00:00
```sh
2024-10-04 19:20:25 +00:00
cargo ndk -t arm64-v8a -o android_example/app/src/main/jniLibs build
2024-10-01 22:23:48 +00:00
```
2022-06-30 19:42:45 +00:00
2024-10-01 22:23:48 +00:00
Setting the output path ensures the shared object files can be found in target-specific directories under `jniLibs` where the JNI can find them.
See the `cargo-ndk` [README](https://crates.io/crates/cargo-ndk) for other options.
After this you can build it with `gradlew`:
```sh
./gradlew build
2022-06-25 20:23:24 +00:00
```
2024-10-01 22:23:48 +00:00
Or build it with Android Studio.
Then you can test it in your Android project.
#### About `libc++_shared.so`
Bevy may require `libc++_shared.so` to run on Android, as it is needed by the `oboe` crate, but typically `cargo-ndk` does not copy this file automatically.
To include it, you can manually obtain it from NDK source or use a `build.rs` script for automation, as described in the `cargo-ndk` [README](https://github.com/bbqsrc/cargo-ndk?tab=readme-ov-file#linking-against-and-copying-libc_sharedso-into-the-relevant-places-in-the-output-directory).
Alternatively, you can modify project files to include it when building an APK. To understand the specific steps taken in this project, please refer to the comments within the project files for detailed instructions(`app/CMakeList.txt`, `app/build.gradle`, `app/src/main/cpp/dummy.cpp`).
2022-06-25 20:23:24 +00:00
2022-06-30 19:42:45 +00:00
### Debugging
You can view the logs with the following command:
```sh
adb logcat | grep 'RustStdoutStderr\|bevy\|wgpu'
```
2023-01-27 12:12:53 +00:00
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.
2022-06-30 19:42:45 +00:00
Sometimes, running the app complains about an unknown activity. This may be fixed by uninstalling the application:
```sh
adb uninstall org.bevyengine.example
```
2022-06-25 20:23:24 +00:00
### Old phones
2024-10-01 22:23:48 +00:00
In its examples, Bevy targets the minimum Android API that Play Store <!-- markdown-link-check-disable -->
[requires](https://developer.android.com/distribute/best-practices/develop/target-sdk) to upload and update apps. <!-- markdown-link-check-enable -->
Users of older phones may want to use an older API when testing. By default, Bevy uses [`GameAvtivity`](https://developer.android.com/games/agdk/game-activity), which only works for Android API level 31 and higher, so if you want to use older API, you need to switch to `NativeActivity`.
2022-06-25 20:23:24 +00:00
2024-10-01 22:23:48 +00:00
To use `NativeActivity`, you need to edit it in `cargo.toml` manually like this:
2022-06-25 20:23:24 +00:00
```toml
2024-10-01 22:23:48 +00:00
bevy = { version = "0.14" , default - features = false , features = [ "android-native-activity" , . . . ] }
2022-06-25 20:23:24 +00:00
```
2024-10-01 22:23:48 +00:00
Then build it as the [Build & Run](#build--run) section stated above.
#### About `cargo-apk`
You can also build an APK with `cargo-apk`, a simpler and deprecated tool which doesn't support `GameActivity`. If you want to use this, there is a [folder](./mobile/android_basic) inside the mobile example with instructions.
2022-06-25 20:23:24 +00:00
Example | File | Description
--- | --- | ---
2023-02-06 18:08:49 +00:00
`android` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound
2022-06-25 20:23:24 +00:00
## 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
```sh
rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim
```
### Build & Run
Using bash:
```sh
2023-02-06 18:08:49 +00:00
cd examples/mobile
2022-06-25 20:23:24 +00:00
make run
```
In an ideal world, this will boot up, install and run the app for the first
2024-02-26 04:59:19 +00:00
iOS simulator in your `xcrun simctl list devices`. If this fails, you can
2022-06-25 20:23:24 +00:00
specify the simulator device UUID via:
```sh
DEVICE_ID=$ { YOUR_DEVICE_ID } make run
```
If you'd like to see xcode do stuff, you can run
```sh
2023-02-06 18:08:49 +00:00
open bevy_mobile_example.xcodeproj/
2022-06-25 20:23:24 +00:00
```
which will open xcode. You then must push the zoom zoom play button and wait
for the magic.
Example | File | Description
--- | --- | ---
2023-02-06 18:08:49 +00:00
`ios` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound
2022-06-25 20:23:24 +00:00
2024-07-31 21:16:05 +00:00
## Wasm
2022-06-25 20:23:24 +00:00
### Setup
```sh
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.
```sh
2023-08-12 21:05:36 +00:00
cargo build --release --example lighting --target wasm32-unknown-unknown
2022-07-25 15:48:13 +00:00
wasm-bindgen --out-name wasm_example \
--out-dir examples/wasm/target \
--target web target/wasm32-unknown-unknown/release/examples/lighting.wasm
2022-06-25 20:23:24 +00:00
```
The first command will build the example for the wasm target, creating a binary. Then,
[wasm-bindgen-cli](https://rustwasm.github.io/wasm-bindgen/reference/cli.html) is used to create
2023-08-12 21:05:36 +00:00
javascript bindings to this wasm file in the output file `examples/wasm/target/wasm_example.js`, which can be loaded using this
2022-06-25 20:23:24 +00:00
[example HTML file](./wasm/index.html).
Then serve `examples/wasm` directory to browser. i.e.
```sh
# 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
```
Webgpu support (#8336)
# Objective
- Support WebGPU
- alternative to #5027 that doesn't need any async / await
- fixes #8315
- Surprise fix #7318
## Solution
### For async renderer initialisation
- Update the plugin lifecycle:
- app builds the plugin
- calls `plugin.build`
- registers the plugin
- app starts the event loop
- event loop waits for `ready` of all registered plugins in the same
order
- returns `true` by default
- then call all `finish` then all `cleanup` in the same order as
registered
- then execute the schedule
In the case of the renderer, to avoid anything async:
- building the renderer plugin creates a detached task that will send
back the initialised renderer through a mutex in a resource
- `ready` will wait for the renderer to be present in the resource
- `finish` will take that renderer and place it in the expected
resources by other plugins
- other plugins (that expect the renderer to be available) `finish` are
called and they are able to set up their pipelines
- `cleanup` is called, only custom one is still for pipeline rendering
### For WebGPU support
- update the `build-wasm-example` script to support passing `--api
webgpu` that will build the example with WebGPU support
- feature for webgl2 was always enabled when building for wasm. it's now
in the default feature list and enabled on all platforms, so check for
this feature must also check that the target_arch is `wasm32`
---
## Migration Guide
- `Plugin::setup` has been renamed `Plugin::cleanup`
- `Plugin::finish` has been added, and plugins adding pipelines should
do it in this function instead of `Plugin::build`
```rust
// Before
impl Plugin for MyPlugin {
fn build(&self, app: &mut App) {
app.insert_resource::<MyResource>
.add_systems(Update, my_system);
let render_app = match app.get_sub_app_mut(RenderApp) {
Ok(render_app) => render_app,
Err(_) => return,
};
render_app
.init_resource::<RenderResourceNeedingDevice>()
.init_resource::<OtherRenderResource>();
}
}
// After
impl Plugin for MyPlugin {
fn build(&self, app: &mut App) {
app.insert_resource::<MyResource>
.add_systems(Update, my_system);
let render_app = match app.get_sub_app_mut(RenderApp) {
Ok(render_app) => render_app,
Err(_) => return,
};
render_app
.init_resource::<OtherRenderResource>();
}
fn finish(&self, app: &mut App) {
let render_app = match app.get_sub_app_mut(RenderApp) {
Ok(render_app) => render_app,
Err(_) => return,
};
render_app
.init_resource::<RenderResourceNeedingDevice>();
}
}
```
2023-05-04 22:07:57 +00:00
#### WebGL2 and WebGPU
Bevy support for WebGPU is being worked on, but is currently experimental.
Update to wgpu 0.19 and raw-window-handle 0.6 (#11280)
# Objective
Keep core dependencies up to date.
## Solution
Update the dependencies.
wgpu 0.19 only supports raw-window-handle (rwh) 0.6, so bumping that was
included in this.
The rwh 0.6 version bump is just the simplest way of doing it. There
might be a way we can take advantage of wgpu's new safe surface creation
api, but I'm not familiar enough with bevy's window management to
untangle it and my attempt ended up being a mess of lifetimes and rustc
complaining about missing trait impls (that were implemented). Thanks to
@MiniaczQ for the (much simpler) rwh 0.6 version bump code.
Unblocks https://github.com/bevyengine/bevy/pull/9172 and
https://github.com/bevyengine/bevy/pull/10812
~~This might be blocked on cpal and oboe updating their ndk versions to
0.8, as they both currently target ndk 0.7 which uses rwh 0.5.2~~ Tested
on android, and everything seems to work correctly (audio properly stops
when minimized, and plays when re-focusing the app).
---
## Changelog
- `wgpu` has been updated to 0.19! The long awaited arcanization has
been merged (for more info, see
https://gfx-rs.github.io/2023/11/24/arcanization.html), and Vulkan
should now be working again on Intel GPUs.
- Targeting WebGPU now requires that you add the new `webgpu` feature
(setting the `RUSTFLAGS` environment variable to
`--cfg=web_sys_unstable_apis` is still required). This feature currently
overrides the `webgl2` feature if you have both enabled (the `webgl2`
feature is enabled by default), so it is not recommended to add it as a
default feature to libraries without putting it behind a flag that
allows library users to opt out of it! In the future we plan on
supporting wasm binaries that can target both webgl2 and webgpu now that
wgpu added support for doing so (see
https://github.com/bevyengine/bevy/issues/11505).
- `raw-window-handle` has been updated to version 0.6.
## Migration Guide
- `bevy_render::instance_index::get_instance_index()` has been removed
as the webgl2 workaround is no longer required as it was fixed upstream
in wgpu. The `BASE_INSTANCE_WORKAROUND` shaderdef has also been removed.
- WebGPU now requires the new `webgpu` feature to be enabled. The
`webgpu` feature currently overrides the `webgl2` feature so you no
longer need to disable all default features and re-add them all when
targeting `webgpu`, but binaries built with both the `webgpu` and
`webgl2` features will only target the webgpu backend, and will only
work on browsers that support WebGPU.
- Places where you conditionally compiled things for webgl2 need to be
updated because of this change, eg:
- `#[cfg(any(not(feature = "webgl"), not(target_arch = "wasm32")))]`
becomes `#[cfg(any(not(feature = "webgl") ,not(target_arch = "wasm32"),
feature = "webgpu"))]`
- `#[cfg(all(feature = "webgl", target_arch = "wasm32"))]` becomes
`#[cfg(all(feature = "webgl", target_arch = "wasm32", not(feature =
"webgpu")))]`
- `if cfg!(all(feature = "webgl", target_arch = "wasm32"))` becomes `if
cfg!(all(feature = "webgl", target_arch = "wasm32", not(feature =
"webgpu")))`
- `create_texture_with_data` now also takes a `TextureDataOrder`. You
can probably just set this to `TextureDataOrder::default()`
- `TextureFormat`'s `block_size` has been renamed to `block_copy_size`
- See the `wgpu` changelog for anything I might've missed:
https://github.com/gfx-rs/wgpu/blob/trunk/CHANGELOG.md
---------
Co-authored-by: François <mockersf@gmail.com>
2024-01-26 18:14:21 +00:00
To build for WebGPU, you'll need to enable the `webgpu` feature. This will override the `webgl2` feature, and builds with the `webgpu` feature enabled won't be able to run on browsers that don't support WebGPU.
2023-10-18 17:30:44 +00:00
Webgpu support (#8336)
# Objective
- Support WebGPU
- alternative to #5027 that doesn't need any async / await
- fixes #8315
- Surprise fix #7318
## Solution
### For async renderer initialisation
- Update the plugin lifecycle:
- app builds the plugin
- calls `plugin.build`
- registers the plugin
- app starts the event loop
- event loop waits for `ready` of all registered plugins in the same
order
- returns `true` by default
- then call all `finish` then all `cleanup` in the same order as
registered
- then execute the schedule
In the case of the renderer, to avoid anything async:
- building the renderer plugin creates a detached task that will send
back the initialised renderer through a mutex in a resource
- `ready` will wait for the renderer to be present in the resource
- `finish` will take that renderer and place it in the expected
resources by other plugins
- other plugins (that expect the renderer to be available) `finish` are
called and they are able to set up their pipelines
- `cleanup` is called, only custom one is still for pipeline rendering
### For WebGPU support
- update the `build-wasm-example` script to support passing `--api
webgpu` that will build the example with WebGPU support
- feature for webgl2 was always enabled when building for wasm. it's now
in the default feature list and enabled on all platforms, so check for
this feature must also check that the target_arch is `wasm32`
---
## Migration Guide
- `Plugin::setup` has been renamed `Plugin::cleanup`
- `Plugin::finish` has been added, and plugins adding pipelines should
do it in this function instead of `Plugin::build`
```rust
// Before
impl Plugin for MyPlugin {
fn build(&self, app: &mut App) {
app.insert_resource::<MyResource>
.add_systems(Update, my_system);
let render_app = match app.get_sub_app_mut(RenderApp) {
Ok(render_app) => render_app,
Err(_) => return,
};
render_app
.init_resource::<RenderResourceNeedingDevice>()
.init_resource::<OtherRenderResource>();
}
}
// After
impl Plugin for MyPlugin {
fn build(&self, app: &mut App) {
app.insert_resource::<MyResource>
.add_systems(Update, my_system);
let render_app = match app.get_sub_app_mut(RenderApp) {
Ok(render_app) => render_app,
Err(_) => return,
};
render_app
.init_resource::<OtherRenderResource>();
}
fn finish(&self, app: &mut App) {
let render_app = match app.get_sub_app_mut(RenderApp) {
Ok(render_app) => render_app,
Err(_) => return,
};
render_app
.init_resource::<RenderResourceNeedingDevice>();
}
}
```
2023-05-04 22:07:57 +00:00
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.
2023-05-17 23:54:35 +00:00
### 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](https://developer.chrome.com/blog/web-audio-autoplay/). This page also describes a JS workaround to resume audio as soon as the user interact with your game.
2022-07-25 15:48:13 +00:00
### Optimizing
On the web, it's useful to reduce the size of the files that are distributed.
2024-07-06 15:38:29 +00:00
With rust, there are many ways to improve your executable sizes, starting with
the steps described in [the quick-start guide](https://bevyengine.org/learn/quick-start/getting-started/setup/#compile-with-performance-optimizations).
2022-07-25 15:48:13 +00:00
2024-07-06 15:38:29 +00:00
Now, when building the executable, use `--profile wasm-release` instead of `--release`:
2022-07-25 15:48:13 +00:00
```sh
cargo build --profile wasm-release --example lighting --target wasm32-unknown-unknown
```
2024-07-06 15:38:29 +00:00
To apply `wasm-opt`, first locate the `.wasm` file generated in the `--out-dir` of the
earlier `wasm-bindgen-cli` command (the filename should end with `_bg.wasm`), then run:
2022-07-25 15:48:13 +00:00
```sh
wasm-opt -Oz --output optimized.wasm examples/wasm/target/lighting_bg.wasm
mv optimized.wasm examples/wasm/target/lighting_bg.wasm
```
2024-07-06 15:38:29 +00:00
Make sure your final executable size is actually smaller. Some optimizations
may not be worth keeping due to compilation time increases.
2022-07-25 15:48:13 +00:00
For a small project with a basic 3d model and two lights,
2023-09-26 19:46:24 +00:00
the generated file sizes are, as of July 2022, as follows:
2022-07-25 15:48:13 +00:00
|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 |
2022-06-25 20:23:24 +00:00
### 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.
