From fcd5cf7e76cc6686c97d34a80bc4cfaa493f2722 Mon Sep 17 00:00:00 2001 From: Nicola Papale Date: Tue, 10 Jan 2023 18:55:22 +0000 Subject: [PATCH] Remove the `GlobalTransform::translation_mut` method (#7134) # Objective It is possible to manually update `GlobalTransform`. The engine actually assumes this is not possible. For example, `propagate_transform` does not update children of an `Entity` which **`GlobalTransform`** changed, leading to unexpected behaviors. A `GlobalTransform` set by the user may also be blindly overwritten by the propagation system. ## Solution - Remove `translation_mut` - Explain to users that they shouldn't manually update the `GlobalTransform` - Remove `global_vs_local.rs` example, since it misleads users in believing that it is a valid use-case to manually update the `GlobalTransform` --- ## Changelog - Remove `GlobalTransform::translation_mut` ## Migration Guide `GlobalTransform::translation_mut` has been removed without alternative, if you were relying on this, update the `Transform` instead. If the given entity had children or parent, you may need to remove its parent to make its transform independent (in which case the new `Commands::set_parent_in_place` and `Commands::remove_parent_in_place` may be of interest) Bevy may add in the future a way to toggle transform propagation on an entity basis. --- Cargo.toml | 11 - .../src/components/global_transform.rs | 12 +- examples/README.md | 1 - .../transforms/global_vs_local_translation.rs | 198 ------------------ 4 files changed, 4 insertions(+), 218 deletions(-) delete mode 100644 examples/transforms/global_vs_local_translation.rs diff --git a/Cargo.toml b/Cargo.toml index d15f4e5111ec2..55b56a549b773 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1384,17 +1384,6 @@ description = "Shows a visualization of gamepad buttons, sticks, and triggers" category = "Tools" wasm = false -# Transforms -[[example]] -name = "global_vs_local_translation" -path = "examples/transforms/global_vs_local_translation.rs" - -[package.metadata.example.global_vs_local_translation] -name = "Global / Local Translation" -description = "Illustrates the difference between direction of a translation in respect to local object or global object Transform" -category = "Transforms" -wasm = true - [[example]] name = "3d_rotation" path = "examples/transforms/3d_rotation.rs" diff --git a/crates/bevy_transform/src/components/global_transform.rs b/crates/bevy_transform/src/components/global_transform.rs index bbf059cf25dfd..f85cb3fec907c 100644 --- a/crates/bevy_transform/src/components/global_transform.rs +++ b/crates/bevy_transform/src/components/global_transform.rs @@ -8,6 +8,8 @@ use bevy_reflect::{std_traits::ReflectDefault, FromReflect, Reflect}; /// Describe the position of an entity relative to the reference frame. /// /// * To place or move an entity, you should set its [`Transform`]. +/// * [`GlobalTransform`] is fully managed by bevy, you cannot mutate it, use +/// [`Transform`] instead. /// * To get the global transform of an entity, you should get its [`GlobalTransform`]. /// * For transform hierarchies to work correctly, you must have both a [`Transform`] and a [`GlobalTransform`]. /// * You may use the [`TransformBundle`](crate::TransformBundle) to guarantee this. @@ -28,9 +30,9 @@ use bevy_reflect::{std_traits::ReflectDefault, FromReflect, Reflect}; /// /// # Examples /// -/// - [`global_vs_local_translation`] +/// - [`transform`] /// -/// [`global_vs_local_translation`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/global_vs_local_translation.rs +/// [`transform`]: https://github.com/bevyengine/bevy/blob/latest/examples/transforms/transform.rs #[derive(Component, Debug, PartialEq, Clone, Copy, Reflect, FromReflect)] #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))] #[reflect(Component, Default, PartialEq)] @@ -169,12 +171,6 @@ impl GlobalTransform { self.0.translation.into() } - /// Mutably access the internal translation. - #[inline] - pub fn translation_mut(&mut self) -> &mut Vec3A { - &mut self.0.translation - } - /// Get the translation as a [`Vec3A`]. #[inline] pub fn translation_vec3a(&self) -> Vec3A { diff --git a/examples/README.md b/examples/README.md index 9b732cc7f9cc8..7817465d9e8b8 100644 --- a/examples/README.md +++ b/examples/README.md @@ -302,7 +302,6 @@ Example | Description Example | Description --- | --- [3D Rotation](../examples/transforms/3d_rotation.rs) | Illustrates how to (constantly) rotate an object around an axis -[Global / Local Translation](../examples/transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform [Scale](../examples/transforms/scale.rs) | Illustrates how to scale an object in each direction [Transform](../examples/transforms/transform.rs) | Shows multiple transformations of objects [Translation](../examples/transforms/translation.rs) | Illustrates how to move an object along an axis diff --git a/examples/transforms/global_vs_local_translation.rs b/examples/transforms/global_vs_local_translation.rs deleted file mode 100644 index a6877a1c68e5f..0000000000000 --- a/examples/transforms/global_vs_local_translation.rs +++ /dev/null @@ -1,198 +0,0 @@ -//! Illustrates the difference between direction of a translation in respect to local object or -//! global object Transform. - -use bevy::{math::Vec3A, prelude::*}; - -// Define a marker for entities that should be changed via their global transform. -#[derive(Component)] -struct ChangeGlobal; - -// Define a marker for entities that should be changed via their local transform. -#[derive(Component)] -struct ChangeLocal; - -// Define a marker for entities that should move. -#[derive(Component)] -struct Move; - -// Define a resource for the current movement direction; -#[derive(Resource, Default)] -struct Direction(Vec3); - -// Define component to decide when an entity should be ignored by the movement systems. -#[derive(Component)] -struct ToggledBy(KeyCode); - -fn main() { - App::new() - .add_plugins(DefaultPlugins) - .add_startup_system(setup) - .init_resource::() - .add_system(move_cubes_according_to_global_transform) - .add_system(move_cubes_according_to_local_transform) - .add_system(update_directional_input) - .add_system(toggle_movement) - .run(); -} - -// Startup system to setup the scene and spawn all relevant entities. -fn setup( - mut commands: Commands, - mut meshes: ResMut>, - mut materials: ResMut>, - asset_server: Res, -) { - // To show the difference between a local transform (rotation, scale and position in respect to a given entity) - // and global transform (rotation, scale and position in respect to the base coordinate system of the visible scene) - // it's helpful to add multiple entities that are attached to each other. - // This way we'll see that the transform in respect to an entity's parent is different to the - // global transform within the visible scene. - // This example focuses on translation only to clearly demonstrate the differences. - - // Spawn a basic cube to have an entity as reference. - commands - .spawn(( - PbrBundle { - mesh: meshes.add(Mesh::from(shape::Cube { size: 1.0 })), - material: materials.add(StandardMaterial { - base_color: Color::YELLOW, - alpha_mode: AlphaMode::Blend, - ..Default::default() - }), - ..default() - }, - ChangeGlobal, - Move, - ToggledBy(KeyCode::Key1), - )) - // Spawn two entities as children above the original main entity. - // The red entity spawned here will be changed via its global transform - // where the green one will be changed via its local transform. - .with_children(|child_builder| { - // also see parenting example - child_builder.spawn(( - PbrBundle { - mesh: meshes.add(Mesh::from(shape::Cube { size: 0.5 })), - material: materials.add(StandardMaterial { - base_color: Color::RED, - alpha_mode: AlphaMode::Blend, - ..Default::default() - }), - transform: Transform::from_translation(Vec3::Y - Vec3::Z), - ..default() - }, - ChangeGlobal, - Move, - ToggledBy(KeyCode::Key2), - )); - child_builder.spawn(( - PbrBundle { - mesh: meshes.add(Mesh::from(shape::Cube { size: 0.5 })), - material: materials.add(StandardMaterial { - base_color: Color::GREEN, - alpha_mode: AlphaMode::Blend, - ..Default::default() - }), - transform: Transform::from_translation(Vec3::Y + Vec3::Z), - ..default() - }, - ChangeLocal, - Move, - ToggledBy(KeyCode::Key3), - )); - }); - - // Spawn a camera looking at the entities to show what's happening in this example. - commands.spawn(Camera3dBundle { - transform: Transform::from_xyz(0.0, 10.0, 20.0).looking_at(Vec3::ZERO, Vec3::Y), - ..default() - }); - - // Add a light source for better 3d visibility. - commands.spawn(PointLightBundle { - transform: Transform::from_translation(Vec3::splat(3.0)), - ..default() - }); - - // Add text to explain inputs and what is happening. - commands.spawn(TextBundle::from_section( - "Press the arrow keys to move the cubes. Toggle movement for yellow (1), red (2) and green (3) cubes via number keys. - -Notice how the green cube will translate further in respect to the yellow in contrast to the red cube. -This is due to the use of its LocalTransform that is relative to the yellow cubes transform instead of the GlobalTransform as in the case of the red cube. -The red cube is moved through its GlobalTransform and thus is unaffected by the yellows transform.", - TextStyle { - font: asset_server.load("fonts/FiraSans-Bold.ttf"), - font_size: 22.0, - color: Color::WHITE, - }, - )); -} - -// This system will move all cubes that are marked as ChangeGlobal according to their global transform. -fn move_cubes_according_to_global_transform( - mut cubes: Query<&mut GlobalTransform, (With, With)>, - direction: Res, - timer: Res