Difference between revisions of "Lua Mod API"
m (→ET filesystem) |
|||
| Line 109: | Line 109: | ||
===qagame execution=== | ===qagame execution=== | ||
| − | et_InitGame( | + | et_InitGame( '''levelTime''', '''randomSeed''', '''restart''' ) |
| − | et_ShutdownGame( | + | :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( | + | et_ShutdownGame( '''restart''' ) |
| − | et_Quit() | + | :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=== | ||
| − | + | '''rejectreason''' = et_ClientConnect( '''clientNum''', '''firstTime''', '''isBot''' ) | |
| − | et_ClientDisconnect( | + | :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 reconnect from a map restart. '''isBot''' indicates if the client is a bot or not. If the mod accepts the connection, return nil. Otherwise, the mod should return a string indicating the reason the client connection was rejected. |
| − | et_ClientBegin( | + | et_ClientDisconnect( '''clientNum''' ) |
| − | et_ClientUserinfoChanged( | + | :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. | ||
<br> | <br> | ||
===commands=== | ===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). | ||
<br> | <br> | ||
===miscellaneous=== | ===miscellaneous=== | ||
| − | et_IPCReceive( vmnumber, message ) | + | et_IPCReceive( '''vmnumber''', '''message''' ) |
| − | et_Print( | + | :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. | ||
<br> | <br> | ||
==defined constants== | ==defined constants== | ||
Revision as of 05:59, 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
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 )
- Returns len -1 on errors.
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
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 reconnect from a map restart. isBot indicates if the client is a bot or not. If the mod accepts the connection, return nil. Otherwise, the mod should return a string indicating 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.
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.
