Skip to content

Commit

Permalink
Grammar: "api" -> "API"
Browse files Browse the repository at this point in the history
  • Loading branch information
wackbyte committed Sep 27, 2023
1 parent 34bfd89 commit 1b6af08
Show file tree
Hide file tree
Showing 19 changed files with 43 additions and 43 deletions.
2 changes: 1 addition & 1 deletion content/learn/book/getting-started/plugins/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Once again run `cargo run`.

You should hopefully notice two things:

* **A window should pop up**. This is because we now have {{rust_type(type="struct" crate="bevy_window" name="WindowPlugin")}}, which defines the window interface (but doesn't actually know how to make windows), and {{rust_type(type="struct" crate="bevy_winit" name="WinitPlugin")}} which uses the [winit library](https://github.com/rust-windowing/winit) to create a window using your OS's native window api.
* **A window should pop up**. This is because we now have {{rust_type(type="struct" crate="bevy_window" name="WindowPlugin")}}, which defines the window interface (but doesn't actually know how to make windows), and {{rust_type(type="struct" crate="bevy_winit" name="WinitPlugin")}} which uses the [winit library](https://github.com/rust-windowing/winit) to create a window using your OS's native window API.
* **Your console is now full of "hello" messages**: This is because {{rust_type(type="struct" crate="bevy" name="DefaultPlugins")}} adds an "event loop" to our application. Our App's ECS Schedule now runs in a loop once per "frame". We will resolve the console spam in a moment.

Note that `add_plugins(DefaultPlugins)` is equivalent to the following:
Expand Down
2 changes: 1 addition & 1 deletion content/learn/migration-guides/0.6-0.7/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ fn camera_system(cameras: Query<&Camera, With<FirstPassCamera>>) {
}
```

### [Remove the config api](https://github.com/bevyengine/bevy/pull/3633)
### [Remove the config API](https://github.com/bevyengine/bevy/pull/3633)

```rs
// 0.6
Expand Down
4 changes: 2 additions & 2 deletions content/learn/migration-guides/0.9-0.10/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -506,7 +506,7 @@ fn clear_events(mut reader: EventReader<SomeEvent>) {

`Archetype` indices and `Table` rows have been newtyped as `ArchetypeRow` and `TableRow`.

### [Round out the untyped api s](https://github.com/bevyengine/bevy/pull/7009)
### [Round out the untyped APIs](https://github.com/bevyengine/bevy/pull/7009)

<div class="migration-guide-area-tags">
<div class="migration-guide-area-tag">ECS</div>
Expand Down Expand Up @@ -1059,7 +1059,7 @@ Removed `SetShadowViewBindGroup`, `queue_shadow_view_bind_group()`, and `LightMe
<div class="migration-guide-area-tag">Assets</div>
</div>

No api changes are required, but it's possible that your gltf meshes look different
No API changes are required, but it's possible that your gltf meshes look different

### [Send emissive color to uniform as linear instead of sRGB](https://github.com/bevyengine/bevy/pull/7897)

Expand Down
2 changes: 1 addition & 1 deletion content/news/2020-08-10-introducing-bevy/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -1127,7 +1127,7 @@ Right now Bevy can render plenty fast for most use cases, but when it comes to r

### Canvas

Right now the only way to draw UI and 2D scenes is via sprites and rectangles. Bevy needs an immediate-mode drawing api capable of drawing anti-aliased curves and shapes. This can then be used to do code-driven drawing of things like rounded corners in Bevy UI, performance graphs in the editor, etc. It's very possible that we will integrate projects like [pathfinder](https://github.com/servo/pathfinder) or [lyon](https://github.com/nical/lyon) for this.
Right now the only way to draw UI and 2D scenes is via sprites and rectangles. Bevy needs an immediate-mode drawing API capable of drawing anti-aliased curves and shapes. This can then be used to do code-driven drawing of things like rounded corners in Bevy UI, performance graphs in the editor, etc. It's very possible that we will integrate projects like [pathfinder](https://github.com/servo/pathfinder) or [lyon](https://github.com/nical/lyon) for this.

### Animation

Expand Down
4 changes: 2 additions & 2 deletions content/news/2020-09-19-bevy-0.2/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ fn system(pool: Res<ComputeTaskPool>, mut query: Query<&mut Transform>) {
}
```

This provides a nice functional api (similar to Rayon) that runs on top of the new `bevy_tasks` system. It breaks the query up into 32 "batches" and runs each batch as a different task in the bevy task system.
This provides a nice functional API (similar to Rayon) that runs on top of the new `bevy_tasks` system. It breaks the query up into 32 "batches" and runs each batch as a different task in the bevy task system.

## Transform System Rewrite

Expand Down Expand Up @@ -97,7 +97,7 @@ However this approach also has some pretty serious downsides:
* Very hard to reason about. There are 5 components users need to think about and they all interact with each other differently.
* Setting a Transform to a specific matrix value (ex: `Mat4::look_at()`) was extremely cumbersome, and the value would be immediately overwritten unless the user explicitly disabled component syncing.

Given these issues, we decided to move to a single unified local-to-parent `Transform` component as the source of truth, and a computed `GlobalTransform` component for world-space transforms. We think this api will be much easier to use and to reason about. [Unity is also considering a similar Transform rework for their ECS](https://gist.github.com/joeante/79d25ec3a0e86436e53eb74f3ac82c0c) and a lot of discussion on this topic happened in this [Amethyst Forum Thread](https://community.amethyst.rs/t/legion-transform-design-discussion).
Given these issues, we decided to move to a single unified local-to-parent `Transform` component as the source of truth, and a computed `GlobalTransform` component for world-space transforms. We think this API will be much easier to use and to reason about. [Unity is also considering a similar Transform rework for their ECS](https://gist.github.com/joeante/79d25ec3a0e86436e53eb74f3ac82c0c) and a lot of discussion on this topic happened in this [Amethyst Forum Thread](https://community.amethyst.rs/t/legion-transform-design-discussion).

## Joystick/Gamepad Input

Expand Down
20 changes: 10 additions & 10 deletions content/news/2020-11-03-bevy-0.3/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,15 +148,15 @@ let mesh = asset_server.load("my_scene.gltf#Mesh0/Primitive0");

### AssetIo Trait

The `AssetServer` is now backed by the `AssetIo` trait. This allows us to load assets from whatever storage we want. This means on desktop we now load from the filesystem, on Android we use the Android Asset Manager, and on the web we make HTTP requests using the `fetch()` api.
The `AssetServer` is now backed by the `AssetIo` trait. This allows us to load assets from whatever storage we want. This means on desktop we now load from the filesystem, on Android we use the Android Asset Manager, and on the web we make HTTP requests using the `fetch()` API.

### Asset Dependencies

Assets can now depend on other assets, which will automatically be loaded when the original asset is loaded. This is useful when loading something like a "scene" which might reference other asset sources. We utilize this in our new GLTF loader.

### Removed AssetServer::load_sync()

This might rustle some feathers, but `AssetServer::load_sync()` had to go! This api wasn't WASM friendly, encouraged users to block game execution for the sake of convenience (which causes "hitching"), and was incompatible with the new AssetLoader api. Asset loading is now always asynchronous. Users of `load_sync()` should instead `load()` their assets, check load status in their systems, and change game state accordingly.
This might rustle some feathers, but `AssetServer::load_sync()` had to go! This API wasn't WASM friendly, encouraged users to block game execution for the sake of convenience (which causes "hitching"), and was incompatible with the new AssetLoader API. Asset loading is now always asynchronous. Users of `load_sync()` should instead `load()` their assets, check load status in their systems, and change game state accordingly.

## GLTF Scene Loader

Expand Down Expand Up @@ -226,7 +226,7 @@ _Why did this take so long? Why would removing a single `&mut` be hard?_

It's a long story! In summary:

* The old api looked the way it did for a reason. It was the result of good design choices that protect against unsafe memory access in a parallel environment.
* The old API looked the way it did for a reason. It was the result of good design choices that protect against unsafe memory access in a parallel environment.
* `query.iter()` didn't actually return an iterator. It returned a _wrapper_ that held an atomic lock on the component storages. The same was true for the type returned by `query.entity()`
* Removing these "wrapper types" would have allowed unsafe behavior because another Query could access the same components in a way that violated Rust's mutability rules.
* Due to the iterator implementation and quirks in the rust compiler, removing the wrapper type _tanked_ iteration performance by about ~2-3x.
Expand Down Expand Up @@ -283,7 +283,7 @@ Note: these numbers are for getting a component 100,000 times, not for an indivi

This is where the big wins were. By removing locks and safety checks from Query systems, we were able to _significantly_ reduce the cost of retrieving a specific entity's component from within a system.

I included a comparison to [Legion ECS](https://github.com/amethyst/legion) (another great archetypal ECS with a parallel scheduler) to illustrate why Bevy's new approach is so cool. Legion exposes a direct "world like" api (called a SubWorld) in its systems. The SubWorld's entry api _cannot_ know ahead of time what types will be passed into it, which means it _must_ do (relatively) expensive safety checks to ensure the user doesn't request access to something they shouldn't.
I included a comparison to [Legion ECS](https://github.com/amethyst/legion) (another great archetypal ECS with a parallel scheduler) to illustrate why Bevy's new approach is so cool. Legion exposes a direct "world like" API (called a SubWorld) in its systems. The SubWorld's entry API _cannot_ know ahead of time what types will be passed into it, which means it _must_ do (relatively) expensive safety checks to ensure the user doesn't request access to something they shouldn't.

Bevy's scheduler pre-checks `Queries` once ahead of time, which allows systems to access their results without any additional checks.

Expand All @@ -294,7 +294,7 @@ The test was to lookup (and modify) a specific entity's component 100,000 times
* legion (world): Direct `World` access using `let entry = world.entry(entity); entry.get_component_mut::<A>()`
* legion (system): A system with `SubWorld` access using `let entry = world.entry(entity); entry.get_component_mut::<A>()`

It's worth noting that using `query.get_component::<T>(entity)` instead of `query.get(entity)` does require safety checks, for the same reason the legion entry api does. We cannot know ahead of time what component type a caller will pass into the method, which means we _must_ check it to make sure it matches the `Query`.
It's worth noting that using `query.get_component::<T>(entity)` instead of `query.get(entity)` does require safety checks, for the same reason the legion entry API does. We cannot know ahead of time what component type a caller will pass into the method, which means we _must_ check it to make sure it matches the `Query`.

Additionally, here are some relevant [ecs_bench_suite](https://github.com/rust-gamedev/ecs_bench_suite) results (omitted benchmarks had no significant change):

Expand Down Expand Up @@ -354,17 +354,17 @@ Rendering meshes often involves using vertex "indices" to cut down on duplicate

Transforms are important to get right. They are used in many slices of the engine, user code touches them constantly, and they are relatively expensive to compute: especially transform hierarchies.

In the last release, we vastly simplified Bevy's transform system to use a consolidated `Transform` and `GlobalTransform` instead of multiple separate `Translation`, `Rotation`, and `Scale` components (which were synced to `Transform` and `GlobalTransform`). This made the user-facing api/dataflow simpler, as well as the underlying implementation. The `Transform` component was backed by a 4x4 matrix. I pressed the big green "merge" button ... happy that we had solved the Transform problem once and for all!
In the last release, we vastly simplified Bevy's transform system to use a consolidated `Transform` and `GlobalTransform` instead of multiple separate `Translation`, `Rotation`, and `Scale` components (which were synced to `Transform` and `GlobalTransform`). This made the user-facing API/dataflow simpler, as well as the underlying implementation. The `Transform` component was backed by a 4x4 matrix. I pressed the big green "merge" button ... happy that we had solved the Transform problem once and for all!

It turns out there was still more work to be done! [@AThilenius pointed out](https://github.com/bevyengine/bevy/issues/229#issuecomment-698953161) that using a 4x4 matrix as the source of truth for an affine transform accumulates error over time. Additionally, the Transform api was still a little cumbersome to use. [At the suggestion of @termhn](https://github.com/bevyengine/bevy/issues/229#issuecomment-699172675) we decided to investigate using a "similarity" as the source of truth. This had the following benefits:
It turns out there was still more work to be done! [@AThilenius pointed out](https://github.com/bevyengine/bevy/issues/229#issuecomment-698953161) that using a 4x4 matrix as the source of truth for an affine transform accumulates error over time. Additionally, the Transform API was still a little cumbersome to use. [At the suggestion of @termhn](https://github.com/bevyengine/bevy/issues/229#issuecomment-699172675) we decided to investigate using a "similarity" as the source of truth. This had the following benefits:

1. no more error accumulation
2. we could directly expose translation/rotation/scale fields, which simplified the api significantly
2. we could directly expose translation/rotation/scale fields, which simplified the API significantly
3. cheaper to store and cheaper to compute hierarchies in some cases

We collectively decided this was a good path forward and now we have a re-rewrite that is even better. Yes this is _another_ breaking change, but thats why we label Bevy as being in the "experimentation phase". Now is the time to break things as often as possible to ensure that we find good apis that will stand the test of time.

This is what the new `Transform` api looks like in a Bevy ECS system:
This is what the new `Transform` API looks like in a Bevy ECS system:

```rust
fn system(mut transform: Mut<Transform>) {
Expand Down Expand Up @@ -444,7 +444,7 @@ app.add_plugins(HelloWorldPlugins);

<div class="release-feature-authors">authors: @mockersf</div>

Bevy provides a backend-agnostic windowing api. Up until this point, window settings could only be set once at app startup. If you wanted to set window settings dynamically, you had to directly interact with window backends (ex: winit).
Bevy provides a backend-agnostic windowing API. Up until this point, window settings could only be set once at app startup. If you wanted to set window settings dynamically, you had to directly interact with window backends (ex: winit).

In this release we added the ability to dynamically set window properties at runtime using the Bevy window abstraction:

Expand Down
4 changes: 2 additions & 2 deletions content/news/2020-12-19-bevy-0.4/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -481,7 +481,7 @@ The new text layout system uses glyph_brush_layout, which fixes the layout bugs

<div class="release-feature-authors">authors: @cart</div>

Bevy's render api was built to be easy to use and extend. I wanted to nail down a good api first, but that resulted in a number of performance TODOs that caused some pretty serious overhead.
Bevy's render API was built to be easy to use and extend. I wanted to nail down a good API first, but that resulted in a number of performance TODOs that caused some pretty serious overhead.

For **Bevy 0.4** I decided to resolve as many of those TODOs as I could. There is still plenty more to do (like instancing and batching), but Bevy already performs _much_ better than it did before.

Expand Down Expand Up @@ -733,7 +733,7 @@ There is still a bit more work to be done here. While Bevy UI renders images and

Bevy's Timer component/resource got a number of quality-of-life improvements: pausing, field accessor methods, ergonomics improvements, and internal refactoring / code quality improvements. Timer Components also no longer tick by default. Timer resources and newtyped Timer components couldn't tick by default, so it was a bit inconsistent to have the (relatively uncommon) "unwrapped component Timer" auto-tick.

The timer api now looks like this:
The timer API now looks like this:

```rust

Expand Down
Loading

0 comments on commit 1b6af08

Please sign in to comment.