LuaCommands.txt

Jedi Knight Galaxies Lua API Documentation

Format:
Arguments are shown as follows: <name>:<type>
the :<type> after the function shows the type of the return value (nil means it doesn't return anything)
If an argument or return value can be of multiple types, they're shown seperated by a /
Arguments enclosed in [ ] are optional.

NOTE: The API is WIP, and therefore subject to change

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

GLua Framework: Framework to work with lua and do engine bindings.

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

	Global Functions

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

print(...):nil - Prints to the console. Args are concatenated strings. Identical in function to trap_Print.
printnn(...):nil - Prints to the console without adding a '\n' to the end of it (good for loops, etc)
log(...):nil - Prints to the log. Args are concatenated strings. Identical in function to G_LogPrintf (minus the formatting)
securitylog(...):nil - Prints to the security log. Args are concatenated strings. Identical in function to G_SecurityLogPrintf (minus the formatting)

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

	Hook module: Provides the interface to hook functions to certain engine events
		
-----------------------------------------------------------------------------------------------	

hook.Add(hookname:string, uniqueid:string, func:function, [priority:number]):nil - Hooks the function to the specified event, uniqueid is used to avoid duplicate bindings (for example due to a lua_reload)
hook.Remove(hookname:string, uniqueid:string):nil - Removes the specified hook

NOTE: To avoid problems, if a hooked function causes an error, the function is unhooked
Hooks have priorities going from 0 to 10, 0 being the lowest (default) and 10 the highest.
Hooks will be called from priority 0 to priority 10, as the last return value is sent to the engine.
This the return value of priority 10 hooks will override those of lower priority hooks.

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

	Events: Valid hooknames you can use and functions they must be bound to:

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

Init():nil - Called when lua finished initializing.
Shutdown():nil - Called before lua is shut down.

PlayerConnect(ply:player, firsttime:bool, isbot:bool):string/nil - Called when a player connects, return a string (reason) to deny the connection.
PlayerDisconnect(ply:player):nil - Called when a player disconnects.
PlayerSay(ply:player, target:player/nil, mode:number,  text:string):bool/nil - Called when a player is trying to say something in chat. Return true to block the message.
PlayerValidationFailed(ply:player):nil - Called when a player failed to validate its client-side. The player is kicked after the hook returns.
PlayerBegin(ply:player):nil	- Called when a player finished connecting and is about to spawn for the first time
PlayerDeath(ply:player, inflictor:entity, attacker:entity, damage:number, meansOfDeath:number):nil - Called when a player dies
PlayerSpawned(ply:player):nil - Called when a player finished spawning (use for loadout for example)
PlayerDeathcam(ply:player):number/nil - Called when a player is entering deathcam. To override the duration of deathcam, return the time in milliseconds to stay in deathcam (5000 is default). To force a respawn once the time is up, make the number negative (ie. -1000 = 1 second with forced respawn)
SelectInitialSpawn(ply:player, team:number):ent/array (2 vectors)/nil - Called when a player is spawned for the first time. Return an ent or an array with two vectors (origin and angles) to specify one, or return nothing to ignore.
SelectSpawn(ply:player, team:number, avoidpoint:vector):ent/array (2 vectors)/nil - Called when a player is spawning and looking for a spawn location. Return an ent or an array with two vectors (origin and angles) to specify one, or return nothing to ignore.
SelectSpectatorSpawn(ply:player):ent/array (2 vectors)/nil - Called when a spectating player is spawning and looking for a spawn location. Return an ent or an array with two vectors (origin and angles) to specify one, or return nothing to ignore.

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

	Cmds module: Binds lua functions to commands (both client and rcon)

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

cmds.Add(command:string, func:function):nil - Binds the function to that command
cmds.Remove(command:string):nil	- Unbinds the command

cmds.AddRcon(command:string, func:function):nil - Binds the function to that command (rcon)
cmds.RemoveRcon(command:string):nil - Unbinds the command (rcon)

Function prototypes:

Normal commands: command(ply:player, argc:number, argv:table)
Rcon commands: command(argc:number, argv:table) - Use print for responses.

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

Generic use commands:

Most standard Lua functions can be used, excluding functions that
execute code (use include instead) or access files (use file. instead)

print(message:string):nil - Displays the message in the console, also used to respond to rcon commands
include(file:string):bool - Loads the specified file and returns whether it was successful or not. Paths are relative to the current script's location. To use root paths (from GameData), start the path with '/'.
PrintTable(tbl:table):nil - Displays the contents of the specified table in the console

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

	sys Library: Provides access to engine functions
	
-----------------------------------------------------------------------------------------------	

sys.GetCvarString(cvarname:string):string - Returns string value of specified cvar.
sys.GetCvarInt(cvarname:string):number - Returns int value of specified cvar.
sys.GetCvarFloat(cvarname:string):number - Returns float value of specified cvar.
sys.SetCvar(cvar:string, value:string):nil - Sets the cvar to the specified value.
sys.SetCS(ID:number, value:string):nil - Sets config string <ID> to the string value.
sys.GetCS(ID:number):string - Returns the string value of the config string identified by <ID>.
sys.Time():number - Returns the current server time (level.time).
sys.Milliseconds():number - Returns the amount of milliseconds elapsed since the operating system started.
sys.Time():number - Returns the current server time (in msecs)
sys.Command(command:string):nil	- Executes the specified command
sys.RemapShader(orgshader:string, newshader:string) - Performs a shader remap
sys.EffectIndex(effect:string):number - Obtains the effect ID for the specified effect
sys.PlayEffect(id:number, origin:vector, [angles:vector]) - Plays the specified effect at the provided origin and angles
sys.RadiusDamage(origin:vector, [attacker:entity], damage:number, radius:number, ignore:entity, missile:entity, meansofdeath:number) - Does radius damage
sys.PlaySound(origin:vector, sound:string, channel:number, ) - Plays sound at the specified location
sys.PlaySoundIdx(origin:vector, soundid:number, channel:number, ) - Plays sound at the specified location (using the ID rather than name)
sys.SoundIndex(sound:string):number - Returns the sound ID of the specified sound
sys.WeaponClipSize(weapon:number, [variation:number], [firemode:number]):number - Returns the clipsize of the specified weapon
sys.AmmoLimit(ammotype:number):number - Returns the limit of the specified type of ammo
sys.MapName():string - Returns the name of the current map
sys.SpotWouldTelefrag(ent:entity, location:vector):bool - Returns whether or not teleporting the ent to location would cause a telefrag
sys.StripColorcodes(text:string):string - Retuns the passed string with all colorcodes removed

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

	Trace results table: Contains the results from a trace.

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

table.StartSolid (boolean) - Whether or not the trace started in something solid.
table.AllSolid (boolean) - Whether or not the entire trace was in something solid.
table.Hit (boolean) - Whether or not the trace hit something.
table.HitWorld (boolean) - Whether or not the trace hit the world.
table.HitEnt (boolean) - Whether or not the trace hit an entity.
table.Entity (entity/nil) - The entity that was hit by the trace, nil if no ent was hit.
table.Contents (number) - The contents of the surface hit.
table.SurfaceFlags (number) - SurfaceFlags of the surface hit.
table.StartPos (vector) - Starting position of the trace.
table.EndPos (vector) - Ending position of the trace. (point of impact if something was hit)
table.HitNormal (vector) - Vector perpendicular to the surface hit.

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

	File Library:

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

file.Read(file:string):string - Returns contents of a file (uses glua/data as starting path)
file.Write(file:string, buffer:string):nil - Writes to a file (uses glua/data as starting path)
file.Exists(file:string):boolean - Checks if a file exists (uses glua/data as starting path)
file.ListFiles(path:string, extension:string):string table - Returns a string table listing all of the files in the path. extension arg is optional. (uses glua/data as starting path)

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

	JSON Library:

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

json.Register(file:string):jsonHandle - Returns a jsonHandle (or in other words, the pointer to the root JSON node) for the given file, if it is a valid JSON file. (otherwise, returns nil)
json.GetObjectItem(root:jsonHandle, nodeName:string):jsonHandle - Gets a node
json.Clear(nil):nil - Run this func once you're done with json stuff.

json.GetFirstObject(node:jsonHandle):jsonHandle - Gets the first object within an object node
json.GetNextObject(node:jsonHandle):jsonHandle - Returns the next object that you're targetting. Returns nil if no node is found.

json.IsNumber(node:jsonHandle):boolean - Returns true if the node is a number type
json.IsObject(node:jsonHandle):boolean - Returns true if the node is an object type
json.IsBoolean(node:jsonHandle):boolean - Returns true if the node is a boolean type

json.ToString(node:jsonHandle):string - Converts node to string
json.ToNumber(node:jsonHandle):number - Converts node to number
json.ToInteger(node:jsonHandle):integer - Converts node to integer
json.ToBoolean(node:jsonHandle):boolean - Converts node to boolean
json.ToStringOpt(node:jsonHandle, opt:string):string - Converts node to string. If string is clear, or node does not exist, returns opt.
json.ToNumberOpt(node:jsonHandle, opt:number):number - Converts node to number. If node does not exist, returns opt.
json.ToIntegerOpt(node:jsonHandle, opt:integer):integer - Converts node to integer. If node does not exist, returns opt.
json.ToBooleanOpt(node:jsonHandle, opt:boolean):boolean - Converts node to boolean. If node does not exist, returns opt.

json.GetArraySize(node:jsonHandle):integer - Returns size of array object within node.
json.GetArrayItem(node:jsonHandle, member:integer):jsonHandle - Returns node within array.

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

	Vector Library:

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

Vector(x:number, y:number, z:number):vector - Constructs a vector

Vector Class:
vec:Sub(vec:vector):nil - Subtracts the vector from the one specified
vec:Add(vec:vector):nil - Adds the vector to the one specified
vec:Scale(scale:number):nil - Scales the vector
vec:Length():number - Returns the length of the vector
vec:Normalize():nil - Normalizes the vector (changes all axes to a -1 to 1 range)
vec:GetNormalized():vector - Returns the normalized vector (but does not alter the vector that uses the function)
vec:DotProduct(vec:vector):number - Returns the dot product of the vector
vec:CrossProduct(vec:vector):number - Returns the cross product of the vector
vec:ToAngles() - Converts the vector to angles
vec:ToForward() - Converts the angle-vector to the forward vector
vec:ToRight() - Converts the angle-vector to the right vector
vec:ToUp() - Converts the angle-vector to the up vector
vec:GetAngles() - Converts the vector to angles and returns the new angle-vector (Original vector remains unchanged)
vec:GetForward() - Converts the angle-vector to the forward vector and returns this new vector (Original vector remains unchanged)
vec:GetRight() - Converts the angle-vector to the right vector and returns this new vector (Original vector remains unchanged)
vec:GetUp() - Converts the angle-vector to the up vector and returns this new vector (Original vector remains unchanged)
vec:Copy():vector - Returns a copy of the vector

vec.x - Get/set the X component of the vector
vec.y - Get/set the Y component of the vector
vec.z - Get/set the Z component of the vector

Addition, subtraction, multiplication, division and comparing of vectors is also allowed

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

	ents Library:

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

ents.GetByID(id:number):entity/nil - Returns the entity with the specified ID (or nil if it doesn't exist)
ents.GetAll():table - Returns a table will all entities on the server
ents.GetByClass(class:string):table - Returns a table with all entities with the specified classname
ents.GetByName(name:string):table - Returns a table with all entities with the specified targetname
ents.FindInBox(minx:vector, maxs:vector):table - Returns a table with all entities in the specified bounding box

----

Entity Class:

NOTE: On deleted entities, only IsValid() works!
All other functions return nil and do nothing!

Entities and derived objects (i.e. players) are fitted with a dynamic storage system
This allows you to store any kinda of data in the player object by simply reading or writing it as if the
player object were to be a table (ply.var = value, ply["var"] = value, etc will all work)
Please note that you should avoid using function names as variables (it wont overwrite them, but retrieving them will call the function)

If you wish to obtain the full table of custom variables for that entity, you can use the GetTable() function


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

	players Library:

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

players.GetByID(ID:number):player/nil - Returns player based on specified ID (or nil if the player doesnt exist)
players.GetByName(name:string):player/nil - Returns the player with the specified name (partial names allowed)
players.GetAll():table - Returns a table with all players on the server


Player Class:

NOTE: On invalid player objects (disconnected players), only IsValid() works!
All other functions return nil and do nothing!

Player objects, (like all other entity derived objects) are fitted with a dynamic storage system
See 'Entity Class' for more information

player:GetTable():table - Returns a table with all variables assigned to this player.
player:GetID():number - Returns this player's ID.
player:GetName():string - Returns this player's Name.
player:GetIP():string - Returns this player's IP in a string. (IP and port)
player:IsValid():bool - Returns whether this player object is valid or not.

player:SendChat(text:string):nil - Shows the specified text in the player's chat area.
player:SendCenterPrint(text:string):nil - Shows the specified text in the center of the player's screen.
player:SendPrint(text:string):nil Shows the specified text in the player's console.
player:SendCommand(command:string):nil - Sends the specified command to the player (CAUTION: The client side must know the command or the client gets errors!)

player:SetPos(position:vector):nil - Moves the player to the specified location (Note: This is not a teleport and moving the player into another player will render them stuck)
player:GetPos():vector - Returns the player's current position

player:Teleport(position:vector, [angles:vector]):nil - Teleports the player to the specified location (facing the direction specified if any), telefrags anyone at that destination.
player:Kill():nil - Kills the player immediately.
player:Kick([reason:string]):nil - Kicks the player off the server with the reason specified. If no reason is specified, 'was kicked' will be used.
player:SetTeam(team:string):nil - Sends the player to the specified team ("r" = red, "b" = blue, "s" = spectators, "f" = free)
player:GetTeam():number - Returns the team the player is currently on (0 = free, 1 = red, 2 = blue, 3 = spectators)
player:Spawn():nil - Forces the player to (re)spawn

player:GetEyeTrace():table - Returns a table with trace results (see above)
player:GetEntity():entity - Returns the entity object of the player

player:GetCreditCount():number - Returns number of credits that the player is currently holding on to.
player:SetCreditCount(amount:number):nil - sets the amount of credits that the player has
player:ModifyCreditCount(amount:number):nil - adds to the number of credits that the player has (eg a value of 100 adds 100 credits, -100 subtracts 100 credits)

player:SetAmmo(ammotype:string, amount:number):nil - sets ammo of a certain type.
player:GetAmmo(ammotype:string):number - returns amount of ammo of a certain type that the player is holding
player:ModifyAmmo(ammotype:string, amount:number):nil - adds to, rather than setting current ammo
player:GetCurrentGunAmmoType():number - retrieves the ammo ID of the currently equipped weapon

player:PossessingItem(itemid:number):bool - returns true if we are possessing the item, returns false otherwise
player:PossessingWeapon(weapon: number, variation:number):bool - returns true if we are possessing this weapon in our inventory, returns false otherwise

player:SetAdminAccount(account:string):nil - Sets our current admin account to a certain value
player:GetAdminAccount():string - Gets our current admin account

player:ExecuteChatCommand(command:string):nil - Executes a chat command (such as /me). This includes Lua commands!

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

	NPCs Library:

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

NPC Class:

NPC:GetTable():table - Returns a table with all variables assigned to this NPC.
NPC:GetID():number - Returns this NPC's ID.
NPC:IsValid():bool - Determines whether this NPC is valid.

NPC:Kill():nil - Kills the NPC
NPC:Teleport(position:vector, [angles:vector]):nil - Teleports the NPC to the given coordinates.

NPC:SetPos(position:vector):nil - Sets the NPC's position.
NPC:GetPos():vector - Returns the NPC's position.
NPC:SetOrigin(position:vector):nil - Identical to SetPos.
NPC:GetOrigin():vector - Identical to GetPos.
NPC:SetAngles(angles:vector):nil - Sets the NPC's angles.
NPC:GetAngles():vector - Gets the NPC's angles.
NPC:SetNavGoal(position:vector):nil - Instructs the NPC to walk/run to the specified coordinates.
NPC:SetNavGoal(position:entity):nil - Instructs the NPC to walk/run to the specified entity.
NPC:SetNavGoal(position:string):nil - Instructs the NPC to walk/run to the entity with the given targetname.

NPC:MakeVendor(tc:string):nil - Makes the NPC into a vendor with the given treasure class.
NPC:RefreshVendorStock():nil - Refreshes the vendor's stock. DO NOT call this on map-created vendors (jkg_target_vendor), it won't work.

There are more functions here that need to be documented.