etlegacy/etlegacy-lua-docs
0
0
Fork 0
mirror of https://github.com/etlegacy/etlegacy-lua-docs.git synced 2024-11-10 06:51:49 +00:00
Code Issues Projects Releases Packages Wiki Activity

expanded misc, added database and sample code

Browse source
This commit is contained in:
Remy Marquis 2016-09-17 18:57:29 +02:00
parent c765028a27
commit 4acb084595
11 changed files with 1324 additions and 415 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
callbacks.rst
View file

@ -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 <damages.html#damage-flags>`__ that controls how damage is inflicted.
* `meansOfDeath` is the `means of death <damages.html#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 <misc.html#damage-bitflags>`__ for possible values.
* **meansOfDeath** is the means of death. See `et.MOD_* constants <constants.html#mod-constants>`__ for possible values.
et_SpawnEntitiesFromString()

2
commands.rst
View file

@ -2,7 +2,7 @@
Commands
========
Here are all available Lua commands.
**Commands** shows information about currently loaded scripts.
Server commands

2
constants.rst
View file

@ -2,7 +2,7 @@
Constants
=========
Here is a list of all the Lua constants.
**Constants** are strings set on the server.
CS constants

6
cvars.rst
View file

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

205
database.rst Normal file
View file

@ -0,0 +1,205 @@
========
Database
========
Both the Legacy mod and the ET:Legacy engine are built-in with `SQLite3 <https://www.sqlite.org/>`_ database support. The engine allows to execute SQL statement directly in console, while the Legacy mod has access through `LuaSQL <https://keplerproject.github.io/luasql/>`_.
.. tip:: See the `Database <sample.html#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 <https://dev.etlegacy.com/projects/etlegacy/wiki/List_of_Cvars#db_-Additional>`_ cvar is set to **1**.
To save this in memory database to disk use the **saveDB** console command. See also the `db_url <https://dev.etlegacy.com/projects/etlegacy/wiki/List_of_Cvars#db_-Additional>`_ 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 <database.html#connection-objects>`__.
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 <database.html#env-connect-sourcename-username-password>`__ 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 <database.html#cursor-objects>`__ 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 <database.html#conn-execute-statement>`__ 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 <database.html#environment-objects>`__.
Returns a `connection object <database.html#connection-objects>`__.
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 <http://www.sqlite.org/c3ref/mprintf.html>`_.
Returns the **escaped string**.

536
fields.rst
View file

@ -2,7 +2,7 @@
Fields
======
Here are all available Lua fields supported by `et.gentity_get() <functions.html#variable-et-gentity-get-entnum-fieldname-arrayindex>`__ and `et.gentity_set() <functions.html#et-gentity-set-entnum-fieldname-arrayindex-value>`__ functions.
**Fields** are entity parameters supported by `et.gentity_get() <functions.html#variable-et-gentity-get-entnum-fieldname-arrayindex>`__ and `et.gentity_set() <functions.html#et-gentity-set-entnum-fieldname-arrayindex-value>`__ 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() <functions.html#variable-et-gentity-get-entnum-fieldname-arrayindex>`__ and `et.gentity_set() <functions.html#et-gentity-set-entnum-fieldname-arrayindex-value>`__ 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 = <number>, --- int
trTime = <number>, -- int
trType = <number>, -- see below for allowed values
trBase = <vec3_t>, -- vec3, as described above
trDelta = <vec3_t> -- 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`.

300
functions.rst
View file

@ -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() <sample.html>`__ callback.
.. important:: The mod receiving message must have an `et_IPCReceive() <functions.html#et-ipcreceive-vmnumber-message>`__ callback.
.. tip:: See the `Inter Process Communication (IPC) <sample.html>`__ 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() <functions.html#success-et-ipcsend-vmnumber-message>`__ 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 <cvars.html#lua-modules>`__ cvar, otherwise the receiver module cannot find it.
.. tip:: See the `Inter Process Communication (IPC) <sample.html#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 <constants.html#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 <constants.html#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 <constants.html#cs-constants>`__ for possible values.
* `value` is the full configstring to set.
* **index** is the configstring index. See `et.CS_* constants <constants.html#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 <constants.html#exec-constants>`__ for possible values.
* `command` is the full command to execute.
* **when** tells when the command is executed. See `et.EXEC_* constants <constants.html#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 <sample.html>`__ page for a detailed example usage of possible commands.
.. tip:: See `SendServerCommand() <misc.html#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 <constants.html#say-constants>`__.
* `text` is the chat text.
* **clientnum** is the slot number of the client.
* **mode** is the broadcast mode. See `et.SAY_* constants <constants.html#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 <constants.html#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 <constants.html#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 <misc.html#damage-flags>`__ for possible values.
* `mod` is the means of death. See `et.MOD_* constants <constants.html#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 <misc.html#damage-bitflags>`__ for possible values.
* **mod** is the means of death. See `et.MOD_* constants <constants.html#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 <misc.html#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 <misc.html#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 <misc.html#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 <misc.html#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 <misc.html#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 <misc.html#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 <constants.html#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 <constants.html#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 <constants.html#wp-constants>`__ for possible values.
* **clientNum** is the slot number of the client.
* **weapon** is the weapon to add. See `et.WP_* constants <constants.html#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 <misc.html#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 <misc.html#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 <fields.html#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 <fields.html#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 <fields.html#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 <fields.html#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 <fields.html>`__ 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 <fields.html>`__ 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 <fields.html>`__ 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 <fields.html>`__ 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.

9
index.rst
View file

@ -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 ) <callbacks.html#et-obituary-target-attacker-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 <https://github.com/etlegacy/etlegacy-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 <functions.html#cvars>`__, external `files <functions.html#filesystem>`__ or `database <database.html>`__.
Implementation
@ -44,10 +44,3 @@ Contents
misc
database
sample
Indices and tables
------------------
* :ref:`genindex`

235
misc.rst
View file

@ -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 <functions.html#configstrings>`__ and `String utility <functions.html#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 <constants.html#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 <https://en.wikipedia.org/wiki/ISO_3166-1>`_ country code
=== =========================== ===================================================
Userinfo
========
Userinfo strings are strings set on clients for server processing.
They can be accessed with the `Userinfo <functions.html#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() <functions.html#et-trap-sendservercommand-clientnum-command>`__ 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 <Vsay-Number> <Vsay-String>`).
* **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 <Vsay-Number> <Vsay-String>`).
* 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 <Vsay-Number> <Vsay-String>`).
* 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() <functions.html#et-trap-dropclient-clientnum-reason-bantime>`__ instead.
Set a client's configstring to a string::
"cs Number \"String\""
* **String** is the new configstring string.
.. note:: Use `et.trap_SetUserinfo() <functions.html#et-trap-setuserinfo-clientnum-userinfo>`__ 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
===============
============================= ================== ==================================

378
sample.rst Normal file
View file

@ -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 <https://github.com/etlegacy/etlegacy-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() <functions.html#success-et-ipcsend-vmnumber-message>`__ and `et_IPCReceive() <functions.html#et-ipcreceive-vmnumber-message>`__ 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.

2
standard.rst
View file

@ -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 <http://www.lua.org/manual/5.3/manual.html#6.1>`_
* `string <http://www.lua.org/manual/5.3/manual.html#6.4>`_