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

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

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