---------------------------------
KFY Scripting Documentation
Latest revision on 2014-11-26
---------------------------------

Currently scripting is only implemented on a per-map basis.
The ability to modify and add to most of the server functionality, however, is planned.
Scripts are assumed to have .lua filename extensions and be located in the UserData/Maps directory, or one of its subdirectories.
For some examples of current scripting functionality, check out UserData/Maps/LuaExamples.
The file UserData/Maps/empty.lua can be used as a template for writing new map scripts.

Use the reloadmapscript command from the client (must be dev/admin) or server app to reload script from disk at runtime.
The script is also reloaded when starting a new round or reloading the map.

Lua functions called by the KFY server application:
-----------------------------------------
mapOnRoundBegin()
mapOnUpdate()
mapOnTileActivate(uint16 tag)
mapOnTileDeactivate(uint16 tag)
mapOnTilePlayerCollision(uint16 tag, x, y, player)
mapOnTileLmbClick(uint16 tag, x, y, player)
-----------------------------------------

Global objects and functions:
-----------------------------------------

General functions:
-----------------------------------------
void print(string) - To stdout.

kfyMap
--------------------
(arguments for tiles are in tile world coordinates, so pixel world coordinates divided by 16)

-- For tagged tiles:
void        kfyMap:tileActivate(uint16 tag)
void        kfyMap:tileDeactivate(uint16 tag)
void        kfyMap:tileSleep(uint16 tag, float duration)
void        kfyMap:tileMove(uint16 tag, int32 dx, int32 dy)
void        kfyMap:tileMoveTo(uint16 tag, uint16 x, uint16 y)
bool        kfyMap:tileDamage(uint16 tag, int16 damage, bool playDefaultSound) -- Returns true if one or more tile was destroyed.
void        kfyMap:tileMapTilesetCoords(uint16 tag, uint8 tsx, uint8 tsy) -- Maps rectangular area from tileset onto group of tiles.
KfyVec2i    kfyMap:tileGetPosition(uint16 tag) - Returns coords of top left tile if there is more than one with the given tag.
KfyIntRect  kfyMap:tileGetBounds(uint16 tag) - Returns bounding box for tiles (x,y,w,h)
bool        kfyMap:tileIsActive(uint16 tag)
bool        kfyMap:tileIsSolid(uint16 tag) -- Returns true if the test returns true for any tile with that tag.
bool        kfyMap:tileIsDestructible(uint16 tag)
bool        kfyMap:tileIsDeadly(uint16 tag)
bool        kfyMap:tileIsClimbable(uint16 tag)
bool        kfyMap:tileIsHidden(uint16 tag)
void        kfyMap:tileSetTilesetCoords(uint16 tag, uint8 tsx, uint8 tsy)
void        kfyMap:tileSetSolid(uint16 tag, bool)
void        kfyMap:tileSetDestructible(uint16 tag, bool)
void        kfyMap:tileSetDeadly(uint16 tag, bool)
void        kfyMap:tileSetClimbable(uint16 tag, bool)
void        kfyMap:tileSetHidden(uint16 tag, bool)

-- For arbitrary tiles:
void        kfyMap:tileDamageAt(uint16 x, uint16 y, int16 damage, bool playDefaultSound) -- Returns true if tile was destroyed.
bool        kfyMap:tileIsSolidAt(uint16 x, uint16 y)
bool        kfyMap:tileIsDestructibleAt(uint16 x, uint16 y)
bool        kfyMap:tileIsDeadlyAt(uint16 x, uint16 y)
bool        kfyMap:tileIsClimbableAt(uint16 x, uint16 y)
bool        kfyMap:tileIsHiddenAt(uint16 x, uint16 y)
uint16      kfyMap:tileGetTagAt(uint16 x, uint16 y) -- Returns 0 if tile at x,y is not tagged.
KfyVec2i    kfyMap:tileGetTilesetCoordsAt(uint16 x, uint16 y, uint8 layer) - Valid layers are [0,2].
void        kfyMap:tileSetTilesetCoordsAt(uint16 x, uint16 y, uint8 layer, uint8 tsx, uint8 tsy)
void        kfyMap:tileSetSolidAt(uint16 x, uint16 y, bool)
void        kfyMap:tileSetDestructibleAt(uint16 x, uint16 y, bool)
void        kfyMap:tileSetDeadlyAt(uint16 x, uint16 y, bool)
void        kfyMap:tileSetClimbableAt(uint16 x, uint16 y, bool)
void        kfyMap:tileSetHiddenAt(uint16 x, uint16 y, bool)

int32       kfyMap:getWidth() -- In tiles.
int32       kfyMap:getHeight()
int32       kfyMap:getWidthInPixels()
int32       kfyMap:getHeightInPixels()
string      kfyMap:getName()
string      kfyMap:getFilename()
string      kfyMap:getTilesetFilename
string      kfyMap:getScriptFilename
string      kfyMap:getScriptString() -- Returns content of the current map script.

kfyRound
--------------------
float   kfyRound:getTime() - Get current round time in seconds.
uint64  kfyRound:getTimeMs() - Get current round time in milliseconds.
string  kfyRound:getTimeMinsSecs() - Get current round time in format MM:SS
string  kfyRound:getTimeHoursMinsSecs() - Get current round time in format HH:MM:SS
void    kfyRound:nextMap(bool skipBreak) - End current round and play the next map in list.
void    kfyRound:prevMap(bool skipBreak) - End current round and play the previous map in list.
void    kfyRound:setMap(string filename, bool skipBreak) - End current round and play specified map in list.


kfyEffect
--------------------
void    kfyEffect:playSound(string filename, float pitch) - Filename relative to KFY directory. Standard pitch is 1.0.
void    kfyEffect:playSoundAt(string filename, uint16 x, uint16 y, float pitch)
void    kfyEffect:playSoundToPlayer(string filename, KfyPlayer, float pitch)

kfyPlayerManager
--------------------
bool        isPlayerAtRect(int32 x, int32 y, int32 w, int32 h)
bool        isPlayerAtCircle(int x, int y, float radius)
KfyPlayer   getPlayerClosestToPoint() -- Returns nil if no eligible players.
uint32      getNumConnectedPlayers()
uint32      getNumSpawnedPlayers()
bool        isValidPlayer(KfyPlayer)

kfyProjectileManager
--------------------
KfyProjectile   createProjectile(uint16 type, float posX, float posY, float velX, float velY)
void            addProjectiles()
int32           getNumProjectileTypes()

kfyGrenadeManager
--------------------
KfyGrenade  createGrenade(uint16 type, float posX, float posY, float velX, float velY)
void        addGrenades()
int32       getNumGrenadeTypes()

-----------------------------------------

KFY classes and member functions:
-----------------------------------------
KfyPlayer
--------------------
void        sendConsoleMsg(string msg)
void        sendChatMsg(string msg)
uint64      getId()
string      getName()
string      getWinMsg()
int16       getHealth()
int16       getSauce()
int16       getKills()
uint16      getDeaths()
uint16      getCaptures()
uint8       getTeam()
uint16      getMouseX()
uint16      getMouseY()
KfyVec2f    getPosition()
KfyVec2f    getCenterPosition()
float       getPositionX()
float       getPositionY()
KfyVec2f    getVelocity()
float       getVelocityX()
float       getVelocityY()
void        setPosition(float x, float y)
void        setPositionX(float)
void        setPositionY(float)
void        setVelocity(float x, float y)
void        setVelocityX(float)
void        setVelocityY(float)
void        setFace(uint8) - Valid faces are [0,5].

KfyProjectile
--------------------
KfyPlayer   getOwner()
KfyVec2f    getPosition()
float       getPositionX()
float       getPositionY()
KfyVec2f    getVelocity()
float       getVelocityX()
float       getVelocityY()
void        setDeflectCharge(uint8)
void        setOwner(KfyPlayer)
void        setPosition(KfyVec2f)
void        setPositionX(float)
void        setPositionY(float)
void        setVelocity(KfyVec2f)
void        setVelocityX(float)
void        setVelocityY(float)

KfyGrenade
--------------------
KfyPlayer   getOwner()
KfyVec2f    getPosition()
float       getPositionX()
float       getPositionY()
KfyVec2f    getVelocity()
float       getVelocityX()
float       getVelocityY()
void        setDeflectCharge(uint8)
void        setOwner(KfyPlayer)
void        setPosition(KfyVec2f)
void        setPositionX(float)
void        setPositionY(float)
void        setVelocity(KfyVec2f)
void        setVelocityX(float)
void        setVelocityY(float)

KfyTimer
--------------------
KfyTimer    ()
void        start()
void        stop()
void        restart()
void        update()
float       getTime()
uint64      getTimeMs()

KfyVec2i
--------------------
KfyVec2i    ()
KfyVec2i    (int32 x, int32 y)
int32       x
int32       y

KfyVec2f
--------------------
KfyVec2f    ()
KfyVec2f    (float x, float y)
float       x
float       y
void        normalize()
void        rotate(float angle)
float       getLength()
float       getLengthTo(float x, float y)
float       getDot()

KfyIntRect
--------------------
KfyIntRect  ()
int32       x
int32       y
int32       w
int32       h
-----------------------------------------
