User Guide (Version 1.17)

Common Functions


Sets the position and orientation of the entity. You can use offset/quaternion/scaling values directly or allow the physics to extract them from a 3x3 (orientation+scaling) or a 4x4 (orientation_scaling+offset) matrix. Physics use a right-to-left transformation order convention, with vectors being columns (vector_in_world = Matrix_Entity * Matrix_Entity_Parts * vector_in_geometry). All interface structures that support matrices can use either row-major or column-major matrix layout in memory (the latter is considered transposed; thus, the corresponding member has T at the end of its name).

There is no per-entity scaling; scaling is only present for parts. When a new scaling is set with pe_params_pos, it is copied into each part and overrides any previous individual scalings. This structure also allows you to set the simulation type manually. After changes are made, entity bounds are typically recalculated and the entity is re-registered in the collision hash grid; however, this can be postponed if bRecalcBounds is set to 0.


Sets an entity's bounding box to a particular value, or queries it when used with GetParams). The bounding box is recalculated automatically based on the entity's geometries, but you can set the bounding box manually for entities without geometries (for example, triggers) or placeholders. If the entity has geometries, it might recalculate its bounding box later, overriding these values. Bounding boxes are axis-aligned and in the world coordinate system.


Specifies an outer entity for an entity. When a box of interest (its center) is inside the entity with an outer entity, the outer entity is excluded from the set of potential colliders. This allows you to have a building exterior quickly culled away when the region of interest is inside the building's interior. Outer entities can be nested and an optional geometry to test for containment is supported.


Sets or queries the entity part's properties. The part can be specified using an internal part index or its ID.


Sets simulation parameters for entities that can accept these parameters (e.g. physical entities, ropes, and soft entities). minEnergy is equal to sleep speed squared. Damping and gravity can be specified independently for colliding and falling state, for example when there are no contacts.


Sets the buoyancy properties of the object and the water plane. The physics engine does not have a list of water volumes, so the outer system must update water plane parameters when they change. The water surface is assumed to be a perfect plane, so you can simulate bobbing of the waves by disturbing the normal of this surface. waterFlow specifies the water movement velocity and affects the object based on its waterResistance property). A separate sleeping condition is used in the water (waterEmin).


Attaches sensors to entities. Sensors are rays that the entity can shoot to sample the environment around it. It is more efficient to do it from inside the entity step than by calling the world's ray tracing function for every ray from outside the entity step. Living entities support vertical-down sensors.


Adds a one-time impulse to an entity. impulse is the impulse property (in N*sec; impulse P will change the object's velocity by P/[object mass]). point is a point in world space where the impulse is applied and used to calculate the rotational effects of the impulse. The of point momentum can be used to specify the rotational impulse explicitly. If neither the point nor momentum are specified, the impulse is applied to the center of the mass of the object. iApplyTime specifies the time when the impulse is applied. By default the value is 2 ("after the next step") to allow the solver an opportunity to reflect the impulse.


Adds a constraint between two objects. Points specify the constraint positions in world space. If the second point is used and different from the first point, the solver will attempt to join them.

Relative positions are always fully constrained to be 0 (i.e. the points on the bodies will always be in one spot) and relative rotations can be constrained in twist and bend directions. These directions correspond to rotation around the x-axis and the remaining rotation around a line on the yz-plane (tilt of the x-axis) of a relative transformation between the two constraint coordinate frames attached to the affected bodies.

The original position of the constraint frames are specified with qframe parameters in world or entity coordinate space (as indicated by the corresponding flag in flags). If one or both qframes are unused, they are considered to be an identity transformation in either the world or entity frame.

Rotation limits are specified with the xlimits and yzlimits parameters, with valid element values of 0 (minimum) and 1 (maximum). If the minimum is more than or equal to the maximum, the corresponding relative rotation is prohibited. pConstraintEntity specifies an entity that represents the constraint. When passed a pe_action_add_constraint pointer, Action returns a constraint identifier that can be used to remove the constraint. 0 indicates a failure.


Sets the velocity of an object, which is useful for rigid bodies with infinite mass (represented as mass). pe_action_set_velocity informs the physics system about the body's velocity, which can help the solver ensure zero relative velocity with the objects contacted. If velocity is not set and only the position is changed, the engine relies solely on penetrations to enforce the contacts. Velocity will not be computed automatically if the position is set manually each frame. The body will continue moving with the specified velocity once it has been set.


Requests the current transformation (position, orientation, and scale) of an entity or its part. You can also use pe_params_pos with GetParams. If matrix pointers are set, the engine will provide data in the corresponding format. The BBox member in this structure is relative to the entity's position.


Retrieves an entity's movement parameters. Acceleration and angular acceleration are computed based on gravity and interactions with other objects. External impulses that might have been added to the entity are considered instantaneous. submergedFraction is a fraction of the entity's volume under water during the last frame (only parts with the geom_float flag are considered). waterResistance contains the maximum water resistance that the entity encountered in one frame since the status was last requested (the accumulated value is cleared when the status is returned). This value can be useful for generating splash effects.