added intro, cvars, commands, callbacks

callbacks.rst

@@ -0,0 +1,201 @@
+=========
+Callbacks
+=========
+
+Here is a list of all the Lua callbacks of Legacy mod.
+
+
+qagame execution
+================
+
+
+et_InitGame( levelTime, randomSeed, restart )
+---------------------------------------------
+
+Called when qagame initializes.
+
+* `levelTime` is the current level time in milliseconds.
+* `randomSeed` is a number that can be used to seed random number generators.
+* `restart` indicates if et_InitGame() is being called due to a `map_restart` (1) or not (0).
+
+
+et_ShutdownGame( restart )
+--------------------------
+
+Called when qagame shuts down.
+
+* `restart` indicates if the shutdown is being called due to a `map_restart` (1) or not (0).
+
+
+et_RunFrame( levelTime )
+------------------------
+
+Called when qagame runs a server frame.
+
+* `levelTime` is the current level time in milliseconds.
+
+
+et_Quit()
+---------
+
+Called when Legacy unloads the mod.
+
+The mod should close all open filedescriptors and perform all cleanup.
+
+
+Client management
+=================
+
+
+rejectreason = et_ClientConnect( clientNum, firstTime, isBot )
+--------------------------------------------------------------
+
+Called when a client attempts to connect to the server.
+
+* `clientNum` is the client slot id.
+* `firstTime` indicates if this is a new connection (1) or a reconnection (0).
+* `isBot` indicates if the client is a bot (1) or not (0).
+
+If the mod accepts the connection, it should return `nil`. Otherwise, the mod should return a string describing the reason the client connection was rejected.
+
+
+et_ClientDisconnect( clientNum )
+--------------------------------
+
+Called when a client disconnects.
+
+* `clientNum` is the client slot id.
+
+
+et_ClientBegin( clientNum )
+---------------------------
+
+Called when a client begins (becomes active, and enters the gameworld).
+
+* `clientNum` is the client slot id.
+
+
+et_ClientUserinfoChanged( clientNum )
+-------------------------------------
+
+Called when a client's Userinfo string has changed.
+
+* `clientNum` is the client slot id.
+
+.. 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 )
+---------------------------------------------------------------
+
+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).
+
+
+Commands
+========
+
+
+intercepted = et_ClientCommand( clientNum, command )
+----------------------------------------------------
+
+Called when a command is received from a client.
+
+* `clientNum` is the client slot id.
+* `command` is the command.
+
+The mod should return 1 if the command was intercepted by the mod, and 0 if the command was ignored by the mod and should be passed through to the server (and other mods in the chain).
+
+.. tip:: The actual command can be accessed through the argument handling functions, as seen in the `Sample Code <sample.html>`__.
+
+
+intercepted = et_ConsoleCommand()
+---------------------------------
+
+Called when a command is entered on the server console.
+
+The mod should return 1 if the command was intercepted by the mod, and 0 if the command was ignored by the mod and should be passed through to the server (and other mods in the chain).
+
+.. tip:: The actual command can be accessed through the argument handling functions, as seen in the `Sample Code <sample.html>`__.
+
+
+XP
+==
+
+
+et_UpgradeSkill( clientNum, skill )
+-----------------------------
+
+Called when a client gets a skill upgrade.
+
+* `clientNum` is the client slot.
+* `skill` is the skill number.
+
+Return -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough.
+
+
+et_SetPlayerSkill( clientNum, skill )
+-------------------------------
+
+Called when a client skill is set.
+
+* `clientNum` is the client slot.
+* `skill` is the skill number.
+
+Return -1 to override (abort) the qagame function, anything else to "passthrough". Callback may modify skills (or do anything else it wants) during passthrough.
+
+
+Miscellaneous
+=============
+
+
+et_IPCReceive( vmnumber, message )
+----------------------------------
+
+Called when another mod sends an et.IPCSend() message to this mod.
+
+* `vmnumber` is the VM slot number of the sender.
+* `message` is the message.
+
+
+et_Print( text )
+----------------
+
+Called whenever the server or qagame prints a string to the console.
+
+
+.. warning:: Text may contain a player name and their chat message. This makes it very easy to spoof.
+
+             DO NOT TRUST STRINGS OBTAINED IN THIS WAY!
+
+
+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.
+
+
+et_Damage( target, attaker, 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.
+
+
+et_SpawnEntitiesFromString()
+----------------------------
+
+Called when an entity definition is parsed to spawn gentities.

commands.rst

@@ -0,0 +1,32 @@
+========
+Commands
+========
+
+Here is a list of all the Lua commands of Legacy mod.
+
+
+Server commands
+===============
+
+lua_status
+-----------
+
+Lists all currently loaded Lua modules.
+
+
+lua_api
+-------
+
+Lists all exported functions and constants available to modders.
+
+
+Client commands
+===============
+
+
+lua_status
+-----------
+
+Lists all currently loaded Lua modules.
+
+.. note:: Lua mods cannot override this client command.

cvars.rst

@@ -0,0 +1,24 @@
+=====
+Cvars
+=====
+
+Here is a list of all the Lua cvars of Legacy mod.
+
+
+.. note:: Changing either cvar will cause all currently loaded modules to quit and be unloaded until the next `map_restart`.
+
+
+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.

index.rst

@@ -8,9 +8,9 @@ Legacy Lua API
 
 Welcome to the Legacy Lua API's documentation!
 
-The **Legacy mod** is the default mod shipped with `ET: Legacy <http://www.etlegecy.com>`_. It supports server-side modifications via the `Lua <http://www.lua.org/>`_ scripting language.
+The **Legacy mod** is the default mod shipped with `ET: Legacy <http://www.etlegacy.com>`_. It supports server-side modifications via the `Lua <http://www.lua.org/>`_ scripting language.
 
-If present, the embedded Lua 5.3 interpreter will load user-defined scripts from the Legacy directory. It also provides an "et" library of function calls for Lua that allow access to the server engine, and provides callbacks so a server side mod may trigger on specific server events.
+If present, the embedded **Lua 5.3** interpreter will load user-defined scripts from the Legacy directory. It also provides an "et" library of function calls for Lua that allow access to the server engine, and provides callbacks so a server side mod may trigger on specific server events.
 
 For more information about Lua, check out the `Reference Manual <http://www.lua.org/manual/5.3/>`_, the online edition of the book `Programming in Lua <http://www.lua.org/pil/>`_ or the `Lua-users wiki <http://lua-users.org/wiki/>`_.
 
@@ -21,7 +21,7 @@ Contents
 --------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    intro
    cvars
@@ -31,12 +31,12 @@ Contents
    fields
    constants
    database
+   sample
 
 
 Indices and tables
 ------------------
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

intro.rst

@@ -0,0 +1,33 @@
+============
+Introduction
+============
+
+Legacy's Lua API is the interface for communication between Lua and Legacy mod.
+
+The basic idea for this Lua API is event-management. After a certain event, the lua-interaction-code in Legacy executes a predefined function, with additional predefined arguments.
+
+For example, if a player dies the `et_Obituary( victim, killer, meansOfDeath ) <callbacks.html#et-obituary-victim-killer-meansofdeath>`__ function is executed. The Lua API allows you to manipulate and control this information.
+
+In some cases you can also return a value to Legacy, whenever you intercepted something (i.e. a command), and prevent Legacy to handle it further.
+
+This way, you can easily define new commands, or alter existing ones. Through special functions, it is also possible to alter Legacy's internal structures or Entities (remap shaders, manipulate client XP, set and read cvars, etc.).
+
+
+Implementation
+==============
+
+Legacy's Lua API follows mostly the `ETPub <http://www.etpub.org/>`_ implementation with partial code of the `NoQuarter <http://shitstorm.org/noquarter/>`_ implemention. The ETPub implementation being built to be compatible with `ETPro's Lua <http://wolfwiki.anime.net/index.php/Lua_Mod_API>`_, all scripts written in ETPro's documentation should be valid and more or less compatible with Legacy mod's Lua API.
+
+.. important:: As Legacy uses the newer Lua 5.3, you might want to check the *Incompatibilities with the Previous Version* sections of the `Lua 5.1 <https://www.lua.org/manual/5.1/manual.html#7>`_, `Lua 5.2 <https://www.lua.org/manual/5.2/manual.html#8>`_, and `Lua 5.3 <https://www.lua.org/manual/5.3/manual.html#8>`_ manuals while porting scripts written for other mods.
+
+Standard libraries
+==================
+
+The following standard Lua libraries are initialized by default and available to Legacy Lua 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>`_
+* `table <http://www.lua.org/manual/5.3/manual.html#6.6>`_
+* `math <http://www.lua.org/manual/5.3/manual.html#6.7>`_
+* `i/o <http://www.lua.org/manual/5.3/manual.html#6.8>`_
+* `os <http://www.lua.org/manual/5.3/manual.html#6.9>`_ (available features vary depending on your OS)