Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-21 12:13:25 +00:00
Code Issues Projects Releases Packages Wiki Activity

Cleanup of Markdown Files and add CI Checking (#1463)

Browse source 
I have run the VSCode Extension [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) on all Markdown Files in the Repo.
The provided Rules are documented here: https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md

Rules I didn't follow/fix:
* MD024/no-duplicate-heading
  * Changelog: Here Heading will always repeat.
  * Examples Readme: Platform-specific documentation should be symmetrical.
* MD025/single-title
* MD026/no-trailing-punctuation
  * Caused by the ! in "Hello, World!".
* MD033/no-inline-html
  * The plugins_guidlines file does need HTML, so the shown badges aren't downscaled too much.
* ~~MD036/no-emphasis-as-heading:~~
  * ~~This Warning only Appears in the Github Issue Templates and can be ignored.~~
* ~~MD041/first-line-heading~~
  * ~~Only appears in the Readme for the AlienCake example Assets, which is unimportant.~~

---

I also sorted the Examples in the Readme and Cargo.toml in this order/Priority:
* Topic/Folder
* Introductionary Examples
* Alphabetical Order

The explanation for each case, where it isn't Alphabetical :
* Diagnostics
  * log_diagnostics: The usage of inbuild Diagnostics is more important than creating your own.
* ECS (Entity Component System)
  * ecs_guide: The guide should be read, before diving into other Features.
* Reflection
  * reflection: Basic Explanation should be read, before more advanced Topics.
* WASM Examples
  * hello_wasm: It's "Hello, World!".
This commit is contained in:
MinerSebas 2021-02-22 04:50:05 +00:00
parent e5b0c65c86
commit c9f19d8663
18 changed files with 224 additions and 125 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/CONTRIBUTING.md vendored
View file

@ -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/).
[The Book](https://bevyengine.org/learn/book/introduction/).

12
.github/ISSUE_TEMPLATE/bug_report.md vendored
View file

@ -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.

8
.github/ISSUE_TEMPLATE/feature_request.md vendored
View file

@ -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.

1
.github/bors.toml vendored
View file

@ -6,6 +6,7 @@ status = [
"build-wasm (stable, ubuntu-latest)",
"build-wasm (nightly, ubuntu-latest)",
"build-android",
"markdownlint",
]
use_squash_merge = true

3
.github/linters/.markdown-lint.yml vendored Normal file
View file

@ -0,0 +1,3 @@
{
"MD013": false
}

21
.github/workflows/ci.yml vendored
View file

@ -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 }}

20
CHANGELOG.md
View file

@ -1,3 +1,6 @@
<!-- MD024 - We want repeated headings in a changelog file -->
<!-- markdownlint-disable-file MD024 -->
# 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<T>` 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

6
CREDITS.md
View file

@ -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)
* Environment maps (`.hdr` files) from [HDRIHaven](https://hdrihaven.com) (CC0 license)

155
Cargo.toml
View file

@ -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,22 +273,7 @@ path = "examples/game/alien_cake_addict.rs"
name = "breakout"
path = "examples/game/breakout.rs"
[[example]]
name = "mouse_input"
path = "examples/input/mouse_input.rs"
[[example]]
name = "mouse_input_events"
path = "examples/input/mouse_input_events.rs"
[[example]]
name = "keyboard_input"
path = "examples/input/keyboard_input.rs"
[[example]]
name = "keyboard_input_events"
path = "examples/input/keyboard_input_events.rs"
# Input
[[example]]
name = "char_input_events"
path = "examples/input/char_input_events.rs"
@ -289,6 +286,22 @@ path = "examples/input/gamepad_input.rs"
name = "gamepad_input_events"
path = "examples/input/gamepad_input_events.rs"
[[example]]
name = "keyboard_input"
path = "examples/input/keyboard_input.rs"
[[example]]
name = "keyboard_input_events"
path = "examples/input/keyboard_input_events.rs"
[[example]]
name = "mouse_input"
path = "examples/input/mouse_input.rs"
[[example]]
name = "mouse_input_events"
path = "examples/input/mouse_input_events.rs"
[[example]]
name = "touch_input"
path = "examples/input/touch_input.rs"
@ -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"

2
README.md
View file

@ -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.

2
assets/models/AlienCake/README.md
View file

@ -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)

2
crates/bevy_ecs/README.md
View file

@ -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.
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.

4
crates/bevy_reflect/README.md
View file

@ -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::<u32>() {
println!("{} is a u32 with the value: {}", field_name, *value);
}
}
}
```

6
crates/bevy_tasks/README.md
View file

@ -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

47
docs/linters.md Normal file
View file

@ -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).

6
docs/linux_dependencies.md
View file

@ -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

10
docs/plugins_guidelines.md
View file

@ -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.
<!-- MD033 - The Badges could be downsized, without the inline HTML due to the large code colum -->
<!-- markdownlint-disable-next-line MD033 -->
|<div style="width:100px">badge</div>|<div style="width:200px">description</div>|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)`|

42
examples/README.md
View file

@ -1,3 +1,6 @@
<!-- MD024 - The Headers from the Platform-Specific Examples should be identical -->
<!-- markdownlint-disable-file MD024 -->
# 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 <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
<!-- MD026 - Hello, World! looks better with the ! -->
<!-- markdownlint-disable-next-line MD026 -->
## 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