Skyline Lua API  Version 1.0 RC1
Lua Script Reference for Skyline Game Engine.
controller Class Reference

#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 - http://www.chi-ad.com/Skyline/SDN/

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
intdccID : - 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
intdccID :
intstate : - 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
intdccID :
intstate : - 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
intdccID : The controller dccID , dynamically spawned controller ID
Stringflags : 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
intdccID : - the state refers to the boolean value of true or false in the form of 0 and 1. In other words on/off
intstate : - 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: