Player Class

List of Functions:

This class is used to create cameras that view the world. Their viewing frustum is defined by a near clipping plane, far clipping plane and the field of view. Note that if you set up a custom model-view or projection matrix and after that call any of these functions:

your custom matrices will be overwritten.

Objects, decals and lights can be selectively displayed in the player viewport. To be displayed, their viewport mask should be matching with the player's viewport mask (one matching bit is enough):

Object surface viewport mask or decal viewport mask
Light viewport mask to light the object/decal
Material viewport mask to render the object/decal material

Reflections can also be selectively rendered into the viewport: an object can be rendered without reflection or reflection without an object. For that, the player's reflection mask should match with:

Reflection mask of the reflecting material
Viewport mask of the reflecting material
Object surface viewport mask
Material viewport mask of the reflected material
Light viewport mask

That is enough to render reflection from the object without an object itself. If an object needs to be present as well, all these conditions should simply go together with above mentioned ones.

To render an object without reflection, simply either its material viewport mask or object surface viewport mask should not match the player's reflection mask.

Players cannot have a parent node; they always use the world coordinates for their transformations. The only exception is PlayerDummy.

Player Class

This class inherits from Node

Members

void flushTransform ()

Forces to immediately set transformations to the player. This function should be called manually after user input has been updated via updateControls().

Controls getControls ()

Returns a Controls object that holds settings of input controls relevant to the player.

Return value

Controls object used to handle input controls.

float getFov ()

Returns the current vertical field of view of the player. (Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio.)

Return value

Vertical field of view in degrees.

mat4 getIModelview ()

Returns the inverted modelview matrix of the player.

Return value

Inverse modelview matrix.

mat4 getModelview ()

Returns the modelview matrix of the player.

Return value

Modelview matrix.

mat4 getOffset ()

Returns an additional transformation (an offset matrix) set for the player. This transformation is applied after the model-view transformation. It does not affect it or the position of the player. For example, the offset matrix can be used to set player's head position (in case the player turns his head) or to simulate camera shake from an explosion.

Return value

Offset matrix.

mat4 getOldModelview ()

Returns the modelview matrix of the player used in the previous frame.

Return value

Old modelview matrix.

string getPostMaterials ()

Returns names of the current post postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.
They are used after engine.render.getPostMaterials(), if any.

Return value

Name of the current post postprocess materials.

mat4 getProjection ()

Returns the current projection matrix with unit (1.0) aspect ratio.

Return value

Projection matrix.

int getReflectionMask ()

Returns the current bit mask for rendering reflections into the viewport. Reflections are rendered in the viewport if masks of reflective materials match this one.

Return value

Integer, each bit of which is a mask.

int getReverbMask ()

Returns the current bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match with a reverb mask of the sound source and a reverb mask of the reverberation zone. (Masks of a sound source and reverberation zone can match with the player's one in different bits, not necessarily one).

Return value

Integer, each bit of which is a mask for reverberating sound sources and reverberation zones.

mat4 getSProjection ()

Returns the current shader projection matrix. This matrix can be used for oblique projection clipping planes with correct shadow rendering.

Return value

Projection matrix.

int getSourceMask ()

Returns a bit mask that determines what sound channels can be heard. For a sound source to be heard, its mask should match with this one in at least one bit. Plus, the volume of sound channel in which the sound plays (its number also depends on this mask) should not be equal to 0.

Return value

Integer, each bit of which specifies a sound channel.

vec3 getUp ()

Returns the current up direction of the player's viewport (i.e. tilt of the player's viewport).

Return value

Upward direction vector.

vec3 getVelocity ()

Returns a player's velocity.

Return value

Velocity in units per second.

vec3 getView ()

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 getViewportMask ()

Returns the current bit mask for rendering into the viewport. Object surfaces, materials, decals, lights and GUI objects will be rendered into the viewport only if their viewport mask matches the player's one (one matching bit is enough).

Return value

Integer, each bit of which is a mask.

float getZFar ()

Returns the current distance to the far clipping plane of the player's viewing frustum.

Return value

Distance in units.

float getZNear ()

Returns the current distance to the near clipping plane of the player's viewing frustum.

Return value

Distance in units.

int isControlled ()

Returns a value indicating whether player controls are disabled (player does not respond to them) or enabled.

Return value

Positive number if player controls are disabled; otherwise, 0.

void setControlled (int mode)

Disables or enables player controls.

Arguments

int mode - Positive number to disable player controls (player stops responding to them), 0 to enable.

void setControls (Controls controls)

Sets a Controls object that will hold settings of input controls relevant to the player.

Arguments

Controls controls - Controls object used to handle input controls.

void setFov (float fov)

Sets a vertical field of view of the player. (Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio.)

Arguments

float fov - New vertical field of view in degrees. The provided value will be saturated in the range [0; 180].

void setModelview (mat4 modelview)

Updates a modelview matrix for the player.

Arguments

mat4 modelview - New modelview matrix.

void setOffset (mat4 offset)

Sets an additional transformation (an offset matrix) for the player. This transformation is applied after the model-view transformation. It does not affect it or the position of the player. For example, the offset matrix can be used to set player's head position (in case the player turns his head) or to simulate camera shake from an explosion.

Arguments

mat4 offset - Offset matrix.

void setOldModelview (mat4 modelview)

Sets the modelview matrix to be used as a previous fame matrix.

Arguments

mat4 modelview - Old modelview matrix.

void setPostMaterials (string material)

Sets post postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.
They are used after engine.render.setPostMaterials(), if any.

Arguments

string material - List of comma-separated postprocess materials names.

void setProjection (mat4 projection)

Updates the current projection matrix.

Arguments

mat4 projection - Projection matrix.

void setReflectionMask (int mask)

Sets a bit mask for rendering reflections into the viewport. Reflections are rendered in the viewport if masks of reflective materials match this one.

Arguments

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

void setReverbMask (int mask)

Updates a bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match with a reverb mask of the sound source and a reverb mask of the reverberation zone. (Masks of a sound source and reverberation zone can match with the player's one in different bits, not necessarily one).

Arguments

int mask - Integer, each bit of which is a mask for reverberating sound sources and reverberation zones.

void setSProjection (mat4 projection)

Sets a shader projection matrix. This matrix can be used for oblique projection clipping planes with correct shadow rendering.

Arguments

mat4 projection - New projection matrix.

void setSourceMask (int mask)

Updates a bit mask that determines what sound sources can be heard. For a sound source to be heard, its mask should match with this one in at least one bit. Plus, the volume of sound channel in which the sound plays (its number also depends on this mask) should not be equal to 0.

Arguments

int mask - Integer, each bit of which specifies a sound channel.

void setUp (vec3 direction)

Sets an up direction of the player's viewport (i.e. tilt of the player's viewport).

Notice

In case of PlayerActor, its transformation forces it to recalculate its inner state (position, direction, angles and so on), so the up direction of the player's viewport may become "negative forward". And then transformation will be recalculated by using this direction, causing flip of the basis of the player actor. To avoid such flipping, the theta and phi angles should be recalculated by using the current viewing orientation of the player.

Arguments

vec3 direction - New upward direction vector. The vector is normalized to 1.

void setVelocity (vec3 velocity)

Sets a player's velocity.

Notice

In case of PlayerActor, this function is valid only when the player is not simulated physically (setPhysical() is set to 0). If it is, moving PlayerActor is done via accessing its body.

Arguments

vec3 velocity - New velocity in units per second.

void setView (vec3 view)

Sets the viewing orientation of the player.

Notice

This function recalculate phi and theta angles by given vector.

Usage Example

The following example shows how to create a sphere and set PlayerActor walking on it. The gravity affects PlayerActor. In the flush() function, setView() is called. It uses current view direction of PlayerActor to recalculate theta and phi angles.

Notice

As any transformation of a player actor forces it to recalculate its inner state (position, direction, angles and so on), the up direction of the player's viewport may become "negative forward". And then transformation will be recalculated by using this direction, causing flip of the player's basis. To avoid such flipping, the theta and phi angles should be recalculated by using the current viewing orientation of the player.

Source code (UnigineScript)

PlayerActor player;
BodyRigid player_body;
ObjectMeshStatic sphere;

int init() {
	
	/* ... */

	// create a sphere with the specified radius and add it to the editor
	float radius = 20.0f;
		
	Mesh mesh = class_manage(new Mesh());
	mesh.addSphereSurface("sphere",radius,32,32);
	
	sphere = add_editor(new ObjectMeshStatic(mesh));
	sphere.setMaterial("mesh_base","*");
	sphere.setProperty("surface_base","*");
	
	// create PlayerActor
	player = add_editor(new PlayerActor());
	player.setPosition(Vec3(0.0f,0.0f,radius));
	
	player_body = body_cast(player.getBody());
	player_body.setGravity(0);
	
	engine.game.setPlayer(player);

	/* .. */
}

int flush() {
	
	/* ... */

	// apply the world force to the player body.
	Vec3 direction = normalize(player_body.getCenterOfMass() - player.getWorldPosition());
	player_body.addWorldForce(Vec3(player_body.getCenterOfMass()),direction * 9.8f * player_body.getMass());
	
	// set up direction of the player's viewport
	player.setUp(-direction);
	// recalculate the theta and phi angles to avoid flipping of the player's basis
	player.setView(player.getView());

	/* ... */
}

Arguments

vec3 view - View direction vector.

void setViewportMask (int mask)

Sets a bit mask for rendering into the viewport. Object surfaces, materials, decals, lights and GUI objects will be rendered into the viewport only if their viewport mask matches the player's one (one matching bit is enough).

Arguments

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

void setZFar (float distance)

Sets a distance to the far clipping plane of the player's viewing frustum.

Arguments

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

void setZNear (float distance)

Sets a distance to the near clipping plane of the player's viewing frustum.

Arguments

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

void updateControls (float ifps)

Gets the current player's parameters (impulse, direction, velocity etc) according to user input. After the input has been updated, flushTransform() should be called manually to apply it to the player.

Arguments

float ifps - Frame duration in seconds.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)