Skip to content

Commit 267d6c8

Browse files
inodentryinodentry
committed
Update Cargo.toml and create new READMEs
1 parent 7ee373e commit 267d6c8

File tree

9 files changed

+1551
-1208
lines changed

9 files changed

+1551
-1208
lines changed

‎Cargo.toml

Lines changed: 704 additions & 420 deletions
Large diffs are not rendered by default.

‎examples/README.md

Lines changed: 26 additions & 787 deletions
Large diffs are not rendered by default.

‎examples/api/README.md

Lines changed: 478 additions & 0 deletions
Large diffs are not rendered by default.

‎examples/games/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Game Examples
2+
3+
See the [main examples README](../) for general information about Bevy's examples.
4+
5+
---
6+
7+
These examples demonstrate how to structure larger, more complete game projects in Bevy. Each example is a small, simple game, representing different genres.
8+
9+
Each example consists of multiple files, just like in a real project.
10+
11+
---
12+
13+
Example | Description
14+
--- | ---
15+
[Alien Cake Addict](./alien_cake_addict.rs) | Eat the cakes. Eat them all. An example 3D game.
16+
[Breakout](./breakout.rs) | An implementation of the classic game "Breakout".
17+
[Contributors](./contributors.rs) | Displays each contributor as a bouncy bevy-ball!
18+
[Desk Toy](./desk_toy.rs) | Bevy logo as a desk toy using transparent windows! Now with Googly Eyes!

‎examples/mobile/README.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Mobile Example
2+
3+
See the [main examples README](../) for general information about Bevy's examples.
4+
5+
---
6+
7+
This directory contains an example project structure when developing for Android and iOS.
8+
These platforms require special SDKs, toolchains, build configuration, etc.
9+
10+
Here we show you what you need to get started.
11+
12+
---
13+
14+
## Android
15+
16+
### Setup
17+
18+
```sh
19+
rustup target add aarch64-linux-android
20+
cargo install cargo-ndk
21+
```
22+
23+
The Android SDK must be installed, and the environment variable `ANDROID_SDK_ROOT` set to the root Android `sdk` folder.
24+
25+
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]`.
26+
27+
Alternatively, you can install Android Studio.
28+
29+
### Build & Run
30+
31+
To build an Android app, you first need to build shared object files for the target architecture with `cargo-ndk`:
32+
33+
```sh
34+
cargo ndk -t <target_name> -o <project_name>/app/src/main/jniLibs build
35+
```
36+
37+
For example, to compile to a 64-bit ARM platform:
38+
39+
```sh
40+
cargo ndk -t arm64-v8a -o android_example/app/src/main/jniLibs build
41+
```
42+
43+
Setting the output path ensures the shared object files can be found in target-specific directories under `jniLibs` where the JNI can find them.
44+
45+
See the `cargo-ndk` [README](https://crates.io/crates/cargo-ndk) for other options.
46+
47+
After this you can build it with `gradlew`:
48+
49+
```sh
50+
./gradlew build
51+
```
52+
53+
Or build it with Android Studio.
54+
55+
Then you can test it in your Android project.
56+
57+
#### About `libc++_shared.so`
58+
59+
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.
60+
61+
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).
62+
63+
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`).
64+
65+
### Debugging
66+
67+
You can view the logs with the following command:
68+
69+
```sh
70+
adb logcat | grep 'RustStdoutStderr\|bevy\|wgpu'
71+
```
72+
73+
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.
74+
75+
Sometimes, running the app complains about an unknown activity. This may be fixed by uninstalling the application:
76+
77+
```sh
78+
adb uninstall org.bevyengine.example
79+
```
80+
81+
### Old phones
82+
83+
In its examples, Bevy targets the minimum Android API that Play Store <!-- markdown-link-check-disable -->
84+
[requires](https://developer.android.com/distribute/best-practices/develop/target-sdk) to upload and update apps. <!-- markdown-link-check-enable -->
85+
Users of older phones may want to use an older API when testing. By default, Bevy uses [`GameActivity`](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`.
86+
87+
To use `NativeActivity`, you need to edit it in `cargo.toml` manually like this:
88+
89+
```toml
90+
bevy = { version = "0.14", default-features = false, features = ["android-native-activity", ...] }
91+
```
92+
93+
Then build it as the [Build & Run](#build--run) section stated above.
94+
95+
#### About `cargo-apk`
96+
97+
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.
98+
99+
## iOS
100+
101+
### Setup
102+
103+
You need to install the correct rust targets:
104+
105+
- `aarch64-apple-ios`: iOS devices
106+
- `x86_64-apple-ios`: iOS simulator on x86 processors
107+
- `aarch64-apple-ios-sim`: iOS simulator on Apple processors
108+
109+
```sh
110+
rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim
111+
```
112+
113+
### Build & Run
114+
115+
Using bash:
116+
117+
```sh
118+
cd examples/mobile
119+
make run
120+
```
121+
122+
In an ideal world, this will boot up, install and run the app for the first
123+
iOS simulator in your `xcrun simctl list devices`. If this fails, you can
124+
specify the simulator device UUID via:
125+
126+
```sh
127+
DEVICE_ID=${YOUR_DEVICE_ID} make run
128+
```
129+
130+
If you'd like to see xcode do stuff, you can run
131+
132+
```sh
133+
open bevy_mobile_example.xcodeproj/
134+
```
135+
136+
which will open xcode. You then must push the zoom zoom play button and wait
137+
for the magic.

‎examples/tools/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Tools
2+
3+
See the [main examples README](../) for general information about Bevy's examples.
4+
5+
---
6+
7+
Various tools useful when working with Bevy.
8+
9+
These "examples" are not necessarily intended for teaching how to use Bevy.
10+
11+
---
12+
13+
Example | Description
14+
--- | ---
15+
[Gamepad Viewer](./gamepad_viewer.rs) | Shows a visualization of gamepad buttons, sticks, and triggers
16+
[Scene Viewer](./scene_viewer/main.rs) | 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.

‎examples/usage/README.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Usage Examples
2+
3+
See the [main examples README](../) for general information about Bevy's examples.
4+
5+
---
6+
7+
These examples demonstrate how to accomplish common game development tasks in Bevy.
8+
9+
---
10+
11+
The examples are grouped into categories for easier navigation:
12+
13+
- [Camera](#camera)
14+
- [Control Flow](#control-flow)
15+
- [Movement](#movement)
16+
17+
---
18+
19+
## Camera
20+
21+
Example | Description
22+
--- | ---
23+
[2D top-down camera](./camera/2d_top_down_camera.rs) | A 2D top-down camera smoothly following player movements
24+
[2D Screen Shake](./camera/2d_screen_shake.rs) | A simple 2D screen shake effect
25+
[3D Camera Orbit](./camera/camera_orbit.rs) | Shows how to orbit a static scene using pitch, yaw, and roll.
26+
[First person view model](./camera/first_person_view_model.rs) | A first-person camera that uses a world model and a view model with different field of views (FOV)
27+
[Split Screen](./camera/split_screen.rs) | Demonstrates how to render two cameras to the same window to accomplish "split screen"
28+
29+
## Control Flow
30+
31+
Example | Description
32+
--- | ---
33+
[Game Menu](./control_flow/game_menu.rs) | A simple "main menu"
34+
[Loading Screen](./control_flow/loading_screen.rs) | Demonstrates how to create a loading screen that waits for all assets to be loaded and render pipelines to be compiled.
35+
36+
## Movement
37+
38+
Example | Description
39+
--- | ---
40+
[Run physics in a fixed timestep](../examples/movement/physics_in_fixed_timestep.rs) | Handles input, physics, and rendering in an industry-standard way by using a fixed timestep.
41+
[Smooth Follow](../examples/movement/smooth_follow.rs) | Demonstrates how to make an entity smoothly follow another using interpolation

‎examples/wasm/README.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# WASM Supporting Files
2+
3+
See the [main examples README](../) for general information about Bevy's examples.
4+
5+
---
6+
7+
This folder contains the minimal extra files you need to run Bevy in a web browser.
8+
9+
Most of our [rich collection of examples](../) can be run on the Web, but some
10+
special configuration and build steps are needed.
11+
12+
---
13+
14+
## Setup
15+
16+
```sh
17+
rustup target add wasm32-unknown-unknown
18+
cargo install wasm-bindgen-cli
19+
```
20+
21+
## Build & Run
22+
23+
Following is an example for `lighting`. For other examples, change the `lighting` in the
24+
following commands.
25+
26+
```sh
27+
cargo build --release --example lighting --target wasm32-unknown-unknown
28+
wasm-bindgen --out-name wasm_example \
29+
--out-dir examples/wasm/target \
30+
--target web target/wasm32-unknown-unknown/release/examples/lighting.wasm
31+
```
32+
33+
The first command will build the example for the wasm target, creating a binary. Then,
34+
[wasm-bindgen-cli](https://rustwasm.github.io/wasm-bindgen/reference/cli.html) is used to create
35+
javascript bindings to this wasm file in the output file `examples/wasm/target/wasm_example.js`, which can be loaded using this
36+
[example HTML file](./index.html).
37+
38+
Then serve `examples/wasm` directory to browser. i.e.
39+
40+
```sh
41+
# cargo install basic-http-server
42+
basic-http-server examples/wasm
43+
44+
# with python
45+
python3 -m http.server --directory examples/wasm
46+
47+
# with ruby
48+
ruby -run -ehttpd examples/wasm
49+
```
50+
51+
### WebGL2 and WebGPU
52+
53+
Bevy support for WebGPU is being worked on, but is currently experimental.
54+
55+
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.
56+
57+
Bevy has a helper to build its examples:
58+
59+
- Build for WebGL2: `cargo run -p build-wasm-example -- --api webgl2 load_gltf`
60+
- Build for WebGPU: `cargo run -p build-wasm-example -- --api webgpu load_gltf`
61+
62+
This helper will log the command used to build the examples.
63+
64+
## Audio in the browsers
65+
66+
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.
67+
68+
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.
69+
70+
## Optimizing
71+
72+
On the web, it's useful to reduce the size of the files that are distributed.
73+
With rust, there are many ways to improve your executable sizes, starting with
74+
the steps described in [the quick-start guide](https://bevyengine.org/learn/quick-start/getting-started/setup/#compile-with-performance-optimizations).
75+
76+
Now, when building the executable, use `--profile wasm-release` instead of `--release`:
77+
78+
```sh
79+
cargo build --profile wasm-release --example lighting --target wasm32-unknown-unknown
80+
```
81+
82+
To apply `wasm-opt`, first locate the `.wasm` file generated in the `--out-dir` of the
83+
earlier `wasm-bindgen-cli` command (the filename should end with `_bg.wasm`), then run:
84+
85+
```sh
86+
wasm-opt -Oz --output optimized.wasm examples/wasm/target/lighting_bg.wasm
87+
mv optimized.wasm examples/wasm/target/lighting_bg.wasm
88+
```
89+
90+
Make sure your final executable size is actually smaller. Some optimizations
91+
may not be worth keeping due to compilation time increases.
92+
93+
For a small project with a basic 3d model and two lights,
94+
the generated file sizes are, as of July 2022, as follows:
95+
96+
profile | wasm-opt | no wasm-opt
97+
----------------------------------|----------|-------------
98+
Default | 8.5M | 13.0M
99+
opt-level = "z" | 6.1M | 12.7M
100+
"z" + lto = "thin" | 5.9M | 12M
101+
"z" + lto = "fat" | 5.1M | 9.4M
102+
"z" + "thin" + codegen-units = 1 | 5.3M | 11M
103+
"z" + "fat" + codegen-units = 1 | 4.8M | 8.5M
104+
105+
## Loading Assets
106+
107+
To load assets, they need to be available in the folder examples/wasm/assets. Cloning this
108+
repository will set it up as a symlink on Linux and macOS, but you will need to manually move
109+
the assets on Windows.

‎stress-tests/README.md

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Stress tests
1+
# Stress Tests
22

33
These examples are used to stress test Bevy's performance in various ways. These
44
should be run with the "stress-test" profile to accurately represent performance
@@ -10,3 +10,24 @@ very slow.
1010
```bash
1111
cargo run --profile stress-test --example <EXAMPLE>
1212
```
13+
14+
---
15+
16+
Example | Description
17+
--- | ---
18+
[Bevymark](./bevymark.rs) | A heavy sprite rendering workload to benchmark your system with Bevy
19+
[Many Animated Materials](./many_materials.rs) | Benchmark to test rendering many animated materials
20+
[Many Animated Sprites](./many_animated_sprites.rs) | Displays many animated sprites in a grid arrangement with slight offsets to their animation timers. Used for performance testing.
21+
[Many Buttons](./many_buttons.rs) | Test rendering of many UI elements
22+
[Many Cameras & Lights](./many_cameras_lights.rs) | Test rendering of many cameras and lights
23+
[Many Components (and Entities and Systems)](./many_components.rs) | Test large ECS systems
24+
[Many Cubes](./many_cubes.rs) | Simple benchmark to test per-entity draw overhead. Run with the `sphere` argument to test frustum culling
25+
[Many Foxes](./many_foxes.rs) | 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
26+
[Many Gizmos](./many_gizmos.rs) | Test rendering of many gizmos
27+
[Many Glyphs](./many_glyphs.rs) | Simple benchmark to test text rendering.
28+
[Many Lights](./many_lights.rs) | Simple benchmark to test rendering many point lights. Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights
29+
[Many Sprites](./many_sprites.rs) | Displays many sprites in a grid arrangement! Used for performance testing. Use `--colored` to enable color tinted sprites.
30+
[Many Text2d](./many_text2d.rs) | Displays many Text2d! Used for performance testing.
31+
[Text Pipeline](./text_pipeline.rs) | Text Pipeline benchmark
32+
[Transform Hierarchy](./transform_hierarchy.rs) | Various test cases for hierarchy and transform propagation performance
33+

0 commit comments

Comments
 (0)