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] 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.

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

  • bounce_angle_affects_friction (bool): [Read-Write] 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] 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] 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] 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

  • force_sub_stepping (bool): [Read-Write] 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] 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] The magnitude of our acceleration towards the homing target. Overall velocity magnitude will still be limited by MaxSpeed.

  • homing_target_component (SceneComponent): [Read-Only] 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 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] If true, the initial Velocity is interpreted as being in local space upon startup. see: SetVelocityInLocalSpace()

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

  • interp_location_snap_to_target_distance (float): [Read-Write] 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] “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] 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] 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] “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] If true, the component will be excluded from non-editor builds

  • is_homing_projectile (bool): [Read-Write] 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] If true, projectile is sliding / rolling along a surface.

  • max_simulation_iterations (int32): [Read-Write] 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 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] Limit on speed of projectile (0 means no limit).

  • min_friction_fraction (float): [Read-Write] 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] 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

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

  • on_projectile_stop (OnProjectileStopDelegate): [Read-Write] 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] 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().

  • previous_hit_normal (Vector): [Read-Only] 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] 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] Main tick function for the Component

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

  • replicates (bool): [Read-Write] 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] If true, this projectile will have its rotation updated each frame to match the direction of its velocity.

  • rotation_remains_vertical (bool): [Read-Write] 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] If true, simple bounces will be simulated. Set this to false to stop simulating on contact.

  • simulation_enabled (bool): [Read-Write] 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] 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] 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] 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 bounce_additional_iterations

[Read-Write] 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] 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] 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] 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] 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] 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] 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] 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 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] 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] Max distance behind UpdatedComponent which the interpolated component is allowed to lag.

Type

(float)

property interp_location_snap_to_target_distance

[Read-Write] 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] “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] 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] 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] “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] 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.

Returns

Return type

bool

property is_sliding

[Read-Only] 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.

Returns

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) –

Returns

Return type

Vector

property max_simulation_iterations

[Read-Write] 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 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] Limit on speed of projectile (0 means no limit).

Type

(float)

property min_friction_fraction

[Read-Write] 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] Called when projectile impacts something and bounces are enabled.

Type

(OnProjectileBounceDelegate)

property on_projectile_stop

[Read-Write] 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] 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] 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] 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] 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] 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] If true, simple bounces will be simulated. Set this to false to stop simulating on contact.

Type

(bool)

property simulation_enabled

[Read-Write] 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] 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)