mirror of
https://github.com/bevyengine/bevy
synced 2024-11-22 20:53:53 +00:00
3d79dc4cdc
# Objective Current `FixedTime` and `Time` have several problems. This pull aims to fix many of them at once. - If there is a longer pause between app updates, time will jump forward a lot at once and fixed time will iterate on `FixedUpdate` for a large number of steps. If the pause is merely seconds, then this will just mean jerkiness and possible unexpected behaviour in gameplay. If the pause is hours/days as with OS suspend, the game will appear to freeze until it has caught up with real time. - If calculating a fixed step takes longer than specified fixed step period, the game will enter a death spiral where rendering each frame takes longer and longer due to more and more fixed step updates being run per frame and the game appears to freeze. - There is no way to see current fixed step elapsed time inside fixed steps. In order to track this, the game designer needs to add a custom system inside `FixedUpdate` that calculates elapsed or step count in a resource. - Access to delta time inside fixed step is `FixedStep::period` rather than `Time::delta`. This, coupled with the issue that `Time::elapsed` isn't available at all for fixed steps, makes it that time requiring systems are either implemented to be run in `FixedUpdate` or `Update`, but rarely work in both. - Fixes #8800 - Fixes #8543 - Fixes #7439 - Fixes #5692 ## Solution - Create a generic `Time<T>` clock that has no processing logic but which can be instantiated for multiple usages. This is also exposed for users to add custom clocks. - Create three standard clocks, `Time<Real>`, `Time<Virtual>` and `Time<Fixed>`, all of which contain their individual logic. - Create one "default" clock, which is just `Time` (or `Time<()>`), which will be overwritten from `Time<Virtual>` on each update, and `Time<Fixed>` inside `FixedUpdate` schedule. This way systems that do not care specifically which time they track can work both in `Update` and `FixedUpdate` without changes and the behaviour is intuitive. - Add `max_delta` to virtual time update, which limits how much can be added to virtual time by a single update. This fixes both the behaviour after a long freeze, and also the death spiral by limiting how many fixed timestep iterations there can be per update. Possible future work could be adding `max_accumulator` to add a sort of "leaky bucket" time processing to possibly smooth out jumps in time while keeping frame rate stable. - Many minor tweaks and clarifications to the time functions and their documentation. ## Changelog - `Time::raw_delta()`, `Time::raw_elapsed()` and related methods are moved to `Time<Real>::delta()` and `Time<Real>::elapsed()` and now match `Time` API - `FixedTime` is now `Time<Fixed>` and matches `Time` API. - `Time<Fixed>` default timestep is now 64 Hz, or 15625 microseconds. - `Time` inside `FixedUpdate` now reflects fixed timestep time, making systems portable between `Update ` and `FixedUpdate`. - `Time::pause()`, `Time::set_relative_speed()` and related methods must now be called as `Time<Virtual>::pause()` etc. - There is a new `max_delta` setting in `Time<Virtual>` that limits how much the clock can jump by a single update. The default value is 0.25 seconds. - Removed `on_fixed_timer()` condition as `on_timer()` does the right thing inside `FixedUpdate` now. ## Migration Guide - Change all `Res<Time>` instances that access `raw_delta()`, `raw_elapsed()` and related methods to `Res<Time<Real>>` and `delta()`, `elapsed()`, etc. - Change access to `period` from `Res<FixedTime>` to `Res<Time<Fixed>>` and use `delta()`. - The default timestep has been changed from 60 Hz to 64 Hz. If you wish to restore the old behaviour, use `app.insert_resource(Time::<Fixed>::from_hz(60.0))`. - Change `app.insert_resource(FixedTime::new(duration))` to `app.insert_resource(Time::<Fixed>::from_duration(duration))` - Change `app.insert_resource(FixedTime::new_from_secs(secs))` to `app.insert_resource(Time::<Fixed>::from_seconds(secs))` - Change `system.on_fixed_timer(duration)` to `system.on_timer(duration)`. Timers in systems placed in `FixedUpdate` schedule automatically use the fixed time clock. - Change `ResMut<Time>` calls to `pause()`, `is_paused()`, `set_relative_speed()` and related methods to `ResMut<Time<Virtual>>` calls. The API is the same, with the exception that `relative_speed()` will return the actual last ste relative speed, while `effective_relative_speed()` returns 0.0 if the time is paused and corresponds to the speed that was set when the update for the current frame started. ## Todo - [x] Update pull name and description - [x] Top level documentation on usage - [x] Fix examples - [x] Decide on default `max_delta` value - [x] Decide naming of the three clocks: is `Real`, `Virtual`, `Fixed` good? - [x] Decide if the three clock inner structures should be in prelude - [x] Decide on best way to configure values at startup: is manually inserting a new clock instance okay, or should there be config struct separately? - [x] Fix links in docs - [x] Decide what should be public and what not - [x] Decide how `wrap_period` should be handled when it is changed - [x] ~~Add toggles to disable setting the clock as default?~~ No, separate pull if needed. - [x] Add tests - [x] Reformat, ensure adheres to conventions etc. - [x] Build documentation and see that it looks correct ## Contributors Huge thanks to @alice-i-cecile and @maniwani while building this pull. It was a shared effort! --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Cameron <51241057+maniwani@users.noreply.github.com> Co-authored-by: Jerome Humbert <djeedai@gmail.com>
254 lines
9.9 KiB
Rust
254 lines
9.9 KiB
Rust
//! Demonstrates rotating entities in 2D using quaternions.
|
|
|
|
use bevy::prelude::*;
|
|
|
|
const BOUNDS: Vec2 = Vec2::new(1200.0, 640.0);
|
|
|
|
fn main() {
|
|
App::new()
|
|
.add_plugins(DefaultPlugins)
|
|
.insert_resource(Time::<Fixed>::from_hz(60.0))
|
|
.add_systems(Startup, setup)
|
|
.add_systems(
|
|
FixedUpdate,
|
|
(
|
|
player_movement_system,
|
|
snap_to_player_system,
|
|
rotate_to_player_system,
|
|
),
|
|
)
|
|
.add_systems(Update, bevy::window::close_on_esc)
|
|
.run();
|
|
}
|
|
|
|
/// player component
|
|
#[derive(Component)]
|
|
struct Player {
|
|
/// linear speed in meters per second
|
|
movement_speed: f32,
|
|
/// rotation speed in radians per second
|
|
rotation_speed: f32,
|
|
}
|
|
|
|
/// snap to player ship behavior
|
|
#[derive(Component)]
|
|
struct SnapToPlayer;
|
|
|
|
/// rotate to face player ship behavior
|
|
#[derive(Component)]
|
|
struct RotateToPlayer {
|
|
/// rotation speed in radians per second
|
|
rotation_speed: f32,
|
|
}
|
|
|
|
/// Add the game's entities to our world and creates an orthographic camera for 2D rendering.
|
|
///
|
|
/// The Bevy coordinate system is the same for 2D and 3D, in terms of 2D this means that:
|
|
///
|
|
/// * `X` axis goes from left to right (`+X` points right)
|
|
/// * `Y` axis goes from bottom to top (`+Y` point up)
|
|
/// * `Z` axis goes from far to near (`+Z` points towards you, out of the screen)
|
|
///
|
|
/// The origin is at the center of the screen.
|
|
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
|
|
let ship_handle = asset_server.load("textures/simplespace/ship_C.png");
|
|
let enemy_a_handle = asset_server.load("textures/simplespace/enemy_A.png");
|
|
let enemy_b_handle = asset_server.load("textures/simplespace/enemy_B.png");
|
|
|
|
// 2D orthographic camera
|
|
commands.spawn(Camera2dBundle::default());
|
|
|
|
let horizontal_margin = BOUNDS.x / 4.0;
|
|
let vertical_margin = BOUNDS.y / 4.0;
|
|
|
|
// player controlled ship
|
|
commands.spawn((
|
|
SpriteBundle {
|
|
texture: ship_handle,
|
|
..default()
|
|
},
|
|
Player {
|
|
movement_speed: 500.0, // meters per second
|
|
rotation_speed: f32::to_radians(360.0), // degrees per second
|
|
},
|
|
));
|
|
|
|
// enemy that snaps to face the player spawns on the bottom and left
|
|
commands.spawn((
|
|
SpriteBundle {
|
|
texture: enemy_a_handle.clone(),
|
|
transform: Transform::from_xyz(0.0 - horizontal_margin, 0.0, 0.0),
|
|
..default()
|
|
},
|
|
SnapToPlayer,
|
|
));
|
|
commands.spawn((
|
|
SpriteBundle {
|
|
texture: enemy_a_handle,
|
|
transform: Transform::from_xyz(0.0, 0.0 - vertical_margin, 0.0),
|
|
..default()
|
|
},
|
|
SnapToPlayer,
|
|
));
|
|
|
|
// enemy that rotates to face the player enemy spawns on the top and right
|
|
commands.spawn((
|
|
SpriteBundle {
|
|
texture: enemy_b_handle.clone(),
|
|
transform: Transform::from_xyz(0.0 + horizontal_margin, 0.0, 0.0),
|
|
..default()
|
|
},
|
|
RotateToPlayer {
|
|
rotation_speed: f32::to_radians(45.0), // degrees per second
|
|
},
|
|
));
|
|
commands.spawn((
|
|
SpriteBundle {
|
|
texture: enemy_b_handle,
|
|
transform: Transform::from_xyz(0.0, 0.0 + vertical_margin, 0.0),
|
|
..default()
|
|
},
|
|
RotateToPlayer {
|
|
rotation_speed: f32::to_radians(90.0), // degrees per second
|
|
},
|
|
));
|
|
}
|
|
|
|
/// Demonstrates applying rotation and movement based on keyboard input.
|
|
fn player_movement_system(
|
|
time: Res<Time>,
|
|
keyboard_input: Res<Input<KeyCode>>,
|
|
mut query: Query<(&Player, &mut Transform)>,
|
|
) {
|
|
let (ship, mut transform) = query.single_mut();
|
|
|
|
let mut rotation_factor = 0.0;
|
|
let mut movement_factor = 0.0;
|
|
|
|
if keyboard_input.pressed(KeyCode::Left) {
|
|
rotation_factor += 1.0;
|
|
}
|
|
|
|
if keyboard_input.pressed(KeyCode::Right) {
|
|
rotation_factor -= 1.0;
|
|
}
|
|
|
|
if keyboard_input.pressed(KeyCode::Up) {
|
|
movement_factor += 1.0;
|
|
}
|
|
|
|
// update the ship rotation around the Z axis (perpendicular to the 2D plane of the screen)
|
|
transform.rotate_z(rotation_factor * ship.rotation_speed * time.delta_seconds());
|
|
|
|
// get the ship's forward vector by applying the current rotation to the ships initial facing
|
|
// vector
|
|
let movement_direction = transform.rotation * Vec3::Y;
|
|
// get the distance the ship will move based on direction, the ship's movement speed and delta
|
|
// time
|
|
let movement_distance = movement_factor * ship.movement_speed * time.delta_seconds();
|
|
// create the change in translation using the new movement direction and distance
|
|
let translation_delta = movement_direction * movement_distance;
|
|
// update the ship translation with our new translation delta
|
|
transform.translation += translation_delta;
|
|
|
|
// bound the ship within the invisible level bounds
|
|
let extents = Vec3::from((BOUNDS / 2.0, 0.0));
|
|
transform.translation = transform.translation.min(extents).max(-extents);
|
|
}
|
|
|
|
/// Demonstrates snapping the enemy ship to face the player ship immediately.
|
|
fn snap_to_player_system(
|
|
mut query: Query<&mut Transform, (With<SnapToPlayer>, Without<Player>)>,
|
|
player_query: Query<&Transform, With<Player>>,
|
|
) {
|
|
let player_transform = player_query.single();
|
|
// get the player translation in 2D
|
|
let player_translation = player_transform.translation.xy();
|
|
|
|
for mut enemy_transform in &mut query {
|
|
// get the vector from the enemy ship to the player ship in 2D and normalize it.
|
|
let to_player = (player_translation - enemy_transform.translation.xy()).normalize();
|
|
|
|
// get the quaternion to rotate from the initial enemy facing direction to the direction
|
|
// facing the player
|
|
let rotate_to_player = Quat::from_rotation_arc(Vec3::Y, to_player.extend(0.));
|
|
|
|
// rotate the enemy to face the player
|
|
enemy_transform.rotation = rotate_to_player;
|
|
}
|
|
}
|
|
|
|
/// Demonstrates rotating an enemy ship to face the player ship at a given rotation speed.
|
|
///
|
|
/// This method uses the vector dot product to determine if the enemy is facing the player and
|
|
/// if not, which way to rotate to face the player. The dot product on two unit length vectors
|
|
/// will return a value between -1.0 and +1.0 which tells us the following about the two vectors:
|
|
///
|
|
/// * If the result is 1.0 the vectors are pointing in the same direction, the angle between them is
|
|
/// 0 degrees.
|
|
/// * If the result is 0.0 the vectors are perpendicular, the angle between them is 90 degrees.
|
|
/// * If the result is -1.0 the vectors are parallel but pointing in opposite directions, the angle
|
|
/// between them is 180 degrees.
|
|
/// * If the result is positive the vectors are pointing in roughly the same direction, the angle
|
|
/// between them is greater than 0 and less than 90 degrees.
|
|
/// * If the result is negative the vectors are pointing in roughly opposite directions, the angle
|
|
/// between them is greater than 90 and less than 180 degrees.
|
|
///
|
|
/// It is possible to get the angle by taking the arc cosine (`acos`) of the dot product. It is
|
|
/// often unnecessary to do this though. Beware than `acos` will return `NaN` if the input is less
|
|
/// than -1.0 or greater than 1.0. This can happen even when working with unit vectors due to
|
|
/// floating point precision loss, so it pays to clamp your dot product value before calling
|
|
/// `acos`.
|
|
fn rotate_to_player_system(
|
|
time: Res<Time>,
|
|
mut query: Query<(&RotateToPlayer, &mut Transform), Without<Player>>,
|
|
player_query: Query<&Transform, With<Player>>,
|
|
) {
|
|
let player_transform = player_query.single();
|
|
// get the player translation in 2D
|
|
let player_translation = player_transform.translation.xy();
|
|
|
|
for (config, mut enemy_transform) in &mut query {
|
|
// get the enemy ship forward vector in 2D (already unit length)
|
|
let enemy_forward = (enemy_transform.rotation * Vec3::Y).xy();
|
|
|
|
// get the vector from the enemy ship to the player ship in 2D and normalize it.
|
|
let to_player = (player_translation - enemy_transform.translation.xy()).normalize();
|
|
|
|
// get the dot product between the enemy forward vector and the direction to the player.
|
|
let forward_dot_player = enemy_forward.dot(to_player);
|
|
|
|
// if the dot product is approximately 1.0 then the enemy is already facing the player and
|
|
// we can early out.
|
|
if (forward_dot_player - 1.0).abs() < f32::EPSILON {
|
|
continue;
|
|
}
|
|
|
|
// get the right vector of the enemy ship in 2D (already unit length)
|
|
let enemy_right = (enemy_transform.rotation * Vec3::X).xy();
|
|
|
|
// get the dot product of the enemy right vector and the direction to the player ship.
|
|
// if the dot product is negative them we need to rotate counter clockwise, if it is
|
|
// positive we need to rotate clockwise. Note that `copysign` will still return 1.0 if the
|
|
// dot product is 0.0 (because the player is directly behind the enemy, so perpendicular
|
|
// with the right vector).
|
|
let right_dot_player = enemy_right.dot(to_player);
|
|
|
|
// determine the sign of rotation from the right dot player. We need to negate the sign
|
|
// here as the 2D bevy co-ordinate system rotates around +Z, which is pointing out of the
|
|
// screen. Due to the right hand rule, positive rotation around +Z is counter clockwise and
|
|
// negative is clockwise.
|
|
let rotation_sign = -f32::copysign(1.0, right_dot_player);
|
|
|
|
// limit rotation so we don't overshoot the target. We need to convert our dot product to
|
|
// an angle here so we can get an angle of rotation to clamp against.
|
|
let max_angle = forward_dot_player.clamp(-1.0, 1.0).acos(); // clamp acos for safety
|
|
|
|
// calculate angle of rotation with limit
|
|
let rotation_angle =
|
|
rotation_sign * (config.rotation_speed * time.delta_seconds()).min(max_angle);
|
|
|
|
// rotate the enemy to face the player
|
|
enemy_transform.rotate_z(rotation_angle);
|
|
}
|
|
}
|