#include <LUA_API_CharacterController.h>

Public Member Functions
void	move (int EntityID, int Speed)
	Moves the character by the arg speed. More...

void	moveUp (int EntityID, int moveUpSpd)
	Moves the character up/down by the arg speed. More...

void	setActive (int EntityID, int state)
	Enable or disable the SCC physics. state=1 for enabled. More...

int	isActive (int objID)
	Returns the current characters activity state. Either 1=enabled or 0=deactivated. More...

void	doStrafe (int EntityID, int state)

void	doJump (int EntityID, int force)

void	setJumpDownforce (int EntityID, int force)

void	setGravity (int EntityID, float x, float y, float z)

void	enableGravity (int EntityID, state)

void	invertGravity (int EntityID, state)

void	setPosition (int entityID, float x, float y, float z)
	Sets the player position . More...

void	setPositionString (int entityID, String xyz)
	Sets the player position . More...

void	getPosition (int EntityID)

void	getCollisionFlag (int EntityID)
	A flag value that is returned from the system when this controller collides with an object. More...

void	setMoveDirection (int EntityID, float x, float y, float z)

void	ko (int entityID)
	Sets the player to its knock out status and is provided to have more dynamic control over certain players features. More...

void	revive (int entityID)
	Sets the player to its knock out status to false and enable the characters movement once again. Provided to have more dynamic control over certain players features. More...

void	followPath (int entityID, string pathName, float speed)
	make the character controller action follow a path simply by calling this function in an update loop. The movement will automatically be smoothed out based on the setPathAccuracy() accuracy and svariable. More...

int	isFollowingPath (int entityID)
	return whether the character is currently following a path. More...

void	setPathAccuracy (int entityID, float accuracy)
	Set the accuracy of the path to follow. Lower numbers make the distance to each node before trigger smaller. More...

void	setPathMaxTurn (int entityID, float maxTurn)
	Set the speed of the turning rate for this character. More...

void	setPathNodeIndex (int entityID, int nodeIndex)
	Set the current node index the character should head towards on the currently set path. More...

void	followPathPosition (int entityID, float x, float y, float z)
	Override the default path follow and enter your own point to move to. In order for this to take effect, you need to pass a "" in the follow path function. See the example below. More...

int	isDestinationReached (int entityID)
	Poll to check if the character has reached its destination. More...

void	setAdvancedCollision (int entityID, int state)
	Setting advanced Collisions. More...

void	setDimension (int entityID, float radius, float height)
	Change the dimensions of a chatacter controller by passing radius and height. More...

void	setOffset (int entityID, float x, float y, float z)
	Set the offset of the mesh that is moved by the capsule. More...

vec3	getOffset (int entityID, float x, float y, float z)
	Get the offset of the mesh that is moved by the capsule. More...

Detailed Description

The following functions can be used to manage and control character controllers, most functions require the addition of
the SimpleCharacterController to your scene.

The following code is a simple example of using the simple character controller:

    obj             = 0;
    walkSpeed       = 30;
    turnSpeed       = 0.3;
    upSpeed         = 20;
    inv             = 1;
    gvty            = 1;

    function onInit(objID)
        obj = objID;
        character.setJumpDownforce(obj,850);
        character.setGravity(obj, 0, -10, 0);
    end

    function onUpdate( td )
        moveSpd     = 0;
        moveStr     = 0;
        moveUPSpd   = 0;
        
        if(input.keyDown("i")==1)  then moveSpd     = walkSpeed; end
        if(input.keyDown("k")==1)  then moveSpd     = -walkSpeed; end
        if(input.keyDown("u")==1)  then moveStr     = walkSpeed; end
        if(input.keyDown("o")==1)  then moveStr     = -walkSpeed; end
        if(input.keyDown("y")==1)  then moveUPSpd   = upSpeed; end
        if(input.keyDown("h")==1)  then moveUPSpd   = -upSpeed; end

        if (input.keyDown("j")==1) then entity.turn(obj, 0, turnSpeed * td, 0)
        elseif (input.keyDown("l")==1) then entity.turn(obj, 0, -turnSpeed * td, 0)
        end

        --Requires the action property "SCC Use Simple Move" to be disabled
        --character.setMoveDirection(obj,0,0,1);

        --Simple detection based on the collision flags
        --collisionDetection();
        
        --to use the up/down gravity must be reduced for this to have an effect
        character.moveUp(obj, moveUPSpd)
        character.move(obj, moveSpd ); 
        character.doStrafe(obj, moveStr ); 
    end

    function collisionDetection()
        -- flag = 4 results when the object hits the floor
        -- flag = 2 results whent he object hits the roof
        -- flag = 5 results when the object hits a wall
        if(character.getCollisionFlag(obj) == 4) then character.invertGravity(obj,1); end
        if(character.getCollisionFlag(obj) == 2) then character.invertGravity(obj,0); end
    end

    function onCollisionDownEvent()
        --Collision when CC hits the ground
    end

    function onKeyDown( key )
        if(key=="space") then character.doJump(obj,550); end
        if(key=="1") then gvty = 1-gvty; character.enableGravity(obj,gvty); end
        if(key=="2") then inv = 1-inv; character.invertGravity(obj,inv); end
        if(key=="3") then character.setGravity(obj, 0, -0.5, 0); end
        if(key=="4") then character.setGravity(obj, 0, -10, 0); end

        if(key=="5") then 
            x,y,z = character.getPosition(obj);
            sky.lprint("X:"..x.."  Y:"..y.."  Z:"..z);
        end
        
        if(key=="6") then character.setPosition(obj, 0, 10, 0); end
        if(key=="7") then character.moveUp(obj, 5); end
        
    end

For more information on how these functions can be used please visit the User Manual - https://home.aurasoft-skyline.co.uk

Member Function Documentation

void character::doJump	(	int	EntityID,
		int	force
	)

void character::doStrafe	(	int	EntityID,
		int	state
	)

void character::enableGravity	(	int	EntityID,
		state
	)

void character::followPath	(	int	entityID,
		string	pathName,
		float	speed
	)

make the character controller action follow a path simply by calling this function in an update loop.
The movement will automatically be smoothed out based on the setPathAccuracy() accuracy and svariable.

Parameters

objID	: This is the id of the entity the character controller action is attached to.
pathname	: The path to follow, change the name on the fly to start following another path without position stepping.
speed	: The speed the controller should move to follow the path. Best to match animation speed for example walk or run. This variable already uses timedelta in the system to keep framerate in check.

Here is a Small Example of how to use this function:

function onUpdate(timeDelta)
    character.followPath(entityID, pathName, 5);
end

Yes, thats all thats needed to follow a path accurately and very fast. =)

void character::followPathPosition	(	int	entityID,
		float	x,
		float	y,
		float	z
	)

Override the default path follow and enter your own point to move to.
In order for this to take effect, you need to pass a "" in the follow path function. See the example below.

Calling this function on its own will result in nothing happening, it has to be used in conjunction with character.followPath()

Parameters

objID	: This is the id of the entity the character controller action is attached to.
x	: This is the x world position axis. Is defined as a float
y	: This is the y world position axis. Is defined as a float
z	: This is the z world position axis. Is defined as a float

Here is a Small Example of how to use this function:

function onInit(objID)
    character.followPathPosition(entityID, posArray[0].x, posArray[0].y, posArray[0].z );
end

function onUpdate(timeDelta)
    if(character.isDestinationReached(entityID) == 1)then
        posIndex = posIndex + 1;
        newPos = newType.vec3(posArray[posIndex].x, posArray[posIndex].y, posArray[posIndex].z);
        character.followPathPosition(entityID, newPos.x, newPos.y, newPos.z );
    end
    
    character.followPath(entityID, "", 5.0f); -- set path blank as you do not need one.

end

void character::getCollisionFlag ( int EntityID )

A flag value that is returned from the system when this controller collides with an object.

Parameters

entityID : The entityID with the attached FPS System action

The values vary based upon how the collision is made.
top collision = 2
side collision = 5
ground collision = 4
no collision = 0
Here is a Small Example of how to use this function:

    function onUpdate( timeDelta )
     sky.lprint("collision: "..character.getCollisionFlag(obj));
    end

vec3 character::getOffset	(	int	entityID,
		float	x,
		float	y,
		float	z
	)

Get the offset of the mesh that is moved by the capsule.

Parameters

entityID : The entity ID the Action is applied to.

Returns: offsetX : Returns the X Axis component offset in world space; offsetY : Returns the X Axis component offset in world space; offsetZ : Returns the X Axis component offset in world space

function onUpdate( td )
    x,y,z = character.getOffset( objID );
end

void character::getPosition ( int EntityID )

void character::invertGravity	(	int	EntityID,
		state
	)

int character::isActive ( int objID )

Returns the current characters activity state. Either 1=enabled or 0=deactivated.

Parameters

obj	: This is the id of the entity the character controller action is attached to.

Returns: int: 1= character is active, 0 = character is disabled.

int character::isDestinationReached ( int entityID )

Poll to check if the character has reached its destination.

Parameters

objID : This is the id of the entity the character controller action is attached to.

Here is a Small Example of how to use this function:

function 
    
    chara1_dest = isDestinationReached(entity.getIDFromTag("char1"));

end

int character::isFollowingPath ( int entityID )

return whether the character is currently following a path.

Parameters

objID : This is the id of the entity the character controller action is attached to.

Returns: isFollowing : This is an integer value representing a boolean. 1 = true, 0 = false

Here is a Small Example of how to use this function:

function onUpdate(timeDelta)
    isFollowingPath = character.isFollowingPath(entityID);
end

void character::ko ( int entityID )

Sets the player to its knock out status and is provided to have more dynamic control over certain players features.

Parameters

entityID : The EntityID with the attached SCC System action

Sets the SCC to KO status and renders the input control and physics body inactive.

Here is a Small Example of how to use this function:

function ds_onKo()
    character.ko(obj);
end

void character::move	(	int	EntityID,
		int	Speed
	)

Moves the character by the arg speed.

Parameters

Speed : The speed of the movement where 0 = stoped.

Calling this command will advance the characters position in the objects direction.
The following is a Small Example on how to use this function:

obj             = 0;
walkSpeed       = 30;
turnSpeed       = 0.3;

function onInit(objID)
    obj = objID;
    character.setGravity(obj,"0 -9 0");
end

function onUpdate( td )
    moveSpd = 0;
    moveStr = 0;

    if(input.keyDown("i")==1)  then moveSpd = walkSpeed; end
    if(input.keyDown("k")==1)  then moveSpd = -walkSpeed; end
    if(input.keyDown("u")==1)  then moveStr = walkSpeed; end
    if(input.keyDown("o")==1)  then moveStr = -walkSpeed; end

    if (input.keyDown("j")==1) then entity.turn(obj, 0, turnSpeed * td, 0)
    elseif (input.keyDown("l")==1) then entity.turn(obj, 0, -turnSpeed * td, 0)
    end

    character.move(obj, moveSpd ); 
    character.doStrafe(obj, moveStr ); 
end

void character::moveUp	(	int	EntityID,
		int	moveUpSpd
	)

Moves the character up/down by the arg speed.

Parameters

Speed : The speed of the movement where 0 = stoped.

Calling this command will advance the characters position in the objects direction.
The following is a Small Example on how to use this function:

obj             = 0;
walkSpeed       = 30;
turnSpeed       = 0.3;

function onInit(objID)
    obj = objID;
    character.setGravity(obj,"0 -9 0");
end

function onUpdate( td )
    moveSpd = 0;
    moveStr = 0;

    if(input.keyDown("i")==1)  then moveSpd = walkSpeed; end
    if(input.keyDown("k")==1)  then moveSpd = -walkSpeed; end
    if(input.keyDown("u")==1)  then moveStr = walkSpeed; end
    if(input.keyDown("o")==1)  then moveStr = -walkSpeed; end

    if (input.keyDown("j")==1) then entity.turn(obj, 0, turnSpeed * td, 0)
    elseif (input.keyDown("l")==1) then entity.turn(obj, 0, -turnSpeed * td, 0)
    end

    character.move(obj, moveSpd ); 
    character.doStrafe(obj, moveStr ); 
end

void character::revive ( int entityID )

Sets the player to its knock out status to false and enable the characters movement once again. Provided to have more dynamic control over certain players features.

Parameters

entityID : The EntityID with the attached SCC System action

Used when re-spawning after KO.

void character::setActive	(	int	EntityID,
		int	state
	)

Enable or disable the SCC physics. state=1 for enabled.

Parameters

obj	: This is the id of the entity the character controller action is attached to.
state	: Set the current activity state 1=enabled 0=deactivated)

void character::setAdvancedCollision	(	int	entityID,
		int	state
	)

Setting advanced Collisions.

the state refers to the boolean value of true or false in the form of 0 and 1. In other words on/off
same as controller.setAdvancedCollision()
Note: character.functions are built for the SCC(Simple Character Controller) action added to the entities.

function 

    setAdvancedCollision( int entityID, int state);

    end
end

void character::setDimension	(	int	entityID,
		float	radius,
		float	height
	)

Change the dimensions of a chatacter controller by passing radius and height.

Note: This recreates the controller as PhysX 2.x cannot change the capsule dimensions properly.

Parameters

entityID	: The entity ID the Action is applied to.
radius	: The radius of the capsule
height	: The height of the capsule

function onKeyDown( key )
    if(key == "control")then
        character.setDimensions( entityID, radius, height );
        character.setOffset( entityID, 0, 0.5, 0 );
    end
end

void character::setGravity	(	int	EntityID,
		float	x,
		float	y,
		float	z
	)

void character::setJumpDownforce	(	int	EntityID,
		int	force
	)

void character::setMoveDirection	(	int	EntityID,
		float	x,
		float	y,
		float	z
	)

void character::setOffset	(	int	entityID,
		float	x,
		float	y,
		float	z
	)

Set the offset of the mesh that is moved by the capsule.

Parameters

entityID	: The entity ID the Action is applied to.
x	: The X Axis offset position in world space
y	: The Y Axis offset position in world space
z	: The Z Axis offset position in world space

function onKeyDown( key )
    if(key == "control")then
        character.setDimensions( objID, radius, height );
        character.setOffset( objID, 0, 0.5, 0 );
    end
end

void character::setPathAccuracy	(	int	entityID,
		float	accuracy
	)

Set the accuracy of the path to follow. Lower numbers make the distance to each node before trigger smaller.

Parameters

objID	: This is the id of the entity the character controller action is attached to.
accuracy	: This number increases the distance allowed to the wanted node before it triggers to move to the next. If a character travels faster, then you will want a larger accuracy to catch them from going off the path and a faster turn speed.

Here is a Small Example of how to use this function:

function onUpdate(timeDelta)
    character.setPathAccuracy(entityID, 10);
    character.followPath(entityID, pathName, 5);
end

void character::setPathMaxTurn	(	int	entityID,
		float	maxTurn
	)

Set the speed of the turning rate for this character.

Parameters

objID	: This is the id of the entity the character controller action is attached to.
maxTurn	: This number increases the speed of rotation to make the character more responsive. Higher numbers will make the character stick closer to the path lines. Lower numbers make it smoother.

Here is a Small Example of how to use this function:

function onUpdate(timeDelta)
    character.setPathMaxTurn(entityID, 5.0);
    character.followPath(entityID, pathName, 5);
end

void character::setPathNodeIndex	(	int	entityID,
		int	nodeIndex
	)

Set the current node index the character should head towards on the currently set path.

Parameters

entityID	: This is the id of the entity the character controller action is attached to.
nodeIndex	: Set the node index of the path to move to, it will then carry on sequentially.

Here is a Small Example of how to use this function:

function onUpdate(timeDelta)
    character.setPathNodeIndex(entityID, 2);
    character.followPath(entityID, pathName, 5);
end

void character::setPosition	(	int	entityID,
		float	x,
		float	y,
		float	z
	)

Sets the player position .

Parameters

entityID	: The EntityID with the attached FPS System action
x	: The x position .
y	: The y position .
z	: The z position .

Sets the players position including character controller. Used when re-spawning after KO.

Here is a Small Example of how to use this function:

    character.setPosition(obj, 10, 20, 12);

void character::setPositionString	(	int	entityID,
		String	xyz
	)

Sets the player position .

Parameters

entityID	: The EntityID with the attached FPS System action
String	: The position xyz formated in a string.

Sets the players position including character controller. Used when re-spawning after KO.

Here is a Small Example of how to use this function:

    character.setPositionString(obj, "10 20 12");

The documentation for this class was generated from the following file:

LUA_API_CharacterController.h

Public Member Functions

Detailed Description

Member Function Documentation