User:Monster Iestyn/Lua
Lua is a scripting language that can be used by SRB2. It allows users to write custom game logic without editing the game's source code, in addition to many of the capabilities SOC also has. For these reasons, Lua scripting is considered a more powerful method of modification available to SRB2 compared to SOC. However, Lua does not supercede SOC completely – there are still a number of aspects of modding that can only be configured through SOC. A file created in the Lua language is commonly known as a "Lua script".
The name "Lua" itself is from the Portuguese for moon; it should not be referred to as "LUA", as it is not an acronym.
About
The version of Lua used by SRB2 is Lua 5.1. The reference manual for Lua 5.1 can be found here: [1]
For users new to the Lua language, it is highly recommended to read the Lua Tutorial on the lua-users wiki to learn the basics and syntax of Lua.
Changes from vanilla Lua
SRB2's implementation of Lua has a few changes from most implementations of the language. Some of the most important changes are listed and detailed below:
Numbers
While vanilla Lua uses floating-point doubles for all of its math, SRB2's implementation uses purely signed integers. Variables that require greater precision than whole numbers are usually dealt with in multiples of FRACUNIT
to accommodate. Fixed math functions such as FixedMul()
and FixedDiv()
exist to assist with math in these situations.
Vanilla Lua can interpret nil
as false
in some situations; SRB2's implementation additionally allows 0 to be interpreted as the same thing.
Standard Libraries
The only standard libraries loaded are:
- The basic library (including the coroutine manipulation sub-library)
- The string manipulation library
- The table manipulation library
The remaining libraries have not been included due to safety concerns, or are redundant/unneeded for SRB2 Lua scripting purposes.
Bitwise operations
Lua in SRB2 supports all standard bitwise operations: AND, OR, XOR, NOT, and left/right bit-shifts. Note that, since Lua already uses the ^
(caret) symbol for exponentation, XOR is represented as two caret symbols in succession (^^
).
Operation | Symbol(s) |
---|---|
AND | &
|
OR | |
|
XOR | ^^
|
NOT | ~ !
|
Left Shift | <<
|
Right Shift | >>
|
Alternative syntax
Lua in SRB2 supports alternative syntax for several operations, some of which exist to more closely resemble the syntax of the C programming language:
Syntax | Lua syntax | Alt syntax |
---|---|---|
Bitwise NOT | ~
|
!
|
Not equals | ~=
|
!=
|
Short comment | -- comment
|
// comment
|
Long comment | --[[ comment ]] --[=[ comment ]=] --[==[ comment ]==] etc |
/* comment */
|
String concatenation | "string"..var.."string"
|
"string"+var+"string" "string\$var\string"
|
Pseudo-numbers
Pseudo-numbers are a new concept added to Lua in SRB2; these are used to simplify assigning new values to a variable (or variables) relatively to its old value. The old value for a variable is represented by the dollar symbol ($
). An example of a pseudo-number in use is shown below:
// without pseudo-numbers
variable = variable + 1
// with pseudo-numbers
variable = $ + 1
This concept also extends to multiple variable assignment:
// without pseudo-numbers
var1, var2 = var1+5, var2-10
// with pseudo-numbers
var1, var2 = $+5, $-10
Note that, in the above example, $
is the value of var1
for var1
's new value, and then var2
for var2
's own new value.
Numbers can be placed after the $
symbol if needed, for identification of the individual variables – $1
, $2
, $3
and so on then represent the first, second, third and further variables in an assignment. This is particularly useful for the ability to swap the values of two variables, for example:
var1, var2 = $2, $1
Keywords
New keywords have been added, to support a more C-like syntax in Lua scripts:
- "
continue
" and "break N
" keywords are supported in loops . do ... end
blocks are converted intofunction() ... end
blocks when passed as an argument or assigned as a variable.- "
do
" afterfor
andwhile
, and "then
" afterif
have been rendered optional.
String literals
Other types of string literals besides decimal code input (\nnn
) have been added:
- Hexadecimal:
\xnn
or\xnnnn
(2 or 4 digits must be used) - Unicode (UTF-8-encoded):
\unnnn
or\unnnnnn
(4 or 6 digits must be used)
Metatables
Several new metatable hook types have been added:
__usedindex
metatable hook, for when an existing index is assigned a new value.- Bitwise operations:
__and
(&
)__or
(|
)__xor
(^^
)__shl
(<<
)__shr
(>>
)__not
(~)
Special characters
Certain ASCII characters have special effects for text printed using the functions print
or CONS_Printf
:
Chat text
Decimal | Hexadecimal | Usage |
---|---|---|
3 | 0x03
|
Plays a chat beep sound |
4 | 0x04
|
Plays a chat beep sound and colors text yellow |
Text colors
- See also: SOC > Custom colors
Decimal | Hexadecimal | Usage |
---|---|---|
128 | 0x80
|
White/Reset |
129 | 0x81
|
Purple |
130 | 0x82
|
Yellow |
131 | 0x83
|
Green |
132 | 0x84
|
Blue |
133 | 0x85
|
Red |
134 | 0x86
|
Gray |
135 | 0x87
|
Orange |
Script execution
The most common way to load Lua scripts is to add them to a WAD file as a text lump. Lumps with the name prefix LUA_
are recognized as Lua scripts by SRB2 and are loaded automatically upon loading the WAD file, in the order that they are found in the file. Lua scripts with other names are not loaded automatically, and there is no method of loading them after the WAD file containing them has been added. It is important to note that all Lua scripts in a WAD file will be loaded before any SOC lumps also within the file, regardless of lump ordering. This means that any changes to the game in the WAD file's SOC lumps will not be recognised in the file's Lua scripts.
Alternatively, Lua scripts can be stored as standalone files with the file ending .lua
. The console command ADDFILE
can be used to load standalone Lua script files.
Global variables in SRB2
As well as the global variables that come with Lua (e.g.: _G
and _VERSION
), SRB2 allows access to a number of its own pre-defined global variables for use in Lua scripting.
Types of userdata in SRB2
SRB2 allows for userdata variables of many types in Lua scripts. The recognised types of userdata are listed below for reference – note that the type names have no actual relevance to Lua scripts themselves.
General
Type name | Accessibility | Allows custom variables | Description |
---|---|---|---|
mobj_t | Read + Write | Yes | This userdata type represents an Object.
This is not to be confused with an Object type (e.g. |
player_t | Read + Write | Yes | This userdata type represents the properties of a player that are independent of the player Object, which may carry over between maps. This is not to be confused with mobj_t or vice versa.
|
ticcmd_t | Read + Write | No | This userdata type represents a player's current button information, i.e. what buttons are being pressed currently. |
skin_t | Read-only | No | This userdata type represents a skin – i.e. the properties for a character set in the S_SKIN .
|
SOC
Type name | Accessibility | Allows custom variables | Description |
---|---|---|---|
mobjinfo_t | Read + Write | Yes | This userdata type represents the SOC properties of an Object type definition. |
state_t | Read + Write | No | This userdata type represents the SOC properties of a State. |
sfxinfo_t | Read + Write | No | This userdata type represents the SOC properties of a Sound. |
hudinfo_t | Read + Write | No | This userdata type represents the SOC properties of a HUD item. |
Map
Type name | Accessibility | Allows custom variables | Description |
---|---|---|---|
mapthing_t | Read + Write | No | This userdata type represents a Thing. |
sector_t | Read + Write | No | This userdata type represents a sector. |
subsector_t | Read-only | No | This userdata type represents a sub-sector. |
line_t | Read-only | No | This userdata type represents a linedef. |
side_t | Read-only | No | This userdata type represents a sidedef. |
vertex_t | Read-only | No | This userdata type represents a vertex. |
ffloor_t | Read + Write | No | This userdata type represents an FOF. |
Miscellaneous
Type name | Accessibility | Allows custom variables | Description |
---|---|---|---|
mapheader_t | Read-only | SOC-only | This userdata type represents the properties of a level header. |
camera_t | Read-only | No | This userdata type represents a player's camera. |
consvar_t | Read-only | No | This userdata type represents a console variable. |
patch_t | Read-only | No | This userdata type allows access to the properties of a graphics patch (see the HUD library). |
Functions in SRB2
Hooks
Actions
See also
- Constants: A list of constants which can be used in Lua.