User Guide (Version 1.17)

Living Entity-Specific Functions

Living entities use cylinders or capsules as their bounding geometry. Normally the cylinders are hovering above the ground and the entity shoots a single ray down to detect if it is standing on something. This cylinder geometry always occupies the first part slot (it is created automatically). It is possible to add more geometries manually, but they will not be tested against the environment when the entity moves. However, other entities will process them when testing collisions against the entity.

Living entities never change their orientation themselves; this is always set from outside. Normally, living entities are expected to rotate only around the z-axis, but other orientations are supported. However, collisions against living entities always assume vertically oriented cylinders.

pe_player_dimensions (GetParams | SetParams)

Sets the dimensions of the living entity's bounding geometry.

heightPivot specifies the z-coordinate of a point in the entity frame that is considered to be at the feet level (usually 0).

heightEye is the z-coordinate of the camera attached to the entity. This camera does not affect entity movement, its sole purpose is to smooth out height changes that the entity undergoes (during walking on a highly bumpy surface, such as stairs, after dimensions change and during landing after a period of flying). The camera position can be requested via the pe_status_living structure.

sizeCollider specifies the size of the cylinder (x is radius, z is half-height, y is unused).

heightColliders is the cylinder's center z-coordinate.

The head is an auxiliary sphere that is checked for collisions with objects above the cylinder. Head collisions don't affect movement but they make the camera position go down. headRadius is the radius of this sphere and headHeight is the z-coordinate of its center in the topmost state (that is, when it doesn't touch anything).

pe_player_dynamics (GetParams | SetParams)

Sets a living entity's movement parameters. Living entities have their 'desired' (also called 'requested') movement velocity (set with pe_action_move) and they attempt to reach it. How fast that happens depends on the kInertia setting. The greater this value is, the faster the velocity specified by pe_action_move is reached. The default is 8. 0 means that the desired velocity will be reached instantly.

kAirControl (0..1) specifies how strongly the requested velocity affects movement when the entity is flying (1 means that whenever a new requested velocity is set, it is copied to the actual movement velocity).

kAirResistance describes how fast velocity is damped during flying.

nodSpeed (default 60) sets the strength of camera reaction to landings.

bSwimming is a flag that tells that the entity is allowed to attempt to move in all directions (gravity might still pull it down though). If not set, the requested velocity will always be projected on the ground if the entity is not flying.

minSlideAngle, maxClimbAngle, maxJumpAngle and minFallAngle are threshold angles for living entities that specify maximum or minimum ground slopes for certain activities. Note that if an entity's bounding cylinder collides with a sloped ground, the behavior is not governed by these slopes only.

Setting bNetwork makes the entity allocate a much longer movement history array which might be required for synchronization (if not set, this array will be allocated the first time network-related actions are requested, such as performing a step back).

Setting bActive to 0 puts the living entity to a special 'inactive' state where it does not check collisions with the environment and only moves with the requested velocity (other entities can still collide with it, though; note that this applies only to the entities of the same or higher simulation classes).


Requests a movement from a living entity. dir is the requested velocity the entity will try to reach. If iJump is not 0, this velocity will not be projected on the ground, and snapping to the ground will be turned off for a short period of time. If iJump is 1, the movement velocity is set to be equal to dir instantly. If iJump is 2, dir is added to it. dt is reserved for internal use.


Returns the status of a living entity.

vel is the velocity that is averaged from the entity's position change over several frames.

velUnconstrained is the current movement velocity. It can be different from vel because in many cases when the entity bumps into an obstacle, it will restrict the actual movement but keep the movement velocity the same, so that if on the next frame the obstacle ends, no speed will be lost.

groundHeight and groundSlope contain the point's z coordinate and normal if the entity is standing on something; otherwise, bFlying is 1. Note that pGroundCollider is set only if the entity is standing on a non-static object.

camOffset contains the current camera offset as a 3d vector in the entity frame (although only z coordinates actually changes in it).

bOnStairs is a heuristic flag that indicates that the entity assumes that it is currently walking on stairs because of often and abrupt height changes.