Skip to main content

physics kit

58 tools. Generated from the plugin source; do not edit by hand.

Guide​

Use physics for project physics policy, physical-material assets, and collision queries during Play-in-Editor. Use component to change a component's collision and simulation settings, mesh for static mesh collision, and skel for PhysicsAssets.

For a selected primitive component, physics.inspect_body starts a physics-profile workflow. Use the typed body collision, simulation, gravity, damping, mass, and hit-event tools to prepare it, then run PIE and use the live velocity, wake/sleep, impulse, force, torque, and velocity tools.

Start by discovering the project contract:

physics.get_project_settings {}
physics.list_surface_types {}
physics.list_collision_channels {}
physics.list_collision_profiles {}

Project timing and named surfaces are persistent configuration changes and therefore require confirmation under the normal risk policy:

physics.set_project_settings {"substepping":"true","maxSubstepDeltaTime":"0.008333","maxSubsteps":"8"}
physics.set_surface_types {"surfaces":[{"type":1,"name":"Concrete"},{"type":2,"name":"Mud"}]}

Create the physical material through the asset kit, then tune its response here. density is in g/cm³; friction is non-negative and restitution is from 0 to 1:

asset.create_physical_material {"folder":"/Game/Physics","name":"PM_Rubber"}
physics.duplicate_material {"source":"/Engine/EngineMaterials/DefaultPhysicalMaterial","destination":"/Game/Physics/PM_Ice"}
physics.set_material {"material":"/Game/Physics/PM_Rubber","friction":"1.1","staticFriction":"1.3","restitution":"0.65","density":"1.2","surfaceType":"2","overrideFrictionCombineMode":"true","frictionCombineMode":"max"}
physics.get_material {"material":"/Game/Physics/PM_Rubber"}

Assign the material to a mesh component with component.set_physics, or to a material asset with material.set_physical_material; those tools own the assignment relationship.

While PIE is running, query the runtime world by any listed channel. The queries report only the first blocking response. Pass actor labels in ignoreActors when the trace origin belongs to the player or a probe actor:

physics.line_trace {"start":{"x":0,"y":0,"z":500},"end":{"x":0,"y":0,"z":-500},"channel":"Visibility","ignoreActors":["Player"]}
physics.sweep {"shape":"sphere","start":{"x":0,"y":0,"z":100},"end":{"x":1000,"y":0,"z":100},"radius":25,"channel":"Camera"}
physics.overlap_blocking {"shape":"box","start":{"x":500,"y":0,"z":100},"radius":50,"halfHeight":50,"extentZ":100,"channel":"Visibility"}

Box dimensions use radius, halfHeight, and extentZ as X/Y/Z half extents. A capsule needs halfHeight >= radius. line_trace, sweep, and overlap_blocking require an active PIE world; they intentionally do not run against the editor world.

Test bodies and constraints​

The body and constraint tools need a placed actor. To experiment without touching project actors, spawn a movable engine-cube body and a PhysicsConstraintActor (its component is always MyConstraintComp), edit them, then delete them. Engine physical materials are read-only; copy one with physics.duplicate_material before physics.set_material.

physics.spawn_body_actor {"label":"Crate","location":{"x":0,"y":0,"z":300}}
physics.spawn_constraint_actor {"label":"Hinge","actor1":"Crate","location":{"x":0,"y":0,"z":350}}
physics.set_constraint_swing1_limit {"actor":"Hinge","component":"MyConstraintComp","motion":"limited","limit":30}
physics.delete_actors {"actors":["Hinge","Crate"]}

During PIE use the transient variants, which spawn into the play world and initialise the constraint immediately; they disappear when PIE stops:

physics.spawn_test_body {"label":"Crate","location":{"x":0,"y":0,"z":300},"simulate":true}
physics.spawn_test_constraint {"label":"Hinge","actor1":"Crate"}
physics.apply_body_impulse {"actor":"Crate","vector":{"x":0,"y":0,"z":500},"velocityChange":true}
physics.get_constraint_force {"actor":"Hinge","component":"MyConstraintComp"}

physics.delete_actors only removes actors that own a primitive or constraint component (use actor.delete for anything else). Editor-world spawns are undoable; PIE spawns are not recorded.

Tools​

Legend. risk 0 = read-only, 1 = harmless editor op, 2 = modifies asset, 3 = deletes/replaces asset, 4 = project/config/build op, 5 = potentially destructive (calls above MaxAutoRisk need "_confirm": true). mutates = runs in a transaction (edit.undo reverts). requires PIE / requires world = refused without a PIE session / an open level. requires plugin = unavailable while the plugin is disabled. dryRun = honours the dryRun argument. smoke = covered by edit.self_test.

physics.apply_body_force (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
vector{x,y,z}required. Force, impulse, torque, or location vector.
velocityChangebooleanTreat an impulse as a velocity change. Default false.

Returns: actor, component, values, message.

physics.apply_body_impulse (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
vector{x,y,z}required. Force, impulse, torque, or location vector.
velocityChangebooleanTreat an impulse as a velocity change. Default false.

Returns: actor, component, values, message.

physics.apply_body_impulse_at_location (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
impulse{x,y,z}required. Impulse vector.
location{x,y,z}required. World location in centimetres.

Returns: actor, component, values, message.

physics.apply_body_torque (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
vector{x,y,z}required. Force, impulse, torque, or location vector.
velocityChangebooleanTreat an impulse as a velocity change. Default false.

Returns: actor, component, values, message.

physics.break_constraint (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path.
componentstringrequired. PhysicsConstraintComponent name.

Returns: constraint, values.

physics.clear_body_mass_override (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path in the editor or PIE world.
componentstringPrimitive component name; empty selects the first primitive component.

Returns: actor, component, values, message.

physics.delete_actors (risk 3, mutates, destructive, requires world, smoke)​

Deletes actors that own a primitive or physics-constraint component from the editor world (or the PIE world while PIE runs).

ArgumentTypeDescription
actorsarray of stringrequired. Actor labels, names, or paths. Each must own a primitive or constraint component.

Returns: values, surfaces, channels, message.

physics.disable_constraint_collision (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
enabledbooleanrequired. New enabled state.

Returns: constraint, values.

physics.duplicate_material (risk 2, mutates, smoke)​

Copies a PhysicalMaterial (engine or project) to a new project asset so it can be edited with physics.set_material.

ArgumentTypeDescription
sourcestringrequired. Source PhysicalMaterial asset path (engine assets allowed).
destinationstringrequired. Destination object path, for example /Game/Physics/PM_Rubber.

Returns: material, friction, staticFriction, restitution, density, surfaceType, overrideFrictionCombineMode, frictionCombineMode, overrideRestitutionCombineMode, restitutionCombineMode.

physics.enable_body_gravity (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
enabledbooleanrequired. New enabled state.

Returns: actor, component, values, message.

physics.enable_body_hit_events (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
enabledbooleanrequired. New enabled state.

Returns: actor, component, values, message.

physics.enable_body_simulation (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
enabledbooleanrequired. New enabled state.

Returns: actor, component, values, message.

physics.get_body_angular_velocity (risk 0, requires PIE, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path in the editor or PIE world.
componentstringPrimitive component name; empty selects the first primitive component.

Returns: actor, component, values, message.

physics.get_body_velocity (risk 0, requires PIE, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path in the editor or PIE world.
componentstringPrimitive component name; empty selects the first primitive component.

Returns: actor, component, values, message.

physics.get_constraint_force (risk 0, requires PIE, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path.
componentstringrequired. PhysicsConstraintComponent name.

Returns: constraint, values.

physics.get_material (risk 0, smoke)​

Returns the portable physical response values of a PhysicalMaterial asset.

ArgumentTypeDescription
materialstringrequired. PhysicalMaterial asset path or unique name.

Returns: material, friction, staticFriction, restitution, density, surfaceType, overrideFrictionCombineMode, frictionCombineMode, overrideRestitutionCombineMode, restitutionCombineMode.

physics.get_project_settings (risk 0, smoke)​

Returns cross-version project physics timing and degree-of-freedom defaults.

No arguments.

Returns: values, surfaces, channels, message.

physics.inspect_body (risk 0, requires world, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path in the editor or PIE world.
componentstringPrimitive component name; empty selects the first primitive component.

Returns: actor, component, values, message.

physics.inspect_constraint (risk 0, requires world, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path.
componentstringrequired. PhysicsConstraintComponent name.

Returns: constraint, values.

physics.line_trace (risk 0, requires PIE, smoke)​

Performs a blocking line trace in the active PIE world.

ArgumentTypeDescription
start{x,y,z}required. Query start in centimetres.
end{x,y,z}required. Query end in centimetres.

Returns: hit, hit, message.

physics.list_collision_channels (risk 0, smoke)​

Lists engine and project collision-channel names for scene queries.

No arguments.

Returns: values, surfaces, channels, message.

physics.list_collision_profiles (risk 0, smoke)​

Lists collision profiles; component.physics owns applying a profile to a component.

No arguments.

Returns: values, surfaces, channels, message.

physics.list_surface_types (risk 0, smoke)​

Lists project-defined physical surface names.

No arguments.

Returns: values, surfaces, channels, message.

physics.overlap_blocking (risk 0, requires PIE, smoke)​

Tests whether a sphere, box, or capsule overlaps a blocking object in the active PIE world.

ArgumentTypeDescription
shapestringShape kind: sphere, box, or capsule. Default TEXT("sphere").
start{x,y,z}required. Start / overlap centre in centimetres.
end{x,y,z}Sweep end in centimetres; ignored by overlap.
radiusnumberSphere radius, capsule radius, or box X half extent in centimetres. Default 50.0.
halfHeightnumberCapsule half-height or box Y half extent in centimetres. Default 50.0.
extentZnumberBox Z half extent in centimetres. Default 50.0.
rotation{x,y,z}Shape rotation in degrees for box and capsule queries.

Returns: hit, hit, message.

physics.set_body_angular_damping (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
valuenumberrequired. Value in the units named by the tool.

Returns: actor, component, values, message.

physics.set_body_channel_response (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
channelstringrequired. Collision channel name.
responsestringrequired. ignore, overlap, or block.

Returns: actor, component, values, message.

physics.set_body_collision_mode (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
modestringrequired. no_collision, query_only, physics_only, or query_and_physics.

Returns: actor, component, values, message.

physics.set_body_collision_profile (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
profilestringrequired. Registered collision-profile name.

Returns: actor, component, values, message.

physics.set_body_linear_damping (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
valuenumberrequired. Value in the units named by the tool.

Returns: actor, component, values, message.

physics.set_body_linear_velocity (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
vector{x,y,z}required. Force, impulse, torque, or location vector.
velocityChangebooleanTreat an impulse as a velocity change. Default false.

Returns: actor, component, values, message.

physics.set_body_mass_kg (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
valuenumberrequired. Value in the units named by the tool.

Returns: actor, component, values, message.

physics.set_constraint_angular_break (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
enabledbooleanrequired. Enable breaking.
thresholdnumberrequired. Break threshold.

Returns: constraint, values.

physics.set_constraint_angular_drive_params (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
positionStrengthnumberrequired. Position gain.
velocityStrengthnumberrequired. Velocity gain.
forceLimitnumberrequired. Force limit.

Returns: constraint, values.

physics.set_constraint_angular_orientation_drive (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
xbooleanEnable X. Default false.
ybooleanEnable Y. Default false.
zbooleanEnable Z. Default false.

Returns: constraint, values.

physics.set_constraint_angular_velocity_drive (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
xbooleanEnable X. Default false.
ybooleanEnable Y. Default false.
zbooleanEnable Z. Default false.

Returns: constraint, values.

physics.set_constraint_angular_velocity_target (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
value{x,y,z}required. Target position, velocity, or angular velocity.

Returns: constraint, values.

physics.set_constraint_linear_break (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
enabledbooleanrequired. Enable breaking.
thresholdnumberrequired. Break threshold.

Returns: constraint, values.

physics.set_constraint_linear_drive_params (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
positionStrengthnumberrequired. Position gain.
velocityStrengthnumberrequired. Velocity gain.
forceLimitnumberrequired. Force limit.

Returns: constraint, values.

physics.set_constraint_linear_position_drive (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
xbooleanEnable X. Default false.
ybooleanEnable Y. Default false.
zbooleanEnable Z. Default false.

Returns: constraint, values.

physics.set_constraint_linear_position_target (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
value{x,y,z}required. Target position, velocity, or angular velocity.

Returns: constraint, values.

physics.set_constraint_linear_velocity_drive (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
xbooleanEnable X. Default false.
ybooleanEnable Y. Default false.
zbooleanEnable Z. Default false.

Returns: constraint, values.

physics.set_constraint_linear_velocity_target (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
value{x,y,z}required. Target position, velocity, or angular velocity.

Returns: constraint, values.

physics.set_constraint_linear_x_limit (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
motionstringrequired. free, limited, or locked.
limitnumberrequired. Limit distance cm or angle degrees.

Returns: constraint, values.

physics.set_constraint_linear_y_limit (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
motionstringrequired. free, limited, or locked.
limitnumberrequired. Limit distance cm or angle degrees.

Returns: constraint, values.

physics.set_constraint_linear_z_limit (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
motionstringrequired. free, limited, or locked.
limitnumberrequired. Limit distance cm or angle degrees.

Returns: constraint, values.

physics.set_constraint_swing1_limit (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
motionstringrequired. free, limited, or locked.
limitnumberrequired. Limit distance cm or angle degrees.

Returns: constraint, values.

physics.set_constraint_swing2_limit (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
motionstringrequired. free, limited, or locked.
limitnumberrequired. Limit distance cm or angle degrees.

Returns: constraint, values.

physics.set_constraint_twist_limit (risk 2, mutates, requires world, smoke)​

No description.

ArgumentTypeDescription
motionstringrequired. free, limited, or locked.
limitnumberrequired. Limit distance cm or angle degrees.

Returns: constraint, values.

physics.set_material (risk 2, mutates, smoke)​

Updates portable physical response values of a PhysicalMaterial asset.

ArgumentTypeDescription
frictionstringDynamic friction, non-negative.
staticFrictionstringStatic friction, non-negative.
restitutionstringBounciness from zero through one.
densitystringDensity in grams per cubic centimetre, non-negative.
surfaceTypestringSurface type number (0..62).
overrideFrictionCombineModestringOverride friction combination mode.
frictionCombineModestringFriction combination: average, min, multiply, or max.
overrideRestitutionCombineModestringOverride restitution combination mode.
restitutionCombineModestringRestitution combination: average, min, multiply, or max.

Returns: material, friction, staticFriction, restitution, density, surfaceType, overrideFrictionCombineMode, frictionCombineMode, overrideRestitutionCombineMode, restitutionCombineMode.

physics.set_project_settings (risk 4, mutates)​

Saves selected project physics timing defaults to DefaultEngine.ini.

ArgumentTypeDescription
substeppingstringEnable synchronous physics substepping.
substeppingAsyncstringEnable asynchronous physics substepping where supported.
maxPhysicsDeltaTimestringMaximum simulation delta in seconds, greater than zero.
maxSubstepDeltaTimestringMaximum substep delta in seconds, greater than zero.
maxSubstepsstringMaximum substeps, from 1 through 16.
defaultDegreesOfFreedomstringDefault degree-of-freedom mode: full3d, yz, xz, or xy.

Returns: values, surfaces, channels, message.

physics.set_surface_types (risk 4, mutates)​

Saves named physical-surface types to DefaultEngine.ini.

ArgumentTypeDescription
surfacesarray of UeaPhysicsSurfacerequired. Surface names to create or update.

Returns: values, surfaces, channels, message.

physics.sleep_body (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path in the editor or PIE world.
componentstringPrimitive component name; empty selects the first primitive component.

Returns: actor, component, values, message.

physics.spawn_body_actor (risk 2, mutates, requires world, smoke)​

Spawns a movable StaticMeshActor (default engine cube) in the editor world, optionally simulating physics.

ArgumentTypeDescription
labelstringrequired. Actor label for the new actor.
meshstringStatic mesh asset; defaults to the engine cube. Default TEXT("/Engine/BasicShapes/Cube").
location{x,y,z}World location in centimetres.
simulatebooleanEnable physics simulation on the mesh component. Default false.

Returns: actor, component, values, message.

physics.spawn_constraint_actor (risk 2, mutates, requires world, smoke)​

Spawns a PhysicsConstraintActor in the editor world joining actor1 and actor2 (empty = world). Its component is MyConstraintComp.

ArgumentTypeDescription
labelstringrequired. Actor label for the new constraint actor.
actor1stringFirst constrained actor label/name; empty constrains to the world.
actor2stringSecond constrained actor label/name; empty constrains to the world.
location{x,y,z}World location in centimetres.

Returns: constraint, values.

physics.spawn_test_body (risk 1, requires PIE, smoke)​

Spawns a transient simulated StaticMeshActor in the running PIE world for force/velocity experiments.

ArgumentTypeDescription
labelstringrequired. Actor label for the new actor.
meshstringStatic mesh asset; defaults to the engine cube. Default TEXT("/Engine/BasicShapes/Cube").
location{x,y,z}World location in centimetres.
simulatebooleanEnable physics simulation on the mesh component. Default false.

Returns: actor, component, values, message.

physics.spawn_test_constraint (risk 1, requires PIE, smoke)​

Spawns a transient PhysicsConstraintActor in the running PIE world and initialises it between actor1 and actor2 (empty = world).

ArgumentTypeDescription
labelstringrequired. Actor label for the new constraint actor.
actor1stringFirst constrained actor label/name; empty constrains to the world.
actor2stringSecond constrained actor label/name; empty constrains to the world.
location{x,y,z}World location in centimetres.

Returns: constraint, values.

physics.sweep (risk 0, requires PIE, smoke)​

Sweeps a sphere, box, or capsule for the first blocking hit in the active PIE world.

ArgumentTypeDescription
shapestringShape kind: sphere, box, or capsule. Default TEXT("sphere").
start{x,y,z}required. Start / overlap centre in centimetres.
end{x,y,z}Sweep end in centimetres; ignored by overlap.
radiusnumberSphere radius, capsule radius, or box X half extent in centimetres. Default 50.0.
halfHeightnumberCapsule half-height or box Y half extent in centimetres. Default 50.0.
extentZnumberBox Z half extent in centimetres. Default 50.0.
rotation{x,y,z}Shape rotation in degrees for box and capsule queries.

Returns: hit, hit, message.

physics.wake_body (risk 2, mutates, requires PIE, smoke)​

No description.

ArgumentTypeDescription
actorstringrequired. Actor label, name, or path in the editor or PIE world.
componentstringPrimitive component name; empty selects the first primitive component.

Returns: actor, component, values, message.