Example time api (#10204)

# Objective

- Fixes #10133 

## Solution

- Add a new example that focuses on using `Virtual` time

## Changelog

### Added

- new `virtual_time` example

### Changed

- moved `time` & `timers` examples to the new `examples/time` folder

Cargo.toml

@@ -1420,27 +1420,39 @@ description = "Illustrates creating custom system parameters with `SystemParam`"
 category = "ECS (Entity Component System)"
 wasm = false
 
+# Time
 [[example]]
 name = "time"
-path = "examples/ecs/time.rs"
+path = "examples/time/time.rs"
 
 [package.metadata.example.time]
 name = "Time handling"
 description = "Explains how Time is handled in ECS"
-category = "ECS (Entity Component System)"
+category = "Time"
+wasm = false
+
+[[example]]
+name = "virtual_time"
+path = "examples/time/virtual_time.rs"
+
+[package.metadata.example.virtual_time]
+name = "Virtual time"
+description = "Shows how `Time<Virtual>` can be used to pause, resume, slow down and speed up a game."
+category = "Time"
 wasm = false
 
 [[example]]
 name = "timers"
-path = "examples/ecs/timers.rs"
+path = "examples/time/timers.rs"
 doc-scrape-examples = true
 
 [package.metadata.example.timers]
 name = "Timers"
 description = "Illustrates ticking `Timer` resources inside systems and handling their state"
-category = "ECS (Entity Component System)"
+category = "Time"
 wasm = false
 
+
 # Games
 [[example]]
 name = "alien_cake_addict"

examples/README.md

@@ -53,6 +53,7 @@ git checkout v0.4.0
   - [Scene](#scene)
   - [Shaders](#shaders)
   - [Stress Tests](#stress-tests)
+  - [Time](#time)
   - [Tools](#tools)
   - [Transforms](#transforms)
   - [UI (User Interface)](#ui-user-interface)
@@ -233,8 +234,6 @@ Example | Description
 [System Closure](../examples/ecs/system_closure.rs) | Show how to use closures as systems, and how to configure `Local` variables by capturing external state
 [System Parameter](../examples/ecs/system_param.rs) | Illustrates creating custom system parameters with `SystemParam`
 [System Piping](../examples/ecs/system_piping.rs) | Pipe the output of one system into a second, allowing you to handle any errors gracefully
-[Time handling](../examples/ecs/time.rs) | Explains how Time is handled in ECS
-[Timers](../examples/ecs/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state
 
 ## Games
 
@@ -326,6 +325,14 @@ Example | Description
 [Text Pipeline](../examples/stress_tests/text_pipeline.rs) | Text Pipeline benchmark
 [Transform Hierarchy](../examples/stress_tests/transform_hierarchy.rs) | Various test cases for hierarchy and transform propagation performance
 
+## Time
+
+Example | Description
+--- | ---
+[Time handling](../examples/time/time.rs) | Explains how Time is handled in ECS
+[Timers](../examples/time/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state
+[Virtual time](../examples/time/virtual_time.rs) | Shows how `Time<Virtual>` can be used to pause, resume, slow down and speed up a game.
+
 ## Tools
 
 Example | Description

examples/time/virtual_time.rs

@@ -0,0 +1,218 @@
+//! Shows how `Time<Virtual>` can be used to pause, resume, slow down
+//! and speed up a game.
+
+use std::time::Duration;
+
+use bevy::{
+    input::common_conditions::input_just_pressed, prelude::*,
+    time::common_conditions::on_real_timer,
+};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Startup, setup)
+        .add_systems(
+            Update,
+            (
+                move_virtual_time_sprites,
+                move_real_time_sprites,
+                toggle_pause.run_if(input_just_pressed(KeyCode::Space)),
+                change_time_speed::<1>.run_if(input_just_pressed(KeyCode::Up)),
+                change_time_speed::<-1>.run_if(input_just_pressed(KeyCode::Down)),
+                (update_virtual_time_info_text, update_real_time_info_text)
+                    // update the texts on a timer to make them more readable
+                    // `on_timer` run condition uses `Virtual` time meaning it's scaled
+                    // and would result in the UI updating at different intervals based
+                    // on `Time<Virtual>::relative_speed` and `Time<Virtual>::is_paused()`
+                    .run_if(on_real_timer(Duration::from_millis(250))),
+            ),
+        )
+        .run();
+}
+
+/// `Real` time related marker
+#[derive(Component)]
+struct RealTime;
+
+/// `Virtual` time related marker
+#[derive(Component)]
+struct VirtualTime;
+
+/// Setup the example
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>, mut time: ResMut<Time<Virtual>>) {
+    // start with double `Virtual` time resulting in one of the sprites moving at twice the speed
+    // of the other sprite which moves based on `Real` (unscaled) time
+    time.set_relative_speed(2.);
+
+    commands.spawn(Camera2dBundle::default());
+
+    let virtual_color = Color::GOLD;
+    let sprite_scale = Vec2::splat(0.5).extend(1.);
+    let texture_handle = asset_server.load("branding/icon.png");
+
+    // the sprite moving based on real time
+    commands.spawn((
+        SpriteBundle {
+            texture: texture_handle.clone(),
+            transform: Transform::from_scale(sprite_scale),
+            ..default()
+        },
+        RealTime,
+    ));
+
+    // the sprite moving based on virtual time
+    commands.spawn((
+        SpriteBundle {
+            texture: texture_handle,
+            sprite: Sprite {
+                color: virtual_color,
+                ..default()
+            },
+            transform: Transform {
+                scale: sprite_scale,
+                translation: Vec3::new(0., -160., 0.),
+                ..default()
+            },
+            ..default()
+        },
+        VirtualTime,
+    ));
+
+    // info UI
+    let font_size = 40.;
+
+    commands
+        .spawn(NodeBundle {
+            style: Style {
+                display: Display::Flex,
+                justify_content: JustifyContent::SpaceBetween,
+                width: Val::Percent(100.),
+                position_type: PositionType::Absolute,
+                top: Val::Px(0.),
+                padding: UiRect::all(Val::Px(20.0)),
+                ..default()
+            },
+            ..default()
+        })
+        .with_children(|builder| {
+            // real time info
+            builder.spawn((
+                TextBundle::from_section(
+                    "",
+                    TextStyle {
+                        font_size,
+                        ..default()
+                    },
+                ),
+                RealTime,
+            ));
+
+            // keybindings
+            builder.spawn(
+                TextBundle::from_section(
+                    "CONTROLS\nUn/Pause: Space\nSpeed+: Up\nSpeed-: Down",
+                    TextStyle {
+                        font_size,
+                        color: Color::rgb(0.85, 0.85, 0.85),
+                        ..default()
+                    },
+                )
+                .with_text_alignment(TextAlignment::Center),
+            );
+
+            // virtual time info
+            builder.spawn((
+                TextBundle::from_section(
+                    "",
+                    TextStyle {
+                        font_size,
+                        color: virtual_color,
+                        ..default()
+                    },
+                )
+                .with_text_alignment(TextAlignment::Right),
+                VirtualTime,
+            ));
+        });
+}
+
+/// Move sprites using `Real` (unscaled) time
+fn move_real_time_sprites(
+    mut sprite_query: Query<&mut Transform, (With<Sprite>, With<RealTime>)>,
+    // `Real` time which is not scaled or paused
+    time: Res<Time<Real>>,
+) {
+    for mut transform in sprite_query.iter_mut() {
+        // move roughly half the screen in a `Real` second
+        // when the time is scaled the speed is going to change
+        // and the sprite will stay still the the time is paused
+        transform.translation.x = get_sprite_translation_x(time.elapsed_seconds());
+    }
+}
+
+/// Move sprites using `Virtual` (scaled) time
+fn move_virtual_time_sprites(
+    mut sprite_query: Query<&mut Transform, (With<Sprite>, With<VirtualTime>)>,
+    // the default `Time` is either `Time<Virtual>` in regular systems
+    // or `Time<Fixed>` in fixed timestep systems so `Time::delta()`,
+    // `Time::elapsed()` will return the appropriate values either way
+    time: Res<Time>,
+) {
+    for mut transform in sprite_query.iter_mut() {
+        // move roughly half the screen in a `Virtual` second
+        // when time is scaled using `Time<Virtual>::set_relative_speed` it's going
+        // to move at a different pace and the sprite will stay still when time is
+        // `Time<Virtual>::is_paused()`
+        transform.translation.x = get_sprite_translation_x(time.elapsed_seconds());
+    }
+}
+
+fn get_sprite_translation_x(elapsed: f32) -> f32 {
+    elapsed.sin() * 500.
+}
+
+/// Update the speed of `Time<Virtual>.` by `DELTA`
+fn change_time_speed<const DELTA: i8>(mut time: ResMut<Time<Virtual>>) {
+    let time_speed = (time.relative_speed() + DELTA as f32)
+        .round()
+        .clamp(0.25, 5.);
+
+    // set the speed of the virtual time to speed it up or slow it down
+    time.set_relative_speed(time_speed);
+}
+
+/// pause or resume `Relative` time
+fn toggle_pause(mut time: ResMut<Time<Virtual>>) {
+    if time.is_paused() {
+        time.unpause();
+    } else {
+        time.pause();
+    }
+}
+
+/// Update the `Real` time info text
+fn update_real_time_info_text(time: Res<Time<Real>>, mut query: Query<&mut Text, With<RealTime>>) {
+    for mut text in &mut query {
+        text.sections[0].value = format!(
+            "REAL TIME\nElapsed: {:.1}\nDelta: {:.5}\n",
+            time.elapsed_seconds(),
+            time.delta_seconds(),
+        );
+    }
+}
+
+/// Update the `Virtual` time info text
+fn update_virtual_time_info_text(
+    time: Res<Time<Virtual>>,
+    mut query: Query<&mut Text, With<VirtualTime>>,
+) {
+    for mut text in &mut query {
+        text.sections[0].value = format!(
+            "VIRTUAL TIME\nElapsed: {:.1}\nDelta: {:.5}\nSpeed: {:.2}",
+            time.elapsed_seconds(),
+            time.delta_seconds(),
+            time.relative_speed()
+        );
+    }
+}