Developer Guide (Version 1.11)

Physical Entities

Physical entities can be created via calls to the CreatePhysicalEntity method of the physical world. CreatePhysicalEntity can create the types of entities noted in the following table:

Physical Entity Types

Type Description

An articulated structure, consisting of several rigid bodies connected with joints (a ragdoll, for instance). It is also possible to manually connect several PE_RIGID entities with joints, but in this case they will not know that they comprise a single object, and thus some useful optimizations cannot be used.


A special entity type to represent player characters that can move through the physical world and interact with it.


A simple entity that represents a small lightweight rigid body. It is simulated as a point with some thickness and supports flying, sliding and rolling modes. Recommended usage: rockets, grenades and small debris.


A single rigid body. Can have infinite mass (specified by setting mass to 0), in which case it will not be simulated but will interact properly with other simulated objects;


A rope object. It can either hang freely or connect two purely physical entities.


A system of non-rigidly connected vertices that can interact with the environment. A typical usage is cloth objects.


An immovable entity. An immovable entity can still be moved manually by setting positions from outside, but in order to ensure proper interactions with simulated objects, it is better to use PE_RIGID entity with infinite mass.


A wheeled vehicle. Internally it is built on top of a rigid body, with added vehicle functionality (wheels, suspensions, engine, brakes).


PE_RIGID, PE_ARTICULATED and PE_WHEELEDVEHICLE are purely physical entities that comprise the core of the simulation engine. The other entities are processed independently.

Creating and managing entities

When creating and managing entities, keep in mind the following:

  • Entities use a two-dimensional, regular grid to speed up broad phase collision detection. The grid should call the SetupEntityGrid function before physical entities are created.

  • Entities can be created in permanent or on-demand mode and are specified by the parameter lifeTime (use 0 for permanent entities). For on-demand mode, the entity placeholders should be created first using CreatePhysicalPlaceholder. Physics will then call the outer system to create the full entity whenever an interaction is required in the bounding box for this placeholder.

  • If an entity is not involved in any interactions for the specified lifetime, it will be destroyed, with the placeholder remaining. Placeholders require less memory than full entities (around 70 bytes versus 260 bytes). It is possible for an outer system to support hierarchical placeholders, such as meta-placeholders that create other placeholders upon request.

  • A sector-based, on-demand physicalization is activated after RegisterBBoxInPODGrid is called. Entities are created and destroyed on a sector basis. The sector size is specified in SetupEntityGrid.

  • You can use SetHeightfieldData to set up one special static terrain object in the physical world. You can also create unlimited terrain geometry manually and add it to an entity.

Destroying, suspending, and restoring entities

To destroy, suspend, or restore a physical entity, use DestroyPhysicalEntity and set the mode parameter to 0, 1, or 2, respectively. Suspending an entity clears all of its connections to other entities, including constraints, without actually deleting the entity. Restoring an entity after suspension will not restore all lost connections automatically. Deleted entities are not destroyed immediately; instead, they are put into a recycle bin. You might need to remove references to any one-way connections. The recycle bin is emptied at the end of each TimeStep. You can also call PurgeDeletedEntities.

Physical entity IDs

All physical entities have unique IDs that the physics engine generates automatically. You do not need to specify an ID during creation. You can also set a new ID later. Entities use these IDs during serialization to save dependency information. When reading the saved state, be sure that entities have the same IDs. IDs are mapped to entity pointers by use of an array, so using large ID numbers will result in allocation of an equally large array.

Associations with outside objects

To maintain associations with outside engine objects, physical entities store an additional void pointer and two 16-bit integers (pForeignData, iForeignData, and iForeignFlags) . These parameters are set from outside, not by the entities. Use pForeignData to store a pointer to the outside engine reference entity and iForeignData to store the entity type, if applicable.

For each material index, the physical world stores the friction coefficient, a bounciness (restitution) coefficient, and flags. When two surfaces contact, the contact's friction and bounciness are computed as an average of the values of both surfaces. The flags only affect raytracing.

Simulation type

Physical entities are grouped by their simulation type, in order of increasing "awareness". Certain interface functions, such as ray tracing and querying entities in an area, allow filtering of these entities by type.

  • 0 (bitmask ent_static) – Static entities. Although terrain is considered static, it does not have a special simulation type. It can be filtered independently with the ent_terrain bitmask.

  • 1 (bitmask ent_sleeping_rigid) – Deactivated, physical objects (rigid bodies and articulated bodies).

  • 2 (bitmask ent_rigid) – Active, physical objects.

  • 3 (bitmask ent_living) – Living entities.

  • 4 (bitmask ent_independent) – Physical entities that are simulated independently from other entities (particles, ropes, and soft objects).

  • 6 (bitmask ent_triggers) – Entities (or placeholders) that are not simulated and only issue callbacks when other entities enter their bounding box.

  • 7 (bitmask ent_deleted) – Objects in the recycle bin. Do not use this directly.

Entities that have a lower simulation type are not aware of entities with higher simulation types (types 1 and 2 are considered as one for this purpose), so players (type 3) and particles (type 4) check collisions against physical entities (types 1 and 2) but physical entities do not know anything about them. Similarly, ropes (type 4) can check collisions against players but not the other way. However, entities of higher types can still affect entities with lower types by using impulses and constraints. Most entities expect a particular simulation type (and will automatically set to the proper value).

There are exceptions to the 'awareness hierarchy': for example, articulated entities can be simulated in types 1 and 2 as fully physicalized dead bodies, or in type 4 as skeletons that play impact animations without affecting the environment and being affected by it.

Functions for Physical Entities

Most interactions with physical entities will use the functions AddGeometry, SetParams, GetParams, GetStatus, and Action.

  • AddGeometry – Adds multiple geometries (physicalized geometries) to entities. For more details, see the AddGeometry section that follows.

  • RemoveGeometry – Removes geometries from entities.

  • SetParams – Sets parameters.

  • GetParams – Gets the simulation input parameters.

  • GetStatus – Gets the simulation output parameters. GetStatus requests the values that an entity changes during simulation.

  • Action – Makes an entity execute an action, such as adding an impulse.

These functions take structure pointers as parameters. When you want to issue a command, you can create a corresponding structure (for example, as a local variable) and specify only the fields you need. The constructor of each structure provides a special value for all fields that tells the physics engine that the field is unused. You can also do this explicitly by using the MARK_UNUSED macro and is_unused to verify that the field is unused.


AddGeometry adds a physicalized geometry to an entity. Each geometry has the following properties:

  • id – A unique part identifier within the bounds of the entity to which the geometry belongs. You can specify the ID or use AddGeometry to generate a value automatically. The ID doesn't change if the parts array changes (for example, if some parts from the middle are removed), but the internal parts index might change.

  • position, orientation, and uniform scaling – Relative to the entity.

  • mass – Used for non-static objects; static objects assume infinite mass in all interactions. You can specify the mass or density where the complementary value will be computed automatically (using formula mass = density*volume; volume is stored in the physicalized geometry structure and scaled if the geometry is scaled).

  • surface_idx – Used if neither IGeometry nor physicalized geometry have surface (material) identifiers.

  • flags and flagsCollider – When an entity checks collisions against other objects, it checks only parts that have a flag mask that intersects its current part's flagsCollider. You can use 16-type bits (geom_colltype) to represent certain entity groups. Although not enforced, it is good practice to keep these relationships symmetrical. If collision checks are known to be one-sided (for example, entity A can check collisions against entity B but never in reverse), you can choose to not maintain this rule. Certain flags are reserved for special collision groups, such as geom_colltype1 = geom_colltype_players and geom_colltype2 = geom_colltype_explosion (when explosion pressure is calculated, only parts with this flag are considered). There are also special flags for raytracing and buoyancy calculations: geom_colltype_ray and geom_floats.

  • minContactDist – The minimum distance between contacts the current part of the entity might have with another part of an entity. Contacts belonging to different parts are not checked for this. You can leave this unused so it will initialize with a default value based on geometry size. Each part can have both geometry and proxy geometry. Geometry is used exclusively for raytracing and proxy geometry. If no proxy geometry is specified, both geometries are set to be equal to allow the raytracing to test against high-poly meshes without needing to introduce changes to the part array layout.