#include <LUA_API_Controller.h>

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

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

int	spawn (int objID)
	This commands add a dynamic character controller(DCC) to any scene entity. More...

void	doStrafe (int dccID, int state)

void	doJump (int dccID, int force)

void	setJumpDownforce (int dccID, int force)

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

void	enableGravity (int dccID, int state)

void	invertGravity (int dccID, int state)

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

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

void	getPosition (int dccID)

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

void	setCollisionFlag (int dccID, String flags)
	A flag value that is returned from the system when this controller collides with an object. More...

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

void	setData_upDirectionIndex (float val)

void	setData_skinWidth (float val)

void	setData_flipDirection (bool state)

void	setData_slopeLimit (float val)

void	setData_gravityY (float val)

void	setData_stepOffset (float val)

void	setData_characterWidth (float val)

void	setData_shapeType (float val)

void	setData_characterHeight (float val)

void	setData_Offset (float x, float y, float z)

void	resetData ()
	Resets the controller setup date back to its default. This handled internally for you but the command is here just in case you need it. Sets the players position including controller. Used when re-spawning after KO. More...

void	getContactHit_ID (int dccID)
	Gets the last collision contacts hit information - Parent ID. More...

void	getContactHit_WorldPos (int dccID)
	Gets the last collision contacts hit information - WorldPos. More...

void	getContactHit_WorldNormal (int dccID)
	Gets the last collision contacts hit information - WorldNormal. More...

void	getContactHit_MotionDirection (int dccID)
	Gets the last collision contacts hit information - MotionDirection. More...

void	getContactHit_MotionLength (int dccID)
	Gets the last collision contacts hit information - motionLength. More...

void	setQueryFlag (int dccID, int flag)
	Sets the controllers query flag use for overlapping object query such as sensor and raycast. More...

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

int	isFollowingPath (int dccID)
	return whether the controller is currently following a path. More...

string	getFollowPathName (int dccID)
	return the name of the path the controller is following More...

void	setPathAccuracy (int dccID, 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 dccID, float maxTurn)
	Set the maximum speed of the turning rate for this controller. More...

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

void	followPathPosition (int dccID, 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 dccID)
	Poll to check if the controller has reached its destination. More...

void	setAdvancedCollision (int dccID, int state)
	Set Advanced Collisions. More...

void	setMoveAdvanced (int dccID, int state)
	Setting advanced move. More...

int	getBodyID (int dccID)
	Get the Body ID of the object with a dynaminc character controller. More...

void	remove (int dccID)
	remove( int dccID ); More...

void	setMoveAdvanced (int dccID, int state)
	setMoveAdvanced More...

void	setAdvancedCollision (int dccID, int state)
	setAdvancedCollision More...

void	setAdvancedCollision (int dccID, int state)
	setAdvancedCollision More...

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

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

float3	getOffset (int dccID, 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 Dynamic Character Controllers (DCC). Use when spawning players or AI bots.
The following code is a simple example of using the Dynamic Character Controller:

        function vector3()v3={x=0,y=0,z=0}return v3;end

        obj             = 0;
        timer_Interval1 = 1000; --( time in ms ie 1000ms = 1sec )
        walkSpeed       = 2.0
        rotDelay        = 380; -- larger for quicker move
        currentDelay    = 0;
        cYaw            = 0;
        posID           = -1;
        pos             = vector3();
        rayID = 0;  
        range = 10

        RadiusOffset = 0.4;

        function onInit(objID)
            obj = objID;
            controller.setData_Offset(0,-1.0,0); 
            controller.setData_characterHeight(1.0);
            controller.setData_shapeType(0);
            controller.setData_characterWidth(0.3);
            controller.setData_stepOffset(0.4); 
            controller.setData_gravityY(-4);
            controller.setData_slopeLimit(60);
            controller.setData_flipDirection(0);
            controller.setData_skinWidth(0.1);
            controller.setData_upDirectionIndex(1); 
            dccID = controller.spawn(obj);
            controller.setJumpDownforce(dccID,30);  
            spawnMarker();
            rayID = physics.createRay();
            physics.rayDebugLines(rayID,1); 
        end

        function spawnMarker()
            x,y,z = entity.getPosition(obj);
            posID = entity.spawn("Cylinder_BarrelSize",x,y+0.5,z,1,1,1);
            entity.setMaterialName(posID,"transparent");
            pID = physics.addBody(posID,0, 1);
            entity.setShadow(posID,0);
        end

        function onMouseDown( button, x, y )
            pos.x,pos.y,pos.z = sky.raycastToCursor(); 
            physics.setPosition(pID,pos.x,pos.y+0.5,pos.z);
            moveSpd = walkSpeed;
        end     

        function onUpdate( td )
            x,y,z = entity.getPosition(obj)
            dx,dy,dz = entity.getLocalOrientationByAxis( obj, 0,0,1 );
            qw,qx,qy,qz = entity.getWorldOrientation(obj)
            x=x+(dx*RadiusOffset);
            y=y+(dy*RadiusOffset)+0.8;
            z=z+(dz*RadiusOffset);
            hitID,pox,posy,posz = physics.rayFromPoint(rayID, x,y,z,qw,qx,qy,qz,-range);
            
            if(td>40) then td = 20; end
            controller.move(dccID, moveSpd );
            currentDelay = rotDelay * (td*0.001);
            trackTarget();
            if(controller.getCollisionFlag(dccID)==5 and moveSpd > 0) then 
                moveSpd = 0;
                sky.trace();
            end
        end

        function trackTarget()
            entity.setRotation(obj, 0,0,0);
            yawDeg      = entity.getHeading(obj,posID);
            cYaw        = getYawLerp(cYaw, yawDeg);
            entity.yaw(obj, cYaw, 0);
        end

        -- | Get the Yaw Lerped values.
        function getYawLerp( currentYaw, yawDeg )
            if(     currentYaw > 180 ) then currentYaw = -180;
            elseif( currentYaw < -180 )then currentYaw = 180; end

            if(currentYaw >= yawDeg-currentDelay and currentYaw <= yawDeg+currentDelay )then 
                currentYaw = yawDeg;
            else    
                if(currentYaw > 90 and yawDeg < -90 or currentYaw < -90 and yawDeg > 90 )then
                    if(     currentYaw > yawDeg)then    currentYaw = currentYaw + currentDelay; 
                    elseif( currentYaw < yawDeg)then    currentYaw = currentYaw - currentDelay;  end
                else
                    if(     currentYaw > yawDeg)then    currentYaw = currentYaw - currentDelay;
                    elseif( currentYaw < yawDeg)then    currentYaw = currentYaw + currentDelay; end
                end
            end
            return currentYaw;
        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 controller::doJump	(	int	dccID,
		int	force
	)

void controller::doStrafe	(	int	dccID,
		int	state
	)

void controller::enableGravity	(	int	dccID,
		int	state
	)

void controller::followPath	(	int	dccID,
		string	pathName,
		float	speed
	)

follow a path simply by calling this function in an update loop.
The movement will automatically be smoothed out based on the setPathAccuracy() accuracy variable.

Parameters

dccID	: This is the id of the controller to move and rotate to the path.
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)
    controller.followPath(dccID, pathName, 5);
end

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

void controller::followPathPosition	(	int	dccID,
		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 controller.followPath()

Parameters

dccID	: This is the id of the controller.
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)
    controller.followPathPosition(dccID, posArray[0].x, posArray[0].y, posArray[0].z );
end

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

end

int controller::getBodyID ( int dccID )

Get the Body ID of the object with a dynaminc character controller.

Parameters

objID : This is the id of the object.

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

function 

    dccID = controller.getBodyID( objID );

end

void controller::getCollisionFlag ( int dccID )

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

Parameters

dccID : The dccID 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: "..controller.getCollisionFlag(obj));
    end

void controller::getContactHit_ID ( int dccID )

Gets the last collision contacts hit information - Parent ID.

void controller::getContactHit_MotionDirection ( int dccID )

Gets the last collision contacts hit information - MotionDirection.

void controller::getContactHit_MotionLength ( int dccID )

Gets the last collision contacts hit information - motionLength.

void controller::getContactHit_WorldNormal ( int dccID )

Gets the last collision contacts hit information - WorldNormal.

void controller::getContactHit_WorldPos ( int dccID )

Gets the last collision contacts hit information - WorldPos.

string controller::getFollowPathName ( int dccID )

return the name of the path the controller is following

Parameters

dccID : This is the id of the controller.

Returns: pathName : This is the pathname that will be returned.

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

function onUpdate(timeDelta)
    pathname = controller.getFollowedPathName(dccID);
end

float3 controller::getOffset	(	int	dccID,
		float	x,
		float	y,
		float	z
	)

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

Parameters

dccID : Gets the body ID of an dynamic controller

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 controller::getPosition ( int dccID )

void controller::invertGravity	(	int	dccID,
		int	state
	)

int controller::isDestinationReached ( int dccID )

Poll to check if the controller has reached its destination.

Parameters

dccID : This is the id of the controller to poll from.

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

function onUpdate(timeDelta)
    if(controller.isDestinationReached(dccID) == 1)then
        sky.print("detination has been reached.. change position to run to.");
    end
end

int controller::isFollowingPath ( int dccID )

return whether the controller is currently following a path.

Parameters

dccID : This is the id of the controller.

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 = controller.isFollowingPath(dccID);
end

void controller::move	(	int	dccID,
		int	Speed
	)

Moves the controller 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;
    controller.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

    charactercontrollermove(obj, moveSpd ); 
    controller.doStrafe(obj, moveStr ); 
end

void controller::moveUp	(	int	dccID,
		int	moveUpSpd
	)

Moves the controller 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;
    controller.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

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

void controller::remove ( int dccID )

remove( int dccID );

Parameters

int	dccID : - dccID is the id created when calling controller.spawn()

dcc stands for Dynamic Character Controller and can only be created in scripts or modules

function 

    remove( int dccID );

end

void controller::resetData ( )

Resets the controller setup date back to its default. This handled internally for you but the command is here just in case you need it. Sets the players position including controller. Used when re-spawning after KO.

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

    controller.resetData();

void controller::setAdvancedCollision	(	int	dccID,
		int	state
	)

Set Advanced Collisions.

Parameters

objID	: This is the id of the controller to poll from.
state	: Turns on and off 1 = on, 0 =off Here is a Small Example of how to use this function: function controller.setAdvancedCollision(objID, 1); end

void controller::setAdvancedCollision	(	int	dccID,
		int	state
	)

setAdvancedCollision

Parameters

int dccID :

int

state : - the state refers to the boolean value of true or false in the form of 0 and 1. In other words on/off.

setting an advanced collision will allow the controller to be moved by other objects such as elevators to go up/down. Setting to false will allow an elevator moving up to pass through the player
This function can affect an extra 10cm on all axis collisions. can cause heights issue with doorframe tops.
```
function 

    setAdvancedCollision( int dccID, int state );

end
```

void controller::setAdvancedCollision	(	int	dccID,
		int	state
	)

setAdvancedCollision

Parameters

int dccID :

int

state : - the state refers to the boolean value of true or false in the form of 0 and 1. In other words on/off.

setting an advanced collision will allow the controller to be moved by other objects such as elevators to go up/down. Setting to false will allow an elevator moving up to pass through the player
This function can affect an extra 10cm on all axis collisions. can cause heights issue with doorframe tops.
```
function 

    setAdvancedCollision( int dccID, int state );

end
```

void controller::setCollisionFlag	(	int	dccID,
		String	flags
	)

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

Parameters

int	dccID : The controller dccID , dynamically spawned controller ID
String	flags : A string of masks separated by \| (this is not a logic operator only a separator) eg 0\|2 will be read as two individual values 0 and 2.

Value 0 = general collisions Value 1 = Collide with dynamic physics objects Value 2 = Collide with player capsule Value 3 = Collide with game mechanics activate system.

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

    controller.setCollisionFlag(dccID, "0|1|3");

void controller::setData_characterHeight ( float val )

void controller::setData_characterWidth ( float val )

void controller::setData_flipDirection ( bool state )

void controller::setData_gravityY ( float val )

void controller::setData_Offset	(	float	x,
		float	y,
		float	z
	)

void controller::setData_shapeType ( float val )

void controller::setData_skinWidth ( float val )

void controller::setData_slopeLimit ( float val )

void controller::setData_stepOffset ( float val )

void controller::setData_upDirectionIndex ( float val )

void controller::setDimension	(	int	dccID,
		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

dccID	: Gets the body ID of an dynamic controller
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 controller::setGravity	(	int	dccID,
		float	x,
		float	y,
		float	z
	)

void controller::setJumpDownforce	(	int	dccID,
		int	force
	)

void controller::setMoveAdvanced	(	int	dccID,
		int	state
	)

Setting advanced move.

Parameters

dccID	: This is the id of the dynamic charactor controller.
objID	: state 1 = on 0 = off Here is a Small Example of how to use this function: function controller.setMoveAdvanced(dccID, 1); end

void controller::setMoveAdvanced	(	int	dccID,
		int	state
	)

setMoveAdvanced

Parameters

int	dccID : - the state refers to the boolean value of true or false in the form of 0 and 1. In other words on/off
int	state : - Set move advanced means you can use the controller.setMoveDirection(int dccID, float x, float y, float z) to set the Vector3 direction for travel of this kinematic controller

dcc stands for Dynamic Character Controller and can only be created in scripts or modules

function 

    setMoveAdvanced( int dccID, int state);

end

void controller::setMoveDirection	(	int	dccID,
		float	x,
		float	y,
		float	z
	)

void controller::setOffset	(	int	dccID,
		float	x,
		float	y,
		float	z
	)

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

Parameters

dccID	: Gets the body ID of an dynamic controller
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 controller::setPathAccuracy	(	int	dccID,
		float	accuracy
	)

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

Parameters

dccID	: This is the id of the controller.
accuracy	: This number increases the distance allowed to the wanted node before it triggers to move to the next. If a controller travels faster, then you will want a larger accuracy to catch them from going off the path and also a faster rotation.

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

function onUpdate(timeDelta)
    controller.setPathAccuracy(dccID, 10);
    controller.followPath(dccID, pathName, 5);
end

void controller::setPathMaxTurn	(	int	dccID,
		float	maxTurn
	)

Set the maximum speed of the turning rate for this controller.

Parameters

dccID	: This is the id of the controller.
maxTurn	: This number increases the speed of rotation to make the controller more responsive. Higher numbers will make the controller stick closer to the path lines. Lower numbers make it turn more gently.

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

function onUpdate(timeDelta)
    controller.setPathMaxTurn(dccID, 5.0);
    controller.followPath(dccID, pathName, 5);
end

void controller::setPathNodeIndex	(	int	dccID,
		int	nodeIndex
	)

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

Parameters

dccID	: This is the id of the controller.
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)
    controller.setPathNodeIndex(dccID, 2);
    controller.followPath(dccID, pathName, 5);
end

void controller::setPosition	(	int	dccID,
		float	x,
		float	y,
		float	z
	)

Sets the player position .

Parameters

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

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

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

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

void controller::setPositionString	(	int	dccID,
		String	xyz
	)

Sets the player position .

Parameters

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

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

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

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

void controller::setQueryFlag	(	int	dccID,
		int	flag
	)

Sets the controllers query flag use for overlapping object query such as sensor and raycast.

Parameters

dccID	: The dccID with the attached FPS System action
flag	: The flag to set. This must match the flag set on the query test system such as sensor action.

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

    function onInit()
        --do DCC set up stuff......
        controller.setQueryFlag(dccID, queryFlag );
    end

int controller::spawn ( int objID )

This commands add a dynamic character controller(DCC) to any scene entity.

Parameters

objID : The entity ID of the object to have the DCC applied to.

Create any game time dynamic characters using this spawn command. From a single spawn script
you can create many in game enemies with out first adding them to the scene at editor time.
The following is a Small Example on how to use this function:

function onInit(objID)
    obj = objID;
    controller.setData_Offset(0,-1.0,0); 
    controller.setData_characterHeight(1.0);
    controller.setData_shapeType(0);
    controller.setData_characterWidth(0.3);
    controller.setData_stepOffset(0.4); 
    controller.setData_gravityY(-4);
    controller.setData_slopeLimit(60);
    controller.setData_flipDirection(0);
    controller.setData_skinWidth(0.1);
    controller.setData_upDirectionIndex(1);

    dccID = controller.spawn(obj);

    controller.setJumpDownforce(dccID,30);  
end

function onUpdate( td )
    if(td>40) then td = 20; end
    controller.move(dccID, moveSpd );
    currentDelay = rotDelay * (td*0.001);
    trackTarget();
    if(controller.getCollisionFlag(dccID)==5 and moveSpd > 0) then moveSpd = 0; end
end

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

LUA_API_Controller.h

Public Member Functions

Detailed Description

Member Function Documentation