diff --git a/docs-template/EXAMPLE_README.md.tpl b/docs-template/EXAMPLE_README.md.tpl index dfd516303b2dd..e1300061978b9 100644 --- a/docs-template/EXAMPLE_README.md.tpl +++ b/docs-template/EXAMPLE_README.md.tpl @@ -59,37 +59,37 @@ git checkout v0.4.0 - [Optimizing](#optimizing) - [Loading Assets](#loading-assets) -# The Bare Minimum +## The Bare Minimum -## Hello, World! +### Hello, World! Example | Description --- | --- [`hello_world.rs`](./hello_world.rs) | Runs a minimal example that outputs "hello world" -# Cross-Platform Examples +## Cross-Platform Examples {% for category, details in all_examples %} -## {{ category }} +### {{ 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 +## Tests Example | Description --- | --- [How to Test Apps](../tests/how_to_test_apps.rs) | How to test apps (simple integration testing) [How to Test Systems](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources -# Platform-Specific Examples +## Platform-Specific Examples -## Android +### Android -### Setup +#### Setup ```sh rustup target add aarch64-linux-android @@ -102,7 +102,7 @@ When using `NDK (Side by side)`, the environment variable `ANDROID_NDK_ROOT` mus Alternatively, you can install Android Studio. -### Build & Run +#### Build & Run To build an Android app, you first need to build shared object files for the target architecture with `cargo-ndk`: @@ -130,7 +130,7 @@ Or build it with Android Studio. Then you can test it in your Android project. -#### About `libc++_shared.so` +##### 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. @@ -138,7 +138,7 @@ To include it, you can manually obtain it from NDK source or use a `build.rs` sc 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`). -### Debugging +#### Debugging You can view the logs with the following command: @@ -154,7 +154,7 @@ Sometimes, running the app complains about an unknown activity. This may be fixe adb uninstall org.bevyengine.example ``` -### Old phones +#### Old phones In its examples, Bevy targets the minimum Android API that Play Store [requires](https://developer.android.com/distribute/best-practices/develop/target-sdk) to upload and update apps. @@ -168,7 +168,7 @@ bevy = { version = "0.14", default-features = false, features = ["android-native Then build it as the [Build & Run](#build--run) section stated above. -#### About `cargo-apk` +##### 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. @@ -176,9 +176,9 @@ Example | File | Description --- | --- | --- `android` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound -## iOS +### iOS -### Setup +#### Setup You need to install the correct rust targets: @@ -190,7 +190,7 @@ You need to install the correct rust targets: rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim ``` -### Build & Run +#### Build & Run Using bash: @@ -220,16 +220,16 @@ Example | File | Description --- | --- | --- `ios` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound -## Wasm +### Wasm -### Setup +#### Setup ```sh rustup target add wasm32-unknown-unknown cargo install wasm-bindgen-cli ``` -### Build & Run +#### Build & Run Following is an example for `lighting`. For other examples, change the `lighting` in the following commands. @@ -249,17 +249,17 @@ javascript bindings to this wasm file in the output file `examples/wasm/target/w Then serve `examples/wasm` directory to browser. i.e. ```sh -# cargo install basic-http-server +## cargo install basic-http-server basic-http-server examples/wasm -# with python +## with python python3 -m http.server --directory examples/wasm -# with ruby +## with ruby ruby -run -ehttpd examples/wasm ``` -#### WebGL2 and WebGPU +##### WebGL2 and WebGPU Bevy support for WebGPU is being worked on, but is currently experimental. @@ -273,13 +273,13 @@ Bevy has a helper to build its examples: This helper will log the command used to build the examples. -### Audio in the browsers +#### 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. -### Optimizing +#### 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, starting with @@ -314,7 +314,7 @@ opt-level = "z" | 6.1M | 12.7M "z" + "thin" + codegen-units = 1 | 5.3M | 11M "z" + "fat" + codegen-units = 1 | 4.8M | 8.5M -### Loading Assets +#### 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 diff --git a/examples/README.md b/examples/README.md index 29420e66c53ac..06d79d826288f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -89,19 +89,19 @@ git checkout v0.4.0 - [Optimizing](#optimizing) - [Loading Assets](#loading-assets) -# The Bare Minimum +## The Bare Minimum -## Hello, World! +### Hello, World! Example | Description --- | --- [`hello_world.rs`](./hello_world.rs) | Runs a minimal example that outputs "hello world" -# Cross-Platform Examples +## Cross-Platform Examples -## 2D Rendering +### 2D Rendering Example | Description --- | --- @@ -132,7 +132,7 @@ Example | Description [Tilemap Chunk](../examples/2d/tilemap_chunk.rs) | Renders a tilemap chunk [Transparency in 2D](../examples/2d/transparency_2d.rs) | Demonstrates transparency in 2d -## 3D Rendering +### 3D Rendering Example | Description --- | --- @@ -204,7 +204,7 @@ Example | Description [Volumetric fog](../examples/3d/volumetric_fog.rs) | Demonstrates volumetric fog and lighting [Wireframe](../examples/3d/wireframe.rs) | Showcases wireframe rendering -## Animation +### Animation Example | Description --- | --- @@ -223,7 +223,7 @@ Example | Description [Morph Targets](../examples/animation/morph_targets.rs) | Plays an animation from a glTF file with meshes with morph targets [glTF Skinned Mesh](../examples/animation/gltf_skinned_mesh.rs) | Skinned mesh example with mesh and joints data loaded from a glTF file -## Application +### Application Example | Description --- | --- @@ -243,7 +243,7 @@ Example | Description [Thread Pool Resources](../examples/app/thread_pool_resources.rs) | Creates and customizes the internal thread pool [Without Winit](../examples/app/without_winit.rs) | Create an application without winit (runs single time, no event loop) -## Assets +### Assets Example | Description --- | --- @@ -261,14 +261,14 @@ Example | Description [Multi-asset synchronization](../examples/asset/multi_asset_sync.rs) | Demonstrates how to wait for multiple assets to be loaded. [Repeated texture configuration](../examples/asset/repeated_texture.rs) | How to configure the texture to repeat instead of the default clamp to edges -## Async Tasks +### Async Tasks Example | Description --- | --- [Async Compute](../examples/async_tasks/async_compute.rs) | How to use `AsyncComputeTaskPool` to complete longer running tasks [External Source of Data on an External Thread](../examples/async_tasks/external_source_external_thread.rs) | How to use an external thread to run an infinite task and communicate with a channel -## Audio +### Audio Example | Description --- | --- @@ -280,7 +280,7 @@ Example | Description [Spatial Audio 2D](../examples/audio/spatial_audio_2d.rs) | Shows how to play spatial audio, and moving the emitter in 2D [Spatial Audio 3D](../examples/audio/spatial_audio_3d.rs) | Shows how to play spatial audio, and moving the emitter in 3D -## Camera +### Camera Example | Description --- | --- @@ -292,13 +292,13 @@ Example | Description [Projection Zoom](../examples/camera/projection_zoom.rs) | Shows how to zoom orthographic and perspective projection cameras. [Screen Shake](../examples/camera/2d_screen_shake.rs) | A simple 2D screen shake effect -## Dev tools +### Dev tools Example | Description --- | --- [FPS overlay](../examples/dev_tools/fps_overlay.rs) | Demonstrates FPS overlay -## Diagnostics +### Diagnostics Example | Description --- | --- @@ -306,7 +306,7 @@ Example | Description [Enabling/disabling diagnostic](../examples/diagnostics/enabling_disabling_diagnostic.rs) | Shows how to disable/re-enable a Diagnostic during runtime [Log Diagnostics](../examples/diagnostics/log_diagnostics.rs) | Add a plugin that logs diagnostics, like frames per second (FPS), to the console -## ECS (Entity Component System) +### ECS (Entity Component System) Example | Description --- | --- @@ -342,13 +342,13 @@ Example | Description [System Piping](../examples/ecs/system_piping.rs) | Pipe the output of one system into a second, allowing you to handle any errors gracefully [System Stepping](../examples/ecs/system_stepping.rs) | Demonstrate stepping through systems in order of execution. -## Embedded +### Embedded Example | Description --- | --- [`no_std` Compatible Library](../examples/no_std/library/src/lib.rs) | Example library compatible with `std` and `no_std` targets -## Games +### Games Example | Description --- | --- @@ -359,7 +359,7 @@ Example | Description [Game Menu](../examples/games/game_menu.rs) | A simple game menu [Loading Screen](../examples/games/loading_screen.rs) | Demonstrates how to create a loading screen that waits for all assets to be loaded and render pipelines to be compiled. -## Gizmos +### Gizmos Example | Description --- | --- @@ -368,14 +368,14 @@ Example | Description [Axes](../examples/gizmos/axes.rs) | Demonstrates the function of axes gizmos [Light Gizmos](../examples/gizmos/light_gizmos.rs) | A scene showcasing light gizmos -## Helpers +### Helpers Example | Description --- | --- [Camera Controller](../examples/helpers/camera_controller.rs) | Example Free-Cam Styled Camera Controller [Widgets](../examples/helpers/widgets.rs) | Example UI Widgets -## Input +### Input Example | Description --- | --- @@ -393,7 +393,7 @@ Example | Description [Touch Input](../examples/input/touch_input.rs) | Displays touch presses, releases, and cancels [Touch Input Events](../examples/input/touch_input_events.rs) | Prints out all touch inputs -## Math +### Math Example | Description --- | --- @@ -405,13 +405,13 @@ Example | Description [Sampling Primitives](../examples/math/sampling_primitives.rs) | Demonstrates all the primitives which can be sampled. [Smooth Follow](../examples/movement/smooth_follow.rs) | Demonstrates how to make an entity smoothly follow another using interpolation -## Movement +### Movement Example | Description --- | --- [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 -## Picking +### Picking Example | Description --- | --- @@ -420,7 +420,7 @@ Example | Description [Showcases simple picking events and usage](../examples/picking/simple_picking.rs) | Demonstrates how to use picking events to spawn simple objects [Sprite Picking](../examples/picking/sprite_picking.rs) | Demonstrates picking sprites and sprite atlases -## Reflection +### Reflection Example | Description --- | --- @@ -432,20 +432,20 @@ Example | Description [Reflection Types](../examples/reflection/reflection_types.rs) | Illustrates the various reflection types available [Type Data](../examples/reflection/type_data.rs) | Demonstrates how to create and use type data -## Remote Protocol +### Remote Protocol Example | Description --- | --- [client](../examples/remote/client.rs) | A simple command line client that can control Bevy apps via the BRP [server](../examples/remote/server.rs) | A Bevy app that you can connect to with the BRP and edit -## Scene +### Scene Example | Description --- | --- [Scene](../examples/scene/scene.rs) | Demonstrates loading from and saving scenes to files -## Shaders +### Shaders These examples demonstrate how to implement different shaders in user code. @@ -479,7 +479,7 @@ Example | Description [Storage Buffer](../examples/shader/storage_buffer.rs) | A shader that shows how to bind a storage buffer using a custom material. [Texture Binding Array (Bindless Textures)](../examples/shader/texture_binding_array.rs) | A shader that shows how to bind and sample multiple textures as a binding array (a.k.a. bindless textures). -## State +### State Example | Description --- | --- @@ -488,7 +488,7 @@ Example | Description [States](../examples/state/states.rs) | Illustrates how to use States to control transitioning from a Menu state to an InGame state. [Sub States](../examples/state/sub_states.rs) | Using Sub States for hierarchical state handling. -## Stress Tests +### Stress Tests These examples are used to test the performance and stability of various parts of the engine in an isolated way. @@ -517,7 +517,7 @@ Example | Description [Text Pipeline](../examples/stress_tests/text_pipeline.rs) | Text Pipeline benchmark [Transform Hierarchy](../examples/stress_tests/transform_hierarchy.rs) | Various test cases for hierarchy and transform propagation performance -## Time +### Time Example | Description --- | --- @@ -525,14 +525,14 @@ Example | Description [Timers](../examples/time/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state [Virtual time](../examples/time/virtual_time.rs) | Shows how `Time` can be used to pause, resume, slow down and speed up a game. -## Tools +### Tools Example | Description --- | --- [Gamepad Viewer](../examples/tools/gamepad_viewer.rs) | Shows a visualization of gamepad buttons, sticks, and triggers [Scene Viewer](../examples/tools/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 -## Transforms +### Transforms Example | Description --- | --- @@ -542,7 +542,7 @@ Example | Description [Transform](../examples/transforms/transform.rs) | Shows multiple transformations of objects [Translation](../examples/transforms/translation.rs) | Illustrates how to move an object along an axis -## UI (User Interface) +### UI (User Interface) Example | Description --- | --- @@ -586,14 +586,14 @@ Example | Description [Viewport Node](../examples/ui/viewport_node.rs) | Demonstrates how to create a viewport node with picking support [Window Fallthrough](../examples/ui/window_fallthrough.rs) | Illustrates how to access `winit::window::Window`'s `hittest` functionality. -## Usage +### Usage Example | Description --- | --- [Context Menu](../examples/usage/context_menu.rs) | Example of a context menu [Cooldown](../examples/usage/cooldown.rs) | Example for cooldown on button clicks -## Window +### Window Example | Description --- | --- @@ -610,18 +610,18 @@ Example | Description [Window Resizing](../examples/window/window_resizing.rs) | Demonstrates resizing and responding to resizing a window [Window Settings](../examples/window/window_settings.rs) | Demonstrates customizing default window settings -# Tests +## Tests Example | Description --- | --- [How to Test Apps](../tests/how_to_test_apps.rs) | How to test apps (simple integration testing) [How to Test Systems](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources -# Platform-Specific Examples +## Platform-Specific Examples -## Android +### Android -### Setup +#### Setup ```sh rustup target add aarch64-linux-android @@ -634,7 +634,7 @@ When using `NDK (Side by side)`, the environment variable `ANDROID_NDK_ROOT` mus Alternatively, you can install Android Studio. -### Build & Run +#### Build & Run To build an Android app, you first need to build shared object files for the target architecture with `cargo-ndk`: @@ -662,7 +662,7 @@ Or build it with Android Studio. Then you can test it in your Android project. -#### About `libc++_shared.so` +##### 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. @@ -670,7 +670,7 @@ To include it, you can manually obtain it from NDK source or use a `build.rs` sc 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`). -### Debugging +#### Debugging You can view the logs with the following command: @@ -686,7 +686,7 @@ Sometimes, running the app complains about an unknown activity. This may be fixe adb uninstall org.bevyengine.example ``` -### Old phones +#### Old phones In its examples, Bevy targets the minimum Android API that Play Store [requires](https://developer.android.com/distribute/best-practices/develop/target-sdk) to upload and update apps. @@ -700,7 +700,7 @@ bevy = { version = "0.14", default-features = false, features = ["android-native Then build it as the [Build & Run](#build--run) section stated above. -#### About `cargo-apk` +##### 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. @@ -708,9 +708,9 @@ Example | File | Description --- | --- | --- `android` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound -## iOS +### iOS -### Setup +#### Setup You need to install the correct rust targets: @@ -722,7 +722,7 @@ You need to install the correct rust targets: rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim ``` -### Build & Run +#### Build & Run Using bash: @@ -752,16 +752,16 @@ Example | File | Description --- | --- | --- `ios` | [`mobile/src/lib.rs`](./mobile/src/lib.rs) | A 3d Scene with a button and playing sound -## Wasm +### Wasm -### Setup +#### Setup ```sh rustup target add wasm32-unknown-unknown cargo install wasm-bindgen-cli ``` -### Build & Run +#### Build & Run Following is an example for `lighting`. For other examples, change the `lighting` in the following commands. @@ -781,17 +781,17 @@ javascript bindings to this wasm file in the output file `examples/wasm/target/w Then serve `examples/wasm` directory to browser. i.e. ```sh -# cargo install basic-http-server +## cargo install basic-http-server basic-http-server examples/wasm -# with python +## with python python3 -m http.server --directory examples/wasm -# with ruby +## with ruby ruby -run -ehttpd examples/wasm ``` -#### WebGL2 and WebGPU +##### WebGL2 and WebGPU Bevy support for WebGPU is being worked on, but is currently experimental. @@ -805,13 +805,13 @@ Bevy has a helper to build its examples: This helper will log the command used to build the examples. -### Audio in the browsers +#### 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. -### Optimizing +#### 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, starting with @@ -846,7 +846,7 @@ opt-level = "z" | 6.1M | 12.7M "z" + "thin" + codegen-units = 1 | 5.3M | 11M "z" + "fat" + codegen-units = 1 | 4.8M | 8.5M -### Loading Assets +#### 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