diff --git a/.github/bors.toml b/.github/bors.toml index e796353e5c..be6caec1bb 100644 --- a/.github/bors.toml +++ b/.github/bors.toml @@ -1,5 +1,6 @@ status = [ "build", + "markdownlint", ] use_squash_merge = true diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml new file mode 100644 index 0000000000..c4365606ff --- /dev/null +++ b/.github/linters/.markdown-lint.yml @@ -0,0 +1,7 @@ +# Keep synced with duplicate in project root + +{ + "line-length": false, + "no-inline-html": false, + "no-trailing-punctuation": false, +} \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 56b5ba469c..d52c647b91 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,6 +35,22 @@ jobs: BUILD_ONLY: true TOKEN: fake-secret + 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: docker://ghcr.io/github/super-linter:slim-v4 + 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 }} + test-code: runs-on: ubuntu-latest steps: diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000000..1ed28e6258 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,7 @@ +# Keep synced with duplicate in .github/linters folder + +{ + "line-length": false, + "no-inline-html": false, + "no-trailing-punctuation": false, +} \ No newline at end of file diff --git a/content/learn/book/assets/hot-reloading/_index.md b/content/learn/book/assets/hot-reloading/_index.md index 3bb521da69..38153c8a30 100644 --- a/content/learn/book/assets/hot-reloading/_index.md +++ b/content/learn/book/assets/hot-reloading/_index.md @@ -9,4 +9,4 @@ insert_anchor_links = "right" TODO: demonstrate how to watch for changes to automatically hot reload assets when modified -Steal from https://github.com/bevyengine/bevy/blob/main/examples/asset/hot_asset_reloading.rs +Steal from [hot reloading example](https://github.com/bevyengine/bevy/blob/main/examples/asset/hot_asset_reloading.rs) diff --git a/content/learn/book/development-practices/fast-compiles/_index.md b/content/learn/book/development-practices/fast-compiles/_index.md index 7f9b3bd16e..10f1850344 100644 --- a/content/learn/book/development-practices/fast-compiles/_index.md +++ b/content/learn/book/development-practices/fast-compiles/_index.md @@ -29,15 +29,15 @@ TODO: explain why you might want faster compiles * **Arch**: `sudo pacman -S lld` * **Windows**: Ensure you have the latest [cargo-binutils](https://github.com/rust-embedded/cargo-binutils) - ```sh - cargo install -f cargo-binutils - rustup component add llvm-tools-preview - ``` + ```sh + cargo install -f cargo-binutils + rustup component add llvm-tools-preview + ``` - * **MacOS**: Modern LLD does not yet support MacOS, but we can use zld instead: `brew install michaeleisel/zld/zld` +* **MacOS**: Modern LLD does not yet support MacOS, but we can use zld instead: `brew install michaeleisel/zld/zld` * **Nightly Rust Compiler**: This gives access to the latest performance improvements and "unstable" optimizations - ```sh + ```sh # Install the nightly toolchain rustup toolchain install nightly # Configure your current project to use nightly (run this command within the project) diff --git a/content/learn/book/game-logic/system-ordering/_index.md b/content/learn/book/game-logic/system-ordering/_index.md index 3394b4cfa5..d4ec6f0227 100644 --- a/content/learn/book/game-logic/system-ordering/_index.md +++ b/content/learn/book/game-logic/system-ordering/_index.md @@ -16,4 +16,4 @@ TODO: explain SystemSets in the context of labels TODO: explain ambiguities -Steal from https://github.com/bevyengine/bevy/blob/main/examples/ecs/ecs_guide.rs#L282 +Steal from [ECS Guide](https://github.com/bevyengine/bevy/blob/main/examples/ecs/ecs_guide.rs#L282) diff --git a/content/learn/book/migration-guides/0.4-0.5/_index.md b/content/learn/book/migration-guides/0.4-0.5/_index.md index e72a41e09d..02c54ea4e7 100644 --- a/content/learn/book/migration-guides/0.4-0.5/_index.md +++ b/content/learn/book/migration-guides/0.4-0.5/_index.md @@ -62,6 +62,7 @@ commands.entity(entity).despawn(); `commands.spawn()` no longer accepts any parameters. To spawn bundles, use `commands.spawn_bundle(bundle)`. Similarly, rather than using `with(some_component)` to spawn an object with multiple components, you must now use `insert(some_component)`: + ```rust // 0.4 commands.spawn(some_bundle) @@ -78,6 +79,7 @@ commands.spawn() ``` Removing and adding components on entities has also been changed: + ```rust // 0.4 commands.insert_one(some_entity, SomeComponent); @@ -130,9 +132,11 @@ fn event_reader_system(mut my_event_reader: EventReader) { } } ``` + You no longer need two system parameters to read your events. One `EventReader` is sufficient. Following the above example of using an `EventReader` to read events, you can now use `EventWriter` to create new ones. + ```rust // 0.4 fn event_writer_system( @@ -188,7 +192,9 @@ TextBundle { ``` ### Scene must now be specified when loading a GLTF scene + Previously, you were able to load a GLTF scene asset with only a path. Now, you must include a fragment specifying the scene you want to load. If you only have one scene in the file, it's `#Scene0`. + ```rust // 0.4 asset_server.load("models/foo.glb"); @@ -266,9 +272,11 @@ fn some_system( ``` ### Cameras + `Camera3dBundle` is now known as `PerspectiveCameraBundle`, and `Camera2dBundle` is now known as `OrthographicCameraBundle`. `OrthographicCameraBundle` does not implement `Default`, so to change its transform at spawn while keeping everything else the same, consider something like the following: + ```rust let mut camera = OrthographicCameraBundle::new_2d(); camera.transform = Transform::from_translation(Vec3::new(0.0, 0.0, 5.0)); @@ -276,9 +284,11 @@ commands.spawn_bundle(camera); ``` ### Render API changes + `RasterizationStateDescriptor` no longer exists. Much of its functionality has been moved to other fields on `PipelineDescriptor`. `cull_mode`, for example, is now found in the `primitive: PrimitiveState` field. Buffers of type `Vec` can no longer be uploaded to the GPU directly due to limitations with `RenderResources` and the new `Byteable` requirement. Consider using a `Vec` instead, and inserting colors with `as_rgba_f32()` and `.into()` instead: + ```rust #[derive(RenderResources, Default, TypeUuid)] struct SomeShader { @@ -292,6 +302,7 @@ fn add_some_color(shader: SomeShader, color: Color) { ``` ### Shaders should now use `CameraViewProj` + The `ViewProj` matrix is now set via the name `CameraViewProj` rather than `Camera`. If you don't update this, bevy will fail silently and you won't be able to see anything! ```glsl @@ -307,8 +318,8 @@ layout(set = 0, binding = 0) uniform CameraViewProj { ``` ### Diagnostics -`PrintDiagnosticsPlugin` is now `LogDiagnosticsPlugin`. +`PrintDiagnosticsPlugin` is now `LogDiagnosticsPlugin`. ### System Ordering diff --git a/content/learn/book/migration-guides/0.5-0.6/_index.md b/content/learn/book/migration-guides/0.5-0.6/_index.md index a898cad928..4040ebb70c 100644 --- a/content/learn/book/migration-guides/0.5-0.6/_index.md +++ b/content/learn/book/migration-guides/0.5-0.6/_index.md @@ -284,7 +284,7 @@ This was done to accommodate the new [`SystemState`] which allows easier cached ### Vector casting functions are now named to match return type -The casting functions for [`IVec2`], [`DVec2`], [`UVec2`], and [`Vec2`] have all been changed from being named after their inner elements' cast target to what the entire "Vec" is being casted into. This affects all the different dimensions of the math vectors (i.e., [`Vec2`], [`Vec3` ]and [`Vec4`]). +The casting functions for [`IVec2`], [`DVec2`], [`UVec2`], and [`Vec2`] have all been changed from being named after their inner elements' cast target to what the entire "Vec" is being casted into. This affects all the different dimensions of the math vectors (i.e., [`Vec2`], [`Vec3`] and [`Vec4`]). ```rust // 0.5 @@ -343,7 +343,8 @@ SpriteBundle { [`SpriteBundle`]: https://docs.rs/bevy/0.6.0/bevy/sprite/struct.SpriteBundle.html [`Sprite`]: https://docs.rs/bevy/0.6.0/bevy/sprite/struct.Sprite.html -### Visible is now Visibility +### Visible is now Visibility + The [`Visible`] struct, which is used in a number of components to set visibility, was renamed to [`Visibility`]. Additionally, the field `is_transparent` was removed from the struct. For 3D, transparency can be set using the `alpha_mode` field on a material. Transparency is now automatically enabled for all objects in 2D. ```rust diff --git a/content/news/2020-08-10-introducing-bevy/index.md b/content/news/2020-08-10-introducing-bevy/index.md index db645e52a6..7e68717472 100644 --- a/content/news/2020-08-10-introducing-bevy/index.md +++ b/content/news/2020-08-10-introducing-bevy/index.md @@ -20,7 +20,7 @@ It has the following design goals: * Capable: Offer a complete 2D and 3D feature set * Simple: Easy for newbies to pick up, but infinitely flexible for power users -* Data Focused: Data-oriented architecture using the Entity Component System paradigm +* Data Focused: Data-oriented architecture using the Entity Component System paradigm * Modular: Use only what you need. Replace what you don't like * Fast: App logic should run quickly, and when possible, in parallel * Productive: Changes should compile quickly ... waiting isn't fun @@ -33,6 +33,7 @@ Bevy has a number of features that I think set it apart from other engines: * Productive Compile Times: Expect changes to compile in ~0.8-3.0 seconds with the "fast compiles" config It also has many features most people expect from a modern, general purpose engine: + * Cross Platform: Windows, MacOS, and Linux (with planned support for mobile and web) * 3D: Lights, meshes, textures, MSAA, and GLTF loading * Sprites: Render individual images as sprites, render from sprite sheets, and dynamically generate new sprite sheets @@ -45,11 +46,10 @@ It also has many features most people expect from a modern, general purpose engi * Hot Asset Reloading: Automatically reload changes to assets at runtime without recompiles or restarts * Events: Efficiently consume and produce Events from within ECS systems * Properties: Dynamically get and set component fields using a string version of their names -* Hierarchical Transforms: Create parent-child relationships between entities that propagate Transforms down the hierarchy +* Hierarchical Transforms: Create parent-child relationships between entities that propagate Transforms down the hierarchy That being said, Bevy is still in the very early stages. I consider it to be in the "prototyping" phase: features are missing, APIs will change, and documentation is sparse. I don't yet recommend using Bevy in serious projects unless you are willing to deal with gaps and instability. - Hopefully at this point you are either (1) jazzed about Bevy or (2) not reading anymore. If you want to dive in right now, [The Bevy Book](https://bevyengine.org/learn/book/introduction/) is the best place to get started. You can also keep reading to find out what the current state of Bevy is and where we'd like to take it. **Quick note to the reader**: in this article you will find text formatted like this: [`Texture`] @@ -97,7 +97,7 @@ fn main() { } ``` -And of course you can also create your own plugins. In fact, all engine and game logic is built using plugins. Hopefully now you understand what we mean by modular: you are free to add/remove plugins based on your project's unique needs. However I expect that most people will stick to +And of course you can also create your own plugins. In fact, all engine and game logic is built using plugins. Hopefully now you understand what we mean by modular: you are free to add/remove plugins based on your project's unique needs. However I expect that most people will stick to [`AddDefaultPlugins::add_default_plugins`] for simplicity, at least initially. [`AddDefaultPlugins::add_default_plugins`]: https://docs.rs/bevy/0.1.0/bevy/trait.AddDefaultPlugins.html#tymethod.add_default_plugins @@ -110,6 +110,7 @@ All Bevy engine and game logic is built on top of a custom [Entity Component Sys The ECS pattern encourages clean, decoupled designs by forcing you to break up your app data and logic into its core components. Unlike other Rust ECS implementations, which require complex lifetimes, traits, builder patterns, or macros, Bevy ECS uses normal Rust datatypes for all of these concepts: + * Components: normal Rust structs * Systems: normal Rust functions * Entities: a type containing a unique integer @@ -153,6 +154,7 @@ That is a complete self-contained Bevy app with automatic parallel system schedu ### Performance One of the reasons the ECS paradigm is so popular is that it has the potential to make game logic _super_ fast, primarily for these two reasons: + 1. Iteration Speed: Components are packed tightly together to optimize for cache-locality, which makes iterating over them blazing fast 2. Parallelism: Systems declare read/write dependencies, which enables automatic and efficient lock-free parallel scheduling @@ -166,7 +168,7 @@ Bevy ECS does both of these things about as well as it can. According to the pop ![ecs iter performance graph](ecs_build.svg) -Note that `ecs_bench` is a single threaded benchmark, so it doesn't illustrate the multi-threading capabilities of these framework. And as always, please be aware that `ecs_bench` is a micro benchmark and it doesn't illustrate the performance of a complex game. There is a lot of nuance in the ECS performance space and each of the ECS implementations above will perform differently under different workloads. +Note that `ecs_bench` is a single threaded benchmark, so it doesn't illustrate the multi-threading capabilities of these framework. And as always, please be aware that `ecs_bench` is a micro benchmark and it doesn't illustrate the performance of a complex game. There is a lot of nuance in the ECS performance space and each of the ECS implementations above will perform differently under different workloads. I have pushed my version of `ecs_bench` [here](https://github.com/cart/ecs_bench) if anyone wants to double-check my methodology. For some reasonable amount of time I will post updates here if anyone reports a problem or my results are not (on average) reproducible. @@ -197,6 +199,7 @@ fn system(mut query: Query<(&Position, &mut Velocity)>) { ``` #### Change Detection + ```rs // Added queries only run when the given component has been added fn system(mut query: Query>) { @@ -228,6 +231,7 @@ fn system(mut query: Query<&Position>>) { ``` #### Multiple Queries + ```rs fn system(mut wall_query: Query<&Wall>, mut player_query: Query<&Player>) { for player in &mut player_query.iter() { @@ -241,6 +245,7 @@ fn system(mut wall_query: Query<&Wall>, mut player_query: Query<&Player>) { ``` #### Entity Queries and Direct Component Access + ```rs fn system(mut entity_query: Query, mut player_query: Query<&Player>) { for entity in &mut entity_query.iter() { @@ -252,6 +257,7 @@ fn system(mut entity_query: Query, mut player_query: Query<&Player>) { ``` #### Resources + ```rs // Res and ResMut access global resources fn system(time: Res