Physics

A physical object is simulated by the physics engine: it has mass, falls, collides and responds to forces. Non-physical objects stay where they are put but still collide with physical ones.

Physics settings cover the object’s status, its shape and material, how it collides, and what it reports when it hits something. Moving objects without physics is covered under Movement.

Concepts

Physical, phantom, temporary and the rotation locks are object status flags
- Volume detect makes an object phantom while still reporting collisions
Mass depends on size and density; read it in lindograms, in kilograms, for any object, or find the center of mass
- Physics materials set gravity, friction, density and restitution
- The physics shape type changes how the engine sees the prim
- The prim material sets the default collision sound, friction and restitution without affecting mass
Collision events report contacts with objects and avatars, and land_collision events with the ground
- Filters and pass-through settings narrow what is reported
- What hit is read with the detected functions, such as its velocity
- Replace the collision sound
Forces act continuously; impulses act once
- Push other objects and avatars where the parcel allows it
Raycasts trace a line through the region for line of sight, hitscan weapons and placement
Physics performance depends on the region: time dilation and statistics show how busy it is

Functions and events

`void`	`llSetStatus(integer status, integer value)`
`void`	`llSetPhysicsMaterial(integer mask, float gravity_multiplier, float restitution, float friction, float density)`
`void`	`llApplyImpulse(vector momentum, integer is_local)`
`void`	`llSetForce(vector force, integer is_local)`
`void`	`llSetVelocity(vector velocity, integer is_local)`
`void`	`llPushObject(key target, vector impulse, vector ang_impulse, integer is_local)`
`list`	`llCastRay(vector start_pos, vector end_pos, list options)`
`event`	`collision_start(integer num_detected)`
`event`	`land_collision_start(vector pos)`

Collision events

collision_start, collision and collision_end fire for objects and avatars; the land_collision events fire for the ground.

Script library

Example physics scripts from the wiki archive.

Scripting Details

`void`	`llSetStatus(integer status, integer value)` Sets the object status attributes specified by status to value.
`integer`	`llGetStatus(integer status)` Returns a boolean integer indicating whether the specified status flag status is enabled for the object.
`void`	`llVolumeDetect(integer detect)` If detect is TRUE, enables VolumeDetect (object becomes phantom and physical objects/avatars can pass through it). Triggers collision_start on initial intersection and collision_end when intersection stops (standard collision events are suppressed while intersecting).
`float`	`llGetMass()` Returns a float representing the mass of the object (in lindograms). Returns the total linkset mass if called from the root, or the individual prim's mass if called from a child prim. Returns the wearer's mass if inside an attachment.
`float`	`llGetMassMKS()` Returns a float representing the mass of the object in kilograms. Functionally identical to llGetMass except for using MKS (metric) units.
`float`	`llGetObjectMass(key id)` Returns a float representing the mass of the avatar or object specified by id.
`vector`	`llGetCenterOfMass()` Returns the vector position (in region coordinates) of the center of mass. Returns the individual child prim's center of mass if called from a child, or the entire linkset's center of mass if called from the root.
`void`	`llSetPhysicsMaterial(integer mask, float gravity_multiplier, float restitution, float friction, float density)` Configures the physical characteristics of an object. The mask bitfield specifies which of the other parameters (gravity_multiplier, restitution, friction, or density) should be applied to the object.
`list`	`llGetPhysicsMaterial()` Returns a list of the format [float gravity_multiplier, float restitution, float friction, float density] detailing the physical characteristics of the object.
`event`	`collision_start(integer num_detected)` Triggered when an avatar or another object first begins colliding with the object containing the script. Passes num_detected, representing the number of detected collisions.
`event`	`collision(integer num_detected)` Triggered continuously while an avatar or another object is colliding with the object containing the script. Passes num_detected, representing the number of detected collisions.
`event`	`collision_end(integer num_detected)` Triggered when an avatar or another object stops colliding with the object containing the script. Passes num_detected, representing the number of detected collisions.
`event`	`land_collision_start(vector pos)` Triggered in the root prim when a physical object or attached avatar first begins colliding with the ground at position pos.
`event`	`land_collision(vector pos)` Triggered in the root prim when a physical object or attached avatar is colliding with the ground at position pos.
`event`	`land_collision_end(vector pos)` Triggered in the root prim when a physical object or attached avatar stops colliding with the ground at position pos.
`void`	`llCollisionFilter(string name, key id, integer accept)` Sets the collision filter, either exclusively or inclusively. If accept is TRUE, only collisions matching name and id are processed; if FALSE, matches are excluded. Pass an empty string or NULL_KEY to name or id to skip filtering on that parameter.
`void`	`llPassCollisions(integer pass)` Sets the pass-collisions attribute. If pass is TRUE, collision events are passed from child prims to the root; if FALSE (default), they only trigger events in the affected child prim.
`void`	`llCollisionSound(string impact_sound, float impact_volume)` Suppresses default collision sounds and replaces default impact sounds with impact_sound at the volume level specified by impact_volume. Supply an empty string to only suppress collision sounds.
`vector`	`llDetectedVel(integer number)` Returns the vector velocity of the detected object or avatar specified by number, or <0.0, 0.0, 0.0> if number is not a valid offset index.
`void`	`llApplyImpulse(vector momentum, integer is_local)` Applies a linear impulse (momentum) to a physical object. If local is TRUE, the impulse is applied in local coordinates; otherwise, it is applied in global region coordinates.
`void`	`llApplyRotationalImpulse(vector force, integer is_local)` Applies a rotational impulse (force) to a physical object. If local is TRUE, the rotational impulse is applied in local coordinates; otherwise, it is applied in global region coordinates.
`void`	`llSetForce(vector force, integer is_local)` Applies a constant linear force to a physical object. If local is TRUE, force is applied relative to local coordinates; if FALSE, applied relative to region coordinates.
`vector`	`llGetForce()` Returns a vector representing the constant force currently applied to the object (if the object is physical).
`void`	`llSetTorque(vector torque, integer is_local)` Applies a constant torque rotational force to a physical object. If local is TRUE, torque is applied in local coordinates; if FALSE, applied in global coordinates.
`vector`	`llGetTorque()` Returns a vector representing the physical torque force currently acting on the object (if the object is physical).
`void`	`llSetBuoyancy(float buoyancy)` Sets the buoyancy of a physical object (requires physics to be enabled). A value of 0.0 offers no buoyancy, < 1.0 sinks, 1.0 counteracts gravity, and > 1.0 rises.
`void`	`llPushObject(key target, vector impulse, vector ang_impulse, integer is_local)` Applies physical impulse (force) and ang_impulse (rotational force) to the specified target avatar or object.
`void`	`llSetVelocity(vector velocity, integer is_local)` Sets the linear velocity of a physical object to velocity. If local is TRUE, velocity is treated as a local directional vector; if FALSE, as a global region directional vector. Has no effect on non-physical objects.
`vector`	`llGetVel()` Returns a vector representing the velocity of the object (in meters per second) relative to the global region coordinates. For physical objects, returns the velocity of its center of mass.
`list`	`llCastRay(vector start_pos, vector end_pos, list options)` Casts a ray into the physics world from start to end and reports collision data for intersections with objects based on options. Returns a list of strided values [UUID_1, {link_number_1}, hit_position_1, {hit_normal_1}, ..., status_code]. A negative status_code indicates an error; otherwise, it represents the number of hits.
`float`	`llGetRegionTimeDilation()` Returns a float representing the current physics time dilation of the region, ranging from 0.0 (full dilation / slow) to 1.0 (no dilation / real-world speed).
`float`	`llGetSimStats(integer stat_type)` Returns a float containing the value of the requested region statistic specified by stat_type.
`float`	`llGetEnergy()` Returns a float representing the remaining physics energy of the object as a percentage (0.0 to 1.0) of its maximum capacity.

Additional

llSetStatus and llGetStatus — object status flags (ObjectStatusParam)
- STATUS_PHYSICS — Respond to physics, gravity and forces
- STATUS_PHANTOM — Avatars and objects pass through
- STATUS_ROTATE_X, STATUS_ROTATE_Y, STATUS_ROTATE_Z — Allow or lock physical rotation per local axis
- STATUS_DIE_AT_EDGE, STATUS_RETURN_AT_EDGE — Delete or return the object when it goes off-world
- STATUS_BLOCK_GRAB — Block click-and-drag grabbing
- STATUS_SANDBOX — Keep the object near its creation point
llSetLinkPrimitiveParamsFast — the same settings as prim params
- PRIM_PHYSICS, PRIM_PHANTOM, PRIM_TEMP_ON_REZ — Physical, phantom and temporary status
- PRIM_PHYSICS_SHAPE_TYPE — PRIM_PHYSICS_SHAPE_PRIM (default for non-mesh), PRIM_PHYSICS_SHAPE_CONVEX (default for mesh) or PRIM_PHYSICS_SHAPE_NONE (not on the root prim)
- PRIM_MATERIAL — Collision sound, friction and restitution preset
llSetPhysicsMaterial — the mask selects which values apply (PhysicsMaterialParam)
- GRAVITY_MULTIPLIER — Between -1.0 and +28.0
- RESTITUTION — Bounciness, between 0.0 and 1.0
- FRICTION — Between 0.0 and 255.0
- DENSITY — Between 1.0 and 22587.0 kg/m³
llCastRay — options (RayCastParam)
- RC_REJECT_TYPES — Ignore types of hits (RayCastRejectType), such as avatars or land
- RC_DATA_FLAGS — Extra data per hit (RayCastData): normal, root key, link number
- RC_MAX_HITS — Maximum hits to return; keep it small
- RC_DETECT_PHANTOM — Also detect phantom and volume-detect objects
- A negative status code is an error (RayCastError)
llGetObjectDetails — OBJECT_PHYSICS tells whether physics is on; OBJECT_PHYSICS_COST gets the physics cost
llPushObject — restricted by PARCEL_FLAG_RESTRICT_PUSHOBJECT and REGION_FLAG_RESTRICT_PUSHOBJECT
llRezObjectWithParams — REZ_FLAG_PHYSICAL rezzes the object with physics enabled

Constant groups

Constant groups ObjectStatusParam 11 PhysicsMaterialParam 4 PhysicsMaterialPreset 7 PhysicsShapeType 3 RayCastParam 4 RayCastRejectType 4 RayCastData 3 RayCastError 3