PlayerActor Class

This class is used to create a player with a rigid physical body. It is approximated with a capsule (of a certain radius and height) and has such physical parameters as mass and friction. It also accelerate and damp its velocity over time. Unlike all other players that can move in any direction, it can only walk on the ground.

The orientation of a character in space (theta and phi angles) are illustrated here.

Each player state (walking, running, etc.) can be accompanied with one of the four helper states:

• PLAYER_ACTOR_STATE_BEGIN
• PLAYER_ACTOR_STATE_ENABLED
• PLAYER_ACTOR_STATE_END
• PLAYER_ACTOR_STATE_DISABLED

They appear in the order they are listed above. These states allow you to bind parts of animation to them.

PlayerActor Class

This class inherits from Player

Members

---

PlayerActor ()

Constructor. Creates a new actor with default properties.

float getAcceleration ()

Returns the current acceleration of the actor. The default is 4 units per second squared.

Return value

Acceleration in units per second squared.

Body getBody ()

Returns a rigid body, if the body is simulated physically (isPhysical(1)); otherwise a dummy body will be returned (isPhysical(0)).

Return value

Actor body.

int getCeiling ()

Returns a value indicating if the actor touches the ceiling surface with its head.

Return value

1 if the actor touches the ceiling; otherwise, 0.

float getCollisionHeight ()

Returns the height of actor's capsule. The default is 1 unit.

Return value

Height in units.

int getCollisionMask ()

Returns the collision mask of the actor. Two objects collide, if they both have matching masks (i.e. at least one bit matches). The default is ~0.

Return value

Integer, each bit of which is a mask.

float getCollisionRadius ()

Returns the radius of actor's capsule. The default is 0.3 units.

Return value

Radius in units.

int getCollision ()

Returns a value indicating if collisions with a player's capsule should be taken into account. This method is valid only in case setPhysical() is set to 0 and does not handle collisions automatically. The default is 1.

Return value

Positive number if collisions are taken into account; otherwise, 0.

float getContactDepth (int contact)

Returns penetration depth by the given contact.

Arguments

• int contact - Contact number.

Return value

Penetration depth.

vec3 getContactNormal (int contact)

Returns a normal of the contact point, in world coordinates.

Arguments

• int contact - Contact number.

Return value

Normal of the contact point.

Object getContactObject (int contact)

Returns an object participating in the contact with the player (used for collisions with physical object).

Arguments

• int contact - Contact number.

Return value

Object in contact.

vec3 getContactPoint (int contact)

Returns world coordinates of the contact point.

Arguments

• int contact - Contact number.

Return value

Contact point.

Shape getContactShape (int num)

Returns a shape that collided with the player's capsule.

Arguments

• int num - Contact number.

Return value

Shape in contact.

int getContactSurface (int contact)

Returns the surface of the current object, which is in contact (used for collisions with non-physical object).

Arguments

• int contact - Contact number.

Return value

Surface number.

float getDamping ()

Returns actor's velocity damping with the time. The default is 8.

Return value

Velocity damping.

int getGround ()

Returns a flag indicating if the actor currently stands on the ground surface. This flag is used to determine the actor state, i.e. play the corresponding skinned animation of standing/walking instead of being in the air.

Return value

1 if the actor is on the ground; otherwise, 0.

int getIntersectionMask ()

Returns an intersection mask for a player (masks are considered matching if at least one bit matches).

Return value

Integer, each bit of which is a mask.

float getJumping ()

Returns a jumping coefficient. The default is 0.5.

Return value

Jumping coefficient.

float getMaxFriction ()

Returns a friction of the actor, when the actor is not moving, i.e. stands still on the ground. (See also getMinFriction). The default is 1.

Return value

Friction.

float getMaxThetaAngle ()

Returns the maximum theta angle (zenith angle, also known as pitch angle) that determines how far downward the player can look. The higher the value, the further down the player can look. The default is 90.0 degrees.

Return value

Angle in degrees.

float getMaxVelocity ()

Returns the high velocity of the actor, which is used while the actor runs. The default is 4 units per second.

Return value

Velocity in units per second.

float getMinFriction ()

Returns a friction of the actor, when the actor walks upon the ground. (See also getMaxFriction). The default is 0.5.

Return value

Friction.

float getMinThetaAngle ()

minimum theta angle (zenith angle, also known as pitch angle) that determines how far upward the player can look. The lower the value, the further up the player can look. The default is -90 degrees.

Return value

Angle in degrees.

float getMinVelocity ()

Returns the default velocity of the actor. The default is 2 units per second.

Return value

Velocity in units per second.

int getNumContacts ()

Returns the number of contacts, in which the player's capsule participates.

Return value

Number of contacts.

float getPhiAngle ()

Returns the phi angle (azimuth angle, also known as yaw angle). This angle determines the horizontal viewing direction, i.e. left or right. Positive values rotate the player to the right; negative values rotate it to the left.

Return value

Angle in degrees.

int getPhysicalMask ()

Returns the bit mask for interaction with physicals. Two objects interact, if they both have matching masks (i.e. at least one bit matches).

Return value

Integer, each bit of which is a mask.

float getPhysicalMass ()

Returns the current mass of the actor. The default mass is 60.

Return value

Mass.

ShapeCapsule getShape ()

Returns a shape, which approximates the actor in physical interactions.

Return value

Actor shape.

float getStateTime (int state)

Returns time spent by the actor in a given state.

Arguments

• int state - One of the PLAYER_ACTOR_STATE_* pre-defined variables.

Return value

Time in seconds spent by the actor in a given state.

int getState (int state)

Returns a value indicating if the actor is in a given state.

Arguments

• int state - One of the PLAYER_ACTOR_STATE_* pre-defined variables.

Return value

1 if the actor is in the given state; otherwise, 0.

float getThetaAngle ()

Returns the theta angle (zenith angle, also known as pitch angle). This angle determines the vertical viewing direction, i.e. upwards or downwards. By a positive value, the player looks upwards; by a negative one - downwards. The value is clamped between the minimum and the maximum theta angle.

Return value

Angle in degrees.

float getTurning ()

Returns a velocity of player turning. The default is 90 degrees per second.

Return value

Turning velocity in degrees per second.

vec3 getViewDirection ()

Returns the current viewing orientation of the player. The result is the same as using phi and theta angles, but this function returns a vector.

Return value

View direction vector.

int isPhysical ()

Tells whether the actor interacts with the environment as a physical object or not.

Return value

Physical flag, 1 if rigid body model is enabled, 0 otherwise.

void setAcceleration (float acceleration)

Sets an acceleration of the actor. The default is 8.

Arguments

• float acceleration - New acceleration in units per second squared. If a negative value is provided, 0 will be used instead.

void setCeiling (int ceiling)

Sets a value indicating if the actor touches the ceiling surface with its head. The default is 0.

Arguments

• int ceiling - Positive value to indicate that an actor touches the ceiling; otherwise, 0.

void setCollisionHeight (float height)

Sets a height of actor's capsule. The default is 1 unit.

Arguments

• float height - New height in units. If a negative value is provided, 0 will be used instead.

void setCollisionMask (int mask)

Sets a collision mask for the actor. Two objects collide, if they both have matching masks (i.e. at least one bit matches).

Arguments

• int mask - Integer, each bit of which is a mask.

void setCollisionRadius (float radius)

Sets a radius of actor's capsule. The default is 0.3 units.

Arguments

• float radius - New radius in units. If a negative value is provided, 0 will be used instead.

void setCollision (int collision)

Sets a value indicating if collisions with a player's capsule should be taken into account. This method is valid only in case setPhysical() is set to 0 and does not handle collisions automatically.

Arguments

• int collision - Positive number to allow collisions, 0 not to handle collisions with the actor.

void setDamping (float damping)

Sets actor's velocity damping with the time. The default is 8.

Arguments

• float damping - New velocity damping. If a negative value is provided, 0 will be used instead.

void setGround (int ground)

Sets a flag indicating that the actor currently stands on the ground surface. This flag is used to set actor state, i.e. play the corresponding skinned animation of standing/walking instead of being in the air. The default is 0.

Arguments

• int ground - Positive value to indicate that the actor is on the ground; otherwise, 0.

void setIntersectionMask (int mask)

Sets an intersection mask for a player (masks are considered matching if at least one bit matches).

Arguments

• int mask - Integer, each bit of which is a mask.

void setJumping (float coefficient)

Sets a jumping coefficient. The default is 0.5.

Arguments

• float coefficient - Jumping coefficient. The greater a value, the higher the actor jumps. If a negative value is provided, 0 will be used instead.

void setMaxFriction (float friction)

Sets a friction of the actor, when the actor is not moving, i.e. stands still on the ground. (See also setMinFriction). The default is 2.

Arguments

• float friction - Friction. If a negative value is provided, 0 will be used instead.

void setMaxThetaAngle (float angle)

Sets the maximum theta angle (zenith angle, also known as pitch angle) that determines how far downward the player can look. The default is 90.0 degrees.

Arguments

• float angle - New maximum angle in degrees in range [0;90]. The higher the value, the further down the player can look.

void setMaxVelocity (float velocity)

Sets the increased velocity of the actor, which is used while the actor runs. The default is 4 units per meter.

Arguments

• float velocity - New velocity in units per second. If a negative value is provided, 0 will be used instead.

void setMinFriction (float friction)

Sets a friction of the actor, when the actor walks upon the ground. (See also setMaxFriction). The default is 0.5.

Arguments

• float friction - Friction. If a negative value is provided, 0 will be used instead.

void setMinThetaAngle (float angle)

Sets the minimum theta angle (zenith angle, also known as pitch angle) that determines how far upward the player can look. The default is -90.0 degrees.

Arguments

• float angle - New minimum angle in degrees in range [-90;0]. The lower the value, the further up the player can look.

void setMinVelocity (float velocity)

Sets the default velocity of the actor. The default value is 2 units per second.

Arguments

• float velocity - New velocity in units per second. If a negative value is provided, 0 will be used instead.

void setPhiAngle (float angle)

Sets the phi angle (azimuth angle, also known as yaw angle). This angle determines the horizontal viewing direction, i.e. left or right.

Arguments

• float angle - New angle in degrees. Positive values rotate the player to the right; negative values rotate it to the left.

void setPhysicalMask (int mask)

Sets the bit mask for interaction with physicals. Two objects interact, if they both have matching masks (i.e. at least one bit matches).

Arguments

• int mask - Integer, each bit of which is a mask.

void setPhysicalMass (float mass)

Sets a mass of the actor. The default is 60.

Arguments

• float mass - New mass. If a negative value is provided, 0 will be used instead.

void setPhysical (int physical)

Sets whether the actor should interact with the environment as a physical object or not (enables or disables its rigid body). If disabled, collisions can be handled using setCollision() method. The default is 1.

Arguments

• int physical - Physical flag, 1 to enable rigid body model, 0 to disable it.

void setThetaAngle (float angle)

Sets the theta angle of the player (zenith angle, also known as pitch angle). This angle determines the vertical viewing direction, i.e. upward and downward. The value will be clamped between the minimum and the maximum theta angle.

Arguments

• float angle - New angle in degrees in range [-90;90]. By a positive value, the player looks upward; by a negative one - downward.

void setTurning (float velocity)

Sets a velocity of player turning. The default is 90 meters per unit.

Arguments

• float velocity - Turning velocity in degrees per second. If a negative value is provided, 0 will be used instead.

void setViewDirection (vec3 direction)

Sets the viewing orientation of the player. The result is the same as using phi and theta angles, but this function takes a vector as an argument.

Arguments

• vec3 direction - View direction vector.

---

int PLAYER_ACTOR_STATE_BACKWARD

Description

A state, in which the player moves backwards.

int PLAYER_ACTOR_STATE_BEGIN

Description

A state, which denotes a beginning of another state like moving forward.

int PLAYER_ACTOR_STATE_CROUCH

Description

A state, in which the player crouches.

int PLAYER_ACTOR_STATE_DISABLED

Description

A state, which means that another state is disabled.

int PLAYER_ACTOR_STATE_ENABLED

Description

A state, which means that another state is enabled.

int PLAYER_ACTOR_STATE_END

Description

A state, which denotes an end of another state.

int PLAYER_ACTOR_STATE_FIRE

Description

A state, in which the player fires their weapon.

int PLAYER_ACTOR_STATE_FORWARD

Description

A state, in which the player moves forwards.

int PLAYER_ACTOR_STATE_JUMP

Description

A state, in which the player jumps.

int PLAYER_ACTOR_STATE_MOVE_LEFT

Description

A state, in which the player moves left.

int PLAYER_ACTOR_STATE_MOVE_RIGHT

Description

A state, in which the player moves right.

int PLAYER_ACTOR_STATE_RUN

Description

A state, in which the player runs.

int PLAYER_ACTOR_STATE_TURN_DOWN

Description

A state, in which the player turns down.

int PLAYER_ACTOR_STATE_TURN_LEFT

Description

A state, in which the player turns left.

int PLAYER_ACTOR_STATE_TURN_RIGHT

Description

A state, in which the player turns right.

int PLAYER_ACTOR_STATE_TURN_UP

Description

A state, in which the player turns up.

int PLAYER_ACTOR_STATE_USE

Description

A state, in which the player utilizes some object.