unreal.ProjectileMovementComponent

class unreal.ProjectileMovementComponent(outer=None, name='None')

Bases: unreal.MovementComponent

ProjectileMovementComponent updates the position of another component during its tick.

Behavior such as bouncing after impacts and homing toward a target are supported.

Normally the root component of the owning actor is moved, however another component may be selected (see SetUpdatedComponent()). If the updated component is simulating physics, only the initial launch parameters (when initial velocity is non-zero) will affect the projectile, and the physics sim will take over from there. see: UMovementComponent

C++ Source:

  • Module: Engine

  • File: ProjectileMovementComponent.h

Editor Properties: (see get_editor_property/set_editor_property)

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

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

  • auto_register_physics_volume_updates (bool): [Read-Write] Auto Register Physics Volume Updates: 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] Auto Register Updated Component: 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] Auto Update Tick Registration: 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.

  • bounce_additional_iterations (int32): [Read-Write] Bounce Additional Iterations: On the first few bounces (up to this amount), allow extra iterations over MaxSimulationIterations if necessary.

  • bounce_angle_affects_friction (bool): [Read-Write] Bounce Angle Affects Friction: Controls the effects of friction on velocity parallel to the impact surface when bouncing. If true, friction will be modified based on the angle of impact, making friction higher for perpendicular impacts and lower for glancing impacts. If false, a bounce will retain a proportion of tangential velocity equal to (1.0 - Friction), acting as a “horizontal restitution”.

  • bounce_velocity_stop_simulating_threshold (float): [Read-Write] Bounce Velocity Stop Simulating Threshold: If velocity is below this threshold after a bounce, stops simulating and triggers the OnProjectileStop event. Ignored if bShouldBounce is false, in which case the projectile stops simulating on the first impact. see: StopSimulating(), OnProjectileStop

  • bounciness (float): [Read-Write] Bounciness: Percentage of velocity maintained after the bounce in the direction of the normal of impact (coefficient of restitution). 1.0 = no velocity lost, 0.0 = no bounce. Ignored if bShouldBounce is false.

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

  • component_should_update_physics_volume (bool): [Read-Write] Component Should Update Physics Volume: 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] Component Tags: Array of tags that can be used for grouping and categorizing. Can also be accessed from scripting.

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

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

  • force_sub_stepping (bool): [Read-Write] Force Sub Stepping: If true, forces sub-stepping to break up movement into discrete smaller steps to improve accuracy of the trajectory. Objects that move in a straight line typically do not need to set this, as movement always uses continuous collision detection (sweeps) so collision is not missed. Sub-stepping is automatically enabled when under the effects of gravity or when homing towards a target. see: MaxSimulationTimeStep, MaxSimulationIterations

  • friction (float): [Read-Write] Friction: Coefficient of friction, affecting the resistance to sliding along a surface. Normal range is [0,1] : 0.0 = no friction, 1.0+ = very high friction. Also affects the percentage of velocity maintained after the bounce in the direction tangent to the normal of impact. Ignored if bShouldBounce is false. see: bBounceAngleAffectsFriction

  • homing_acceleration_magnitude (float): [Read-Write] Homing Acceleration Magnitude: The magnitude of our acceleration towards the homing target. Overall velocity magnitude will still be limited by MaxSpeed.

  • homing_target_component (SceneComponent): [Read-Only] Homing Target Component: The current target we are homing towards. Can only be set at runtime (when projectile is spawned or updating). see: bIsHomingProjectile

  • initial_speed (float): [Read-Write] Initial Speed: Initial speed of projectile. If greater than zero, this will override the initial Velocity value and instead treat Velocity as a direction.

  • initial_velocity_in_local_space (bool): [Read-Write] Initial Velocity in Local Space: If true, the initial Velocity is interpreted as being in local space upon startup. see: SetVelocityInLocalSpace()

  • interp_location_max_lag_distance (float): [Read-Write] Interp Location Max Lag Distance: Max distance behind UpdatedComponent which the interpolated component is allowed to lag.

  • interp_location_snap_to_target_distance (float): [Read-Write] Interp Location Snap to Target Distance: Max distance behind UpdatedComponent beyond which the interpolated component is snapped to the target location instead. For instance if the target teleports this far beyond the interpolated component, the interpolation is snapped to match the target.

  • interp_location_time (float): [Read-Write] Interp Location Time: “Time” over which most of the location interpolation occurs, when the UpdatedComponent (target) moves ahead of the interpolated component. Since the implementation uses exponential lagged smoothing, this is a rough time value and experimentation should inform a final result. A value of zero is effectively instantaneous interpolation.

  • interp_movement (bool): [Read-Write] Interp Movement: If true and there is an interpolated component set, location (and optionally rotation) interpolation is enabled which allows the interpolated object to smooth uneven updates of the UpdatedComponent’s location (usually to smooth network updates). This requires using SetInterpolatedComponent() to indicate the visual component that lags behind the collision, and using MoveInterpolationTarget() when the new target location/rotation is received (usually on a net update). see: SetInterpolatedComponent(), MoveInterpolationTarget()

  • interp_rotation (bool): [Read-Write] Interp Rotation: If true and there is an interpolated component set, rotation interpolation is enabled which allows the interpolated object to smooth uneven updates of the UpdatedComponent’s rotation (usually to smooth network updates). Rotation interpolation is only applied if bInterpMovement is also enabled. see: SetInterpolatedComponent(), MoveInterpolationTarget()

  • interp_rotation_time (float): [Read-Write] Interp Rotation Time: “Time” over which most of the rotation interpolation occurs, when the UpdatedComponent (target) moves ahead of the interpolated component. Since the implementation uses exponential lagged smoothing, this is a rough time value and experimentation should inform a final result. A value of zero is effectively instantaneous interpolation.

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

  • is_homing_projectile (bool): [Read-Write] Is Homing Projectile: If true, we will accelerate toward our homing target. HomingTargetComponent must be set after the projectile is spawned. see: HomingTargetComponent, HomingAccelerationMagnitude

  • is_sliding (bool): [Read-Only] Is Sliding: If true, projectile is sliding / rolling along a surface.

  • max_simulation_iterations (int32): [Read-Write] Max Simulation Iterations: Max number of iterations used for each discrete simulation step. Increasing this value can address precision issues with fast-moving objects or complex collision scenarios, at the cost of performance.

    WARNING: if (MaxSimulationTimeStep * MaxSimulationIterations) is too low for the min framerate, the last simulation step may exceed MaxSimulationTimeStep to complete the simulation. see: MaxSimulationTimeStep, bForceSubStepping

  • max_simulation_time_step (float): [Read-Write] Max Simulation Time Step: Max time delta for each discrete simulation step. Lowering this value can address precision issues with fast-moving objects or complex collision scenarios, at the cost of performance.

    WARNING: if (MaxSimulationTimeStep * MaxSimulationIterations) is too low for the min framerate, the last simulation step may exceed MaxSimulationTimeStep to complete the simulation. see: MaxSimulationIterations, bForceSubStepping

  • max_speed (float): [Read-Write] Max Speed: Limit on speed of projectile (0 means no limit).

  • min_friction_fraction (float): [Read-Write] Min Friction Fraction: When bounce angle affects friction, apply at least this fraction of normal friction. Helps consistently slow objects sliding or rolling along surfaces or in valleys when the usual friction amount would take a very long time to settle.

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

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

  • on_projectile_bounce (OnProjectileBounceDelegate): [Read-Write] On Projectile Bounce: Called when projectile impacts something and bounces are enabled.

  • on_projectile_stop (OnProjectileStopDelegate): [Read-Write] On Projectile Stop: Called when projectile has come to a stop (velocity is below simulation threshold, bounces are disabled, or it is forcibly stopped).

  • plane_constraint_axis_setting (PlaneConstraintAxisSetting): [Read-Write] Plane Constraint Axis Setting: 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] Plane Constraint Normal: 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] Plane Constraint Origin: 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().

  • previous_hit_normal (Vector): [Read-Only] Previous Hit Normal: Saved HitResult Normal from previous simulation step that resulted in an impact. If PreviousHitTime is 1.0, then the hit was not in the last step.

  • previous_hit_time (float): [Read-Only] Previous Hit Time: Saved HitResult Time (0 to 1) from previous simulation step. Equal to 1.0 when there was no impact.

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

  • projectile_gravity_scale (float): [Read-Write] Projectile Gravity Scale: Custom gravity scale for this projectile. Set to 0 for no gravity.

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

  • rotation_follows_velocity (bool): [Read-Write] Rotation Follows Velocity: If true, this projectile will have its rotation updated each frame to match the direction of its velocity.

  • rotation_remains_vertical (bool): [Read-Write] Rotation Remains Vertical: If true, this projectile will have its rotation updated each frame to maintain the rotations Yaw only. (bRotationFollowsVelocity is required to be true)

  • should_bounce (bool): [Read-Write] Should Bounce: If true, simple bounces will be simulated. Set this to false to stop simulating on contact.

  • simulation_enabled (bool): [Read-Write] Simulation Enabled: If true, does normal simulation ticking and update. If false, simulation is halted, but component will still tick (allowing interpolation to run).

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

  • sweep_collision (bool): [Read-Write] Sweep Collision: If true, movement uses swept collision checks. If false, collision effectively teleports to the destination. Note that when this is disabled, movement will never generate blocking collision hits (though overlaps will be updated).

  • tick_before_owner (bool): [Read-Write] Tick Before Owner: 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] Update Only if Rendered: If true, skips TickComponent() if UpdatedComponent was not recently rendered.

  • updated_component (SceneComponent): [Read-Write] Updated Component: 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] Updated Primitive: UpdatedComponent, cast as a UPrimitiveComponent. May be invalid if UpdatedComponent was null or not a UPrimitiveComponent.

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

property bounce_additional_iterations

[Read-Write] Bounce Additional Iterations: On the first few bounces (up to this amount), allow extra iterations over MaxSimulationIterations if necessary.

Type

(int32)

property bounce_angle_affects_friction

[Read-Write] Bounce Angle Affects Friction: Controls the effects of friction on velocity parallel to the impact surface when bouncing. If true, friction will be modified based on the angle of impact, making friction higher for perpendicular impacts and lower for glancing impacts. If false, a bounce will retain a proportion of tangential velocity equal to (1.0 - Friction), acting as a “horizontal restitution”.

Type

(bool)

property bounce_velocity_stop_simulating_threshold

[Read-Write] Bounce Velocity Stop Simulating Threshold: If velocity is below this threshold after a bounce, stops simulating and triggers the OnProjectileStop event. Ignored if bShouldBounce is false, in which case the projectile stops simulating on the first impact. see: StopSimulating(), OnProjectileStop

Type

(float)

property bounciness

[Read-Write] Bounciness: Percentage of velocity maintained after the bounce in the direction of the normal of impact (coefficient of restitution). 1.0 = no velocity lost, 0.0 = no bounce. Ignored if bShouldBounce is false.

Type

(float)

property force_sub_stepping

[Read-Write] Force Sub Stepping: If true, forces sub-stepping to break up movement into discrete smaller steps to improve accuracy of the trajectory. Objects that move in a straight line typically do not need to set this, as movement always uses continuous collision detection (sweeps) so collision is not missed. Sub-stepping is automatically enabled when under the effects of gravity or when homing towards a target. see: MaxSimulationTimeStep, MaxSimulationIterations

Type

(bool)

property friction

[Read-Write] Friction: Coefficient of friction, affecting the resistance to sliding along a surface. Normal range is [0,1] : 0.0 = no friction, 1.0+ = very high friction. Also affects the percentage of velocity maintained after the bounce in the direction tangent to the normal of impact. Ignored if bShouldBounce is false. see: bBounceAngleAffectsFriction

Type

(float)

property homing_acceleration_magnitude

[Read-Write] Homing Acceleration Magnitude: The magnitude of our acceleration towards the homing target. Overall velocity magnitude will still be limited by MaxSpeed.

Type

(float)

property homing_target_component

[Read-Only] Homing Target Component: The current target we are homing towards. Can only be set at runtime (when projectile is spawned or updating). see: bIsHomingProjectile

Type

(SceneComponent)

property initial_speed

[Read-Write] Initial Speed: Initial speed of projectile. If greater than zero, this will override the initial Velocity value and instead treat Velocity as a direction.

Type

(float)

property initial_velocity_in_local_space

[Read-Write] Initial Velocity in Local Space: If true, the initial Velocity is interpreted as being in local space upon startup. see: SetVelocityInLocalSpace()

Type

(bool)

property interp_location_max_lag_distance

[Read-Write] Interp Location Max Lag Distance: Max distance behind UpdatedComponent which the interpolated component is allowed to lag.

Type

(float)

property interp_location_snap_to_target_distance

[Read-Write] Interp Location Snap to Target Distance: Max distance behind UpdatedComponent beyond which the interpolated component is snapped to the target location instead. For instance if the target teleports this far beyond the interpolated component, the interpolation is snapped to match the target.

Type

(float)

property interp_location_time

[Read-Write] Interp Location Time: “Time” over which most of the location interpolation occurs, when the UpdatedComponent (target) moves ahead of the interpolated component. Since the implementation uses exponential lagged smoothing, this is a rough time value and experimentation should inform a final result. A value of zero is effectively instantaneous interpolation.

Type

(float)

property interp_movement

[Read-Write] Interp Movement: If true and there is an interpolated component set, location (and optionally rotation) interpolation is enabled which allows the interpolated object to smooth uneven updates of the UpdatedComponent’s location (usually to smooth network updates). This requires using SetInterpolatedComponent() to indicate the visual component that lags behind the collision, and using MoveInterpolationTarget() when the new target location/rotation is received (usually on a net update). see: SetInterpolatedComponent(), MoveInterpolationTarget()

Type

(bool)

property interp_rotation

[Read-Write] Interp Rotation: If true and there is an interpolated component set, rotation interpolation is enabled which allows the interpolated object to smooth uneven updates of the UpdatedComponent’s rotation (usually to smooth network updates). Rotation interpolation is only applied if bInterpMovement is also enabled. see: SetInterpolatedComponent(), MoveInterpolationTarget()

Type

(bool)

property interp_rotation_time

[Read-Write] Interp Rotation Time: “Time” over which most of the rotation interpolation occurs, when the UpdatedComponent (target) moves ahead of the interpolated component. Since the implementation uses exponential lagged smoothing, this is a rough time value and experimentation should inform a final result. A value of zero is effectively instantaneous interpolation.

Type

(float)

property is_homing_projectile

[Read-Write] Is Homing Projectile: If true, we will accelerate toward our homing target. HomingTargetComponent must be set after the projectile is spawned. see: HomingTargetComponent, HomingAccelerationMagnitude

Type

(bool)

is_interpolation_complete() bool

Returns whether interpolation is complete because the target has been reached. True when interpolation is disabled.

Return type

bool

property is_sliding

[Read-Only] Is Sliding: If true, projectile is sliding / rolling along a surface.

Type

(bool)

is_velocity_under_simulation_threshold() bool

Returns true if velocity magnitude is less than BounceVelocityStopSimulatingThreshold.

Return type

bool

limit_velocity(new_velocity) Vector

Don’t allow velocity magnitude to exceed MaxSpeed, if MaxSpeed is non-zero.

Parameters

new_velocity (Vector) –

Return type

Vector

property max_simulation_iterations

[Read-Write] Max Simulation Iterations: Max number of iterations used for each discrete simulation step. Increasing this value can address precision issues with fast-moving objects or complex collision scenarios, at the cost of performance.

WARNING: if (MaxSimulationTimeStep * MaxSimulationIterations) is too low for the min framerate, the last simulation step may exceed MaxSimulationTimeStep to complete the simulation. see: MaxSimulationTimeStep, bForceSubStepping

Type

(int32)

property max_simulation_time_step

[Read-Write] Max Simulation Time Step: Max time delta for each discrete simulation step. Lowering this value can address precision issues with fast-moving objects or complex collision scenarios, at the cost of performance.

WARNING: if (MaxSimulationTimeStep * MaxSimulationIterations) is too low for the min framerate, the last simulation step may exceed MaxSimulationTimeStep to complete the simulation. see: MaxSimulationIterations, bForceSubStepping

Type

(float)

property max_speed

[Read-Write] Max Speed: Limit on speed of projectile (0 means no limit).

Type

(float)

property min_friction_fraction

[Read-Write] Min Friction Fraction: When bounce angle affects friction, apply at least this fraction of normal friction. Helps consistently slow objects sliding or rolling along surfaces or in valleys when the usual friction amount would take a very long time to settle.

Type

(float)

move_interpolation_target(new_location, new_rotation) None

Moves the UpdatedComponent, which is also the interpolation target for the interpolated component. If there is not interpolated component, this simply moves UpdatedComponent. Use this typically from PostNetReceiveLocationAndRotation() or similar from an Actor.

Parameters
property on_projectile_bounce

[Read-Write] On Projectile Bounce: Called when projectile impacts something and bounces are enabled.

Type

(OnProjectileBounceDelegate)

property on_projectile_stop

[Read-Write] On Projectile Stop: Called when projectile has come to a stop (velocity is below simulation threshold, bounces are disabled, or it is forcibly stopped).

Type

(OnProjectileStopDelegate)

property previous_hit_normal

[Read-Only] Previous Hit Normal: Saved HitResult Normal from previous simulation step that resulted in an impact. If PreviousHitTime is 1.0, then the hit was not in the last step.

Type

(Vector)

property previous_hit_time

[Read-Only] Previous Hit Time: Saved HitResult Time (0 to 1) from previous simulation step. Equal to 1.0 when there was no impact.

Type

(float)

property projectile_gravity_scale

[Read-Write] Projectile Gravity Scale: Custom gravity scale for this projectile. Set to 0 for no gravity.

Type

(float)

reset_interpolation() None

Resets interpolation so that interpolated component snaps back to the initial location/rotation without any additional offsets.

property rotation_follows_velocity

[Read-Write] Rotation Follows Velocity: If true, this projectile will have its rotation updated each frame to match the direction of its velocity.

Type

(bool)

property rotation_remains_vertical

[Read-Write] Rotation Remains Vertical: If true, this projectile will have its rotation updated each frame to maintain the rotations Yaw only. (bRotationFollowsVelocity is required to be true)

Type

(bool)

set_interpolated_component(component) None

Assigns the component that will be used for network interpolation/smoothing. It is expected that this is a component attached somewhere below the UpdatedComponent. When network updates use MoveInterpolationTarget() to move the UpdatedComponent, the interpolated component’s relative offset will be maintained and smoothed over the course of future component ticks. The current relative location and rotation of the component is saved as the target offset for future interpolation. see: MoveInterpolationTarget(), bInterpMovement, bInterpRotation

Parameters

component (SceneComponent) –

set_velocity_in_local_space(new_velocity) None

Sets the velocity to the new value, rotated into Actor space.

Parameters

new_velocity (Vector) –

property should_bounce

[Read-Write] Should Bounce: If true, simple bounces will be simulated. Set this to false to stop simulating on contact.

Type

(bool)

property simulation_enabled

[Read-Write] Simulation Enabled: If true, does normal simulation ticking and update. If false, simulation is halted, but component will still tick (allowing interpolation to run).

Type

(bool)

property speed

‘speed’ was renamed to ‘initial_speed’.

Type

deprecated

stop_movement(hit_result)

deprecated: ‘stop_movement’ was renamed to ‘stop_simulating’.

stop_simulating(hit_result) None

Clears the reference to UpdatedComponent, fires stop event (OnProjectileStop), and stops ticking (if bAutoUpdateTickRegistration is true).

Parameters

hit_result (HitResult) –

property sweep_collision

[Read-Write] Sweep Collision: If true, movement uses swept collision checks. If false, collision effectively teleports to the destination. Note that when this is disabled, movement will never generate blocking collision hits (though overlaps will be updated).

Type

(bool)