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
MaxAutoRiskneed"_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 thedryRunargument. smoke = covered byedit.self_test.
physics.apply_body_force (risk 2, mutates, requires PIE, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
vector | {x,y,z} | required. Force, impulse, torque, or location vector. |
velocityChange | boolean | Treat 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.
| Argument | Type | Description |
|---|---|---|
vector | {x,y,z} | required. Force, impulse, torque, or location vector. |
velocityChange | boolean | Treat 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.
| Argument | Type | Description |
|---|---|---|
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.
| Argument | Type | Description |
|---|---|---|
vector | {x,y,z} | required. Force, impulse, torque, or location vector. |
velocityChange | boolean | Treat an impulse as a velocity change. Default false. |
Returns: actor, component, values, message.
physics.break_constraint (risk 2, mutates, requires PIE, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path. |
component | string | required. PhysicsConstraintComponent name. |
Returns: constraint, values.
physics.clear_body_mass_override (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path in the editor or PIE world. |
component | string | Primitive 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).
| Argument | Type | Description |
|---|---|---|
actors | array of string | required. 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.
| Argument | Type | Description |
|---|---|---|
enabled | boolean | required. 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.
| Argument | Type | Description |
|---|---|---|
source | string | required. Source PhysicalMaterial asset path (engine assets allowed). |
destination | string | required. 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.
| Argument | Type | Description |
|---|---|---|
enabled | boolean | required. New enabled state. |
Returns: actor, component, values, message.
physics.enable_body_hit_events (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
enabled | boolean | required. New enabled state. |
Returns: actor, component, values, message.
physics.enable_body_simulation (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
enabled | boolean | required. New enabled state. |
Returns: actor, component, values, message.
physics.get_body_angular_velocity (risk 0, requires PIE, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path in the editor or PIE world. |
component | string | Primitive component name; empty selects the first primitive component. |
Returns: actor, component, values, message.
physics.get_body_velocity (risk 0, requires PIE, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path in the editor or PIE world. |
component | string | Primitive component name; empty selects the first primitive component. |
Returns: actor, component, values, message.
physics.get_constraint_force (risk 0, requires PIE, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path. |
component | string | required. PhysicsConstraintComponent name. |
Returns: constraint, values.
physics.get_material (risk 0, smoke)
Returns the portable physical response values of a PhysicalMaterial asset.
| Argument | Type | Description |
|---|---|---|
material | string | required. 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.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path in the editor or PIE world. |
component | string | Primitive component name; empty selects the first primitive component. |
Returns: actor, component, values, message.
physics.inspect_constraint (risk 0, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path. |
component | string | required. PhysicsConstraintComponent name. |
Returns: constraint, values.
physics.line_trace (risk 0, requires PIE, smoke)
Performs a blocking line trace in the active PIE world.
| Argument | Type | Description |
|---|---|---|
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.
| Argument | Type | Description |
|---|---|---|
shape | string | Shape 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. |
radius | number | Sphere radius, capsule radius, or box X half extent in centimetres. Default 50.0. |
halfHeight | number | Capsule half-height or box Y half extent in centimetres. Default 50.0. |
extentZ | number | Box 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.
| Argument | Type | Description |
|---|---|---|
value | number | required. 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.
| Argument | Type | Description |
|---|---|---|
channel | string | required. Collision channel name. |
response | string | required. ignore, overlap, or block. |
Returns: actor, component, values, message.
physics.set_body_collision_mode (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
mode | string | required. 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.
| Argument | Type | Description |
|---|---|---|
profile | string | required. Registered collision-profile name. |
Returns: actor, component, values, message.
physics.set_body_linear_damping (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
value | number | required. 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.
| Argument | Type | Description |
|---|---|---|
vector | {x,y,z} | required. Force, impulse, torque, or location vector. |
velocityChange | boolean | Treat 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.
| Argument | Type | Description |
|---|---|---|
value | number | required. 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.
| Argument | Type | Description |
|---|---|---|
enabled | boolean | required. Enable breaking. |
threshold | number | required. Break threshold. |
Returns: constraint, values.
physics.set_constraint_angular_drive_params (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
positionStrength | number | required. Position gain. |
velocityStrength | number | required. Velocity gain. |
forceLimit | number | required. Force limit. |
Returns: constraint, values.
physics.set_constraint_angular_orientation_drive (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
x | boolean | Enable X. Default false. |
y | boolean | Enable Y. Default false. |
z | boolean | Enable Z. Default false. |
Returns: constraint, values.
physics.set_constraint_angular_velocity_drive (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
x | boolean | Enable X. Default false. |
y | boolean | Enable Y. Default false. |
z | boolean | Enable Z. Default false. |
Returns: constraint, values.
physics.set_constraint_angular_velocity_target (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
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.
| Argument | Type | Description |
|---|---|---|
enabled | boolean | required. Enable breaking. |
threshold | number | required. Break threshold. |
Returns: constraint, values.
physics.set_constraint_linear_drive_params (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
positionStrength | number | required. Position gain. |
velocityStrength | number | required. Velocity gain. |
forceLimit | number | required. Force limit. |
Returns: constraint, values.
physics.set_constraint_linear_position_drive (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
x | boolean | Enable X. Default false. |
y | boolean | Enable Y. Default false. |
z | boolean | Enable Z. Default false. |
Returns: constraint, values.
physics.set_constraint_linear_position_target (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
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.
| Argument | Type | Description |
|---|---|---|
x | boolean | Enable X. Default false. |
y | boolean | Enable Y. Default false. |
z | boolean | Enable Z. Default false. |
Returns: constraint, values.
physics.set_constraint_linear_velocity_target (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
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.
| Argument | Type | Description |
|---|---|---|
motion | string | required. free, limited, or locked. |
limit | number | required. Limit distance cm or angle degrees. |
Returns: constraint, values.
physics.set_constraint_linear_y_limit (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
motion | string | required. free, limited, or locked. |
limit | number | required. Limit distance cm or angle degrees. |
Returns: constraint, values.
physics.set_constraint_linear_z_limit (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
motion | string | required. free, limited, or locked. |
limit | number | required. Limit distance cm or angle degrees. |
Returns: constraint, values.
physics.set_constraint_swing1_limit (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
motion | string | required. free, limited, or locked. |
limit | number | required. Limit distance cm or angle degrees. |
Returns: constraint, values.
physics.set_constraint_swing2_limit (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
motion | string | required. free, limited, or locked. |
limit | number | required. Limit distance cm or angle degrees. |
Returns: constraint, values.
physics.set_constraint_twist_limit (risk 2, mutates, requires world, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
motion | string | required. free, limited, or locked. |
limit | number | required. 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.
| Argument | Type | Description |
|---|---|---|
friction | string | Dynamic friction, non-negative. |
staticFriction | string | Static friction, non-negative. |
restitution | string | Bounciness from zero through one. |
density | string | Density in grams per cubic centimetre, non-negative. |
surfaceType | string | Surface type number (0..62). |
overrideFrictionCombineMode | string | Override friction combination mode. |
frictionCombineMode | string | Friction combination: average, min, multiply, or max. |
overrideRestitutionCombineMode | string | Override restitution combination mode. |
restitutionCombineMode | string | Restitution 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.
| Argument | Type | Description |
|---|---|---|
substepping | string | Enable synchronous physics substepping. |
substeppingAsync | string | Enable asynchronous physics substepping where supported. |
maxPhysicsDeltaTime | string | Maximum simulation delta in seconds, greater than zero. |
maxSubstepDeltaTime | string | Maximum substep delta in seconds, greater than zero. |
maxSubsteps | string | Maximum substeps, from 1 through 16. |
defaultDegreesOfFreedom | string | Default 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.
| Argument | Type | Description |
|---|---|---|
surfaces | array of UeaPhysicsSurface | required. Surface names to create or update. |
Returns: values, surfaces, channels, message.
physics.sleep_body (risk 2, mutates, requires PIE, smoke)
No description.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path in the editor or PIE world. |
component | string | Primitive 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.
| Argument | Type | Description |
|---|---|---|
label | string | required. Actor label for the new actor. |
mesh | string | Static mesh asset; defaults to the engine cube. Default TEXT("/Engine/BasicShapes/Cube"). |
location | {x,y,z} | World location in centimetres. |
simulate | boolean | Enable 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.
| Argument | Type | Description |
|---|---|---|
label | string | required. Actor label for the new constraint actor. |
actor1 | string | First constrained actor label/name; empty constrains to the world. |
actor2 | string | Second 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.
| Argument | Type | Description |
|---|---|---|
label | string | required. Actor label for the new actor. |
mesh | string | Static mesh asset; defaults to the engine cube. Default TEXT("/Engine/BasicShapes/Cube"). |
location | {x,y,z} | World location in centimetres. |
simulate | boolean | Enable 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).
| Argument | Type | Description |
|---|---|---|
label | string | required. Actor label for the new constraint actor. |
actor1 | string | First constrained actor label/name; empty constrains to the world. |
actor2 | string | Second 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.
| Argument | Type | Description |
|---|---|---|
shape | string | Shape 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. |
radius | number | Sphere radius, capsule radius, or box X half extent in centimetres. Default 50.0. |
halfHeight | number | Capsule half-height or box Y half extent in centimetres. Default 50.0. |
extentZ | number | Box 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.
| Argument | Type | Description |
|---|---|---|
actor | string | required. Actor label, name, or path in the editor or PIE world. |
component | string | Primitive component name; empty selects the first primitive component. |
Returns: actor, component, values, message.