diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 49fda44c9ac56..9c9563680e3b0 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,4 +1,4 @@ # Contributing Please see the [Contributing Code](https://bevyengine.org/learn/book/contributing/code/) section of -[The Book](https://bevyengine.org/learn/book/introduction/). \ No newline at end of file +[The Book](https://bevyengine.org/learn/book/introduction/). diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 1169e40dd86a9..9339ee9abddeb 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -6,27 +6,27 @@ labels: '' assignees: '' --- -**Bevy version** +## Bevy version The release number or commit hash of the version you're using. -**Operating system & version** +## Operating system & version Ex: Windows 10, Ubuntu 18.04, iOS 14. -**What you did** +## What you did The steps you took to uncover this bug. Please list full reproduction steps if feasible. -**What you expected to happen** +## What you expected to happen What you think should've happened if everything was working properly. -**What actually happened** +## What actually happened The actual result of the actions you described. -**Additional information** +## Additional information Any additional information you would like to add such as screenshots, logs, etc. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 767f4b71ed325..c2f26b64035ea 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -6,19 +6,19 @@ labels: '' assignees: '' --- -**What problem does this solve or what need does it fill?** +## What problem does this solve or what need does it fill? A description of why this particular feature should be added. -**What solution would you like?** +## What solution would you like? The solution you propose for the problem presented. -**What alternative(s) have you considered?** +## What alternative(s) have you considered? Other solutions to solve and/or work around the problem presented. -**Additional context** +## Additional context Any other information you would like to add such as related previous work, screenshots, benchmarks, etc. diff --git a/.github/bors.toml b/.github/bors.toml index abec6ced19307..008bec455e067 100644 --- a/.github/bors.toml +++ b/.github/bors.toml @@ -6,6 +6,7 @@ status = [ "build-wasm (stable, ubuntu-latest)", "build-wasm (nightly, ubuntu-latest)", "build-android", + "markdownlint", ] use_squash_merge = true diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml new file mode 100644 index 0000000000000..7348131969853 --- /dev/null +++ b/.github/linters/.markdown-lint.yml @@ -0,0 +1,3 @@ +{ + "MD013": false +} \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f0e08c66dbcc3..87b329195226b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,8 +37,8 @@ jobs: run: cargo fmt --all -- --check if: runner.os == 'linux' && matrix.toolchain == 'stable' - # type complexity must be ignored because we use huge templates for queries - # -A clippy::manual-strip: strip_prefix support was added in 1.45. we want to support earlier rust versions + # -A clippy::type_complexity: type complexity must be ignored because we use huge templates for queries. + # -A clippy::manual-strip: strip_prefix support was added in 1.45. We want to support earlier rust versions. - name: Clippy run: cargo clippy --all-targets --all-features -- -D warnings -A clippy::type_complexity -A clippy::manual-strip if: runner.os == 'linux' && matrix.toolchain == 'stable' @@ -80,3 +80,20 @@ jobs: run: cargo install cargo-apk - name: Build APK run: cargo apk build --example android + + markdownlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + # Full git history is needed to get a proper list of changed files within `super-linter` + fetch-depth: 0 + + - name: Run Markdown Lint + uses: github/super-linter@v3 + env: + VALIDATE_ALL_CODEBASE: false + VALIDATE_MARKDOWN: true + DEFAULT_BRANCH: master + # Not needed here as only one Linter is used. + #GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 64cb9051b806f..a532293df74a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ + + + # Changelog While we try to keep the `Unreleased` changes updated, it is often behind and does not include @@ -6,16 +9,16 @@ current changes on git with [previous release tags][git_tag_comparison]. [git_tag_comparison]: https://github.com/bevyengine/bevy/compare/v0.4.0...main - ## Version 0.4.0 (2020-12-19) ### Added + - [add bevymark benchmark example][273] -- [gltf: support camera and fix hierarchy][772] +- [gltf: support camera and fix hierarchy][772] - [Add tracing spans to schedules, stages, systems][789] - [add example that represents contributors as bevy icons][801] - [Add received character][805] -- [Add bevy_dylib to force dynamic linking of bevy][808] +- [Add bevy_dylib to force dynamic linking of bevy][808] - [Added RenderPass::set_scissor_rect][815] - [`bevy_log`][836] - Adds logging functionality as a Plugin. @@ -33,7 +36,7 @@ current changes on git with [previous release tags][git_tag_comparison]. - Replaces the properties system - [Add support for Apple Silicon][928] - [Live reloading of shaders][937] -- [ Store mouse cursor position in Window][940] +- [Store mouse cursor position in Window][940] - [Add removal_detection example][945] - [Additional vertex attribute value types][946] - [Added WindowFocused event][956] @@ -46,9 +49,9 @@ current changes on git with [previous release tags][git_tag_comparison]. ### Changed -- [delegate layout reflection to RenderResourceContext][691] +- [delegate layout reflection to RenderResourceContext][691] - [Fall back to remove components one by one when failing to remove a bundle][719] -- [Port hecs derive macro improvements][761] +- [Port hecs derive macro improvements][761] - [Use glyph_brush_layout and add text alignment support][765] - [upgrade glam and hexasphere][791] - [Flexible ECS Params][798] @@ -242,7 +245,7 @@ current changes on git with [previous release tags][git_tag_comparison]. - [`FrameTimeDiagnosticsPlugin` now shows "frame count" in addition to "frame time" and "fps"][678] - [Add hierarchy example][565] - [`WgpuPowerOptions` for choosing between low power, high performance, and adaptive power][397] -- Derive `Debug` for more types: [#597][597], [#632][632] +- Derive `Debug` for more types: [#597][597], [#632][632] - Index buffer specialization - [Allows the use of U32 indices in Mesh index buffers in addition to the usual U16 indices][568] - [Switch to u32 indices by default][572] @@ -286,7 +289,7 @@ current changes on git with [previous release tags][git_tag_comparison]. - [Migrated to Rodio 0.12][692] - New method of playing audio can be found in the examples. - Added support for inserting custom initial values for `Local` system resources [#745][745] - + ### Fixed - [Properly update bind group ids when setting dynamic bindings][560] @@ -359,7 +362,6 @@ current changes on git with [previous release tags][git_tag_comparison]. [745]: https://github.com/bevyengine/bevy/pull/745 [752]: https://github.com/bevyengine/bevy/pull/752 - ## Version 0.2.1 (2020-9-20) ### Fixed diff --git a/CREDITS.md b/CREDITS.md index da4bccd579993..cefd08df93ad4 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -5,14 +5,14 @@ * hecs * legion_transform * wgpu-rs examples -* yaks: ArchetypeSet, borrowed some ideas from their scheduler implementation +* yaks: ArchetypeSet, borrowed some ideas from their scheduler implementation ## Inspiration * game engines: amethyst, coffee -* ecs: legion, shipyard, yaks +* ecs: legion, shipyard, yaks ## Assets * Generic RPG Pack (CC0 license) by [Bakudas](https://twitter.com/bakudas) and [Gabe Fern](https://twitter.com/_Gabrielfer) -* Environment maps (`.hdr` files) from [HDRIHaven](https://hdrihaven.com) (CC0 license) \ No newline at end of file +* Environment maps (`.hdr` files) from [HDRIHaven](https://hdrihaven.com) (CC0 license) diff --git a/Cargo.toml b/Cargo.toml index fa0cbd53498ac..8b9df8c00f12e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -89,6 +89,11 @@ serde = {version = "1", features = ["derive"]} name = "hello_world" path = "examples/hello_world.rs" +# 2D Rendering +[[example]] +name = "contributors" +path = "examples/2d/contributors.rs" + [[example]] name = "sprite" path = "examples/2d/sprite.rs" @@ -97,18 +102,15 @@ path = "examples/2d/sprite.rs" name = "sprite_sheet" path = "examples/2d/sprite_sheet.rs" -[[example]] -name = "texture_atlas" -path = "examples/2d/texture_atlas.rs" - -[[example]] -name = "contributors" -path = "examples/2d/contributors.rs" - [[example]] name = "text2d" path = "examples/2d/text2d.rs" +[[example]] +name = "texture_atlas" +path = "examples/2d/texture_atlas.rs" + +# 3D Rendering [[example]] name = "3d_scene" path = "examples/3d/3d_scene.rs" @@ -145,6 +147,7 @@ path = "examples/3d/update_gltf_scene.rs" name = "z_sort_debug" path = "examples/3d/z_sort_debug.rs" +# Application [[example]] name = "custom_loop" path = "examples/app/custom_loop.rs" @@ -153,22 +156,22 @@ path = "examples/app/custom_loop.rs" name = "drag_and_drop" path = "examples/app/drag_and_drop.rs" -[[example]] -name = "empty_defaults" -path = "examples/app/empty_defaults.rs" - [[example]] name = "empty" path = "examples/app/empty.rs" [[example]] -name = "logs" -path = "examples/app/logs.rs" +name = "empty_defaults" +path = "examples/app/empty_defaults.rs" [[example]] name = "headless" path = "examples/app/headless.rs" +[[example]] +name = "logs" +path = "examples/app/logs.rs" + [[example]] name = "plugin" path = "examples/app/plugin.rs" @@ -185,10 +188,7 @@ path = "examples/app/return_after_run.rs" name = "thread_pool_resources" path = "examples/app/thread_pool_resources.rs" -[[example]] -name = "hot_asset_reloading" -path = "examples/asset/hot_asset_reloading.rs" - +# Assets [[example]] name = "asset_loading" path = "examples/asset/asset_loading.rs" @@ -201,17 +201,28 @@ path = "examples/asset/custom_asset.rs" name = "custom_asset_io" path = "examples/asset/custom_asset_io.rs" +[[example]] +name = "hot_asset_reloading" +path = "examples/asset/hot_asset_reloading.rs" + +# Audio [[example]] name = "audio" path = "examples/audio/audio.rs" +# Diagnostics +[[example]] +name = "log_diagnostics" +path = "examples/diagnostics/log_diagnostics.rs" + [[example]] name = "custom_diagnostic" path = "examples/diagnostics/custom_diagnostic.rs" +# ECS (Entity Component System) [[example]] -name = "log_diagnostics" -path = "examples/diagnostics/log_diagnostics.rs" +name = "ecs_guide" +path = "examples/ecs/ecs_guide.rs" [[example]] name = "change_detection" @@ -225,6 +236,18 @@ path = "examples/ecs/event.rs" name = "fixed_timestep" path = "examples/ecs/fixed_timestep.rs" +[[example]] +name = "hierarchy" +path = "examples/ecs/hierarchy.rs" + +[[example]] +name = "parallel_query" +path = "examples/ecs/parallel_query.rs" + +[[example]] +name = "removal_detection" +path = "examples/ecs/removal_detection.rs" + [[example]] name = "startup_system" path = "examples/ecs/startup_system.rs" @@ -241,18 +264,7 @@ path = "examples/ecs/system_chaining.rs" name = "timers" path = "examples/ecs/timers.rs" -[[example]] -name = "ecs_guide" -path = "examples/ecs/ecs_guide.rs" - -[[example]] -name = "parallel_query" -path = "examples/ecs/parallel_query.rs" - -[[example]] -name = "hierarchy" -path = "examples/ecs/hierarchy.rs" - +# Games [[example]] name = "alien_cake_addict" path = "examples/game/alien_cake_addict.rs" @@ -261,13 +273,18 @@ path = "examples/game/alien_cake_addict.rs" name = "breakout" path = "examples/game/breakout.rs" +# Input [[example]] -name = "mouse_input" -path = "examples/input/mouse_input.rs" +name = "char_input_events" +path = "examples/input/char_input_events.rs" [[example]] -name = "mouse_input_events" -path = "examples/input/mouse_input_events.rs" +name = "gamepad_input" +path = "examples/input/gamepad_input.rs" + +[[example]] +name = "gamepad_input_events" +path = "examples/input/gamepad_input_events.rs" [[example]] name = "keyboard_input" @@ -278,16 +295,12 @@ name = "keyboard_input_events" path = "examples/input/keyboard_input_events.rs" [[example]] -name = "char_input_events" -path = "examples/input/char_input_events.rs" - -[[example]] -name = "gamepad_input" -path = "examples/input/gamepad_input.rs" +name = "mouse_input" +path = "examples/input/mouse_input.rs" [[example]] -name = "gamepad_input_events" -path = "examples/input/gamepad_input_events.rs" +name = "mouse_input_events" +path = "examples/input/mouse_input_events.rs" [[example]] name = "touch_input" @@ -297,26 +310,33 @@ path = "examples/input/touch_input.rs" name = "touch_input_events" path = "examples/input/touch_input_events.rs" +# Reflection [[example]] name = "reflection" path = "examples/reflection/reflection.rs" -[[example]] -name = "reflection_types" -path = "examples/reflection/reflection_types.rs" - [[example]] name = "generic_reflection" path = "examples/reflection/generic_reflection.rs" +[[example]] +name = "reflection_types" +path = "examples/reflection/reflection_types.rs" + [[example]] name = "trait_reflection" path = "examples/reflection/trait_reflection.rs" +# Scene [[example]] name = "scene" path = "examples/scene/scene.rs" +# Shaders +[[example]] +name = "array_texture" +path = "examples/shader/array_texture.rs" + [[example]] name = "hot_shader_reloading" path = "examples/shader/hot_shader_reloading.rs" @@ -329,22 +349,24 @@ path = "examples/shader/mesh_custom_attribute.rs" name = "shader_custom_material" path = "examples/shader/shader_custom_material.rs" -[[example]] -name = "array_texture" -path = "examples/shader/array_texture.rs" - [[example]] name = "shader_defs" path = "examples/shader/shader_defs.rs" +# Tools [[example]] name = "bevymark" path = "examples/tools/bevymark.rs" +# UI (User Interface) [[example]] name = "button" path = "examples/ui/button.rs" +[[example]] +name = "font_atlas_debug" +path = "examples/ui/font_atlas_debug.rs" + [[example]] name = "text" path = "examples/ui/text.rs" @@ -353,14 +375,11 @@ path = "examples/ui/text.rs" name = "text_debug" path = "examples/ui/text_debug.rs" -[[example]] -name = "font_atlas_debug" -path = "examples/ui/font_atlas_debug.rs" - [[example]] name = "ui" path = "examples/ui/ui.rs" +# Window [[example]] name = "clear_color" path = "examples/window/clear_color.rs" @@ -377,15 +396,17 @@ path = "examples/window/scale_factor_override.rs" name = "window_settings" path = "examples/window/window_settings.rs" -[[example]] -name = "removal_detection" -path = "examples/ecs/removal_detection.rs" - +# WASM [[example]] name = "hello_wasm" path = "examples/wasm/hello_wasm.rs" required-features = [] +[[example]] +name = "assets_wasm" +path = "examples/wasm/assets_wasm.rs" +required-features = ["bevy_winit"] + [[example]] name = "headless_wasm" path = "examples/wasm/headless_wasm.rs" @@ -396,11 +417,7 @@ name = "winit_wasm" path = "examples/wasm/winit_wasm.rs" required-features = ["bevy_winit"] -[[example]] -name = "assets_wasm" -path = "examples/wasm/assets_wasm.rs" -required-features = ["bevy_winit"] - +# Android [[example]] crate-type = ["cdylib"] name = "android" diff --git a/README.md b/README.md index b459746f51582..863bbe2c715f8 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Bevy is still in the _very_ early stages of development. APIs can and will chang ## Community -Before contributing or participating in discussions with the community, you should familiarize yourself with our **[Code of Conduct](./CODE_OF_CONDUCT.md)** and +Before contributing or participating in discussions with the community, you should familiarize yourself with our **[Code of Conduct](./CODE_OF_CONDUCT.md)** and **[How to Contribute](https://bevyengine.org/learn/book/contributing/code/)** * **[Discord](https://discord.gg/gMUk5Ph):** Bevy's official discord server. diff --git a/assets/models/AlienCake/README.md b/assets/models/AlienCake/README.md index 736c126a16a4c..2cf86d3d8bd0d 100644 --- a/assets/models/AlienCake/README.md +++ b/assets/models/AlienCake/README.md @@ -1,4 +1,4 @@ -Assets are from [Kenney](https://www.kenney.nl) +# Assets are from [Kenney](https://www.kenney.nl) - alien from [Space Kit](https://www.kenney.nl/assets/space-kit) - cake from [Food Kit](https://www.kenney.nl/assets/food-kit) diff --git a/crates/bevy_ecs/README.md b/crates/bevy_ecs/README.md index 8522a0e5ea4af..fdbf6ec0fd832 100644 --- a/crates/bevy_ecs/README.md +++ b/crates/bevy_ecs/README.md @@ -4,4 +4,4 @@ Bevy Engine's entity component system ## Licensing -Bevy ECS has its roots in hecs, which is licensed as Apache 2.0. All original hecs code is licensed under Apache 2.0. All added/modified code is dual licensed under MIT and Apache 2.0. Files with an Apache 2.0 license header (with Google LLC as the copyright holder) were from the "original hecs" codebase. Files without the header were created by Bevy contributors. \ No newline at end of file +Bevy ECS has its roots in hecs, which is licensed as Apache 2.0. All original hecs code is licensed under Apache 2.0. All added/modified code is dual licensed under MIT and Apache 2.0. Files with an Apache 2.0 license header (with Google LLC as the copyright holder) were from the "original hecs" codebase. Files without the header were created by Bevy contributors. diff --git a/crates/bevy_reflect/README.md b/crates/bevy_reflect/README.md index 39c9048205021..8ecb319649fc5 100644 --- a/crates/bevy_reflect/README.md +++ b/crates/bevy_reflect/README.md @@ -8,7 +8,7 @@ This crate enables you to dynamically interact with Rust types: * Look up nested fields using "path strings" * Iterate over struct fields * Automatically serialize and deserialize via Serde (without explicit serde impls) -* Trait "reflection" +* Trait "reflection" ## Features @@ -79,7 +79,7 @@ for (i, value: &Reflect) in foo.iter_fields().enumerate() { let field_name = foo.name_at(i).unwrap(); if let Ok(value) = value.downcast_ref::() { println!("{} is a u32 with the value: {}", field_name, *value); - } + } } ``` diff --git a/crates/bevy_tasks/README.md b/crates/bevy_tasks/README.md index 613994ca13d53..523dbff7eaba9 100644 --- a/crates/bevy_tasks/README.md +++ b/crates/bevy_tasks/README.md @@ -3,9 +3,9 @@ A refreshingly simple task executor for bevy. :) This is a simple threadpool with minimal dependencies. The main usecase is a scoped fork-join, i.e. spawning tasks from -a single thread and having that thread await the completion of those tasks. This is intended specifically for +a single thread and having that thread await the completion of those tasks. This is intended specifically for [`bevy`][bevy] as a lighter alternative to [`rayon`][rayon] for this specific usecase. There are also utilities for -generating the tasks from a slice of data. This library is intended for games and makes no attempt to ensure fairness +generating the tasks from a slice of data. This library is intended for games and makes no attempt to ensure fairness or ordering of spawned tasks. It is based on [`async-executor`][async-executor], a lightweight executor that allows the end user to manage their own threads. @@ -19,7 +19,7 @@ It is based on [`async-executor`][async-executor], a lightweight executor that a A very small dependency list is a key feature of this module -``` +```text ├── async-executor │ ├── async-task │ ├── concurrent-queue diff --git a/docs/linters.md b/docs/linters.md new file mode 100644 index 0000000000000..aefbdaa562853 --- /dev/null +++ b/docs/linters.md @@ -0,0 +1,47 @@ +# Linters in this Repository + +## [rustfmt](https://github.com/rust-lang/rustfmt) + +Can be automatically be run with the [CI Script](../tools/ci) together with `Clippy` or manually with this command: + +```bash +cargo +nightly fmt --all +``` + +## [Clippy](https://github.com/rust-lang/rust-clippy) + +Can be automatically be run with the [CI Script](../tools/ci) together with `rustfmt` or manually with this command: + +```bash +cargo clippy --all-targets --all-features -- -D warnings -A clippy::type_complexity -A clippy::manual-strip +``` + +* `-D warnings`: No warnings are allowed in the codebase. +* `-A clippy::type_complexity`: type complexity must be ignored because we use huge templates for queries. +* `-A clippy::manual-strip`: strip_prefix support was added in 1.45. We want to support earlier rust versions. + +## [super-linter](https://github.com/github/super-linter) + +`super-linter` provides easy access to many different Linters. + +### [markdownlint](https://github.com/DavidAnson/markdownlint) + +`markdownlint` is provided by `super-linter` and is responsible for `.md` files. +Its configuration is saved in the [.markdown-lint.yml](../.github/linters/markdown-lint.yml) file. + +The provided rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) and information about setting the config can be seen [here](https://github.com/DavidAnson/markdownlint#optionsconfig). + +#### Using [VS Code markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) + +If you want to use the VS Code Extension with the rules defined in [.markdown-lint.yml](../.github/linters/markdown-lint.yml), then you need to create a local config file in the root of the project with the configuration below. +Currently, this is not needed as the extension already disables the rule `MD013` by default. + +```json +{ + "extends": ".github/linters/.markdown-lint.yml" +} +``` + +### Other Linters provided by [super-linter](https://github.com/github/super-linter) + +All other linters not mentioned in the this file are not activated and can be seen [here](https://github.com/github/super-linter#supported-linters). diff --git a/docs/linux_dependencies.md b/docs/linux_dependencies.md index d56ff72efcd0b..c25736ec7b94d 100644 --- a/docs/linux_dependencies.md +++ b/docs/linux_dependencies.md @@ -9,15 +9,17 @@ If you don't see your distro present in the list, feel free to add the instructi ```bash sudo apt-get install pkg-config libx11-dev libasound2-dev libudev-dev ``` + If you want to enable fast compiles + ```bash sudo apt-get install clang ``` ### Windows Subsystem for Linux (WSL 2) -Graphics and audio need to be configured for them to work with WSL 2 backend. -Please see the ubuntu [WSL documentation](https://wiki.ubuntu.com/WSL) on how to set up graphics and audio. +Graphics and audio need to be configured for them to work with WSL 2 backend. +Please see the ubuntu [WSL documentation](https://wiki.ubuntu.com/WSL) on how to set up graphics and audio. ## Fedora 33 diff --git a/docs/plugins_guidelines.md b/docs/plugins_guidelines.md index 036a56be7c9e1..d4b159cf46ada 100644 --- a/docs/plugins_guidelines.md +++ b/docs/plugins_guidelines.md @@ -4,7 +4,6 @@ Bevy has a plug and play architecture, where you can easily add plugins for new This document targets plugin authors. - ## Checklist * [ ] [Pick a reasonable, descriptive name](#naming) @@ -42,20 +41,25 @@ Indicating which version of your plugin works with which version of Bevy can be ## Bevy Features You should disable Bevy features that you don't use. This is because with Cargo, features are additive. Features that are enabled for Bevy in your plugin can't be disabled by someone using your plugin. You can find the list of features [here](cargo_features.md). -``` + +```toml bevy = { version = "0.4", default-features = false, features = ["..."] } ``` ## Main Branch Tracking If you intend to track Bevy's main branch, you can specify the latest commit you support in your `Cargo.toml` file: -``` + +```toml bevy = { version = "0.4", git = "https://github.com/bevyengine/bevy", rev="509b138e8fa3ea250393de40c33cc857c72134d3", default-features = false } ``` + You can specify the dependency [both as a version and with git](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#multiple-locations), the version will be used if using the dependency from [crates.io](https://crates.io), the git dependency will be used otherwise. Bevy is evolving very fast. You can use one of these badges to communicate to your users how closely you intend to track Bevy's main branch. + + |
badge
|
description
|code| |-|-|-| |[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-main-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)|I intend to track main as much as I can|`[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-main-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)`| diff --git a/examples/README.md b/examples/README.md index 1968eeaa16ec9..6d0545cde77ff 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,3 +1,6 @@ + + + # Examples These examples demonstrate the main features of Bevy and how to use them. @@ -7,19 +10,20 @@ To run an example, use the command `cargo run --example `, and add the cargo run --features wayland --example hello_world ``` -### ⚠️ Note: for users of releases on crates.io, +**⚠️ Note: for users of releases on crates.io!** Due to changes and additions to APIs, there are often differences between the development examples and the released versions of Bevy on crates.io. If you are using a release version from [crates.io](https://crates.io/crates/bevy), view the examples by checking out the appropriate git tag, e.g., users of `0.4` should use the examples on [https://github.com/bevyengine/bevy/tree/v0.4.0/examples](https://github.com/bevyengine/bevy/tree/v0.4.0/examples) If you have cloned bevy's repo locally, `git checkout` with the appropriate version tag. -``` + +```bash git checkout v0.4.0 ``` --- -### Table of Contents +## Table of Contents - [The Bare Minimum](#the-bare-minimum) - [Hello, World!](#hello-world) @@ -46,6 +50,8 @@ git checkout v0.4.0 # The Bare Minimum + + ## Hello, World! Example | Main | Description @@ -61,7 +67,7 @@ Example | Main | Description `contributors` | [`2d/contributors.rs`](./2d/contributors.rs) | Displays each contributor as a bouncy bevy-ball! `sprite` | [`2d/sprite.rs`](./2d/sprite.rs) | Renders a sprite `sprite_sheet` | [`2d/sprite_sheet.rs`](./2d/sprite_sheet.rs) | Renders an animated sprite -`texture2d` | [`2d/text2d.rs`](./2d/text2d.rs) | Generates text in 2d +`text2d` | [`2d/text2d.rs`](./2d/text2d.rs) | Generates text in 2d `texture_atlas` | [`2d/texture_atlas.rs`](./2d/texture_atlas.rs) | Generates a texture atlas (sprite sheet) from individual sprites ## 3D Rendering @@ -112,15 +118,15 @@ Example | File | Description Example | File | Description --- | --- | --- -`custom_diagnostic` | [`diagnostics/custom_diagnostic.rs`](./diagnostics/custom_diagnostic.rs) | Shows how to create a custom diagnostic `log_diagnostics` | [`diagnostics/log_diagnostics.rs`](./diagnostics/log_diagnostics.rs) | Add a plugin that logs diagnostics to the console +`custom_diagnostic` | [`diagnostics/custom_diagnostic.rs`](./diagnostics/custom_diagnostic.rs) | Shows how to create a custom diagnostic ## ECS (Entity Component System) Example | File | Description --- | --- | --- -`change_detection` | [`ecs/change_detection.rs`](./ecs/change_detection.rs) | Change detection on components `ecs_guide` | [`ecs/ecs_guide.rs`](./ecs/ecs_guide.rs) | Full guide to Bevy's ECS +`change_detection` | [`ecs/change_detection.rs`](./ecs/change_detection.rs) | Change detection on components `event` | [`ecs/event.rs`](./ecs/event.rs) | Illustrates event creation, activation, and reception `fixed_timestep` | [`ecs/fixed_timestep.rs`](./ecs/fixed_timestep.rs) | Shows how to create systems that run every fixed timestep, rather than every tick `hierarchy` | [`ecs/hierarchy.rs`](./ecs/hierarchy.rs) | Creates a hierarchy of parents and children entities @@ -156,8 +162,8 @@ Example | File | Description Example | File | Description --- | --- | --- -`generic_reflection` | [`reflection/generic_reflection.rs`](reflection/generic_reflection.rs) | Registers concrete instances of generic types that may be used with reflection `reflection` | [`reflection/reflection.rs`](reflection/reflection.rs) | Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types +`generic_reflection` | [`reflection/generic_reflection.rs`](reflection/generic_reflection.rs) | Registers concrete instances of generic types that may be used with reflection `reflection_types` | [`reflection/reflection_types.rs`](reflection/reflection_types.rs) | Illustrates the various reflection types available `trait_reflection` | [`reflection/trait_reflection.rs`](reflection/trait_reflection.rs) | Allows reflection with trait objects @@ -172,8 +178,8 @@ Example | File | Description Example | File | Description --- | --- | --- `array_texture` | [`shader/array_texture.rs`](./shader/array_texture.rs) | Illustrates how to create a texture for use with a texture2DArray shader uniform variable -`mesh_custom_attribute` | [`shader/mesh_custom_attribute.rs`](./shader/mesh_custom_attribute.rs) | Illustrates how to add a custom attribute to a mesh and use it in a custom shader `hot_shader_reloading` | [`shader/hot_shader_reloading.rs`](./shader/hot_shader_reloading.rs) | Illustrates how to load shaders such that they can be edited while the example is still running +`mesh_custom_attribute` | [`shader/mesh_custom_attribute.rs`](./shader/mesh_custom_attribute.rs) | Illustrates how to add a custom attribute to a mesh and use it in a custom shader `shader_custom_material` | [`shader/shader_custom_material.rs`](./shader/shader_custom_material.rs) | Illustrates creating a custom material and a shader that uses it `shader_defs` | [`shader/shader_defs.rs`](./shader/shader_defs.rs) | Demonstrates creating a custom material that uses "shaders defs" (a tool to selectively toggle parts of a shader) @@ -189,8 +195,8 @@ Example | File | Description --- | --- | --- `button` | [`ui/button.rs`](./ui/button.rs) | Illustrates creating and updating a button `font_atlas_debug` | [`ui/font_atlas_debug.rs`](./ui/font_atlas_debug.rs) | Illustrates how FontAtlases are populated (used to optimize text rendering internally) -`text_debug` | [`ui/text_debug.rs`](./ui/text_debug.rs) | An example for debugging text layout `text` | [`ui/text.rs`](./ui/text.rs) | Illustrates creating and updating text +`text_debug` | [`ui/text_debug.rs`](./ui/text_debug.rs) | An example for debugging text layout `ui` | [`ui/ui.rs`](./ui/ui.rs) | Illustrates various features of Bevy UI ## Window @@ -206,7 +212,7 @@ Example | File | Description ## Android -#### Setup +### Setup ```sh rustup target add aarch64-linux-android armv7-linux-androideabi @@ -217,7 +223,7 @@ The Android SDK must be installed, and the environment variable `ANDROID_SDK_ROO 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 +### Build & Run To run on a device setup for Android development, run: @@ -238,7 +244,7 @@ min_sdk_version = 16 Please reference `cargo-apk` [README](https://crates.io/crates/cargo-apk) for other Android Manifest fields. -#### Old phones +### Old phones Bevy by default targets Android API level 29 in its examples which is the [Play Store's minimum API to upload or update apps](https://developer.android.com/distribute/best-practices/develop/target-sdk). Users of older phones may want to use an older API when testing. @@ -256,14 +262,14 @@ Example | File | Description ## iOS -#### Setup +### Setup ```sh rustup target add aarch64-apple-ios x86_64-apple-ios cargo install cargo-lipo ``` -#### Build & Run +### Build & Run Using bash: @@ -293,7 +299,7 @@ The Xcode build GUI will by default build the rust library for both `x86_64-apple-ios`, and `aarch64-apple-ios` which may take a while. If you'd like speed this up, you update the `IOS_TARGETS` User-Defined environment variable in the "`cargo_ios` target" to be either `x86_64-apple-ios` or -`aarch64-applo-ios` depending on your goal. +`aarch64-apple-ios` depending on your goal. Note: if you update this variable in Xcode, it will also change the default used for the `Makefile`. @@ -304,14 +310,14 @@ Example | File | Description ## WASM -#### Setup +### Setup ```sh rustup target add wasm32-unknown-unknown cargo install wasm-bindgen-cli ``` -#### Build & Run +### Build & Run Following is an example for `headless_wasm`. For other examples in wasm/ directory, change the `headless_wasm` in the following commands **and edit** `examples/wasm/index.html` @@ -331,6 +337,6 @@ basic-http-server examples/wasm Example | File | Description --- | --- | --- `hello_wasm` | [`wasm/hello_wasm.rs`](./wasm/hello_wasm.rs) | Runs a minimal example that logs "hello world" to the browser's console -`headless_wasm` | [`wasm/headless_wasm.rs`](./wasm/headless_wasm.rs) | Sets up a schedule runner and continually logs a counter to the browser's console `assets_wasm` | [`wasm/assets_wasm.rs`](./wasm/assets_wasm.rs) | Demonstrates how to load assets from wasm +`headless_wasm` | [`wasm/headless_wasm.rs`](./wasm/headless_wasm.rs) | Sets up a schedule runner and continually logs a counter to the browser's console `winit_wasm` | [`wasm/winit_wasm.rs`](./wasm/winit_wasm.rs) | Logs user input to the browser's console. Requires the `bevy_winit` features