Difference between revisions of "Lua Mod API"

From WolfWiki
Jump to: navigation, search
m (→‎modules)
(warning about etprint)
 
(105 intermediate revisions by 13 users not shown)
Line 1: Line 1:
−
ETPro now supports serverside mods via the [http://www.lua.org/ lual] scripting language.
+
__NOEDITSECTION__
 +
[[ETPro]] now supports server-side mods via the [http://www.lua.org/ Lua] scripting language. For more information about Lua, visit the [http://www.lua.org/manual/5.0/ Reference manual], the online edition of the book [http://www.lua.org/pil/ Programming in Lua] or the [http://lua-users.org/wiki/ lua-users wiki]. A list of text editors for coding LUA can be found [http://wiki.ptokax.ath.cx/doku.php/misc/editors here].
  
−
ETPro has an embedded lua 5.0.2 interpreter, and if present will load user-defined scripts from the etpro directory. ETPro also provides an "et" library of function calls for lua to access the server engine, and provides callbacks so a serverside mod may trigger on specific server events.
+
ETPro has an embedded Lua 5.0.2 interpreter, and if present will load user-defined scripts from the ETPro directory. It also provides an "et" library of function calls for Lua that allow access to the server engine, and provides callbacks so a server side mod may trigger on specific server events.
  
−
The following standard lua libraries are initialized by default and available to ETPro lua scripts:
+
The following standard Lua libraries are initialized by default and available to ETPro Lua scripts:
−
basic, table, i/o, string, math.
+
[http://www.lua.org/manual/5.0/manual.html#5.1 basic], [http://www.lua.org/manual/5.0/manual.html#5.4 table], [http://www.lua.org/manual/5.0/manual.html#5.6 i/o], [http://www.lua.org/manual/5.0/manual.html#5.7 os] (available features vary depending on your OS), [http://www.lua.org/manual/5.0/manual.html#5.3 string], [http://www.lua.org/manual/5.0/manual.html#5.5 math].
 +
 
 +
A list of ETPro mods can be found [[:Category:ETPro:Mods|here]].
 +
 
 +
A tutorial about ETPro Lua scripting can be found [[Lua Tutorials|here]].
 +
 
 +
API requests can be discussed at the [[Talk:Lua_Mod_API|Lua Mod API talk page]].
 +
 
 +
==client commands==
 +
===lua_status===
 +
:lists all currently loaded lua modules.
 +
:''lua mods cannot override this client command.''
  
 
==server commands==
 
==server commands==
 
===lua_status===
 
===lua_status===
−
lists all currently loaded lua modules.
+
:lists all currently loaded lua modules.
  
 
==cvars==
 
==cvars==
−
===lua_modules=== (default "", disabled) - space separated list of lua modules for ETPro to load. all modules will be run in the order listed.
+
===lua_modules===
−
===lua_allowedmodules=== (default "", disabled) - if set, only lua modules with the matching sha1 signatures listed in this cvar will be allowed to load.
+
:(default "", disabled)
 +
:space separated list of lua modules for ETPro to load. modules will be run in the order listed.
  
−
changing either cvar will cause all currently loaded modules to quit and be unloaded until the next map_restart.<br>
+
===lua_allowedmodules===
 +
:(default "", disabled)
 +
:if set, only lua modules with the matching sha1 signatures listed in this cvar will be allowed to load.
 
<br>
 
<br>
 +
:changing either cvar will cause all currently loaded modules to :quit and be unloaded until the next map_restart.<br>
 +
<br>
 +
 
==et library calls==
 
==et library calls==
  
Line 26: Line 44:
 
:Returns the '''modname''' and sha1 '''signature''' for the mod loaded in the VM slot '''vmnumber'''. Returns nil, nil if the VM slot is invalid.
 
:Returns the '''modname''' and sha1 '''signature''' for the mod loaded in the VM slot '''vmnumber'''. Returns nil, nil if the VM slot is invalid.
 
'''success''' = et.IPCSend( '''vmnumber''', '''message''' )
 
'''success''' = et.IPCSend( '''vmnumber''', '''message''' )
−
:Sends the string '''message''' to the mod in the VM slot indicated by '''vmnumber'''. The mod receiving '''message''' must have an ''et_IPCReceive()'' callback. If the message is successfully sent, '''success''' will be 1. On failure it will be 0.
+
:Sends the string '''message''' to the mod in the VM slot indicated by '''vmnumber'''. The mod receiving '''message''' must have an ''et_IPCReceive()'' callback. If the message is successfully sent, '''success''' will be 1. On failure it will be 0. See the [[Lua:IPC|Lua IPC]] page for a simple example.
 +
<br>
  
 
===printing===
 
===printing===
−
et.G_Print( string text )<br>
+
et.G_Print( '''text''' )
−
et.G_LogPrint( string text )<br>
+
:Prints the string '''text''' to the server console.
 +
et.G_LogPrint( '''text''' )
 +
:Prints the string '''text''' to the server console and writes it to the server log.
 
<br>
 
<br>
 +
 
===argument handling===
 
===argument handling===
−
string args = et.ConcatArgs( integer index )<br>
+
These functions are to be used within the [[#commands|command callback functions]].<br>
−
integer argcount = et.trap_Argc()<br>
+
'''args''' = et.ConcatArgs( '''index''' )
−
string arg = et.trap_Argv( integer argnum )<br>
+
:Returns all arguments beginning from '''index''' concatenated into a single string '''args'''
 +
'''argcount''' = et.trap_Argc()
 +
:Returns a number indicating the number of command line arguments in the command buffer.
 +
'''arg''' = et.trap_Argv( '''argnum''' )
 +
:Returns the contents of the command line argument '''argnum'''.
 
<br>
 
<br>
 +
 
===cvars===
 
===cvars===
−
string cvarvalue = et.trap_Cvar_Get( string cvarname )<br>
+
'''cvarvalue''' = et.trap_Cvar_Get( '''cvarname''' )
−
et.trap_Cvar_Set( string cvarname, string cvarvalue )<br>
+
:Returns the value of the cvar '''cvarname''' as a string. If there is no cvar named '''cvarname''', returns a zero length string.
 +
et.trap_Cvar_Set( '''cvarname''', '''cvarvalue''' )
 +
:Sets the cvar '''cvarname''' to '''cvarvalue'''
 
<br>
 
<br>
 +
 
===configstrings===
 
===configstrings===
−
string configstringvalue = et.trap_GetConfigstring( integer index )<br>
+
'''configstringvalue''' = et.trap_GetConfigstring( '''index''' )
−
et.trap_SetConfigstring( integer index, string configstringvalue )<br>
+
:Returns the string '''configstringvalue''' containing the contents of the configstring '''index'''
 +
et.trap_SetConfigstring( '''index''', '''configstringvalue''' )
 +
:Sets the configstring '''index''' to the string '''configstringvalue'''
 
<br>
 
<br>
−
===server commands===
+
 
−
et.trap_SendConsoleCommand( integer when, string command )<br>
+
===server===
−
et.trap_SendServerCommand( integer clientnum, string command )<br>
+
et.trap_SendConsoleCommand( '''when''', '''command''' )
 +
:Sends the command '''command''' to the server console, to be executed '''when''' (see et.EXEC_* constants)
 
<br>
 
<br>
 +
 +
===clients===
 +
et.trap_DropClient( '''clientnum''', '''reason''', '''ban_time''' )
 +
:Disconnects '''clientnum''' from the server, with descriptive string '''reason''' reported to clients. '''ban_time''' is the time in seconds to ban the client from the server. '''ban_time''' is optional and may be entirely omitted, in which case the ban time defaults to the cvar ''b_defaultbantime''
 +
et.trap_SendServerCommand( '''clientnum''', '''[[SendServerCommand|command]]''' )
 +
:Sends the command '''[[SendServerCommand|command]]''' to the client '''clientnum'''. If '''clientnum''' is -1, the '''[[SendServerCommand|command]]''' is broadcast to all connected clients.
 +
et.G_Say( '''clientNum''', '''mode''', '''text''' )
 +
:Sends a chat command on behalf of client '''clientNum''' with the mode '''mode''' (see et.SAY_* constants) and chat text '''text'''.
 +
et.ClientUserinfoChanged( '''clientNum''' )
 +
:Loads the new [[Userinfo]] of '''clientNum''' and stores it in the configstring and client variables
 +
<br>
 +
 
===userinfo===
 
===userinfo===
−
string userinfo = et.trap_GetUserinfo( integer clientnum )<br>
+
'''userinfo''' = et.trap_GetUserinfo( '''clientnum''' )
−
et.trap_SetUserinfo( integer clientnum, string userinfo )<br>
+
:Returns the contents of the [[Userinfo]] string for the client '''clientnum'''
 +
et.trap_SetUserinfo( '''clientnum''', '''userinfo''' )
 +
:Sets the [[Userinfo]] string for the client '''clientnum''' to '''userinfo'''
 
<br>
 
<br>
−
===key management utility functions===
+
 
−
string infostring = et.Info_RemoveKey( string infostring, string key )<br>
+
===string utility functions===
−
string infostring = et.Info_SetValueForKey( string infostring, string key, string value )<br>
+
'''infostring''' = et.Info_RemoveKey( '''infostring''', '''key''' )
−
string infostring = et.Info_ValueForKey( string infostring, string key )<br>
+
:Removes key '''key''' from infostring '''infostring''' and returns the modified infostring.
 +
'''infostring''' = et.Info_SetValueForKey( '''infostring''', '''key''', '''value''' )
 +
:Sets the key '''key''' in the infostring '''infostring''' to '''value''' and returns the modified infostring. If '''value''' is an empty string, '''key''' is removed from the string.
 +
'''keyvalue''' = et.Info_ValueForKey( '''infostring''', '''key''' )
 +
:Returns the value of the key '''key''' in the infostring '''infostring'''. If '''key''' is not present in the string, an empty string is returned.
 +
'''cleanstring''' = et.Q_CleanStr( '''string''' )
 +
:Returns '''string''' stripped of all color codes
 
<br>
 
<br>
 +
 
===ET filesystem===
 
===ET filesystem===
−
integer fd, integer len = et.trap_FS_FOpenFile( string filename, int mode )<br>
+
'''fd''', '''len''' = et.trap_FS_FOpenFile( '''filename''', '''mode''' )
−
string filedata = et.trap_FS_Read( integer fd, integer count )<br>
+
:Attempts to open the file '''filename''' with the access mode '''mode''' (see et.FS_ constants). Returns the filedescriptor '''fd''' and file length '''len'''. On error, '''len''' returns -1.
−
integer count = et.trap_FS_Write( string filedata, integer count, integer fd )<br>
+
'''filedata''' = et.trap_FS_Read( fd, count )
−
et.trap_FS_Rename( string oldname, string newname )<br>
+
:Reads '''count''' bytes from filedescriptor '''fd'''.
−
et.trap_FS_FCloseFile( integer fd )<br>
+
'''count''' = et.trap_FS_Write( '''filedata''', '''count''', '''fd''' )
 +
:Attempts to write '''count''' bytes of '''filedata''' to filedescriptor '''fd'''. Returns number of bytes successfully written.
 +
et.trap_FS_Rename( '''oldname''', '''newname''' )
 +
:Renames file '''oldname''' to '''newname'''.
 +
et.trap_FS_FCloseFile( '''fd''' )
 +
:Closes filedescriptor '''fd'''
 
<br>
 
<br>
 +
 +
===indexes===
 +
'''soundindex''' = et.G_SoundIndex( '''filename''' )
 +
:Returns an index to the soundfile indicated by '''filename'''
 +
'''modelindex''' = et.G_ModelIndex( '''filename''' )
 +
:Returns an index to the model indicated by '''filename'''
 +
<br>
 +
 +
===sound===
 +
et.G_globalSound( '''sound''' )
 +
:Plays the global sound indicated by the filename '''sound'''.
 +
et.G_Sound( '''entnum''', '''soundindex''' )
 +
:Plays the sound '''soundindex''' at the location of entity '''entnum'''
 +
<br>
 +
 
===miscellaneous===
 
===miscellaneous===
−
integer milliseconds = et.trap_Milliseconds()<br>
+
'''milliseconds''' = et.trap_Milliseconds()
 +
:Returns a number indicating the current server time in milliseconds.
 +
et.G_Damage( '''target''', '''inflictor''', '''attacker''', '''damage''', '''[[etdamage|dflags]]''', '''[[etdamage|mod]]''' )
 +
:Does '''damage''' amount of damage on '''target''' inflicted by '''inflictor''' and cased by '''attacker'''
 +
:'''target''', '''inflictor''', '''attacker''' are entity numbers
 +
:'''[[etdamage|dflags]]''' is a [[Bitmask-cvar|bitflag]] number to decide how the damage is inflickted, see '''[[etdamage|dflags]]''' [[etdamage|flaglist]]
 +
:'''[[etdamage|mod]]''' is a number from 0 up to 64 o set the type of damage, see '''[[etdamage|mod]]''' [[etdamage|list]]
 
<br>
 
<br>
 +
 
===entities===
 
===entities===
−
integer entnum = et.G_Spawn()<br>
+
'''entnum''' = et.G_Spawn()
−
integer entnum = et.G_TempEntity( origin, event )<br>
+
:Spawns a new entity and returns the new entity number.
−
et.G_FreeEntity( integer entnum )<br>
+
'''entnum''' = et.G_TempEntity( '''origin''', '''event''' )
−
integer entnum = et.G_SpawnGEntityFromSpawnVars( string spawnvar, string spawnvalue, ... )<br>
+
:Spawns a new TempEntity of event type '''event''' and places it at '''origin''' in the world.
−
et.trap_LinkEntity( int entnum )<br>
+
et.G_FreeEntity( '''entnum''' )
−
et.trap_UnlinkEntity( int entnum )<br>
+
:Frees the entity '''entnum'''
−
(variable) = et.gentity_get( int entnum, string fieldname )<br>
+
'''spawnval''' = et.G_GetSpawnVar( '''entnum''', '''key''' )
−
et.gentity_set( int entnum, string fieldname, (variable) )<br>
+
:Returns the value of spawnvar '''key''' for entity '''entnum'''
 +
et.G_SetSpawnVar( '''entnum''', '''key''', '''value''' )
 +
:Sets the spawnvar '''key''' to '''value''' for entity '''entnum'''
 +
'''integer entnum''' = et.G_SpawnGEntityFromSpawnVars( string spawnvar, string spawnvalue, ... )
 +
:This function can only be called inside the '''et_InitGame''' callback
 +
et.trap_LinkEntity( '''entnum''' )
 +
:Links the entity '''entnum'''
 +
et.trap_UnlinkEntity( '''entnum''' )
 +
:Unlinks the entity '''entnum'''
 +
'''(variable)''' = et.gentity_get ( '''entnum''', '''[[Fieldname]]''' '',arrayindex'' )
 +
:Gets the value of '''[[Fieldname]]''' from entity '''entnum''' out of the g_entity struct. For NULL entities or clients, ''nil'' is returned.<br>
 +
:''arrayindex'' is used to specify which element of an array entity field to get. It is required when accessing array type fields. Entity field array indexes start at 0.
 +
et.gentity_set( '''entnum''', '''[[Fieldname]]''', ''arrayindex,'' '''(value)''' )
 +
:Sets the value of '''[[Fieldname]]''' from entity '''entnum''' in the g_entity struct to '''(value)'''
 +
:''arrayindex'' is used to specify which element of an array entity field to set.
 +
et.G_AddEvent( '''ent''', '''event''', '''eventparm'''' )
 +
:Adds event '''event''' whit eventparameter '''eventparm'''' to entity '''ent'''
 
<br>
 
<br>
 +
 
==callbacks==
 
==callbacks==
  
 
===qagame execution===
 
===qagame execution===
−
et_InitGame( integer levelTime, integer randomSeed, integer restart )<br>
+
et_InitGame( '''levelTime''', '''randomSeed''', '''restart''' )
−
et_ShutdownGame( integer restart )<br>
+
:Called when qagame initializes. '''levelTime''' is the current level time in milliseconds. '''randomSeed''' is a number that can be used to seed random number generators. '''restart''' indicates if et_InitGame() is being called due to a map restart (1) or not (0).
−
et_RunFrame( integer levelTime )<br>
+
et_ShutdownGame( '''restart''' )
−
et_Quit()<br>
+
:Called when qagame shuts down. '''restart''' indicates if the shutdown is being called due to a map_restart (1) or not (0).
 +
et_RunFrame( '''levelTime''' )
 +
:Called when qagame runs a server frame. '''levelTime''' is the current level time in milliseconds.
 +
et_Quit()
 +
:Called when ETPro unloads the mod. The mod should close all open filedescriptors and perform all cleanup.
 
<br>
 
<br>
 +
 
===client management===
 
===client management===
−
string rejectreason = et_ClientConnect( integer clientNum, boolean firstTime, boolean isBot )<br>
+
'''rejectreason''' = et_ClientConnect( '''clientNum''', '''firstTime''', '''isBot''' )
−
et_ClientDisconnect( integer clientNum )<br>
+
:Called when a client attempts to connect to the server. '''clientNum''' is the client slot id, '''firstTime''' indicates if this is a new connection (1) or a reconnection (0). '''isBot''' indicates if the client is a bot (1) or not (0). If the mod accepts the connection, it should return nil. Otherwise, the mod should return a string describing the reason the client connection was rejected.
−
et_ClientBegin( integer clientNum )<br>
+
et_ClientDisconnect( '''clientNum''' )
−
et_ClientUserinfoChanged( integer clientNum )<br>
+
:Called when a client disconnects. '''clientNum''' is the client slot id.
 +
et_ClientBegin( '''clientNum''' )
 +
:Called when a client begins (becomes active, and enters the gameworld). '''clientNum''' is the client slot id.
 +
et_ClientUserinfoChanged( '''clientNum''' )
 +
:Called when a client's [[Userinfo]] string has changed. '''clientNum''' is the client slot id.
 +
:'''note:''' In ETPro 3.2.6 and below, this only gets called when the players CS_PLAYERS config string changes, rather than every time the userinfo changes. This only happens for a subset of userinfo fields.
 +
et_ClientSpawn( '''clientNum''', '''revived''' )
 +
:Called when a client is spawned. '''clientNum''' is the client slot id. '''revived''' is 1 if the client was spawned by being revived.
 
<br>
 
<br>
 +
 
===commands===
 
===commands===
−
integer intercepted = et_ClientCommand( integer clientNum, string command )<br>
+
'''intercepted''' = et_ClientCommand( '''clientNum''', '''command''' )
−
integer intercepted = et_ConsoleCommand()<br>
+
:Called when a command is received from a client. '''clientNum''' is the client slot id. '''command''' is the command. The mod should return 1 if the command was intercepted by the mod, and 0 if the command was ignored by the mod and should be passed through to the server (and other mods in the chain).
 +
:The actual command can be accessed through the [[#argument_handling|argument handling]] functions, as seen in the [[ETPro:Lua Sample Code]].
 +
'''intercepted''' = et_ConsoleCommand()
 +
:Called when a command is entered on the server console. The mod should return 1 if the command was intercepted by the mod, and 0 if the command was ignored by the mod and should be passed through to the server (and other mods in the chain).
 +
:The actual command can be accessed through the [[#argument_handling|argument handling]] functions, as seen in the [[ETPro:Lua Sample Code]].
 
<br>
 
<br>
 +
 +
===xp===
 +
et_UpgradeSkill( '''cno''', '''skill''' )
 +
:Called when client on slot '''cno''' gets an upgrade on skill '''skill'''. Return -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough.
 +
et_SetPlayerSkill( '''cno''', '''skill''' )
 +
:Called when clients (on slot '''cno''') skill level '''skill''' is set. Return -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough.
 +
<br>
 +
 
===miscellaneous===
 
===miscellaneous===
−
et_IPCReceive( vmnumber, message )<br>
+
et_IPCReceive( '''vmnumber''', '''message''' )
−
et_Print( string text )<br>
+
:Called when another mod sends an et.IPCSend() message to this mod. '''vmnumber''' is the VM slot number of the sender, and '''message''' is the message.
 +
et_Print( '''text''' )
 +
:Called whenever the server or qagame prints a string to the console.
 +
:'''WARNING!''' ''text'' may contain a player name + their chat message. This makes it '''very easy''' to spoof. '''DO NOT TRUST STRINGS OBTAINED IN THIS WAY'''
 +
et_Obituary( '''victim''', '''killer''', '''meansOfDeath''' )
 +
:Called whenever a player is killed.
 
<br>
 
<br>
−
==defined constants==
+
 
 +
==predefined constants==
 
et.EXEC_NOW<br>
 
et.EXEC_NOW<br>
 
et.EXEC_INSERT<br>
 
et.EXEC_INSERT<br>
Line 108: Line 237:
 
et.FS_APPEND<br>
 
et.FS_APPEND<br>
 
et.FS_APPEND_SYNC<br>
 
et.FS_APPEND_SYNC<br>
 +
et.SAY_ALL<br>
 +
et.SAY_TEAM<br>
 +
et.SAY_BUDDY<br>
 +
et.SAY_TEAMNL<br>
 
<br>
 
<br>
 +
et.HOSTARCH
 +
:set to WIN32 or UNIX depending on the host architecture qagame is running on.
 +
LUA_PATH
 +
:set to fs_homepath/fs_game/?.lua in order to ease use of the [http://www.lua.org/pil/8.1.html require] function.
 +
<br>
 +
 +
==configs==
 +
If a config is loaded, all modules are shutdown and reloaded. If a ''certified'' config is loaded, all modules are shutdown and reloaded, and additionally the following functions are disabled: '''require()''', '''loadfile()''', '''loadlib()''', '''loadstring()''', '''dofile()'''<br>
 +
<br>
 +
 +
==caveats==
 +
Like qagame, lua modules are unloaded and reloaded on map_restart and map changes. This means that all global variables and other information is lost. Mods may choose to store persistent data in cvars or external files.<br>
 +
<br>
 +
 
==FAQ==
 
==FAQ==
  
Line 114: Line 261:
 
A: table.foreach(et, function (func, value) _G[func] = value; end)
 
A: table.foreach(et, function (func, value) _G[func] = value; end)
  
−
Q: How do a re-load my lua file without restarting the whole server ?<br>
+
Q: How do a reload my lua file without restarting the whole server?<br>
−
A: Use the following in the server console:
+
A: Use ''map_restart'', ''reset_match'' or simply change the map.
−
lua_modules ""
+
 
−
lua_modules "mymod.lua" ; map_restart
+
Q: Can I see some sample code?<br>
−
Note that lua_modules "" must be on a line by itself.
+
A: [[ETPro:Lua Sample Code|Lua sample code]]
 +
 
 +
Q: Is there a list of [[ETPro]] Lua mods?<br>
 +
A: Yes, [[:Category:ETPro:Mods|here]].
 +
 
 +
Q: OMG my mod doesn't work!<br>
 +
A: Make sure you added your mod's filename to the lua_modules cvar (e.g. set lua_modules mymod.lua).
 +
 
 +
Q: OMG why has et_ClientSay been removed?<br>
 +
A: That's a secret but, to keep the function as it was, just add the following code to your et_ClientCommand() function<br>
 +
<pre> -- et_ClientSay had to be removed in order to intercept all commands
 +
-- so here's a wrapper for that
 +
arg0 = et.trap_Argv(0) -- get the main command
 +
 +
if arg0 == "say" then
 +
return et_ClientSay( clientNum, et.SAY_ALL, et.ConcatArgs(1))
 +
elseif arg0 == "say_team" then
 +
return et_ClientSay( clientNum, et.SAY_TEAM, et.ConcatArgs(1))
 +
elseif arg0 == "say_buddy" then
 +
return et_ClientSay( clientNum, et.SAY_BUDDY, et.ConcatArgs(1))
 +
elseif arg0 == "say_teamnl" then
 +
return et_ClientSay( clientNum, et.SAY_TEAMNL, et.ConcatArgs(1))
 +
end
 +
-- et_ClientSay wrapper end
 +
</pre>
  
−
[[Category:ETPro]]
+
[[Category:Lua]]

Latest revision as of 21:42, 23 March 2008

ETPro now supports server-side mods via the Lua scripting language. For more information about Lua, visit the Reference manual, the online edition of the book Programming in Lua or the lua-users wiki. A list of text editors for coding LUA can be found here.

ETPro has an embedded Lua 5.0.2 interpreter, and if present will load user-defined scripts from the ETPro directory. It also provides an "et" library of function calls for Lua that allow access to the server engine, and provides callbacks so a server side mod may trigger on specific server events.

The following standard Lua libraries are initialized by default and available to ETPro Lua scripts: basic, table, i/o, os (available features vary depending on your OS), string, math.

A list of ETPro mods can be found here.

A tutorial about ETPro Lua scripting can be found here.

API requests can be discussed at the Lua Mod API talk page.

client commands

lua_status

lists all currently loaded lua modules.
lua mods cannot override this client command.

server commands

lua_status

lists all currently loaded lua modules.

cvars

lua_modules

(default "", disabled)
space separated list of lua modules for ETPro to load. modules will be run in the order listed.

lua_allowedmodules

(default "", disabled)
if set, only lua modules with the matching sha1 signatures listed in this cvar will be allowed to load.


changing either cvar will cause all currently loaded modules to :quit and be unloaded until the next map_restart.


et library calls

modules

et.RegisterModname( modname )

Registers a descriptive string modname for this mod.

vmnumber = et.FindSelf()

Returns a number indicating the VM slot the current mod is loaded into.

modname, signature = et.FindMod( vmnumber )

Returns the modname and sha1 signature for the mod loaded in the VM slot vmnumber. Returns nil, nil if the VM slot is invalid.

success = et.IPCSend( vmnumber, message )

Sends the string message to the mod in the VM slot indicated by vmnumber. The mod receiving message must have an et_IPCReceive() callback. If the message is successfully sent, success will be 1. On failure it will be 0. See the Lua IPC page for a simple example.


printing

et.G_Print( text )

Prints the string text to the server console.

et.G_LogPrint( text )

Prints the string text to the server console and writes it to the server log.


argument handling

These functions are to be used within the command callback functions.
args = et.ConcatArgs( index )

Returns all arguments beginning from index concatenated into a single string args

argcount = et.trap_Argc()

Returns a number indicating the number of command line arguments in the command buffer.

arg = et.trap_Argv( argnum )

Returns the contents of the command line argument argnum.


cvars

cvarvalue = et.trap_Cvar_Get( cvarname )

Returns the value of the cvar cvarname as a string. If there is no cvar named cvarname, returns a zero length string.

et.trap_Cvar_Set( cvarname, cvarvalue )

Sets the cvar cvarname to cvarvalue


configstrings

configstringvalue = et.trap_GetConfigstring( index )

Returns the string configstringvalue containing the contents of the configstring index

et.trap_SetConfigstring( index, configstringvalue )

Sets the configstring index to the string configstringvalue


server

et.trap_SendConsoleCommand( when, command )

Sends the command command to the server console, to be executed when (see et.EXEC_* constants)


clients

et.trap_DropClient( clientnum, reason, ban_time )

Disconnects clientnum from the server, with descriptive string reason reported to clients. ban_time is the time in seconds to ban the client from the server. ban_time is optional and may be entirely omitted, in which case the ban time defaults to the cvar b_defaultbantime

et.trap_SendServerCommand( clientnum, command )

Sends the command command to the client clientnum. If clientnum is -1, the command is broadcast to all connected clients.

et.G_Say( clientNum, mode, text )

Sends a chat command on behalf of client clientNum with the mode mode (see et.SAY_* constants) and chat text text.

et.ClientUserinfoChanged( clientNum )

Loads the new Userinfo of clientNum and stores it in the configstring and client variables


userinfo

userinfo = et.trap_GetUserinfo( clientnum )

Returns the contents of the Userinfo string for the client clientnum

et.trap_SetUserinfo( clientnum, userinfo )

Sets the Userinfo string for the client clientnum to userinfo


string utility functions

infostring = et.Info_RemoveKey( infostring, key )

Removes key key from infostring infostring and returns the modified infostring.

infostring = et.Info_SetValueForKey( infostring, key, value )

Sets the key key in the infostring infostring to value and returns the modified infostring. If value is an empty string, key is removed from the string.

keyvalue = et.Info_ValueForKey( infostring, key )

Returns the value of the key key in the infostring infostring. If key is not present in the string, an empty string is returned.

cleanstring = et.Q_CleanStr( string )

Returns string stripped of all color codes


ET filesystem

fd, len = et.trap_FS_FOpenFile( filename, mode )

Attempts to open the file filename with the access mode mode (see et.FS_ constants). Returns the filedescriptor fd and file length len. On error, len returns -1.

filedata = et.trap_FS_Read( fd, count )

Reads count bytes from filedescriptor fd.

count = et.trap_FS_Write( filedata, count, fd )

Attempts to write count bytes of filedata to filedescriptor fd. Returns number of bytes successfully written.

et.trap_FS_Rename( oldname, newname )

Renames file oldname to newname.

et.trap_FS_FCloseFile( fd )

Closes filedescriptor fd


indexes

soundindex = et.G_SoundIndex( filename )

Returns an index to the soundfile indicated by filename

modelindex = et.G_ModelIndex( filename )

Returns an index to the model indicated by filename


sound

et.G_globalSound( sound )

Plays the global sound indicated by the filename sound.

et.G_Sound( entnum, soundindex )

Plays the sound soundindex at the location of entity entnum


miscellaneous

milliseconds = et.trap_Milliseconds()

Returns a number indicating the current server time in milliseconds.

et.G_Damage( target, inflictor, attacker, damage, dflags, mod )

Does damage amount of damage on target inflicted by inflictor and cased by attacker
target, inflictor, attacker are entity numbers
dflags is a bitflag number to decide how the damage is inflickted, see dflags flaglist
mod is a number from 0 up to 64 o set the type of damage, see mod list


entities

entnum = et.G_Spawn()

Spawns a new entity and returns the new entity number.

entnum = et.G_TempEntity( origin, event )

Spawns a new TempEntity of event type event and places it at origin in the world.

et.G_FreeEntity( entnum )

Frees the entity entnum

spawnval = et.G_GetSpawnVar( entnum, key )

Returns the value of spawnvar key for entity entnum

et.G_SetSpawnVar( entnum, key, value )

Sets the spawnvar key to value for entity entnum

integer entnum = et.G_SpawnGEntityFromSpawnVars( string spawnvar, string spawnvalue, ... )

This function can only be called inside the et_InitGame callback

et.trap_LinkEntity( entnum )

Links the entity entnum

et.trap_UnlinkEntity( entnum )

Unlinks the entity entnum

(variable) = et.gentity_get ( entnum, Fieldname ,arrayindex )

Gets the value of Fieldname from entity entnum out of the g_entity struct. For NULL entities or clients, nil is returned.
arrayindex is used to specify which element of an array entity field to get. It is required when accessing array type fields. Entity field array indexes start at 0.

et.gentity_set( entnum, Fieldname, arrayindex, (value) )

Sets the value of Fieldname from entity entnum in the g_entity struct to (value)
arrayindex is used to specify which element of an array entity field to set.

et.G_AddEvent( ent, event, eventparm' )

Adds event event whit eventparameter eventparm' to entity ent


callbacks

qagame execution

et_InitGame( levelTime, randomSeed, restart )

Called when qagame initializes. levelTime is the current level time in milliseconds. randomSeed is a number that can be used to seed random number generators. restart indicates if et_InitGame() is being called due to a map restart (1) or not (0).

et_ShutdownGame( restart )

Called when qagame shuts down. restart indicates if the shutdown is being called due to a map_restart (1) or not (0).

et_RunFrame( levelTime )

Called when qagame runs a server frame. levelTime is the current level time in milliseconds.

et_Quit()

Called when ETPro unloads the mod. The mod should close all open filedescriptors and perform all cleanup.


client management

rejectreason = et_ClientConnect( clientNum, firstTime, isBot )

Called when a client attempts to connect to the server. clientNum is the client slot id, firstTime indicates if this is a new connection (1) or a reconnection (0). isBot indicates if the client is a bot (1) or not (0). If the mod accepts the connection, it should return nil. Otherwise, the mod should return a string describing the reason the client connection was rejected.

et_ClientDisconnect( clientNum )

Called when a client disconnects. clientNum is the client slot id.

et_ClientBegin( clientNum )

Called when a client begins (becomes active, and enters the gameworld). clientNum is the client slot id.

et_ClientUserinfoChanged( clientNum )

Called when a client's Userinfo string has changed. clientNum is the client slot id.
note: In ETPro 3.2.6 and below, this only gets called when the players CS_PLAYERS config string changes, rather than every time the userinfo changes. This only happens for a subset of userinfo fields.

et_ClientSpawn( clientNum, revived )

Called when a client is spawned. clientNum is the client slot id. revived is 1 if the client was spawned by being revived.


commands

intercepted = et_ClientCommand( clientNum, command )

Called when a command is received from a client. clientNum is the client slot id. command is the command. The mod should return 1 if the command was intercepted by the mod, and 0 if the command was ignored by the mod and should be passed through to the server (and other mods in the chain).
The actual command can be accessed through the argument handling functions, as seen in the ETPro:Lua Sample Code.

intercepted = et_ConsoleCommand()

Called when a command is entered on the server console. The mod should return 1 if the command was intercepted by the mod, and 0 if the command was ignored by the mod and should be passed through to the server (and other mods in the chain).
The actual command can be accessed through the argument handling functions, as seen in the ETPro:Lua Sample Code.


xp

et_UpgradeSkill( cno, skill )

Called when client on slot cno gets an upgrade on skill skill. Return -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough.

et_SetPlayerSkill( cno, skill )

Called when clients (on slot cno) skill level skill is set. Return -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough.


miscellaneous

et_IPCReceive( vmnumber, message )

Called when another mod sends an et.IPCSend() message to this mod. vmnumber is the VM slot number of the sender, and message is the message.

et_Print( text )

Called whenever the server or qagame prints a string to the console.
WARNING! text may contain a player name + their chat message. This makes it very easy to spoof. DO NOT TRUST STRINGS OBTAINED IN THIS WAY

et_Obituary( victim, killer, meansOfDeath )

Called whenever a player is killed.


predefined constants

et.EXEC_NOW
et.EXEC_INSERT
et.EXEC_APPEND
et.FS_READ
et.FS_WRITE
et.FS_APPEND
et.FS_APPEND_SYNC
et.SAY_ALL
et.SAY_TEAM
et.SAY_BUDDY
et.SAY_TEAMNL

et.HOSTARCH

set to WIN32 or UNIX depending on the host architecture qagame is running on.

LUA_PATH

set to fs_homepath/fs_game/?.lua in order to ease use of the require function.


configs

If a config is loaded, all modules are shutdown and reloaded. If a certified config is loaded, all modules are shutdown and reloaded, and additionally the following functions are disabled: require(), loadfile(), loadlib(), loadstring(), dofile()

caveats

Like qagame, lua modules are unloaded and reloaded on map_restart and map changes. This means that all global variables and other information is lost. Mods may choose to store persistent data in cvars or external files.

FAQ

Q: OMG I hate the libary prefix et.* on everything!!11!1oneone
A: table.foreach(et, function (func, value) _G[func] = value; end)

Q: How do a reload my lua file without restarting the whole server?
A: Use map_restart, reset_match or simply change the map.

Q: Can I see some sample code?
A: Lua sample code

Q: Is there a list of ETPro Lua mods?
A: Yes, here.

Q: OMG my mod doesn't work!
A: Make sure you added your mod's filename to the lua_modules cvar (e.g. set lua_modules mymod.lua).

Q: OMG why has et_ClientSay been removed?
A: That's a secret but, to keep the function as it was, just add the following code to your et_ClientCommand() function

	-- et_ClientSay had to be removed in order to intercept all commands 
	-- so here's a wrapper for that
		arg0 = et.trap_Argv(0) -- get the main command
		
		if arg0 == "say" then
			return et_ClientSay( clientNum, et.SAY_ALL, et.ConcatArgs(1))
		elseif arg0 == "say_team" then
			return et_ClientSay( clientNum, et.SAY_TEAM, et.ConcatArgs(1))
		elseif arg0 == "say_buddy" then
			return et_ClientSay( clientNum, et.SAY_BUDDY, et.ConcatArgs(1))
		elseif arg0 == "say_teamnl" then
			return et_ClientSay( clientNum, et.SAY_TEAMNL, et.ConcatArgs(1))
		end
	-- et_ClientSay wrapper end
Retrieved from "https://wolfwiki.anime.net/index.php?title=Lua_Mod_API&oldid=2921"