From 4acb084595c04dbd69225939bcc24fc97501e2e0 Mon Sep 17 00:00:00 2001 From: Remy Marquis Date: Sat, 17 Sep 2016 18:57:29 +0200 Subject: [PATCH] expanded misc, added database and sample code --- callbacks.rst | 64 +++--- commands.rst | 2 +- constants.rst | 2 +- cvars.rst | 6 +- database.rst | 205 +++++++++++++++++++ fields.rst | 536 +++++++++++++++++++++++++++++--------------------- functions.rst | 300 ++++++++++++++-------------- index.rst | 9 +- misc.rst | 235 +++++++++++++++++++++- sample.rst | 378 +++++++++++++++++++++++++++++++++++ standard.rst | 2 +- 11 files changed, 1324 insertions(+), 415 deletions(-) create mode 100644 database.rst create mode 100644 sample.rst diff --git a/callbacks.rst b/callbacks.rst index c6eabaf..ab8a873 100644 --- a/callbacks.rst +++ b/callbacks.rst @@ -2,7 +2,7 @@ Callbacks ========= -Here are all available Lua callbacks. +**Callbacks** trigger on specific server events. qagame execution @@ -14,9 +14,9 @@ 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). +* **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 ) @@ -24,7 +24,7 @@ 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). +* **restart** indicates if the shutdown is being called due to a `map_restart` (1) or not (0). et_RunFrame( levelTime ) @@ -32,7 +32,7 @@ et_RunFrame( levelTime ) Called when qagame runs a server frame. -* `levelTime` is the current level time in milliseconds. +* **levelTime** is the current level time in milliseconds. et_Quit() @@ -52,11 +52,11 @@ 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). +* **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 returns `nil`. Otherwise, the mod should return a string describing the reason the client connection was rejected. +If the mod accepts the connection, it returns **nil**. Otherwise, the mod should return a string describing the reason the client connection was rejected. et_ClientDisconnect( clientNum ) @@ -64,7 +64,7 @@ et_ClientDisconnect( clientNum ) Called when a client disconnects. -* `clientNum` is the client slot id. +* **clientNum** is the client slot id. et_ClientBegin( clientNum ) @@ -72,7 +72,7 @@ et_ClientBegin( clientNum ) Called when a client begins (becomes active, and enters the gameworld). -* `clientNum` is the client slot id. +* **clientNum** is the client slot id. et_ClientUserinfoChanged( clientNum ) @@ -80,9 +80,9 @@ et_ClientUserinfoChanged( clientNum ) Called when a client's Userinfo string has changed. -* `clientNum` is the client slot id. +* **clientNum** is the client slot id. -.. note:: 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. +.. note:: 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, teamChange, restoreHealth ) @@ -90,10 +90,10 @@ et_ClientSpawn( clientNum, revived, teamChange, restoreHealth ) Called when a client is spawned. -* `clientNum` is the client slot id. -* `revived` indicates if the client was spawned by being revived (1) or not (0). -* `teamChange` indicates if the client changed team (1) or not (0). -* `restoreHealth` indicates if the player health bar is fully restored (1) or not (0). +* **clientNum** is the client slot id. +* **revived** indicates if the client was spawned by being revived (1) or not (0). +* **teamChange** indicates if the client changed team (1) or not (0). +* **restoreHealth** indicates if the player health bar is fully restored (1) or not (0). Commands @@ -105,8 +105,8 @@ intercepted = et_ClientCommand( clientNum, command ) Called when a command is received from a client. -* `clientNum` is the client slot id. -* `command` is the command. +* **clientNum** is the client slot id. +* **command** is the command. Returns 1 if the command was intercepted by the mod, and 0 if the command was ignored and passed through to the server (and other mods in the chain). @@ -132,8 +132,8 @@ et_UpgradeSkill( clientNum, skill ) Called when a client gets a skill upgrade. -* `clientNum` is the client slot. -* `skill` is the skill number. +* **clientNum** is the client slot. +* **skill** is the skill number. Returns -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough. @@ -143,8 +143,8 @@ et_SetPlayerSkill( clientNum, skill ) Called when a client skill is set. -* `clientNum` is the client slot. -* `skill` is the skill number. +* **clientNum** is the client slot. +* **skill** is the skill number. Returns -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough. @@ -169,9 +169,9 @@ et_Obituary( target, attacker, meansOfDeath ) Called whenever a player is killed. -* `target` is the victim. -* `attacker` is the killer. -* `meansOfDeath` is the means of death. +* **target** is the victim. +* **attacker** is the killer. +* **meansOfDeath** is the means of death. et_Damage( target, attacker, damage, damageFlags, meansOfDeath) @@ -179,11 +179,11 @@ et_Damage( target, attacker, damage, damageFlags, meansOfDeath) Called whenever a player gets damage. -* `target` is the victim. -* `attacker` is the killer. -* `damage` is the amount of damage. -* `damageFlags` is the `flag `__ that controls how damage is inflicted. -* `meansOfDeath` is the `means of death `__. +* **target** is the victim. +* **attacker** is the killer. +* **damage** is the amount of damage. +* **damageFlags** controls how damage is inflicted. See `Damage bitflags `__ for possible values. +* **meansOfDeath** is the means of death. See `et.MOD_* constants `__ for possible values. et_SpawnEntitiesFromString() diff --git a/commands.rst b/commands.rst index ca621cf..f61cd40 100644 --- a/commands.rst +++ b/commands.rst @@ -2,7 +2,7 @@ Commands ======== -Here are all available Lua commands. +**Commands** shows information about currently loaded scripts. Server commands diff --git a/constants.rst b/constants.rst index dff5cbe..0dd4f5d 100644 --- a/constants.rst +++ b/constants.rst @@ -2,7 +2,7 @@ Constants ========= -Here is a list of all the Lua constants. +**Constants** are strings set on the server. CS constants diff --git a/cvars.rst b/cvars.rst index 4648652..cd9d3df 100644 --- a/cvars.rst +++ b/cvars.rst @@ -2,7 +2,7 @@ Cvars ===== -Here are all available Lua cvars. +**Cvars** control loaded modules. .. note:: Changing either cvar will cause all currently loaded modules to quit and be unloaded until the next `map_restart`. @@ -11,14 +11,10 @@ Here are all available Lua cvars. lua_modules ----------- -**Default:** "" (disabled) - Space separated list of lua modules for Legacy mod 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. If empty, all loaded modules are allowed. diff --git a/database.rst b/database.rst new file mode 100644 index 0000000..caae2b9 --- /dev/null +++ b/database.rst @@ -0,0 +1,205 @@ +======== +Database +======== + +Both the Legacy mod and the ET:Legacy engine are built-in with `SQLite3 `_ database support. The engine allows to execute SQL statement directly in console, while the Legacy mod has access through `LuaSQL `_. + +.. tip:: See the `Database `__ sample code for an example of basic database usage. + +If desired, Lua scripts can also connect to the engine memory database by the following Lua command:: + + --[[ + Lua Example connecting to engine database + --]] + con = assert (env:connect( "file::memory:?cache=shared")) + +.. Note:: The database is only active when the `db_mode `_ cvar is set to **1**. + +To save this in memory database to disk use the **saveDB** console command. See also the `db_url `_ cvar to specify the database path. + + +Error handling +============== + + +LuaSQL is just an abstraction layer that communicates between Lua and a database system. Therefore errors can occur on both levels, that is, inside the database client or inside LuaSQL driver. + +Errors such as malformed SQL statements, unknown table names etc. are called database errors and will be reported by the function/method returning `nil` followed by the error message provided by the database system. Errors such as wrong parameters, absent connection, invalid objects etc., called API errors, are usually program errors and so will raise a Lua error. + +This behavior will be followed by all functions/methods described in this document unless otherwise stated. + + +Drivers +======= + + +A LuaSQL driver allows the use of the LuaSQL API with a database management system that corresponds to the driver. To use a driver you have to load it. The example below:: + + local driver = require "luasql.sqlite3" + +loads the SQLite3 driver and returns a table with an entry with the name of the driver (sqlite3 in this case). + +.. Note that you can have more than one driver loaded at the same time doing something like: +.. +.. local odbc_driver = require "luasql.odbc" +.. local oci8_driver = require "luasql.oci8" + +.. This example also shows that the driver name not always correspond to the Database name, but to the driver name in the file system. Since it refers to the OCI8 API, the Oracle driver has the name oci8. + + +Environment objects +=================== + + +An environment object is created by calling the driver's initialization function that is stored in the table returned when it was loaded, indexed with the same name as the driver (odbc, postgres etc). The following example, will try to create an environment object using the SQLite3 driver:: + + local driver = require "luasql.sqlite3" + local env = driver.sqlite3() + + +env:close() +----------- + +Closes the environment `env`. Only successful if all connections pertaining to it were closed first. + +Returns **true** in case of success; **false** when the object is already closed. + + +env:connect(sourcename[,username[,password]]) +--------------------------------------------- + +Connects to a data source specified in sourcename using username and password if they are supplied. +The sourcename may vary according to each driver. SQLite3 uses a simple database name. + +.. Some use a simple database name, like PostgreSQL, MySQL and SQLite; the ODBC driver expects the name of the DSN; the Oracle driver expects the service name; See also: PostgreSQL, and MySQL extensions. + +Returns a `connection object `__. + + +Connection objects +================== + + +A connection object contains specific attributes and parameters of a single data source connection. A connection object is created by calling the `environment:connect `__ method. + + +conn:close() +------------ + +Closes the connection conn. Only successful if all cursors pertaining to it have been closed and the connection is still open. + +Returns **true** in case of success and **false** in case of failure. + + +conn:commit() +------------- + +Commits the current transaction. + +.. This feature might not work on database systems that do not implement transactions. + +Returns **true** in case of success and **false** when the operation could not be performed or when it is not implemented. + + +conn:execute(statement) +----------------------- + +Executes the given `SQL statement`. + +Returns a `cursor object `__ if there are results, or the **number of rows** affected by the command otherwise. + + +conn:rollback() +--------------- + +Rolls back the current transaction. + +.. This feature might not work on database systems that do not implement transactions. + +Returns **true** in case of success and **false** when the operation could not be performed or when it is not implemented. + + +conn:setautocommit(boolean) +--------------------------- + +Turns on or off the "auto commit" mode. + +.. This feature might not work on database systems that do not implement transactions. On database systems that do not have the concept of "auto commit mode", but do implement transactions, this mechanism is implemented by the driver. + +Returns **true** in case of success and **false** when the operation could not be performed or when it is not implemented. + + +Cursor objects +============== + + +A cursor object contains methods to retrieve data resulting from an executed statement. A cursor object is created by using the `connection:execute `__ function. + +.. See also PostgreSQL and Oracle extensions. + + +cur:close() +----------- + +Closes this cursor. + +Returns **true** in case of success and **false** when the object is already closed. + + +cur:fetch([table[,modestring]]) +------------------------------- + +Retrieves the next row of results. + +If fetch is called without parameters, the results will be returned directly to the caller. If fetch is called with a table, the results will be copied into the table and the changed table will be returned. In this case, an optional modestring parameter can be used. It is just a string indicating how the resulting table should be constructed. + +The mode string can contain: + +* **n**: the resulting table will have numerical indices (default) +* **a**: the resulting table will have alphanumerical indices + +The numerical indices are the positions of the fields in the SELECT statement; the alphanumerical indices are the names of the fields. +The optional table parameter is a table that should be used to store the next row. This allows the use of a unique table for many fetches, which can improve the overall performance. + +A call to fetch after the last row has already being returned will close the corresponding cursor. There is no guarantee about the types of the results: they may or may not be converted to adequate Lua types by the driver. + +.. In the current implementation, the PostgreSQL and MySQL drivers return all values as strings while the ODBC and Oracle drivers convert them to Lua types. + +Returns **data**, as above, or **nil** if there are no more rows. + +.. note: Note that this method could return nil as a valid result. + + +cur:getcolnames() +----------------- + +Returns a **list (table) of column names**. + + +cur:getcoltypes() +----------------- + +Returns a **list (table) of column types**. + + +SQLite3 extensions +================== + + +Besides the basic functionality provided by all drivers, the SQLite3 driver also offers this extra feature: + + +env:connect(sourcename[,locktimeout]) +------------------------------------- + +In the SQLite3 driver, this method adds an optional parameter that indicate the amount of milisseconds to wait for a write lock if one cannot be obtained immediately. See also `environment objects `__. + +Returns a `connection object `__. + + +conn:escape(str) +---------------- + +Escape especial characters in the given string according to the connection's character set. See also the official documentation of function `sqlite3_mprintf `_. + +Returns the **escaped string**. diff --git a/fields.rst b/fields.rst index 7141d85..860f444 100644 --- a/fields.rst +++ b/fields.rst @@ -2,7 +2,7 @@ Fields ====== -Here are all available Lua fields supported by `et.gentity_get() `__ and `et.gentity_set() `__ functions. +**Fields** are entity parameters supported by `et.gentity_get() `__ and `et.gentity_set() `__ functions. Player fields @@ -12,121 +12,121 @@ Player fields ================================= =========== ======== ================================== Name Type Flag Description ================================= =========== ======== ================================== -noclip INT RO -lastKillTime INT RO -saved_persistant INT_ARRAY RO -lastConstructibleBlockingWarnTime INT RO -landmineSpottedTime INT RO -lasthurt_client INT RO -lasthurt_mod INT RO -lasthurt_time INT RO -respawnTime INT RO -inactivityTime INT RW -inactivityWarning INT RW -PCSpecialPickedUpCount INT RO -combatState INT RO -deathAnimTime INT RO -deathTime INT RO -disguiseClientNum INT RO -medals INT RO -acc FLOAT RO -hspct FLOAT RO -freezed INT RW -constructSoundTime INT RO +noclip int ro +lastKillTime int ro +saved_persistant int_array ro +lastConstructibleBlockingWarnTime int ro +landmineSpottedTime int ro +lasthurt_client int ro +lasthurt_mod int ro +lasthurt_time int ro +respawnTime int ro +inactivityTime int rw +inactivityWarning int rw +PCSpecialPickedUpCount int ro +combatState int ro +deathAnimTime int ro +deathTime int ro +disguiseClientNum int ro +medals int ro +acc float ro +hspct float ro +freezed int rw +constructSoundTime int ro -pers.connected INT RO -pers.netname STRING NOPTR -pers.localClient INT RW -pers.initialSpawn INT RW -pers.enterTime INT RW -pers.connectTime INT RO -pers.teamState.state INT RW -pers.voteCount INT RW -pers.complaints INT RW -pers.complaintClient INT RW -pers.complaintEndTime INT RW -pers.lastReinforceTime INT RW -pers.applicationClient INT RW -pers.applicationEndTime INT RW -pers.invitationClient INT RW -pers.invitationEndTime INT RW -pers.propositionClient INT RW -pers.propositionClient2 INT RW -pers.propositionEndTime INT RW -pers.autofireteamEndTime INT RW -pers.autofireteamCreateEndTime INT RW -pers.autofireteamJoinEndTime INT RW -pers.lastSpawnTime INT RO -pers.ready INT RW -pers.lastkilled_client INT RO -pers.lastrevive_client INT RO -pers.lastkiller_client INT RO -pers.lastammo_client INT RO -pers.lasthealth_client INT RO -pers.lastteambleed_client INT RO -pers.lastteambleed_dmg INT RO -pers.playerStats.hitRegions INT_ARRAY RO -pers.lastBattleSenseBonusTime INT RO -pers.lastHQMineReportTime INT RO -pers.maxHealth INT RO -pers.playerStats.selfkills INT RO +pers.connected int ro +pers.netname string noptr +pers.localClient int rw +pers.initialSpawn int rw +pers.enterTime int rw +pers.connectTime int ro +pers.teamState.state int rw +pers.voteCount int rw +pers.complaints int rw +pers.complaintClient int rw +pers.complaintEndTime int rw +pers.lastReinforceTime int rw +pers.applicationClient int rw +pers.applicationEndTime int rw +pers.invitationClient int rw +pers.invitationEndTime int rw +pers.propositionClient int rw +pers.propositionClient2 int rw +pers.propositionEndTime int rw +pers.autofireteamEndTime int rw +pers.autofireteamCreateEndTime int rw +pers.autofireteamJoinEndTime int rw +pers.lastSpawnTime int ro +pers.ready int rw +pers.lastkilled_client int ro +pers.lastrevive_client int ro +pers.lastkiller_client int ro +pers.lastammo_client int ro +pers.lasthealth_client int ro +pers.lastteambleed_client int ro +pers.lastteambleed_dmg int ro +pers.playerStats.hitRegions int_array ro +pers.lastBattleSenseBonusTime int ro +pers.lastHQMineReportTime int ro +pers.maxHealth int ro +pers.playerStats.selfkills int ro -ps.pm_flags INT RO -ps.pm_time INT RO -ps.eFlags INT RO -ps.weapon INT RO -ps.weaponstate INT RO -ps.stats INT_ARRAY RW -ps.persistant INT_ARRAY RW -ps.ping INT RO -ps.powerups INT_ARRAY RW -ps.origin VEC3 RW -ps.ammo INT_ARRAY RW -ps.ammoclip INT_ARRAY RW -ps.classWeaponTime INT RW +ps.pm_flags int ro +ps.pm_time int ro +ps.eFlags int ro +ps.weapon int ro +ps.weaponstate int ro +ps.stats int_array rw +ps.persistant int_array rw +ps.ping int ro +ps.powerups int_array rw +ps.origin vec3 rw +ps.ammo int_array rw +ps.ammoclip int_array rw +ps.classWeaponTime int rw -sess.sessionTeam INT RW -sess.spectatorTime INT RW -sess.spectatorState INT RW -sess.spectatorClient INT RW -sess.playerType INT RW -sess.playerWeapon INT RW -sess.playerWeapon2 INT RW -sess.spawnObjectiveIndex INT RW -sess.latchPlayerType INT RW -sess.latchPlayerWeapon INT RW -sess.latchPlayerWeapon2 INT RW -sess.ignoreClients INT_ARRAY RW -sess.muted INT RW -sess.skillpoints FLOAT_ARRAY RO -sess.startskillpoints FLOAT_ARRAY RO -sess.startxptotal FLOAT RO -sess.skill INT_ARRAY RW -sess.rank INT RW -sess.medals INT_ARRAY RW -sess.referee INT RW -sess.rounds INT RW -sess.spec_invite INT RW -sess.spec_team INT RW -sess.kills INT RW -sess.deaths INT RW -sess.gibs INT RW -sess.self_kills INT RW -sess.team_kills INT RW -sess.team_gibs INT RW -sess.damage_given INT RW -sess.damage_received INT RW -sess.team_damage_given INT RW -sess.team_damage_received INT RW -sess.time_axis INT RW -sess.time_allies INT RW -sess.time_played INT RW -sess.mu FLOAT RW -sess.sigma FLOAT RW -sess.oldmu FLOAT RW -sess.oldsigma FLOAT RW -sess.uci INT RW -sess.aWeaponStats WEAPONSTAT RW +sess.sessionTeam int rw +sess.spectatorTime int rw +sess.spectatorState int rw +sess.spectatorClient int rw +sess.playerType int rw +sess.playerWeapon int rw +sess.playerWeapon2 int rw +sess.spawnObjectiveIndex int rw +sess.latchPlayerType int rw +sess.latchPlayerWeapon int rw +sess.latchPlayerWeapon2 int rw +sess.ignoreClients int_array rw +sess.muted int rw +sess.skillpoints float_array ro +sess.startskillpoints float_array ro +sess.startxptotal float ro +sess.skill int_array rw +sess.rank int rw +sess.medals int_array rw +sess.referee int rw +sess.rounds int rw +sess.spec_invite int rw +sess.spec_team int rw +sess.kills int rw +sess.deaths int rw +sess.gibs int rw +sess.self_kills int rw +sess.team_kills int rw +sess.team_gibs int rw +sess.damage_given int rw +sess.damage_received int rw +sess.team_damage_given int rw +sess.team_damage_received int rw +sess.time_axis int rw +sess.time_allies int rw +sess.time_played int rw +sess.mu float rw +sess.sigma float rw +sess.oldmu float rw +sess.oldsigma float rw +sess.uci int rw +sess.aWeaponStats weaponstat rw ================================= =========== ======== ================================== .. note:: All the session `sess.*` fields will return `nil` unless the entity is associated with a client slot. @@ -141,110 +141,208 @@ Entity fields ================================= =========== ======== ================================== Name Type Flag Description ================================= =========== ======== ================================== -activator ENTITY RO -chain ENTITY RW -classname STRING RW -clipmask INT RW -closespeed FLOAT RW -count INT RW -count2 INT RW -damage INT RW -deathType INT RW -delay FLOAT RW -dl_atten INT RW -dl_color VEC3 RW -dl_shader STRING RO -dl_stylestring STRING RO -duration FLOAT RW -end_size INT RW -enemy ENTITY RW -entstate INT RO -flags INT RO -harc FLOAT RW -health INT RW -inuse INT RW -isProp INT RO -item STRING RO -key INT RW -message STRING RW -methodOfDeath INT RW -mg42BaseEnt INT RW -missionLevel INT RW -model STRING RO -model2 STRING RO -nextTrain ENTITY RW -noise_index INT RW -prevTrain ENTITY RW -props_frame_state INT RO -r.absmax VEC3 RO -r.absmin VEC3 RO -r.bmodel INT RO -r.contents INT RW -r.currentAngles VEC3 RW -r.currentOrigin VEC3 RW -r.eventTime INT RW -r.linked INT RO -r.maxs VEC3 RW -r.mins VEC3 RW -r.ownerNum INT RW -r.singleClient INT RW -r.svFlags INT RW -r.worldflags INT RO -radius INT RW -random FLOAT RW -rotate VEC3 RW -s.angles VEC3 RW -s.angles2 VEC3 RW -s.apos TRAJECTORY RW -s.clientNum INT RW -s.constantLight INT RW -s.density INT RW -s.dl_intensity INT RW -s.dmgFlags INT RW -s.eFlags INT RW -s.eType INT RW -s.effect1Time INT RW -s.effect2Time INT RW -s.effect3Time INT RW -s.frame INT RW -s.groundEntityNum INT RO -s.loopSound INT RW -s.modelindex INT RW -s.modelindex2 INT RW -s.number INT RO -s.onFireEnd INT RW -s.onFireStart INT RW -s.origin VEC3 RW -s.origin2 VEC3 RW -s.pos TRAJECTORY RW -s.powerups INT RO -s.solid INT RW -s.teamNum INT RW -s.time INT RW -s.time2 INT RW -s.weapon INT RO -s.eventParm INT RW -scriptName STRING RO -spawnflags INT RO -spawnitem STRING RO -speed INT RW -splashDamage INT RW -splashMethodOfDeath INT RW -splashRadius INT RW -start_size INT RW -tagName STRING NOPTR+RO -tagParent ENTITY RW -takedamage INT RW -tankLink ENTITY RW -target STRING RW -TargetAngles VEC3 RW -TargetFlag INT RO -targetname STRING RO -teamchain ENTITY RW -teammaster ENTITY RW -track STRING RO -varc FLOAT RW -wait FLOAT RW -waterlevel INT RO -watertype INT RO +activator entity ro +chain entity rw +classname string rw +clipmask int rw +closespeed float rw +count int rw +count2 int rw +damage int rw +deathType int rw +delay float rw +dl_atten int rw +dl_color vec3 rw +dl_shader string ro +dl_stylestring string ro +duration float rw +end_size int rw +enemy entity rw +entstate int ro +flags int ro +harc float rw +health int rw +inuse int rw +isProp int ro +item string ro +key int rw +message string rw +methodOfDeath int rw +mg42BaseEnt int rw +missionLevel int rw +model string ro +model2 string ro +nextTrain entity rw +noise_index int rw +prevTrain entity rw +props_frame_state int ro +r.absmax vec3 ro +r.absmin vec3 ro +r.bmodel int ro +r.contents int rw +r.currentAngles vec3 rw +r.currentOrigin vec3 rw +r.eventTime int rw +r.linked int ro +r.maxs vec3 rw +r.mins vec3 rw +r.ownerNum int rw +r.singleClient int rw +r.svFlags int rw +r.worldflags int ro +radius int rw +random float rw +rotate vec3 rw +s.angles vec3 rw +s.angles2 vec3 rw +s.apos trajectory rw +s.clientNum int rw +s.constantLight int rw +s.density int rw +s.dl_intensity int rw +s.dmgFlags int rw +s.eFlags int rw +s.eType int rw +s.effect1Time int rw +s.effect2Time int rw +s.effect3Time int rw +s.frame int rw +s.groundEntityNum int ro +s.loopSound int rw +s.modelindex int rw +s.modelindex2 int rw +s.number int ro +s.onFireEnd int rw +s.onFireStart int rw +s.origin vec3 rw +s.origin2 vec3 rw +s.pos trajectory rw +s.powerups int ro +s.solid int rw +s.teamNum int rw +s.time int rw +s.time2 int rw +s.weapon int ro +s.eventParm int rw +scriptName string ro +spawnflags int ro +spawnitem string ro +speed int rw +splashDamage int rw +splashMethodOfDeath int rw +splashRadius int rw +start_size int rw +tagName string noptr+ro +tagParent entity rw +takedamage int rw +tankLink entity rw +target string rw +TargetAngles vec3 rw +TargetFlag int ro +targetname string ro +teamchain entity rw +teammaster entity rw +track string ro +varc float rw +wait float rw +waterlevel int ro +watertype int ro ================================= =========== ======== ================================== + + +Field types +=========== + + +int +--- + +An integer value. + + +float +----- + +A float value. + + +string +------ + +A string. + + +array +----- + +An array is a list of integer or float values. Individual elements of the array are accessed by passing the desired index in the `arrayindex` argument. +Valid array indexes are integers from 0 up to some field specific maximum. + +.. note:: The `arrayindex` argument is required when accessing array type fields, so only one element of an array can be accessed in a given call to the `et.gentity_get() `__ and `et.gentity_set() `__ functions. + + +vec3 +---- + +A vec3_t is a 3-element array of numbers, usually used to store and process coordinates in 3D space. +Similarly, in Legacy a vector is an array (table indexed by integers) containing 3 numbers. It can be accessed by:: + + origin = et.gentity_get(entNum, "r.currentOrigin") --a vec3 value + x, y, z = origin[1], origin[2], origin[3] + + + +trajectory +---------- + +A trajectory is returned as a lua table as described below:: + + { + trDuration = , --- int + trTime = , -- int + trType = , -- see below for allowed values + trBase = , -- vec3, as described above + trDelta = -- also a vec3 + } + + +The allowed values for `trType` are as follows: + +================================= ========================================================= +Name Description +================================= ========================================================= +TR_STATIONARY +TR_INTERPOLATE non-parametric, but interpolate between snapshots +TR_LINEAR +TR_LINEAR_STOP +TR_LINEAR_STOP_BACK so reverse movement can be different than forward +TR_SINE value = base + sin( time / duration ) * delta +TR_GRAVITY +TR_GRAVITY_LOW +TR_GRAVITY_FLOAT super low grav with no gravity acceleration (floating feathers/fabric/leaves/...) +TR_GRAVITY_PAUSED has stopped, but will still do a short trace to see if it should be switched back to TR_GRAVITY +TR_ACCELERATE +TR_DECCELERATE +TR_SPLINE +TR_LINEAR_PATH +================================= ========================================================= + +.. note:: Not all values make sense for all entity types. + + +entity +------ + +Entity numbers are integers from 0 through 1023. +Some of the entity numbers have special meanings: + +=========================== =============================================================== +Value Description +=========================== =============================================================== +0 - (sv_privateclients - 1) Reserved for clients who connect with the private slot password +0 - 63 Reserved for clients and also the client number +1022 Worldspawn entity +1023 ENTITYNUM_NONE which is used to indicate no entity when an entity number will be passed over the network +=========================== =============================================================== + +.. note:: Some other fields not listed as type `entity` may take an entity number value. Examples are `mg42BaseEnt` and `s.number`. diff --git a/functions.rst b/functions.rst index 2fb7d34..a4a1db5 100644 --- a/functions.rst +++ b/functions.rst @@ -2,8 +2,7 @@ Functions ========= - -Here are all available Lua functions of the `et` library. +**Functions** allow to manipulate and control the server, or alter internal structures and entities. Modules @@ -15,7 +14,7 @@ et.RegisterModname( modname ) Registers a descriptive name for this mod. -* `modname` is the name to register the Lua module. +* **modname** is the name to register the Lua module. vmnumber = et.FindSelf() @@ -23,7 +22,7 @@ vmnumber = et.FindSelf() Returns the assigned Lua VM slot number. -* `vmnumber` is the returned slot number assigned to this Lua VM. +* **vmnumber** is the returned slot number assigned to this Lua VM. modname, signature = et.FindMod( vmnumber ) @@ -31,23 +30,36 @@ modname, signature = et.FindMod( vmnumber ) Returns the name and SHA1 signature for the mod loaded in a VM slot. -* `vmnumber` is the VM slot number of the Lua module. -* `modname, signature` is the returned registered module's name and its SHA-1 signature. Returns `nil, nil` if the VM slot is invalid. +* **vmnumber** is the VM slot number of the Lua module. +* **modname, signature** are the returned registered module's name and SHA-1 signature. 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`. +Sends a message string to the mod in the another VM slot. -* `vmnumber` is the VM slot number of the Lua module to send a message to. -* `message` is the message string to sent to the Lua module. +* **vmnumber** is the VM slot number of the Lua module to send a message to. +* **message** is the message to sent to the Lua module. Returns 1 if the message is sent successfully, and 0 if it fails. -.. note:: The mod receiving message must have an `et_IPCReceive() `__ callback. +.. important:: The mod receiving message must have an `et_IPCReceive() `__ callback. -.. tip:: See the `Inter Process Communication (IPC) `__ for an example of communication between different loaded Lua modules. +.. note:: Data cannot be received and sent back in the same server frame. + + +et_IPCReceive( vmnumber, message ) +---------------------------------- + +Called when another module sends an `et.IPCSend() `__ message to this module. + +* **vmnumber** is the VM slot number of the sender. +* **message** is the message sent. + +.. important:: The sender module must be loaded earlier in the `lua_modules `__ cvar, otherwise the receiver module cannot find it. + +.. tip:: See the `Inter Process Communication (IPC) `__ sample code for an example of communication between different loaded Lua modules. Printing @@ -59,7 +71,7 @@ et.G_Print( text ) Prints text to the server console. -* `text` is the printed string. +* **text** is the printed string. et.G_LogPrint( text ) @@ -67,7 +79,7 @@ et.G_LogPrint( text ) Prints text to the server console and writes it to the server log. -* `text` is the printed and logged string. +* **text** is the printed and logged string. Argument handling @@ -81,8 +93,8 @@ args = et.ConcatArgs( index ) Returns all arguments beginning concatenated into a single string. -* `index` is the index of the first argument in the concatenated string. -* `args` is the returned concatenated string. +* **index** is the index of the first argument in the concatenated string. +* **args** is the returned concatenated string. argcount = et.trap_Argc() @@ -90,7 +102,7 @@ argcount = et.trap_Argc() Returns the number of command line arguments in the server command. -* `argcount` is the returned count of arguments. +* **argcount** is the returned count of arguments. arg = et.trap_Argv( index ) @@ -98,8 +110,8 @@ arg = et.trap_Argv( index ) Returns the contents of the command line argument. -* `index` is the index of the argument to return. -* `arg` is the returned argument. +* **index** is the index of the argument to return. +* **arg** is the returned argument. Cvars @@ -111,8 +123,8 @@ cvarvalue = et.trap_Cvar_Get( name ) Returns the value of the given cvar. -* `name` is the name of the cvar. -* `cvarvalue` is the returned string containing the value. If there is no cvar with the given name, the returning string has zero length. +* **name** is the name of the cvar. +* **cvarvalue** is the returned string containing the value. If there is no cvar with the given name, the returning string has zero length. et.trap_Cvar_Set( name, cvarvalue ) @@ -120,8 +132,8 @@ et.trap_Cvar_Set( name, cvarvalue ) Sets value to a cvar. -* `name` is the name of the cvar to set. -* `cvarvalue` is the new value for the cvar. +* **name** is the name of the cvar to set. +* **cvarvalue** is the new value for the cvar. Configstrings @@ -133,8 +145,8 @@ configstring = et.trap_GetConfigstring( index ) Returns content of the configstring index. -* `index` is the index of the configstring. See `et.CS_* constants `__ for possible values. -* `configstring` is the returned string containing the full configstring. +* **index** is the index of the configstring. See `et.CS_* constants `__ for possible values. +* **configstring** is the returned string containing the full configstring. et.trap_SetConfigstring( index, value ) @@ -142,8 +154,8 @@ et.trap_SetConfigstring( index, value ) Sets the full configstring. -* `index` is the configstring index. See `et.CS_* constants `__ for possible values. -* `value` is the full configstring to set. +* **index** is the configstring index. See `et.CS_* constants `__ for possible values. +* **value** is the full configstring to set. Server @@ -155,8 +167,8 @@ et.trap_SendConsoleCommand( when, command ) Sends command to the server console. -* `when` tells when the command is executed. See `et.EXEC_* constants `__ for possible values. -* `command` is the full command to execute. +* **when** tells when the command is executed. See `et.EXEC_* constants `__ for possible values. +* **command** is the full command to execute. Clients @@ -166,9 +178,9 @@ Clients 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. +Sends the command command to the client clientnum. If clientnum is `-1`, the command is broadcast to all clients. -.. tip:: See the `SendServerCommand `__ page for a detailed example usage of possible commands. +.. tip:: See `SendServerCommand() `__ for a detailed example usage of possible commands. et.trap_DropClient( clientnum, reason, bantime ) @@ -176,9 +188,9 @@ et.trap_DropClient( clientnum, reason, bantime ) Disconnects client from the server. -* `clientnum` is the slot number of the client. -* `reason` is the descriptive reason for the kick which is reported to the client. -* `bantime` is the length of the ban in seconds. +* **clientnum** is the slot number of the client. +* **reason** is the descriptive reason for the kick which is reported to the client. +* **bantime** is the length of the ban in seconds. clientnum = et.ClientNumberFromString( string ) @@ -186,8 +198,8 @@ clientnum = et.ClientNumberFromString( string ) Searches for one partial match with player name. -* `string` is a pattern to match against client names. -* `clientnum` is the returned client slot number if one match is found, otherwise `nil` is returned (none or more than one match). +* **string** is a pattern to match against client names. +* **clientnum** is the returned client slot number if one match is found, otherwise **nil** is returned (none or more than one match). et.G_Say( clientNum, mode, text ) @@ -195,9 +207,9 @@ et.G_Say( clientNum, mode, text ) Sends a chat command on behalf of client. -* `clientnum` is the slot number of the client. -* `mode` is the broadcast mode. See `et.SAY_* constants `__. -* `text` is the chat text. +* **clientnum** is the slot number of the client. +* **mode** is the broadcast mode. See `et.SAY_* constants `__. +* **text** is the chat text. et.MutePlayer( clientnum, duration, reason ) @@ -205,9 +217,9 @@ et.MutePlayer( clientnum, duration, reason ) Mutes the specified player. -* `clientnum` is the slot number of the client to mute. -* `duration` is the optional duration of the mute in seconds. -* `reason` is the optional reason of the mute. +* **clientnum** is the slot number of the client to mute. +* **duration** is the optional duration of the mute in seconds. +* **reason** is the optional reason of the mute. et.UnmutePlayer( clientnum ) @@ -215,7 +227,7 @@ et.UnmutePlayer( clientnum ) Unmutes the specified player. -* `clientnum` is the slot number of the client to unmute. +* **clientnum** is the slot number of the client to unmute. Userinfo @@ -227,8 +239,8 @@ userinfo = et.trap_GetUserinfo( clientNum ) Returns the userinfo string of a client. -* `clientnum` is the slot number of the client. -* `userinfo` is the returned string of the specified client. +* **clientnum** is the slot number of the client. +* **userinfo** is the returned string of the specified client. et.trap_SetUserinfo( clientnum, userinfo ) @@ -236,10 +248,10 @@ et.trap_SetUserinfo( clientnum, userinfo ) Sets the userinfo string of the client to the specified userinfo. -* `clientnum` is the slot number of the client. -* `userinfo` is the userinfo string that replaces the current userinfo. +* **clientnum** is the slot number of the client. +* **userinfo** is the userinfo string that replaces the current userinfo. -.. note:: The `et.ClientUserinfoChanged( clientnum ) <#et-clientuserinfochanged-clientnum>`__ function must be called after this function for the changes to take effect. +.. note:: The `et.ClientUserinfoChanged() <#et-clientuserinfochanged-clientnum>`__ function must be called after this function for the changes to take effect. et.ClientUserinfoChanged( clientnum ) @@ -247,7 +259,7 @@ et.ClientUserinfoChanged( clientnum ) Loads the new userinfo string of the client and sets the client settings to match it. -* `clientnum` is the slot number of the client. +* **clientnum** is the slot number of the client. String utility @@ -259,9 +271,9 @@ newinfostring = et.Info_RemoveKey( infostring, key ) Removes a key and its associated value from an infostring. -* `infostring` is the infostring from which to remove the key. -* `key` is the key to remove. -* `newinfostring` is the returned modified infostring without the key. +* **infostring** is the infostring from which to remove the key. +* **key** is the key to remove. +* **newinfostring** is the returned modified infostring without the key. newinfostring = et.Info_SetValueForKey( infostring, key, value ) @@ -269,10 +281,10 @@ newinfostring = et.Info_SetValueForKey( infostring, key, value ) Sets a value in an infostring. -* `infostring` is the original infostring. -* `key` is the key to set. -* `value` is the value to set to the key. If empty, the key is removed from the infostring. -* `newinfostring` is the returned modified infostring. +* **infostring** is the original infostring. +* **key** is the key to set. +* **value** is the value to set to the key. If empty, the key is removed from the infostring. +* **newinfostring** is the returned modified infostring. keyvalue = et.Info_ValueForKey( infostring, key ) @@ -280,9 +292,9 @@ keyvalue = et.Info_ValueForKey( infostring, key ) Returns a value from an infostring. -* `infostring` is the infostring from where to search the key. -* `key` is the key which value is returned. -* `keyvalue` is the returned value from the searched key. If key is not present in the infostring, an empty string is returned. +* **infostring** is the infostring from where to search the key. +* **key** is the key which value is returned. +* **keyvalue** is the returned value from the searched key. If key is not present in the infostring, an empty string is returned. cleanstring = et.Q_CleanStr( string ) @@ -290,8 +302,8 @@ cleanstring = et.Q_CleanStr( string ) Returns string stripped of all color codes and special characters. -* `string` is the string to clean. -* `cleanstring` is the returned cleaned string. +* **string** is the string to clean. +* **cleanstring** is the returned cleaned string. Filesystem @@ -303,9 +315,9 @@ fd, len = et.trap_FS_FOpenFile( filename, mode ) Opens a file in the local file system. -* `filename` is the name of the file to open. The file is opened under the current working directory and absolute paths will not work. -* `mode` is the access mode the file is opened. See `et.FS_* constants `__ for possible values. -* `fd, len` are returned descriptor of the file and the length of the file. On error, len returns -1. +* **filename** is the name of the file to open. The file is opened under the current working directory and absolute paths will not work. +* **mode** is the access mode the file is opened. See `et.FS_* constants `__ for possible values. +* **fd, len** are returned descriptor of the file and the length of the file. On error, len returns **-1**. filedata = et.trap_FS_Read( fd, count ) @@ -313,9 +325,9 @@ filedata = et.trap_FS_Read( fd, count ) Reads from an open file. -* `fd` is the descriptor of the file to read. -* `count` is the amount of bytes to read. -* `filedata` is the returned value that have the read bytes. +* **fd** is the descriptor of the file to read. +* **count** is the amount of bytes to read. +* **filedata** is the returned value that have the read bytes. count = et.trap_FS_Write( filedata, count, fd ) @@ -323,10 +335,10 @@ count = et.trap_FS_Write( filedata, count, fd ) Writes at the end of an open file. -* `filedata` is a block of bytes to write. -* `count` is the size of the block to write. -* `fd` is the descriptor of the file. -* `count` is the returned amount of bytes written to the file. +* **filedata** is a block of bytes to write. +* **count** is the size of the block to write. +* **fd** is the descriptor of the file. +* **count** is the returned amount of bytes written to the file. et.trap_FS_FCloseFile( fd ) @@ -334,7 +346,7 @@ et.trap_FS_FCloseFile( fd ) Closes an opened file. -* `fd` is the descriptor of the opened file. +* **fd** is the descriptor of the opened file. et.trap_FS_Rename( oldname, newname ) @@ -342,8 +354,8 @@ et.trap_FS_Rename( oldname, newname ) Renames a file in the local file system. -* `oldname` is the name of the file to rename. -* `newname` is the name the old file name is changed to. +* **oldname** is the name of the file to rename. +* **newname** is the name the old file name is changed to. filelist = et.trap_FS_GetFileList( dirname, fileextension ) @@ -351,9 +363,9 @@ filelist = et.trap_FS_GetFileList( dirname, fileextension ) Retrieves list of files from a directory. -* `dirname` is the name of the directory. -* `filextension` is the file extension of file names to retrieve. -* `filelist` is the returned array of file names strings. +* **dirname** is the name of the directory. +* **filextension** is the file extension of file names to retrieve. +* **filelist** is the returned array of file names strings. Indexes @@ -365,8 +377,8 @@ soundindex = et.G_SoundIndex( filename ) Returns the index to the searched soundfile. -* `filename` is the sound file name that is searched. -* `soundindex` is the returned string index that includes the filename or 0 if not found. +* **filename** is the sound file name that is searched. +* **soundindex** is the returned string index that includes the filename or 0 if not found. modelindex = et.G_ModelIndex( filename ) @@ -374,8 +386,8 @@ modelindex = et.G_ModelIndex( filename ) Returns the index to the searched model. -* `filename` is the name that is searched. -* `modelindex` is the returned string index that included the filename or 0 if not found. +* **filename** is the name that is searched. +* **modelindex** is the returned string index that included the filename or 0 if not found. Sound @@ -387,7 +399,7 @@ et.G_globalSound( sound ) Plays a sound to all connected clients. -* `sound` is the name of the sound to play. +* **sound** is the name of the sound to play. et.G_Sound( entnum, soundindex ) @@ -395,8 +407,8 @@ et.G_Sound( entnum, soundindex ) Plays a sound originating from position of an entity. -* `entnum` is the number of the entity which position is used as the sound origin. -* `soundindex` is the index of the sound that is played. +* **entnum** is the number of the entity which position is used as the sound origin. +* **soundindex** is the index of the sound that is played. et.G_ClientSound( clientnum, soundindex ) @@ -404,8 +416,8 @@ et.G_ClientSound( clientnum, soundindex ) Plays a sound originating from a client entity to the team members of that client. -* `clientnum` is the slot number of the connected player. -* `soundindex` is the index to the sound to play. +* **clientnum** is the slot number of the connected player. +* **soundindex** is the index to the sound to play. Miscellaneous @@ -417,7 +429,7 @@ milliseconds = et.trap_Milliseconds() Returns level time. -* `milliseconds` is the returned time in milliseconds. +* **milliseconds** is the returned time in milliseconds. success = et.isBitSet( bit, value ) @@ -425,8 +437,8 @@ success = et.isBitSet( bit, value ) Checks bit status of a bitmask value. -* `bit` is the checked bit. -* `value` is the bitmask value. +* **bit** is the checked bit. +* **value** is the bitmask value. Returns 1 if the bit is set in the bitmask value, and 0 if it is not. @@ -436,12 +448,12 @@ et.G_Damage( target, inflictor, attacker, damage, dflags, mod ) Damages target entity on behalf of the attacker entity. -* `target` is the entity number to damage. -* `inflictor` is the entity number that does the damage. -* `attacker` is the entity number that causes the `inflictor` entity to cause damage to `target`. -* `damage` is the amount of damage to inflict. -* `dflags` is the type of damage to inflict. See `Damage flags `__ for possible values. -* `mod` is the means of death. See `et.MOD_* constants `__ for possible values. +* **target** is the entity number to damage. +* **inflictor** is the entity number that does the damage. +* **attacker** is the entity number that causes the **inflictor** entity to cause damage to **target**. +* **damage** is the amount of damage to inflict. +* **dflags** is the type of damage to inflict. See `Damage bitflags `__ for possible values. +* **mod** is the means of death. See `et.MOD_* constants `__ for possible values. et.G_AddSkillPoints( clientNum, skill, points ) @@ -449,9 +461,9 @@ et.G_AddSkillPoints( clientNum, skill, points ) Adds points to the client's skill. -* `clientNum` is the slot number of the client. -* `skill` identifies the skill that the points are added to. See `Skill types `__ for possible values. -* `points` is the amount of points to add. +* **clientNum** is the slot number of the client. +* **skill** identifies the skill that the points are added to. See `Skill types `__ for possible values. +* **points** is the amount of points to add. et.G_LoseSkillPoints( clientNum, skill, points ) @@ -459,9 +471,9 @@ et.G_LoseSkillPoints( clientNum, skill, points ) Removes points to the client's skill. -* `clientNum` is the slot number of the client. -* `skill` identifies the skill that the points are removed from. See `Skill types `__ for possible values. -* `points` is the amount of points to remove. +* **clientNum** is the slot number of the client. +* **skill** identifies the skill that the points are removed from. See `Skill types `__ for possible values. +* **points** is the amount of points to remove. et.G_XP_Set ( clientNum , xp, skill, points ) @@ -469,10 +481,10 @@ et.G_XP_Set ( clientNum , xp, skill, points ) Sets XP of the client. -* `clientNum` is the slot number of the client. -* `xp` is the cumulative number of XP points. -* `skill` identifies the skill that the points are added to. See `Skill types `__ for possible values. -* `points` is the amount of points to add. +* **clientNum** is the slot number of the client. +* **xp** is the cumulative number of XP points. +* **skill** identifies the skill that the points are added to. See `Skill types `__ for possible values. +* **points** is the amount of points to add. et.G_ResetXP ( clientNum ) @@ -480,7 +492,7 @@ et.G_ResetXP ( clientNum ) Resets XP of the client. -* `clientNum` is the slot number of the client. +* **clientNum** is the slot number of the client. et.AddWeaponToPlayer( clientNum, weapon, ammo, ammoclip, setcurrent ) @@ -488,11 +500,11 @@ et.AddWeaponToPlayer( clientNum, weapon, ammo, ammoclip, setcurrent ) Adds a weapon to a client. -* `clientNum` is the slot number of the client. -* `weapon` is the weapon to add. See `et.WP_* constants `__ for possible values. -* `ammon` is the number of ammo to add. -* `ammoclip` is the number of ammo clip to add. -* `setcurrent` sets the weapon as current weapon if 1, or does not select it if 0. +* **clientNum** is the slot number of the client. +* **weapon** is the weapon to add. See `et.WP_* constants `__ for possible values. +* **ammon** is the number of ammo to add. +* **ammoclip** is the number of ammo clip to add. +* **setcurrent** sets the weapon as current weapon if 1, or does not select it if 0. et.RemoveWeaponFromPlayer( clientNum, weapon ) @@ -500,8 +512,8 @@ et.RemoveWeaponFromPlayer( clientNum, weapon ) Removes a weapon from a client. -* `clientNum` is the slot number of the client. -* `weapon` is the weapon to add. See `et.WP_* constants `__ for possible values. +* **clientNum** is the slot number of the client. +* **weapon** is the weapon to add. See `et.WP_* constants `__ for possible values. Entities @@ -513,8 +525,8 @@ entnum = et.G_CreateEntity( params ) Creates a new entity. -* `params` are mapscript parameters. -* `entnum` is the returned number of the new entity. +* **params** are mapscript parameters. +* **entnum** is the returned number of the new entity. et.G_DeleteEntity( params ) @@ -522,7 +534,7 @@ et.G_DeleteEntity( params ) Deletes an entity. -* `params` are mapscript parameters. +* **params** are mapscript parameters. entnum = et.G_TempEntity( origin, event ) @@ -530,9 +542,9 @@ entnum = et.G_TempEntity( origin, event ) Spawns a new temp entity to a location. -* `origin` is the location the temp entity is placed. -* `event` is the event type of the entity. See `Event types `__ for possible values. -* `entnum` is the returned the number of the new entity. +* **origin** is the location the temp entity is placed. +* **event** is the event type of the entity. See `Event types `__ for possible values. +* **entnum** is the returned the number of the new entity. et.G_FreeEntity( entnum ) @@ -540,7 +552,7 @@ et.G_FreeEntity( entnum ) Deletes an entity. -* `entnum` is the entity number. +* **entnum** is the entity number. count = et.G_EntitiesFree() @@ -548,7 +560,7 @@ count = et.G_EntitiesFree() Calculates all free entities. -* `count` is the returned number of free entities. +* **count** is the returned number of free entities. .. note:: Free client entities (slots) are not counted. @@ -558,8 +570,8 @@ et.G_SetEntState( entnum, newstate ) Sets an entity state. -* `entnum` is the entity number. -* `newstate` is the new entity state. +* **entnum** is the entity number. +* **newstate** is the new entity state. et.trap_LinkEntity( entnum ) @@ -567,7 +579,7 @@ et.trap_LinkEntity( entnum ) Links an entity. -* `entnum` is the entity number to link. +* **entnum** is the entity number to link. et.trap_UnlinkEntity( entnum ) @@ -575,7 +587,7 @@ et.trap_UnlinkEntity( entnum ) Unlinks an entity. -* `entnum` is the entity number to unlink. +* **entnum** is the entity number to unlink. spawnval = et.G_GetSpawnVar( entnum, key ) @@ -583,9 +595,9 @@ spawnval = et.G_GetSpawnVar( entnum, key ) Returns a value of a spawnvar. -* `entnum` is the entity number of the target. -* `key` is the key for the value to return. See `Entity fields `__ for possible values. -* `spawnval` is the returned spawn value. +* **entnum** is the entity number of the target. +* **key** is the key for the value to return. See `Entity fields `__ for possible values. +* **spawnval** is the returned spawn value. et.G_SetSpawnVar( entnum, key, value ) @@ -593,9 +605,9 @@ et.G_SetSpawnVar( entnum, key, value ) Sets spawn value to an entity. -* `entitynum` is the target entity. -* `key` is the key for the value. See `Entity fields `__ for possible values. -* `value` is the new value for the key. +* **entitynum** is the target entity. +* **key** is the key for the value. See `Entity fields `__ for possible values. +* **value** is the new value for the key. variable = et.gentity_get ( entnum, fieldname, arrayindex ) @@ -603,10 +615,10 @@ variable = et.gentity_get ( entnum, fieldname, arrayindex ) Returns a field value associated with an entity. -* `entnum` is the number of the entity. -* `fieldname` is the name of the field to get. See `Fields `__ for possible values. -* `arrayindex`, if present, specifies which element of an array entity field to get. -* `variable` is the returned field value. For NULL entities or clients, `nil` is returned. +* **entnum** is the number of the entity. +* **fieldname** is the name of the field to get. See `Fields `__ for possible values. +* **arrayindex**, if present, specifies which element of an array entity field to get. +* **variable** is the returned field value. For NULL entities or clients, **nil** is returned. .. note:: `arrayindex` is required when accessing array type fields. Array indexes start at 0. @@ -616,10 +628,10 @@ et.gentity_set( entnum, fieldname, arrayindex, value ) Sets a value in an entity. -* `entnum` is the entity number that is manipulated. -* `fieldname` is the name of the field to manipulate. See `Fields `__ for possible values. -* `value` is the new value. -* `arrayindex`, if present, specifies which element of an array entity field to set. +* **entnum** is the entity number that is manipulated. +* **fieldname** is the name of the field to manipulate. See `Fields `__ for possible values. +* **value** is the new value. +* **arrayindex**, if present, specifies which element of an array entity field to set. et.G_AddEvent( ent, event, eventparm ) @@ -627,9 +639,9 @@ et.G_AddEvent( ent, event, eventparm ) Adds an event to the entity event sequence. -* `ent` is the entity which event sequnce is handled. -* `event` is the event to add. -* `eventparm` is optional parameter for the event. +* **ent** is the entity which event sequnce is handled. +* **event** is the event to add. +* **eventparm** is optional parameter for the event. Shaders @@ -641,8 +653,8 @@ et.G_ShaderRemap( oldShader, newShader ) Remaps shader. -* `oldShader` is the old shader. -* `newShader` is the new shader. +* **oldShader** is the old shader. +* **newShader** is the new shader. et.G_ResetRemappedShaders() @@ -662,4 +674,4 @@ et.G_SetGlobalFog( params ) Sets global fog to a specific color and density. -* `params` are mapscript fog parameters. +* **params** are mapscript fog parameters. diff --git a/index.rst b/index.rst index 63baf46..6d3b23b 100644 --- a/index.rst +++ b/index.rst @@ -17,7 +17,7 @@ In some cases values can be returned to Legacy mod, whenever something is interc Through special functions, it is also possible to alter internal structures or entities (manipulate client XP, set and read cvars, remap shaders, etc.). For example, if a player dies the `et_Obituary( victim, killer, meansOfDeath ) `__ function is executed, and the Lua API allows you to manipulate and control this information. -If you want to see some ET-specific Lua examples, you can check the `ET Legacy Lua scripts `_ repository. +.. note:: Like qagame, Lua modules are unloaded and reloaded on `map_restart` and map changes, which means that all global variables and other information is lost. Persistent data can be stored in `cvars `__, external `files `__ or `database `__. Implementation @@ -44,10 +44,3 @@ Contents misc database sample - - -Indices and tables ------------------- - -* :ref:`genindex` - diff --git a/misc.rst b/misc.rst index 978824b..3cee651 100644 --- a/misc.rst +++ b/misc.rst @@ -2,12 +2,239 @@ Miscellaneous ============= - -Damage flags +Configstring ============ -`Damage flags` are bitflags that controls how damage is inflicted. -The following bits are available. +Configstrings are strings (often in the form of a set of `key\\value` pairs) set on the server and automatically sent to each client. +They can be accessed with the `Configstring `__ and `String utility `__ functions. + +.. tip:: A group of related configstrings usually only have a symbolic name for the first value, with a number added to get a particular value. For example, to access a user `CS_PLAYERS` configstring you must use `et.trap_GetConfigstring(et.CS_PLAYERS + slotNumber)`. + +See `et.CS_* constants `__ for available configstrings. + +Here is the detailed content of the user **CS_PLAYERS** configstring: + +=== =========================== =================================================== +Key Value Description +=== =========================== =================================================== +n pers.netname Nickname +t sess.sessionTeam Team +c sess.playerType Class +lc sess.latchPlayerType Latched class +r sess.rank Rank +m medalStr Medals +s skillStr Skills +dn disguiseClientNum Disguised covert ops +w sess.playerWeapon Weapon +lw sess.latchPlayerWeapon Latched primary weapon +sw sess.latchPlayerWeapon2 Latched secondary weapon +mu sess.muted Muted +ref sess.referee Referee +sr sess.mu - 3 * sess.sigma Skill rating +u sess.uci GeoIP `ISO 3166-1 `_ country code +=== =========================== =================================================== + + +Userinfo +======== + + +Userinfo strings are strings set on clients for server processing. +They can be accessed with the `Userinfo `__ functions. + + +===================== ================================ ================================================== +Key Example Value Description +===================== ================================ ================================================== +cg_etVersion Enemy Territory, ET 2.60b Mod name, ET version +cg_uinfo 12 0 100 Client settings [cg_autoreload/cg_autoactivate/cg_predictitems] [cl_timenudge] [cl_maxpackets] +g_password none Server password +cl_guid 0123456789ABCDEF0123456789ABCDEF GUID +cl_wwwDownload 1 Missing files downloading toggle +name ETLPlayer Nickname +rate 2500 Rate setting +snaps 20 Snaps setting +protocol 84 Game protocol +qport 4834 Randomly chosen as startup +challenge -686256943 Random 31 bit integer +ip 192.168.123.45:27960 IP and port +===================== ================================ ================================================== + +.. note:: The userinfo string of bots only includes the `cl_guid`, `name`, `rate`, `snap` and `ip` keys/values. + + +SendServerCommand +================= + +`et.trap_SendServerCommand() `__ is used to send a command from the server to one or more clients. + +The first argument is the slot number of the client the command is sent to. If it's equal to **-1**, the command is broadcast to all clients. + +The following commands can be issued: + + +Printing +-------- + + +Print a message to the client's console:: + + "print \"Message\n\"" + +Print a message to the client's annoucement area and console:: + + "cpm \"Message\n\"" + +Print a message to the center of the client's screen:: + + "cp \"Message\n\"" + +Print a message to the client's console and writes it to the statsdump file:: + + "sc \"Message\n\"" + + +Chatting +-------- + +Print a message as a global chat message on behalf of the specified client:: + + "chat ClientNum \"Message\"" + +Print a message as a team chat message on behalf of the specified client:: + + "tchat ClientNum \"Message\" X-Location Y-Location Z-Location" + +* The **X,Y,Z-Location**'s are optional parameters that represent the client's location. + +.. Print a message as a fireteam chat message on behalf of the specified client: +.. +.. "bchat ClientNum \"Message\" X-Location Y-Location Z-Location" +.. +.. * The X,Y,Z-Location's are optional parameters that represent the client's location. + +Print a message as a global chat message via rcon (qsay command):: + + "chat \"Message\"" + + +Voice Chat +---------- + + +Send a global voice chat on behalf of the specified client:: + + "vchat VoiceOnly ClientNum 50 Vsay-String Vsay-Number \"Custom-Message\"". + +* **VoiceOnly** prints a global chat message on behalf of ClientNum if set to **0**, or only play the sound if set to **1**. +* **Vsay-String** is the global voice chat message. +* **Vsay-Number** is the vsay number of Vsay as listed in the .voice files. It is by default random, but can be set by the player by passing parameters to the vsay command (`/vsay `). +* **Custom-Message** is by default empty (\"\"). If set, it prints the message in the chat area. + +Send a team voice chat on behalf of the specified client:: + + "vtchat VoiceOnly ClientNum 50 Vsay-String X-Location Y-Location Z-Location Vsay-Number \"Custom-Message\"" + +* **VoiceOnly** prints a team chat message on behalf of ClientNum if set to **0**, or only play the sound if set to **1**. +* **Vsay-String** is the team voice chat message. +* **Vsay-Number** is the vsay number of Vsay as listed in the .voice files. It is by default random, but can be set by the player by passing parameters to the vsay command (`/vsay `). +* The **X,Y,Z-Location**'s are optional parameters that represent the client's location. +* **Custom-Message** is by default empty (\"\"). If set, it prints the message in the chat area. + +Send a fireteam voice chat on behalf of the specified client:: + + "vtchat VoiceOnly ClientNum 50 Fireteam-String X-Location Y-Location Z-Location Vsay-Number \"Custom-Message\"" + +* **VoiceOnly** prints a fireteam chat message on behalf of ClientNum if set to **0**, or only play the sound if set to **1**. +* **Fireteam-String** is the fireteam voice chat message. +* **Vsay-Number** is the vsay number of Vsay as listed in the .voice files. It is by default random, but can be set by the player by passing parameters to the vsay command (`/vsay `). +* The **X,Y,Z-Location**'s are optional parameters that represent the client's location. +* **Custom-Message** is by default empty (\"\"). If set, it prints the message in the chat area.m contaning the message +if VoiceOnly is 1 it will only do the sound but not the message + + +Fireteam +-------- + + +Show a fireteam invation message to the client:: + + "application Number" + +* if **Number** is **> -1**, the "Accept ...'s application to join your fireteam?" message is displayed. In this case, **Number** is the ClientNum of the applying client. +* if **Number** is **-1**, the "Your application has been submitted" message is displayed. +* if **Number** is **-2**, the "Your application failed" message is displayed. +* if **Number** is **-3**, the "Your application has been approved" message is displayed. +* if **Number** is **-4**, the "Your application reply has been sent" message is displayed. + +Show a fireteam proposition message to the client:: + + "proposition Number Number2" + +* if **Number** is **> -1**, the "Accept ...'s proposition to invite ... to your fireteam?" message is displayed. In this case, **Number** is the ClientNum of the proposed client, and **Number2** is the ClientNum of the proposing player. +* if **Number** is **-1**, the "Your proposition has been submitted" message is displayed. +* if **Number** is **-2**, the "Your proposition was rejected" message is displayed. +* if **Number** is **-3**, the "Your proposition was accepted" message is displayed. +* if **Number** is **-4**, the "Your proposition reply has been sent" message is displayed. +* **Number2** is an optional parameter only used when **Number** > **-1**. + +Show a fireteam invitation message to the client:: + + "invitation Number" + +* if **Number** is **> -1**, the "Accept ..'s invitation to join your fireteam?" message is displayed. In this case, **Number** is the ClientNum of the applying client. +* if **Number** is **-1**, the "Your invitation has been submitted" message is displayed. +* if **Number** is **-2**, the "Your invitation rejected" message is displayed. +* if **Number** is **-3**, the "Your invitation was accepted" message is displayed. +* if **Number** is **-4**, the "Your invitation reply has been sent" message is displayed. + + +Others +------ + + +Show the complaint vote message to the client:: + + "complaint Number" + +* if **Number** is **> 1**, the "File complaint against ... for team-killing?" message is displayed. In this case, **Number** is the ClientNum of the teamkilling player. +* if **Number** is **-1**, the "Complaint filed" message is displayed. +* if **Number** is **-2**, the "Complaint dismissed" message is displayed. + + +Set the client game selected spawnpoint:: + + "setspawnpt Number" + +* **Number** is the selected spawnpoint. + +Disconnect the client with a "Server disconnected" message:: + + "disconnect \"reason\"" + +* **reason** is an optional parameter to show a reason after "Server disconnected". + +.. note:: Use `et.trap_DropClient() `__ instead. + +Set a client's configstring to a string:: + + "cs Number \"String\"" + +* **String** is the new configstring string. + +.. note:: Use `et.trap_SetUserinfo() `__ instead. + +Replace any texture:: + + "remapShader \"OldShader\" \"NewShader\" #" + +* **OldShader** is the old shader. +* **NewShader** is the new shader. +* **#** is the Timeoffset, which currently should be left as 0. + + +Damage bitflags +=============== ============================= ================== ================================== diff --git a/sample.rst b/sample.rst new file mode 100644 index 0000000..064654a --- /dev/null +++ b/sample.rst @@ -0,0 +1,378 @@ +=========== +Sample code +=========== + +.. tip:: If you want to see some ET-specific Lua examples, you can check the `ET Legacy Lua scripts `_ repository. + + +General +======= + + +General example:: + + --[[ + Lua Example ETLegacy + --]] + + function et_InitGame(levelTime,randomSeed,restart) + et.RegisterModname("Lua Example") -- Registering the modname. + et.G_Print("Lua Loaded!\n") -- Printing out that the lua module has been loaded! + end + + function et_ClientCommand(clientNum, command) + local mapname = et.trap_Cvar_Get( "mapname" ) -- local varible storing the map name + if string.lower(command) == "mapname" then -- checking if the command is /mapname + et.trap_SendServerCommand(clientNum, "chat \"Current Map:"..mapname.." \n\"") -- printing out the map name to the client + end + return 1 + end + + +This code does nothing useful besides demonstrate and exercise the Lua API:: + + -- printf wrapper + function et.G_Printf(...) + et.G_Print(string.format(unpack(arg))) + end + + + -- test some of the supported etpro lua functions + function test_lua_functions() + et.trap_Cvar_Set( "bla1", "bla2" ) + et.G_Printf( "sv_hostname [%s]\n", et.trap_Cvar_Get( "sv_hostname" ) ) + et.G_Printf( "configstring 1 [%s] \n", et.trap_GetConfigstring( 1 ) ) + et.trap_SetConfigstring( 4, "yadda test" ) + et.G_Printf( "configstring 4 [%s]\n", et.trap_GetConfigstring( 4 ) ) + et.trap_SendConsoleCommand( et.EXEC_APPEND, "cvarlist *charge*\n" ) + et.trap_SendServerCommand( -1, "print \"Yadda yadda\"" ) + et.G_Printf( "gentity[1022].classname = [%s]", et.gentity_get( 1022, "classname" ) ) + end + + + -- called when game inits + function et_InitGame( levelTime, randomSeed, restart ) + et.G_Printf( "et_InitGame [%d] [%d] [%d]\n", levelTime, randomSeed, restart ) + et.RegisterModname( "bani qagame " .. et.FindSelf() ) + -- test_lua_functions() + end + + + -- called every server frame + function et_RunFrame( levelTime ) + if math.mod( levelTime, 1000 ) == 0 then + -- et.G_Printf( et_RunFrame [%d]\n", levelTime ) + end + end + + + -- called for every clientcommand + -- return 1 if intercepted, 0 if passthrough + function et_ClientCommand( clientNum, cmd ) + et.G_Printf( "et_ClientCommand: [%d] [%s]\n", et.trap_Argc(), cmd ) + return 0 + end + + + -- called for every consolecommand + -- return 1 if intercepted, 0 if passthrough + function et_ConsoleCommand() + et.G_Printf( "et_ConsoleCommand: [%s] [%s]\n", et.trap_Argc(), et.trap_Argv(0) ) + if et.trap_Argv(0) == "listmods" then + i = 1 + repeat + modname, signature = et.FindMod( i ) + if modname and signature then + et.G_Printf( "vm slot [%d] name [%s] signature [%s]\n", i, modname, signature ) + et.IPCSend( i, "hello" ) + end + i = i + 1 + until modname == nil or signature == nil + return 1 + end + return 0 + end + + + -- called when we receive an IPC from another VM + function et_IPCReceive( vmnumber, message ) + et.G_Printf( "IPCReceive [%d] from [%d] message [%s]\n", et.FindSelf(), vmnumber, message ) + end + + + -- called for every ClientConnect + function et_ClientConnect( clientNum, firstTime, isBot ) + et.G_Printf( "et_ClientConnect: [%d] [%d] [%d]\n", clientNum, firstTime, isBot ) + -- return "go away" + return nil + end + + + -- called for every ClientDisconnect + function et_ClientDisconnect( clientNum ) + et.G_Printf( "et_ClientDisconnect: [%d]\n", clientNum ) + end + + + -- called for every ClientBegin + function et_ClientBegin( clientNum ) + et.G_Printf( "et_ClientBegin: [%d]\n", clientNum ) + end + + + -- called for every ClientUserinfoChanged + function et_ClientUserinfoChanged( clientNum ) + et.G_Printf( "et_ClientUserinfoChanged: [%d] = [%s]\n", clientNum, et.trap_GetUserinfo( clientNum ) ) + end + + + -- called for every trap_Printf + function et_Print( text ) + -- et.G_Printf( "et_Print [%s]", text ) + end + + +Configstring +============ + +Example:: + + -- get the name of client #3 using configstrings + local cs = et.trap_GetConfigstring(et.CS_PLAYERS + 3) + local name = et.Info_ValueForKey(cs, "n") + + +Inter Process Communication (IPC) +================================= + +Example scripts illustrating communication between these scripts using the `et.IPCSend() `__ and `et_IPCReceive() `__ functions. + + +Sender +------ + +Example of sender module:: + + --[[ + ipcdemo-admin.lua + --]] + + local IPCQueue = {} + local AdminGUIDs = { + -- name, guid, level + { "Vetinari", "ABCDEF1234567890ABCDEF1234567890", 5 }, + { "Havelock", "1234567890ABCDEF1234567890ABCDEF", 3 } + } + + function et_InitGame(levelTime, randomSeed, restart) + et.RegisterModname("ipcdemo-admin.lua") + end + + function et_IPCReceive(vm, msg) + local level + local junk1, junk2, id = string.find(msg, "IsAdmin:%s+(%d+)") + if id ~= nil then + id = tonumber(id) + guid = et.Info_ValueForKey(et.trap_GetUserinfo(id), "cl_guid") + level = table.foreach(AdminGUIDs, + function(i, admin) + if admin[2] == guid then + return(admin[3]) + end + end + ) + if level == nil then + level = 0 + end + table.insert(IPCQueue, { vm, level, id }) + end + end + + function et_RunFrame(lvltime) + table.foreach(IPCQueue, + function(i, queue) + local ok = et.IPCSend(queue[1], + string.format("IsAdmin: %d %d", queue[2], queue[3])) + if ok ~= 1 then + local mod, cksum = et.FindMod(queue[1]) + et.G_Print(string.format("ipcdemo-admin: IPCSend to %s (vm: %d) failed", mod, queue[1])) + end + end + ) + IPCQueue = {} + end + + +Receiver +-------- + +Example of receiver module:: + + --[[ + ipcdemo-cmd.lua + --]] + + local admin_vm = -1 + local CommandQueue = {} + + function et_InitGame(levelTime, randomSeed, restart) + local mod = "" + local sig = "" + local i = 1 + while mod ~= nil do + mod, sig = et.FindMod(i) + if string.find(mod, "^ipcdemo-admin.lua") == 1 then + admin_vm = i + mod = nil + end + i = i + 1 + end + if admin_vm == -1 then + et.G_Print("ipcdemo-cmd.lua: Could not find vm number for ipcdemo-admin.lua") + end + et.RegisterModname("ipcdemo-cmd.lua") + end + + function et_IPCReceive(vm, msg) + if vm == admin_vm then + local junk1,junk2,level,id = string.find(msg, "IsAdmin:%s+(%d+)%s+(%d)") + if level ~= nil and id ~= nil then + runAction(tonumber(id), tonumber(level)) + end + end + end + + function runAction(id, level) + local done = table.foreach(CommandQueue, + function(i, queue) + if id == queue[1] then + if queue[2] <= level then + if queue[4] == nil then + et.trap_SendConsoleCommand(et.EXEC_INSERT, queue[3]) + else + et.trap_SendConsoleCommand(et.EXEC_INSERT, + string.format("%s %s", queue[3], queue[4])) + end + end + return(i) + end + end + ) + if done ~= nil then + table.remove(CommandQueue, done) + end + end + + function et_ClientCommand(id, command) + local arg0 = et.trap_Argv(0) + local arg1 = et.trap_Argv(1) + if arg0 == "say" then + if arg1 == "!axis" then + -- id, lvl, cmd, argument + queueCommand(id, 4, "forceteam r", id) + elseif arg1 == "!allies" then + queueCommand(id, 4, "forceteam b", id) + elseif arg1 == "!shuffle" then + queueCommand(id, 3, "shuffleteamsxp_norestart", nil) + end + end + return(0) + end + + function queueCommand(id, level, cmd, argument) + if admin_vm ~= -1 then + local ok = et.IPCSend(admin_vm, string.format("IsAdmin: %d", id)) + if ok ~= 1 then + et.G_Print("ipcdemo-cmd: IPCSend to ipcdemo-admin failed") + else + table.insert(CommandQueue, { id, level, cmd, argument }) + end + end + end + + +Database +======== + + +Exemple using LuaSQL. + + +Basic use +--------- + +Here is an example of the basic use of the library:: + + --[[ + LuaSQL demo + --]] + + -- load driver + local driver = require "luasql.sqlite3" + -- create environment object + env = assert (driver.sqlite3()) + -- connect to data source + con = assert (env:connect("luasql-test")) + -- reset our table + res = con:execute"DROP TABLE people" + res = assert (con:execute[[ + CREATE TABLE people( + name varchar(50), + email varchar(50) + ) + ]]) + -- add a few elements + list = { + { name="Jose das Couves", email="jose@couves.com", }, + { name="Manoel Joaquim", email="manoel.joaquim@cafundo.com", }, + { name="Maria das Dores", email="maria@dores.com", }, + } + for i, p in pairs (list) do + res = assert (con:execute(string.format([[ + INSERT INTO people + VALUES ('%s', '%s')]], p.name, p.email) + )) + end + -- retrieve a cursor + cur = assert (con:execute"SELECT name, email from people") + -- print all rows, the rows will be indexed by field names + row = cur:fetch ({}, "a") + while row do + et.G_Print("Name:" .. row.name .. ", E-mail: " .. row.email .."\n") + -- reusing the table of results + row = cur:fetch (row, "a") + end + -- close everything + cur:close() -- already closed because all the result set was consumed + con:close() + env:close() + + +And the output of this script should be:: + + Name: Jose das Couves, E-mail: jose@couves.com + Name: Manoel Joaquim, E-mail: manoel.joaquim@cafundo.com + Name: Maria das Dores, E-mail: maria@dores.com + + +Iterator +-------- + +Here is how to create an iterator over the result of a SELECT query:: + + function rows (connection, sql_statement) + local cursor = assert (connection:execute (sql_statement)) + return function () + return cursor:fetch() + end + end + +Here is how the iterator is used:: + + env = assert (require"luasql.mysql".mysql()) + con = assert (env:connect"my_db") + for id, name, address in rows (con, "select * from contacts") do + print (string.format ("%s: %s", name, address)) + end + +Obviously, the code above only works if there is a table called contacts with the columns id, name and address in this order. At the end of the loop the cursor will be automatically closed by the driver. diff --git a/standard.rst b/standard.rst index 19ee255..be30e4a 100644 --- a/standard.rst +++ b/standard.rst @@ -2,7 +2,7 @@ Standard libraries ================== -The following standard Lua libraries are initialized by default and available to Legacy Lua scripts: +The following **standard Lua libraries** are initialized by default and are available to scripts: * `basic `_ * `string `_