Difference between revisions of "Lua Mod API"

Revision as of 09:09, 1 November 2005

ETPro now supports serverside mods via the lua 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( 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

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

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 commands

et.trap_SendConsoleCommand( when, command )

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

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.

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

key management 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.

infostring = et.Info_ValueForKey( infostring, key )

Returns the value of the key key in the infostring infostring

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

miscellaneous

milliseconds = et.trap_Milliseconds()

Returns a number indicating the current server time in milliseconds.

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

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

Links the entity entnum

et.trap_UnlinkEntity( entnum )

Unlinks the entity entnum

(variable) = et.gentity_get( int entnum, string fieldname )
et.gentity_set( int entnum, string fieldname, (variable) )

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.

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).

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).

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.

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

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.