Struct GlobalTransform

pub struct GlobalTransform(/* private fields */);

GlobalTransform is an affine transformation from entity-local coordinates to worldspace coordinates.

You cannot directly mutate GlobalTransform; instead, you change an entity’s transform by manipulating its Transform, which indirectly causes Bevy to update its GlobalTransform.

• 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. GlobalTransform is automatically inserted whenever Transform is inserted.

Transform and GlobalTransform

Transform transforms an entity relative to its parent’s reference frame, or relative to world space coordinates, if it doesn’t have a ChildOf component.

GlobalTransform is managed by Bevy; it is computed by successively applying the Transform of each ancestor entity which has a Transform. This is done automatically by Bevy-internal systems in the system set TransformPropagate.

This system runs during PostUpdate. If you update the Transform of an entity in this schedule or after, you will notice a 1 frame lag before the GlobalTransform is updated.

Examples

• transform

Implementations

impl GlobalTransform

pub const IDENTITY: Self

An identity GlobalTransform that maps all points in space to themselves.

pub fn compute_matrix(&self) -> Mat4

Returns the 3d affine transformation matrix as a Mat4.

pub fn affine(&self) -> Affine3A

Returns the 3d affine transformation matrix as an Affine3A.

pub fn compute_transform(&self) -> Transform

Returns the transformation as a Transform.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

pub fn to_isometry(&self) -> Isometry3d

Returns the isometric part of the transformation as an isometry. Any scaling done by the transformation will be ignored.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

pub fn reparented_to(&self, parent: &GlobalTransform) -> Transform

Returns the Transform self would have if it was a child of an entity with the parent GlobalTransform.

This is useful if you want to “reparent” an Entity. Say you have an entity e1 that you want to turn into a child of e2, but you want e1 to keep the same global transform, even after re-parenting. You would use:

#[derive(Component)]
struct ToReparent {
    new_parent: Entity,
}
fn reparent_system(
    mut commands: Commands,
    mut targets: Query<(&mut Transform, Entity, &GlobalTransform, &ToReparent)>,
    transforms: Query<&GlobalTransform>,
) {
    for (mut transform, entity, initial, to_reparent) in targets.iter_mut() {
        if let Ok(parent_transform) = transforms.get(to_reparent.new_parent) {
            *transform = initial.reparented_to(parent_transform);
            commands.entity(entity)
                .remove::<ToReparent>()
                .set_parent(to_reparent.new_parent);
        }
    }
}

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

pub fn to_scale_rotation_translation(&self) -> (Vec3, Quat, Vec3)

Extracts scale, rotation and translation from self.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

pub fn right(&self) -> Dir3

Return the local right vector (X).

pub fn left(&self) -> Dir3

Return the local left vector (-X).

pub fn up(&self) -> Dir3

Return the local up vector (Y).

pub fn down(&self) -> Dir3

Return the local down vector (-Y).

pub fn back(&self) -> Dir3

Return the local back vector (Z).

pub fn forward(&self) -> Dir3

Return the local forward vector (-Z).

pub fn translation(&self) -> Vec3

Get the translation as a Vec3.

pub fn translation_vec3a(&self) -> Vec3A

Get the translation as a Vec3A.

pub fn rotation(&self) -> Quat

Get the rotation as a Quat.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

Warning

This is calculated using to_scale_rotation_translation, meaning that you should probably use it directly if you also need translation or scale.

pub fn scale(&self) -> Vec3

Get the scale as a Vec3.

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

Some of the computations overlap with to_scale_rotation_translation, which means you should use it instead if you also need rotation.

pub fn radius_vec3a(&self, extents: Vec3A) -> f32

Get an upper bound of the radius from the given extents.

pub fn transform_point(&self, point: Vec3) -> Vec3

Transforms the given point from local space to global space, applying shear, scale, rotation and translation.

It can be used like this:

let global_transform = GlobalTransform::from_xyz(1., 2., 3.);
let local_point = Vec3::new(1., 2., 3.);
let global_point = global_transform.transform_point(local_point);
assert_eq!(global_point, Vec3::new(2., 4., 6.));

let global_point = Vec3::new(2., 4., 6.);
let global_transform = GlobalTransform::from_xyz(1., 2., 3.);
let local_point = global_transform.affine().inverse().transform_point3(global_point);
assert_eq!(local_point, Vec3::new(1., 2., 3.))

To apply shear, scale, and rotation without applying translation, different functions are available:

let global_transform = GlobalTransform::from_xyz(1., 2., 3.);
let local_direction = Vec3::new(1., 2., 3.);
let global_direction = global_transform.affine().transform_vector3(local_direction);
assert_eq!(global_direction, Vec3::new(1., 2., 3.));
let roundtripped_local_direction = global_transform.affine().inverse().transform_vector3(global_direction);
assert_eq!(roundtripped_local_direction, local_direction);

pub fn mul_transform(&self, transform: Transform) -> Self

Multiplies self with transform component by component, returning the resulting GlobalTransform

Trait Implementations

impl Clone for GlobalTransform

fn clone(&self) -> GlobalTransform

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Component for GlobalTransform

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have [Component<Mutability = Mutable>], while immutable components will instead have [Component<Mutability = Immutable>].

fn register_required_components( requiree: ComponentId, components: &mut ComponentsRegistrator<'_>, required_components: &mut RequiredComponents, inheritance_depth: u16, recursion_check_stack: &mut Vec<ComponentId>, )

Registers required components.

fn on_insert() -> Option<ComponentHook>

Gets the on_insert ComponentHook for this Component if one is defined.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn register_component_hooks(hooks: &mut ComponentHooks)

👎Deprecated since 0.16.0: Use the individual hook methods instead (e.g., Component::on_add, etc.)

Called when registering this component, allowing mutable access to its ComponentHooks.

fn on_add() -> Option<for<'w> fn(_: DeferredWorld<'w>, _: HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_replace() -> Option<for<'w> fn(_: DeferredWorld<'w>, _: HookContext)>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(_: DeferredWorld<'w>, _: HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(_: DeferredWorld<'w>, _: HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl Debug for GlobalTransform

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GlobalTransform

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GlobalTransform

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<Affine3A> for GlobalTransform

fn from(value: Affine3A) -> Self

Converts to this type from the input type.

impl From<GlobalTransform> for Transform

The transform is expected to be non-degenerate and without shearing, or the output will be invalid.

fn from(transform: GlobalTransform) -> Self

Converts to this type from the input type.

impl From<Mat4> for GlobalTransform

fn from(world_from_local: Mat4) -> Self

Converts to this type from the input type.

impl From<Transform> for GlobalTransform

fn from(transform: Transform) -> Self

Converts to this type from the input type.

impl FromReflect for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl Mul<GlobalTransform> for Transform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, global_transform: GlobalTransform) -> Self::Output

Performs the * operation.

impl Mul<Transform> for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, transform: Transform) -> Self::Output

Performs the * operation.

impl Mul<Vec3> for GlobalTransform

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, value: Vec3) -> Self::Output

Performs the * operation.

impl Mul for GlobalTransform

type Output = GlobalTransform

The resulting type after applying the * operator.

fn mul(self, global_transform: GlobalTransform) -> Self::Output

Performs the * operation.

impl PartialEq for GlobalTransform

fn eq(&self, other: &GlobalTransform) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialReflect for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn debug(&self, f: &mut Formatter<'_>) -> Result

Debug formatter for the value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn clone_value(&self) -> Box<dyn PartialReflect>

👎Deprecated since 0.16.0: to clone reflected values, prefer using reflect_clone. To convert reflected values to dynamic ones, use to_dynamic.

Clones Self into its dynamic representation.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl Reflect for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl Serialize for GlobalTransform

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TransformPoint for GlobalTransform

fn transform_point(&self, point: impl Into<Vec3>) -> Vec3

Transform a point.

impl TupleStruct for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, index: usize) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_mut(&mut self, index: usize) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn field_len(&self) -> usize

Returns the number of fields in the tuple struct.

fn iter_fields(&self) -> TupleStructFieldIter<'_>

Returns an iterator over the values of the tuple struct’s fields.

fn to_dynamic_tuple_struct(&self) -> DynamicTupleStruct

Creates a new DynamicTupleStruct from this tuple struct.

fn clone_dynamic(&self) -> DynamicTupleStruct

👎Deprecated since 0.16.0: use to_dynamic_tuple_struct instead

Clones the struct into a DynamicTupleStruct.

fn get_represented_tuple_struct_info(&self) -> Option<&'static TupleStructInfo>

Will return None if TypeInfo is not available.

impl TypePath for GlobalTransform

where GlobalTransform: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for GlobalTransform

where GlobalTransform: Any + Send + Sync, Affine3A: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl Copy for GlobalTransform

impl StructuralPartialEq for GlobalTransform