Difference between revisions of "Lua Mod API"

Revision as of 04:05, 1 November 2005

ETPro now supports serverside mods via the lual scripting language.

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.

The following standard lua libraries are initialized by default and available to ETPro lua scripts: basic, table, i/o, string, math.

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.

printing

et.G_Print( string text )
et.G_LogPrint( string text )

argument handling

string args = et.ConcatArgs( integer index )
integer argcount = et.trap_Argc()
string arg = et.trap_Argv( integer argnum )

cvars

string cvarvalue = et.trap_Cvar_Get( string cvarname )
et.trap_Cvar_Set( string cvarname, string cvarvalue )

configstrings

string configstringvalue = et.trap_GetConfigstring( integer index )
et.trap_SetConfigstring( integer index, string configstringvalue )

server commands

et.trap_SendConsoleCommand( integer when, string command )
et.trap_SendServerCommand( integer clientnum, string command )

userinfo

string userinfo = et.trap_GetUserinfo( integer clientnum )
et.trap_SetUserinfo( integer clientnum, string userinfo )

key management utility functions

string infostring = et.Info_RemoveKey( string infostring, string key )
string infostring = et.Info_SetValueForKey( string infostring, string key, string value )
string infostring = et.Info_ValueForKey( string infostring, string key )

ET filesystem

integer fd, integer len = et.trap_FS_FOpenFile( string filename, int mode )
string filedata = et.trap_FS_Read( integer fd, integer count )
integer count = et.trap_FS_Write( string filedata, integer count, integer fd )
et.trap_FS_Rename( string oldname, string newname )
et.trap_FS_FCloseFile( integer fd )

miscellaneous

integer milliseconds = et.trap_Milliseconds()

entities

integer entnum = et.G_Spawn()
integer entnum = et.G_TempEntity( origin, event )
et.G_FreeEntity( integer entnum )
integer entnum = et.G_SpawnGEntityFromSpawnVars( string spawnvar, string spawnvalue, ... )
et.trap_LinkEntity( int entnum )
et.trap_UnlinkEntity( int entnum )
(variable) = et.gentity_get( int entnum, string fieldname )
et.gentity_set( int entnum, string fieldname, (variable) )

callbacks

qagame execution

et_InitGame( integer levelTime, integer randomSeed, integer restart )
et_ShutdownGame( integer restart )
et_RunFrame( integer levelTime )
et_Quit()

client management

string rejectreason = et_ClientConnect( integer clientNum, boolean firstTime, boolean isBot )
et_ClientDisconnect( integer clientNum )
et_ClientBegin( integer clientNum )
et_ClientUserinfoChanged( integer clientNum )

commands

integer intercepted = et_ClientCommand( integer clientNum, string command )
integer intercepted = et_ConsoleCommand()

miscellaneous

et_IPCReceive( vmnumber, message )
et_Print( string text )

defined constants

et.EXEC_NOW
et.EXEC_INSERT
et.EXEC_APPEND
et.FS_READ
et.FS_WRITE
et.FS_APPEND
et.FS_APPEND_SYNC

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 re-load my lua file without restarting the whole server ?
A: Use the following in the server console:

lua_modules ""
lua_modules "mymod.lua" ; map_restart

Note that lua_modules "" must be on a line by itself.