This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Landscape Tool
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Objects
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine.Player Class

Inherits from: Node

This class is used to create cameras that view the world. When you create a new player, it creates a camera and specifies controls, masks, postprocess materials for this camera.

Players' 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 projection matrix and after that call any of these functions:

your custom matrices will be overwritten.

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

Player Masks#

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):

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 viewport mask should match:

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 viewport mask.

Players also can have sound source and sound reverberation masks. As well as for viewports, corresponding masks of the Player object should match with SoundReverb and SoundSource masks.

Perspective and Orthographic Projection#

Depending on your project's requirements you can set your player to use perspective or orthographic projection. This can be done via the setProjection() method.

For example, you can use the following code to set up orthographic projection or perspective projection for your current game player depending on a flag value:

Source code (C#)
// AppWorldLogic.cs

namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
		Player player;

		/* ... */
		
		// ortho flag - change this value to switch projection type
		int ortho = 0;
		public override bool Init()
		{
			/* ... */
			
			// getting the current player
			player = Game.Player;
	
			// setting up near and far clipping planes and aspect ratio
			float znear = 0.001f;
			float zfar = 10000.0f;
			float aspect = 16.0f / 9.0f;

			if (ortho)
			{
				// setting up orthographic projection
				player.Projection = MathLib.Ortho(-1.0f, 1.0f, -1.0f, 1.0f, znear, zfar);
			}
			else
			{
				// setting up perspective projection
				player.Projection = MathLib.Perspective(60.0f, aspect, znear, zfar);
			}

			return true;
		}
	}
}

Getting Euler Angles for an Active Camera

Sometimes it might be necessary to get current rotation of the active camera as a set of Euler angles. When we talk about axes in UNIGINE we assume that:

  • X axis points to the right giving us a pitch angle.
  • Y axis points forward giving us a roll angle.
  • Z axis points up giving us a yaw (heading) angle.
Object Direction Vectors

To get the Euler angles we should use decomposeRotationZXY() also known as Cardan angles (yaw is independent, then we get pitch and in the end, roll). But, there is one thing to be taken into account - cameras have a different system:

  • X axis points to the right giving us a pitch angle.
  • Y axis points up giving us a yaw (heading) angle.
  • Z axis points backward giving us a -roll angle.
Camera Direction Vectors
To compensate it, we need to rotate our camera -90 degrees around X axis.
Source code (C#)
#if UNIGINE_DOUBLE
using Mat4 = Unigine.dmat4;
#else
	using Mat4 = Unigine.mat4;
#endif
// getting the current view matrix of the current camera
Mat4 currentModelview = Game.Player.Camera.IModelview;

// decomposing rotation matrix of the camera (with compensation)
vec3 euler = MathLib.DecomposeRotationZXY(new mat3(currentModelview * new Mat4(MathLib.RotateX(-90.0f))));
euler.x += 90.0f;

// perform correction for negative angle values
if (euler.x < 0) euler.x += 360.0f;
if (euler.y < 0) euler.y += 360.0f;
if (euler.z < 0) euler.z += 360.0f;

// Euler angles for the camera
float pitch = euler.x;
float roll = euler.y;
float yaw = euler.z;

Usage Example

In this example a PlayerSpectator class instance (which inherited from Player class) created and added to the current scene. Here is a code from the AppWorldLogic.cs file.

Source code (C#)
namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
		PlayerSpectator playerSpectator;

		/* ... */

		public override bool Init()
		{
			/* ... */
			playerSpectator = new PlayerSpectator();

			// specify the necessary parameters: FOV, ZNear, ZFar, view direction vector and PlayerSpectator position.
			playerSpectator.Fov = 90.0f;
			playerSpectator.ZNear = 0.1f;
			playerSpectator.ZFar = 10000.0f;
			playerSpectator.ViewDirection = new vec3(0.0f, 1.0f, 0.0f);
			playerSpectator.WorldPosition = new dvec3(-1.6f, -1.7f, 1.7f);

			// set the Player to the Game singleton instance
			Game.Player = playerSpectator;

			return true;
		}
	}
}

Player Class

Properties

Camera Camera#

The camera instance of the player node.
set
Sets given Camera instance to the Player.
set value - Camera instance to be set.

int NumScriptableMaterials#

The total number of scriptable materials attached to the player.

bool MainPlayer#

A value indicating indicating if the player is a main player.
set
Sets a player as a main player.
set value - true to set the player as the main player, false to unset it.

Controls Controls#

A controls smart pointer that holds settings of input controls relevant to the player.
set
Sets a Controls object that will hold settings of input controls relevant to the player.
set value - Controls object used to handle input controls.

bool Controlled#

A value indicating whether player controls are disabled (player does not respond to them) or enabled.
set
Disables or enables the player controls.
set value - true to enable player controls, false to disable (player stops responding to them).

vec3 Velocity#

The current velocity of the player.
set
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.
set value - New velocity in units per second.

vec3 ViewDirection#

Player's view direction vector.
set
Sets given view direction vector to the Player instance.
set value - A view direction vector.

string PostMaterials#

Names of postprocess materials applied after all other postprocess (such as hdr, dof, etc.) are rendered.
set
Sets postprocess materials that are applied after all other postprocess (such as HDR, DOF, etc.) are rendered.
set value - List of comma-separated postprocess materials names.

int ReverbMask#

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).
set
Sets a reverb mask that determines reverberation zones, which 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.
set value - Integer, each bit of which is a mask for reverberating sound sources and reverberation zones.

int SourceMask#

The source mask that determines sound sources, which 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.
set
Sets a source mask that determines sound sources, which 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.
set value - Integer, each bit of which specifies a sound channel.

int ReflectionViewportMask#

The current bit mask for rendering reflections into the viewport. reflections are rendered in the viewport if masks of reflective materials match this one (one bit at least).
set
Sets a bit mask for rendering reflections into the viewport. Reflections are rendered in the viewport if masks of reflective materials match this one (one bit at least).
set value - Reflection viewport mask (an integer, each bit of which is a mask).

int ViewportMask#

The current viewport mask. 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).
set
Sets a viewport mask. 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).
set value - Integer, each bit of which is a mask.

bool ObliqueFrustum#

A value indicating if the viewing frustum is oblique.
set
Enables or disables obliqueness of the viewing frustum.
Notice
It is recommended to set oblique viewing frustum using this method, as it doesn't affect the projection matrix. To specify the near clipping plane use the setObliqueFrustumPlane() method.
set value - true to enable oblique viewing frustum; false to disable it.

vec4 ObliqueFrustumPlane#

The oblique near clipping plane of the viewing frustum.
set
Sets the oblique near clipping plane of the viewing frustum.
Notice
This method does not affect the projection matrix. To enable the oblique frustum use the setObliqueFrustum() method.
Source code (C#)
// AppWorldLogic.cs
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Unigine;

namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
		/* .. */
		
		public override bool Update()
		{

            float time = Game.Time;
			
				// initializing a plane to be set as a near clipping plane
                dvec4 plane = new dvec4(1.0f, 1.0f, 1.0f, 1.0f + MathLib.Sin(time) * 4.0f);
				
				// getting a player
                Player player = Game.Player;
                if (player != null)
                {
					// enabling oblique frustum
                    player.ObliqueFrustum = true;

					// setting our plane as an oblique near clipping plane
                    player.setObliqueFrustumPlane(plane);
                }

            return true;
		}
		
		/* .. */
	}
}
set value - World coordinates of the oblique near clipping plane to set (Nx, Ny, Nz, D), where Nx, Ny, Nz - coordinates of the plane normal, D - distance from the origin to the plane.

vec3 Up#

The current up direction of the player's viewport (i.e. tilt of the player's viewport).
set
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.
set value - New upward direction vector. The vector is normalized to 1.

float ZFar#

The current distance to the far clipping plane of the player's viewing frustum. the default is 10000 units.
set
Sets a distance to the far clipping plane of the player's viewing frustum. The default is 10000 units.
set value - New distance in units. If a negative value is provided, 0 will be used instead.

float ZNear#

The distance to the near clipping plane of the player's viewing frustum. the default is 0.1 units.
set
Sets a distance to the near clipping plane of the player's viewing frustum. The default is 0.1 units.
set value - New distance in units. If a negative value is provided, 0 will be used instead.

float FocalLength#

The focal length of the physically-based camera lens.
set
Sets a focal length of the physically-based camera lens.
set value - Camera lens focal length.

float FilmGate#

A film gate for the physically-based camera with horizontal fov.
set
Sets a film gate for the physically-based camera with horizontal FOV.
set value - Film gate.

float Fov#

Current vertical field of view of the player.

Notice
Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio. Setting FOV recalculates projection matrix with aspect ratio = 1.

You can use the following formula to calculate horizontal FOV from the vertical one for the given aspect ratio (width/height): FOV_h = 2 × atan ( (width / height) × tan(FOV_v / 2)).

set

Sets a vertical field of view of the player.

Notice
Horizontal FOV cannot be used since it varies depending on the viewport's aspect ratio. Setting FOV recalculates projection matrix with aspect ratio = 1.

You can use the following formula to calculate horizontal FOV from the vertical one for the given aspect ratio (width/height): FOV_h = 2 × atan ( (width / height) × tan(FOV_v / 2)).

set value - New vertical field of view in degrees. The provided value will be saturated in the range [0; 180]. The default is 60 degrees.

int FovFixed#

A value indicating which fov component (horizontal or vertical) is currently fixed.

int FovMode#

Sets the value indicating the type of FOV that is used for the player.
set
Sets the value indicating the type of FOV that is used for the player:
  • For the standard player, the vertical FOV should be set. In this case, FOV is directly set in degrees.
  • For the physically-based player, the horizontal FOV should be set. In this case, FOV is calculated depending on the film gate and focal length of the player.
set value - FOV_MODE_VERTICAL for the player with the vertical FOV; FOV_MODE_PHYSICALLY_BASED_CAMERA for the physically-based player with the horizontal FOV.

mat4 Projection#

The current projection matrix with unit (1.0) aspect ratio.
set
Updates the current projection matrix.
Notice
It is not recommended to use this method for setting obliqueness of the near clipping plane of the frustum, as in this case a number of features (such as clouds, shadows, TAA, a number of engine optimizations, etc.) will not function properly. Please, use the setObliqueFrustum() method instead.
set value - New projection matrix.

bool Listener#

Checks if the player is a listener.
set
Sets the player as the listener.
set value - true to set the player as the listener, false to unset it.

Members


void GetDirectionFromScreen ( out Vec3 p0, out Vec3 p1, int x = -1, int y = -1, int width = -1, int height = -1 ) #

Casts the ray to a certain position on the screen and returns coordinates of the start (p0) and end (p1) points of the ray.
Source code (C#)
// get the current player (camera)
Player player = Game.Player;
if (player == null)
	return 0;
// get width and height of the current application window
int width = App.getWidth();
int height = App.getHeight();
// get the current X and Y coordinates of the mouse pointer
int mouse_x = App.getMouseX();
int mouse_y = App.getMouseY();
// get the mouse direction from the player's position (p0) to the mouse cursor pointer (p1)
player.getDirectionFromScreen(out p0, out p1, mouse_x, mouse_y, width, height);

Arguments

  • out Vec3 p0 - Start coordinates of the ray.
  • out Vec3 p1 - End coordinates of the ray.
  • int x - X-coordinate of the screen position. If the value is less than 0, the getMouseX() value will be used.
  • int y - Y-coordinate of the screen position. If the value is less than 0, the getMouseY() value will be used.
  • int width - Screen width. If the width is less than 0, the getWidth() value will be used.
  • int height - Screen height. If the height is less than 0, the getHeight() value will be used.

vec3 GetDirectionFromScreen ( int x = -1, int y = -1, int width = -1, int height = -1 ) #

Casts the ray to a certain position on the screen and returns a vector in the direction of this position.
Source code (C#)
// initializing points of the ray from player's position in the direction pointed by the mouse cursor 
Vec3 p0 = player.getWorldPosition();
Vec3 p1 = p0 + Vec3(player.getDirectionFromScreen(App.getMouseX(), App.getMouseY())) * 100;

Arguments

  • int x - X-coordinate of the screen position. If the value is less than 0, the getMouseX() value will be used.
  • int y - Y-coordinate of the screen position. If the value is less than 0, the getMouseY() value will be used.
  • int width - Screen width. If the width is less than 0, the getWidth() value will be used.
  • int height - Screen height. If the height is less than 0, the getHeight() value will be used.

Return value

Vector coordinates.

mat4 GetProjectionFromScreen ( int x0, int y0, int x1, int y1, int width = -1, int height = -1 ) #

Creates a projection matrix out of 2 screen positions. This is required for the frame selection.

Arguments

  • int x0 - X-coordinate of the first screen position.
  • int y0 - Y-coordinate of the first screen position.
  • int x1 - X-coordinate of the second screen position.
  • int y1 - Y-coordinate of the second screen position.
  • int width - Screen width. If the width is less than 0, the getWidth() value will be used.
  • int height - Screen height. If the height is less than 0, the getHeight() value will be used.

Return value

Projection matrix.

int GetScreenPosition ( out int x, out int y, vec3 point, int width = -1, int height = -1 ) #

Projects the point in world coordinates to the screen. Screen coordinates are written into the first 2 variables passed to the method.

Arguments

  • out int x - X-coordinate of the screen position.
  • out int y - Y-coordinate of the screen position.
  • vec3 point - Point coordinates.
  • int width - Screen width. If the width is less than 0, the getWidth() value will be used.
  • int height - Screen height. If the height is less than 0, the getHeight() value will be used.

Return value

1 if the point has been projected successfully; otherwise, 0.

void FlushTransform ( ) #

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

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.

mat4 GetAspectCorrectedProjection ( int width = -1, int height = -1 ) #

Returns projection matrix after correction for the specified aspect ratio (screen width / screen height). Currently fixed FOV component is taken into account.

Arguments

  • int width - Screen width.
  • int height - Screen height.

Return value

Projection matrix after correction for the specified aspect ratio (screen width / screen height).

void AddScriptableMaterial ( Material material ) #

Attaches a new scriptable material to the player. To apply a scriptable material globally, use the addScriptableMaterial() method of the Render class. The order of execution for scripts assigned to scriptable materials is defined by material's number in the list of the player.
Notice
Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

  • Material material - Scriptable material to be attached to the player.

void InsertScriptableMaterial ( int num, Material material ) #

Inserts a new scriptable material into the list of the ones assigned to the player. To apply a scriptable material globally, use the insertScriptableMaterial() method of the Render class. The order of execution for scripts assigned to scriptable materials is defined by material's number in the player's list.
Notice
Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

  • int num - Position at which a new scriptable material is to be inserted.
  • Material material - Scriptable material to be inserted.

void RemoveScriptableMaterial ( int num ) #

Removes the scriptable material with the specified number from the player.

Arguments

int FindScriptableMaterial ( Material material ) #

Returns the number of the specified scriptable material for the player. This number is player-specific (valid for this player only) and determines the order in which the assigned expressions are executed.
Notice
Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

  • Material material - Scriptable material for which a number is to be found.

Return value

Scriptable material number in the range from 0 to the total number of scriptable materials, or -1 if the specified material was not found.

void SetScriptableMaterial ( int num, Material material ) #

Replaces the scriptable material with the specified number with the new scriptable material specified. The number of material determines the order in which the expressions assigned to it are executed. This number is player-specific (valid for this player only).
Notice
Scriptable materials applied globally have their expressions executed before the ones that are applied per-player.

Arguments

Material GetScriptableMaterial ( int num ) #

Returns a scriptable material attached to the player by its number.

Arguments

Return value

Scriptable material attached to the player with the specified number.

void SetScriptableMaterialEnabled ( int num, bool enabled ) #

Enables or disables the scriptable material with the specified number. When a material is disabled (inactive), the scripts attached to it are not executed.

Arguments

  • int num - Scriptable material number in the range from 0 to the total number of scriptable materials.
  • bool enabled - true to enable the scriptable material with the specified number, false to disable it.

bool GetScriptableMaterialEnabled ( int num ) #

Returns a value indicating if the scriptable material with the specified number attached to the player is enabled (active). When a material is disabled (inactive), the scripts attached to it are not executed.

Arguments

Return value

true if the scriptable material with the specified number is enabled; otherwise, false.

void SwapScriptableMaterials ( int num_0, int num_1 ) #

Swaps two scriptable materials with specified numbers. The number of material determines the order in which the expressions assigned to it are executed.
Notice
The number is player-specific (valid for this player only).

Arguments

void ClearScriptableMaterials ( ) #

Clears all scriptable materials attached to the player.

void SetListener ( bool listener ) #

Sets the player as the listener.

Arguments

  • bool listener - true to set the player as the listener, false to unset it.

bool IsListener ( ) #

Checks if the player is a listener.

Return value

true if the player is a listener; otherwise, false.
Last update: 2021-04-29
Build: ()