From 2a7c0b29d4174a7e42facea5e716c8df13851a0e Mon Sep 17 00:00:00 2001
From: Cameron <51241057+maniwani@users.noreply.github.com>
Date: Thu, 26 Oct 2023 19:05:45 -0700
Subject: [PATCH] 0.12: Add section on `Time`/`FixedTime` changes (#770)

Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
---
 content/news/2023-10-21-bevy-0.12/index.md | 40 ++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/content/news/2023-10-21-bevy-0.12/index.md b/content/news/2023-10-21-bevy-0.12/index.md
index 6b93fa692d..dc73129313 100644
--- a/content/news/2023-10-21-bevy-0.12/index.md
+++ b/content/news/2023-10-21-bevy-0.12/index.md
@@ -269,6 +269,46 @@ world.run_system_once(increment); // prints 2
 
 This is great for unit testing systems and queries, and it's both lower overhead and simpler to use. However, there is one caveat. Some systems have state, either in the form of `Local` arguments, change detection, or `EventReader`s. This state isn't saved between two `run_system_once` calls, creating odd behavior. The `Local`s reset every run, while change detection will _always_ detect data as added/changed. Be careful and you'll be alright.
 
+## Unified `Time`
+
+<div class="release-feature-authors">authors: @nakedible @maniwani @alice-i-cecile</div>
+
+Bevy 0.12 brings two major quality of life improvements to `FixedUpdate`.
+
+- `Time` now returns the contextually correct values for systems running in `FixedUpdate`. (As such, `FixedTime` has been removed.)
+- `FixedUpdate` can no longer snowball into a "death spiral" (where the app freezes because `FixedUpdate` steps are enqueued faster than it can run them).
+
+The `FixedUpdate` schedule and its companion `FixedTime` resource were introduced in Bevy 0.10, and it soon became apparent that `FixedTime` was lacking. Its methods were different from `Time` and it didn't even track "total time elapsed" like `Time` did, to name a few examples. Having two different "time" APIs also meant you had to write systems to specifically support "fixed timestep" or "variable timestep" and not both. It was desirable to not have this split as it can lead to incompatibilities between plugins down the road (which is sometimes the case with plugins in other game engines).
+
+Now, you can just write systems that read `Time` and schedule them in either context.
+
+```rust
+// This system will see a constant delta time if scheduled in `FixedUpdate` or
+// a variable delta time if scheduled in `Update`.
+fn integrate_velocity(
+    mut query: Query<(&mut Transfrom, &Velocity)>,
+    time: Res<Time>,
+) {
+    for (mut transform, velocity) in &mut query {
+        transform.translation.x += velocity.x * time.delta_seconds();
+        transform.translation.y += velocity.y * time.delta_seconds();
+    }
+}
+```
+
+Most systems should continue to use `Time`, but behind the scenes, the methods from previous APIs have been refactored into four clocks:
+
+- `Time<Real>`
+- `Time<Virtual>`
+- `Time<Fixed>`
+- `Time<()>`
+
+`Time<Real>` measures the true, unedited frame and app durations. For diagnostics/profiling, use that one. It's also used to derive the others. `Time<Virtual>` can be sped up, slowed down, and paused, and `Time<Fixed>` chases `Time<Virtual>` in fixed increments. Lastly, `Time<()>` is automatically overwritten with the current value of `Time<Fixed>` or `Time<Virtual>` upon entering or exiting `FixedUpdate`. When a system borrows `Time`, it actually borrows `Time<()>`.
+
+Try the new `time` example to get a better feel for these resources.
+
+The fix for the windup problem was limiting how much `Time<Virtual>` can advance from a single frame. This then limits how many times `FixedUpdate` can be queued for the next frame, and so things like frame lag or your computer waking up from a long sleep can no longer cause a death spiral. So now, the app won't freeze, but things happening in `FixedUpdate` will appear to slow down since it'll be running at a temporarily reduced rate.
+
 ## <a name="what-s-next"></a>What's Next?
 
 We have plenty of work that is pretty much finished and is therefore very likely to land in **Bevy 0.13**: