unreal.MovementComponent

class unreal.MovementComponent(outer: Object | None = None, name: Name | str = 'None')

Bases: ActorComponent

MovementComponent is an abstract component class that defines functionality for moving a PrimitiveComponent (our UpdatedComponent) each tick. Base functionality includes:

  • Restricting movement to a plane or axis.

  • Utility functions for special handling of collision results (SlideAlongSurface(), ComputeSlideVector(), TwoWallAdjust()).

  • Utility functions for moving when there may be initial penetration (SafeMoveUpdatedComponent(), ResolvePenetration()).

  • Automatically registering the component tick and finding a component to move on the owning Actor.

Normally the root component of the owning actor is moved, however another component may be selected (see SetUpdatedComponent()). During swept (non-teleporting) movement only collision of UpdatedComponent is considered, attached components will teleport to the end location ignoring collision.

C++ Source:

  • Module: Engine

  • File: MovementComponent.h

Editor Properties: (see get_editor_property/set_editor_property)

  • asset_user_data (Array[AssetUserData]): [Read-Write] Array of user data stored with the component

  • auto_activate (bool): [Read-Write] Whether the component is activated at creation or must be explicitly activated.

  • auto_register_physics_volume_updates (bool): [Read-Write] If true, then applies the value of bComponentShouldUpdatePhysicsVolume to the UpdatedComponent. If false, will not change bShouldUpdatePhysicsVolume on the UpdatedComponent at all. see: bComponentShouldUpdatePhysicsVolume

  • auto_register_updated_component (bool): [Read-Write] If true, registers the owner’s Root component as the UpdatedComponent if there is not one currently assigned.

  • auto_update_tick_registration (bool): [Read-Write] If true, whenever the updated component is changed, this component will enable or disable its tick dependent on whether it has something to update. This will NOT enable tick at startup if bAutoActivate is false, because presumably you have a good reason for not wanting it to start ticking initially.

  • can_ever_affect_navigation (bool): [Read-Write] Whether this component can potentially influence navigation

  • component_should_update_physics_volume (bool): [Read-Write] If true, enables bShouldUpdatePhysicsVolume on the UpdatedComponent during initialization from SetUpdatedComponent(), otherwise disables such updates. Only enabled if bAutoRegisterPhysicsVolumeUpdates is true. WARNING: UpdatePhysicsVolume is potentially expensive if overlap events are also disabled because it requires a separate query against all physics volumes in the world.

  • component_tags (Array[Name]): [Read-Write] Array of tags that can be used for grouping and categorizing. Can also be accessed from scripting.

  • constrain_to_plane (bool): [Read-Write] If true, movement will be constrained to a plane. see: PlaneConstraintNormal, PlaneConstraintOrigin, PlaneConstraintAxisSetting

  • editable_when_inherited (bool): [Read-Write] True if this component can be modified when it was inherited from a parent actor class

  • is_editor_only (bool): [Read-Write] If true, the component will be excluded from non-editor builds

  • on_component_activated (ActorComponentActivatedSignature): [Read-Write] Called when the component has been activated, with parameter indicating if it was from a reset

  • on_component_deactivated (ActorComponentDeactivateSignature): [Read-Write] Called when the component has been deactivated

  • plane_constraint_axis_setting (PlaneConstraintAxisSetting): [Read-Write] Setting that controls behavior when movement is restricted to a 2D plane defined by a specific axis/normal, so that movement along the locked axis is not be possible. see: SetPlaneConstraintAxisSetting

  • plane_constraint_normal (Vector): [Read-Write] The normal or axis of the plane that constrains movement, if bConstrainToPlane is enabled. If for example you wanted to constrain movement to the X-Z plane (so that Y cannot change), the normal would be set to X=0 Y=1 Z=0. This is recalculated whenever PlaneConstraintAxisSetting changes. It is normalized once the component is registered with the game world. see: bConstrainToPlane, SetPlaneConstraintNormal(), SetPlaneConstraintFromVectors()

  • plane_constraint_origin (Vector): [Read-Write] The origin of the plane that constrains movement, if plane constraint is enabled. This defines the behavior of snapping a position to the plane, such as by SnapUpdatedComponentToPlane(). see: bConstrainToPlane, SetPlaneConstraintOrigin().

  • primary_component_tick (ActorComponentTickFunction): [Read-Write] Main tick function for the Component

  • replicate_using_registered_sub_object_list (bool): [Read-Write] When true the replication system will only replicate the registered subobjects list When false the replication system will instead call the virtual ReplicateSubObjects() function where the subobjects need to be manually replicated.

  • replicates (bool): [Read-Write] Is this component currently replicating? Should the network code consider it for replication? Owning Actor must be replicating first!

  • snap_to_plane_at_start (bool): [Read-Write] If true and plane constraints are enabled, then the updated component will be snapped to the plane when first attached.

  • tick_before_owner (bool): [Read-Write] If true, after registration we will add a tick dependency to tick before our owner (if we can both tick). This is important when our tick causes an update in the owner’s position, so that when the owner ticks it uses the most recent position without lag. Disabling this can improve performance if both objects tick but the order of ticks doesn’t matter.

  • update_only_if_rendered (bool): [Read-Write] If true, skips TickComponent() if UpdatedComponent was not recently rendered.

  • updated_component (SceneComponent): [Read-Write] The component we move and update. If this is null at startup and bAutoRegisterUpdatedComponent is true, the owning Actor’s root component will automatically be set as our UpdatedComponent at startup. see: bAutoRegisterUpdatedComponent, SetUpdatedComponent(), UpdatedPrimitive

  • updated_primitive (PrimitiveComponent): [Read-Write] UpdatedComponent, cast as a UPrimitiveComponent. May be invalid if UpdatedComponent was null or not a UPrimitiveComponent.

  • velocity (Vector): [Read-Write] Current velocity of updated component.

property auto_register_physics_volume_updates: bool

[Read-Only] If true, then applies the value of bComponentShouldUpdatePhysicsVolume to the UpdatedComponent. If false, will not change bShouldUpdatePhysicsVolume on the UpdatedComponent at all. see: bComponentShouldUpdatePhysicsVolume

Type:

(bool)

property auto_register_updated_component: bool

[Read-Only] If true, registers the owner’s Root component as the UpdatedComponent if there is not one currently assigned.

Type:

(bool)

property auto_update_tick_registration: bool

[Read-Only] If true, whenever the updated component is changed, this component will enable or disable its tick dependent on whether it has something to update. This will NOT enable tick at startup if bAutoActivate is false, because presumably you have a good reason for not wanting it to start ticking initially.

Type:

(bool)

property component_should_update_physics_volume: bool

[Read-Only] If true, enables bShouldUpdatePhysicsVolume on the UpdatedComponent during initialization from SetUpdatedComponent(), otherwise disables such updates. Only enabled if bAutoRegisterPhysicsVolumeUpdates is true. WARNING: UpdatePhysicsVolume is potentially expensive if overlap events are also disabled because it requires a separate query against all physics volumes in the world.

Type:

(bool)

constrain_direction_to_plane(direction) → Vector

Constrain a direction vector to the plane constraint, if enabled. see: SetPlaneConstraint

Parameters:

direction (Vector) –

Return type:

Vector

constrain_location_to_plane(location) → Vector

Constrain a position vector to the plane constraint, if enabled.

Parameters:

location (Vector) –

Return type:

Vector

constrain_normal_to_plane(normal) → Vector

Constrain a normal vector (of unit length) to the plane constraint, if enabled.

Parameters:

normal (Vector) –

Return type:

Vector

constrain_position_to_plane(location: Vector) → Vector

deprecated: ‘constrain_position_to_plane’ was renamed to ‘constrain_location_to_plane’.

property constrain_to_plane: bool

[Read-Only] If true, movement will be constrained to a plane. see: PlaneConstraintNormal, PlaneConstraintOrigin, PlaneConstraintAxisSetting

Type:

(bool)

get_gravity_z() → float

Returns gravity that affects this component

Return type:

float

get_max_speed() → float

Returns maximum speed of component in current movement mode.

Return type:

float

get_physics_volume() → PhysicsVolume

Returns the PhysicsVolume this MovementComponent is using, or the world’s default physics volume if none. *

Return type:

PhysicsVolume

get_plane_constraint_axis_setting() → PlaneConstraintAxisSetting

Get the plane constraint axis setting.

Return type:

PlaneConstraintAxisSetting

get_plane_constraint_normal() → Vector

Returns the normal of the plane that constrains movement, enforced if the plane constraint is enabled.

Return type:

Vector

get_plane_constraint_origin() → Vector

Get the plane constraint origin. This defines the behavior of snapping a position to the plane, such as by SnapUpdatedComponentToPlane().

Returns:

The origin of the plane that constrains movement, if the plane constraint is enabled.

Return type:

Vector

is_exceeding_max_speed(max_speed) → bool

Returns true if the current velocity is exceeding the given max speed (usually the result of GetMaxSpeed()), within a small error tolerance. Note that under normal circumstances updates cause by acceleration will not cause this to be true, however external forces or changes in the max speed limit can cause the max speed to be violated.

Parameters:

max_speed (float) –

Return type:

bool

move_updated_component(delta, new_rotation, sweep=True, teleport=False) → HitResult or None

Moves our UpdatedComponent by the given Delta, and sets rotation to NewRotation. Respects the plane constraint, if enabled.

Parameters:
Returns:

True if some movement occurred, false if no movement occurred. Result of any impact will be stored in OutHit.

out_hit (HitResult):

Return type:

HitResult or None

property plane_constraint_normal: Vector

[Read-Only] The normal or axis of the plane that constrains movement, if bConstrainToPlane is enabled. If for example you wanted to constrain movement to the X-Z plane (so that Y cannot change), the normal would be set to X=0 Y=1 Z=0. This is recalculated whenever PlaneConstraintAxisSetting changes. It is normalized once the component is registered with the game world. see: bConstrainToPlane, SetPlaneConstraintNormal(), SetPlaneConstraintFromVectors()

Type:

(Vector)

property plane_constraint_origin: Vector

[Read-Only] The origin of the plane that constrains movement, if plane constraint is enabled. This defines the behavior of snapping a position to the plane, such as by SnapUpdatedComponentToPlane(). see: bConstrainToPlane, SetPlaneConstraintOrigin().

Type:

(Vector)

set_plane_constraint_axis_setting(new_axis_setting) → None

Set the plane constraint axis setting. Changing this setting will modify the current value of PlaneConstraintNormal.

Parameters:

new_axis_setting (PlaneConstraintAxisSetting) – New plane constraint axis setting.

set_plane_constraint_enabled(enabled) → None

Sets whether or not the plane constraint is enabled.

Parameters:

enabled (bool) –

set_plane_constraint_from_vectors(forward, up) → None

Uses the Forward and Up vectors to compute the plane that constrains movement, enforced if the plane constraint is enabled.

Parameters:
set_plane_constraint_normal(plane_normal) → None

Sets the normal of the plane that constrains movement, enforced if the plane constraint is enabled. Changing the normal automatically sets PlaneConstraintAxisSetting to “Custom”.

Parameters:

plane_normal (Vector) – The normal of the plane. If non-zero in length, it will be normalized.

set_plane_constraint_origin(plane_origin) → None

Sets the origin of the plane that constrains movement, enforced if the plane constraint is enabled.

Parameters:

plane_origin (Vector) –

set_updated_component(new_updated_component) → None

Assign the component we move and update.

Parameters:

new_updated_component (SceneComponent) –

property snap_to_plane_at_start: bool

[Read-Only] If true and plane constraints are enabled, then the updated component will be snapped to the plane when first attached.

Type:

(bool)

snap_updated_component_to_plane() → None

Snap the updated component to the plane constraint, if enabled.

stop_movement_immediately() → None

Stops movement immediately (zeroes velocity, usually zeros acceleration for components with acceleration).

property tick_before_owner: bool

[Read-Only] If true, after registration we will add a tick dependency to tick before our owner (if we can both tick). This is important when our tick causes an update in the owner’s position, so that when the owner ticks it uses the most recent position without lag. Disabling this can improve performance if both objects tick but the order of ticks doesn’t matter.

Type:

(bool)

property update_only_if_rendered: bool

[Read-Write] If true, skips TickComponent() if UpdatedComponent was not recently rendered.

Type:

(bool)

property updated_component: SceneComponent

[Read-Only] The component we move and update. If this is null at startup and bAutoRegisterUpdatedComponent is true, the owning Actor’s root component will automatically be set as our UpdatedComponent at startup. see: bAutoRegisterUpdatedComponent, SetUpdatedComponent(), UpdatedPrimitive

Type:

(SceneComponent)

property updated_primitive: PrimitiveComponent

[Read-Only] UpdatedComponent, cast as a UPrimitiveComponent. May be invalid if UpdatedComponent was null or not a UPrimitiveComponent.

Type:

(PrimitiveComponent)

property velocity: Vector

[Read-Write] Current velocity of updated component.

Type:

(Vector)