Lua/Metatables

Metatables are an advanced feature of Lua that can be used to define custom operations for variables. Each variable has a set of metatable events that are called in certain situations, usually when a particular operator is used on the variable. For example, when the length operator is used on a variable var (e.g., #var), the metatable event __len is called. A variable can have a metatable applied to it, which is a table where the keys are the metatable events and the values are metamethods that will be executed when the corresponding metatable event is called. Metamethods are usually functions, although in some cases tables or other types of values are used. Applying metamethods to metatable events is similar to how functions can be bound to hooks. For example, if you want to control what happens when #var is called, you can write a metamethod, create a metatable for var and assign your metamethod to the metatable's __len key. Then, whenever #var is called, your metamethod is executed. For more information on how metatables work, consult the Metamethods Tutorial on the lua-users wiki.

Usage

Metatables are created like normal tables, with the keys being the names of the metatable events that you want to use:

local metatable = {__event = value}

local metatable = {__event1 = value1, __event2 = value2}

Individual events can be modified afterwards:

metatable.__event = newvalue

You can also assign the metamethods to other variables outside of the metatable:

local var = metatable.__event

If the metamethod of an event is a function, it may be called as such:

metatable.__event(arguments)

setmetatable is used to apply a metatable to a table:

local myTable = {}
local metatable = {__event = value}

setmetatable(myTable, metatable)

Alternatively the metatable can be applied implicitly:

local myTable = {}

setmetatable(myTable, {__event = value})

Because setmetatable returns the table that was supplied to it (in this example, {} is used as a dummy table), the metatable can also be created and applied in the same line:

local myTable = setmetatable({}, {__event = value})

getmetatable can be used to retrieve the metatable for a table or other variable:

local metatable = getmetatable(myTable)

getmetatable can retrieve the metatable for any type of variable, not just tables. It will return nil if no metatable is set. Note that getmetatable returns a direct reference to the metatable rather than just a copy – if this reference is modified, it will directly affect the metatable for the variable itself!

By contrast, setmetatable can only be used on tables. This means that it is not possible to create new metatables for other types of variables, including userdata. However, strings and userdata already have metatables applied to them in SRB2, which you can retrieve and modify with getmetatable.

If a variable's metatable has the metatable event __metatable set, the metatable cannot be retrieved or modified – instead, getmetatable will return the value of __metatable, while setmetatable will print an error in the console.

List of events

For any examples below, a represents the variable the metatable events are applied to. Binary operations such as addition or subtraction use a second variable, which will be represented by b. In the "Type of value" column, functions are written in the format returntype function(args), where returntype of the type of value returned by the function and args is the list of arguments taken by the function.

Name	Event	Type of value	Further details
Table indexes
`__index`	Accessing a table at a key that does not exist (`a.key` or `a["key"]`, value is `nil`)	`any function(a, key)` or table	`__index` is highly useful for allowing a table to fall back on another table if a key doesn't exist in the first. This can be use to simulate object inheritance and object-oriented programming in Lua (see this page for more info): If a table `a` falls back on a table `b` for keys that don't exist in `a`, it will appear as if `a` inherits those keys from `b`. The value for a key `key` that is inherited from `b` can be overridden in `a` by assigning a new value to `a.key`, which will prevent the fallback from occurring. As a reminder, `a.key` is the same as `a["key"]`, i.e., `key` from `a.key` is a variable of type string in this situation. If a function is used as the value for `__index`, that function will be executed and its return value will be returned as the value of the `a.key` call. If a table `table` is used as the value for `__index`, it will be used as the fallback table. If `a.key` does not exist, `table.key` will be used instead. If `table.key` does not exist either and `table` has its own `__index` metamethod, this metamethod will be called. This can be used to create a chain of tables falling back on each other.
`__newindex`	Assigning a value to a new key in a table (`a.key = value` or `a["key"] = value`, old value is `nil`)	`void function(a, key, value)` or table	When simulating inheritance, as described for `__index` above, `__newindex` can be used to ensure that if the key whose value is changed is inherited from a fallback table, the value is changed in that fallback table. If a function is used as the value for `__newindex`, that function will be executed with `value` as a parameter instead of assigning `value` to `a.key`. If a table `table` is used as the value for `__newindex`, it will be used as the fallback table. If `a.key` does not exist, the value will be assigned to `table.key` instead. However, if `table.key` already exists and `table` has its own `__usedindex` metamethod, that metamethod will be called instead. If `table.key` does not exist and `table` has its own `__newindex` metamethod, this metamethod will be called.
`__usedindex`	Assigning a value to an existing key in a table (`a.key = value` or `a["key"] = value`, old value is not `nil`)	`void function(a, key, value)` or table	This metamethod is only usable for tables. If a function is used as the value for `__usedindex`, that function will be executed with `value` as a parameter instead of assigning `value` to `a.key`. If a table `table` is used as the value for `__usedindex`, it will be used as the fallback table. Instead of assigning the value to `a.key`, it will be assigned to `table.key` instead. However, if `table.key` already exists and `table` has its own `__usedindex` metamethod, that metamethod will be called instead. If `table.key` does not exist and `table` has its own `__newindex` metamethod, this metamethod will be called.
Arithmetic
`__add`	Addition (`a + b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__sub`	Subtraction (`a - b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__mul`	Multiplication (`a * b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__div`	Division (`a / b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__mod`	Modulus (`a % b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__pow`	Exponentation (`a ^ b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__unm`	Unary negation ( `-a` )	`any function(a)`
`__len`	Length ( `#a` )	`any function(a)`
Comparison
`__eq`	Equals check (`a == b`)	`any function(a, b)`	`a` and `b` must share the same metamethod for `__eq` for the function to be run.
`__lt`	Less-than (`a < b`) or Greater-than (`b > a`)	`any function(a, b)`	Greater-than comparisons are done by flipping the order of `a` and `b` so it is treated as a less-than operation. `a` and `b` must share the same metamethod for `__lt` for the function to be run. `__lt` may also be run for less-than operations if a `__le` metamethod does not exist for both `a` and `b` (or they do not share the same `__le` metamethod). In this case, `a <= b` is checked as `b > a`, and `b >= a` as `a < b`.
`__le`	Less-than-or-equals (`a <= b`) or Greater-than-or-equals (`b >= a`)	`any function(a, b)`	Greater-than-or-equals comparisons are done by flipping the order of `a` and `b` so it is treated as a less-than-or-equals operation. `a` and `b` must share the same metamethod for `__le` for the function to be run.
Bitwise operations
`__and`	Bitwise AND (`a & b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__or`	Bitwise OR (`a \| b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__xor`	Bitwise XOR (`a ^^ b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__shl`	Left shift (`a << b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__shr`	Right shift (`a >> b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__not`	Bitwise NOT ( `~a` )	`any function(a)`
Miscellaneous
`__concat`	Concatenation (`a..b`)	`any function(a, b)`	This operation can be performed even when the other value does not share the same metamethod or does not have one. If `a` does not have a metamethod, `b`'s metamethod is used instead. `a` is always the first argument in the function, and `b` the second, even if `b`'s metamethod is the one called.
`__tostring`	Conversion to string using `tostring`	`string function(a)`	Lua will pass `a` itself to the function set for `__tostring`. The function should return a string as the result of the conversion.
`__call`	Calling as a function (`a([args])`)	`any function(a, [args])`	This is used to treat `a` like a function, even if it is not one, when followed by parantheses as shown. `a` and any arguments passed to it will be passed along to the function set for `__call`, and the return value of this function will be the return value of the `a([args])` call.
`__gc`	Garbage collection for userdata	`void function(a)`	This metamethod is only usable for userdata. This metamethod is called before the garbage collector collects the userdata, making it possible to define additional garbage collection behavior.
`__mode`	Weak references handling	string	This metamethod is only usable for tables. This controls whether the keys or values of the table are weak references, depending on whether certain letters are present in the string: "k" – Keys are marked as weak "v" – Values are marked as weak.
`__metatable`	Metatable protection	any	This prevents the metatable for `a` from being accessed and modified: `getmetatable` will return the value set for `__metatable` instead of the metatable itself. `setmetatable` will print an error in the console instead of setting a new metatable.

List of existing metatables

This article or section is outdated and has not been fully updated to reflect the current version of SRB2.

Please help the Wiki by correcting or removing any misinformation, as well as adding any new information to the page.

SRB2's userdata types and global tables are in fact simply empty tables whose entire functionality comes through the implementation of their metatable events, mainly __index for accessing elements and __newindex for modifying them. The metatables and events applied to them are listed here.

Name/Type of variable	Metamethods set
Userdata
(`mobj_t`)	`__index` → `mobj.var` `__newindex` → `mobj.var = value`
(`player_t`)	`__index` → `player.var` `__newindex` → `player.var = value` `__len` → `#player`
`player.powers` (`player` is `player_t`)	`__index` → `player.powers[pw_powername]` `__newindex` → `player.powers[pw_powername] = value` `__len` → `#player.powers`
(`ticcmd_t`)	`__index` → `ticcmd.var` `__newindex` → `ticcmd.var = value`
(`skin_t`)	`__index` → `skin.var` `__newindex` → warning message to state `skin_t` cannot be modified `__len` → `#skin`
`skin.soundsid` (`skin` is `skin_t`)	`__index` → `skin.soundsid[SKSNAME]` `__len` → `#skin.soundsid`
(`mobjinfo_t`)	`__index` → `info.var` `__newindex` → `info.var = value` `__len` → `#info`
(`state_t`)	`__index` → `info.var` `__newindex` → `info.var = value` `__len` → `#info`
(`sfxinfo_t`)	`__index` → `info.var` `__newindex` → `info.var = value` `__len` → `#info`
(`hudinfo_t`)	`__index` → `info.var` `__newindex` → `info.var = value` `__len` → `#info`
(`mapheader_t`)	`__index` → `mapheader.var` `__len` → `#mapheader`
(`mapthing_t`)	`__index` → `mthing.var` `__newindex` → `mthing.var = value`
(`sector_t`)	`__index` → `sector.var` `__newindex` → `sector.var = value` `__len` → `#sector`
`sector.lines` (`sector` is `sector_t`)	`__index` → `sector.lines[i]` `__len` → `#sector.lines`
(`subsector_t`)	`__index` → `subsector.var` `__len` → `#subsector`
(`line_t`)	`__index` → `line.var` `__len` → `#line`
`line.sidenum` (`line` is `line_t`)	`__index` → `line.sidenum[i]`
(`side_t`)	`__index` → `side.var` `__newindex` → `side.var = value` `__len` → `#side`
(`vertex_t`)	`__index` → `vertex.var` `__len` → `#vertex`
(`ffloor_t`)	`__index` → `ffloor.var` `__newindex` → `ffloor.var = value`
(`camera_t`)	`__index` → `camera.var`
(`consvar_t`)	`__index` → `consvar.var`
(`patch_t`)	`__index` → `patch.var` `__newindex` → warning message to state `patch_t` cannot be modified
(`colormap`)	`__index` → warning message to state `colormap` is not a struct
Tables
`mobjinfo`	`__index` → `mobjinfo[MT_NAME]` `__newindex` → `mobjinfo[MT_NAME] = { }` `__len` → `#mobjinfo`
`states`	`__index` → `states[S_NAME]` `__newindex` → `states[S_NAME] = { }` `__len` → `#states`
`S_sfx` or `sfxinfo`	`__index` → `sfxinfo[sfx_name]` `__newindex` → `sfxinfo[sfx_name] = { }` `__len` → `#sfxinfo`
`sprnames`	`__index` → `sprnames[SPR_NAME]` or `sprnames["NAME"]` `__len` → `#sprnames`
`players`	`__index` → `players[i]` `__len` → `#players`
`skins`	`__index` → `skins[i]` or `skins["name"]` `__len` → `#skins`
`mapthings`	`__index` → `mapthings[i]` `__len` → `#mapthings`
`vertexes`	`__index` → `vertexes[i]` `__len` → `#vertexes`
`lines`	`__index` → `lines[i]` `__len` → `#lines`
`sides`	`__index` → `sides[i]` `__len` → `#sides`
`subsectors`	`__index` → `subsectors[i]` `__len` → `#subsectors`
`sectors`	`__index` → `sectors[i]` `__len` → `#sectors`
`mapheaderinfo`	`__index` → `mapheaderinfo[i]` `__len` → `#mapheaderinfo`
`hudinfo`	`__index` → `hudinfo[HUD_NAME]` `__len` → `#hudinfo`
Miscellaneous
(string)	`__add` → Concatenation using "+" (`string1"+variable+"string2`) `__index` → String library functions, called as `stringvar.function([args])`

	Lua	[view]
Language features	Syntax • Metatables
SRB2 data	Actions • Constants • Functions • Global variables • Hooks • Userdata structures
SRB2Kart data	Kart Userdata structures • Kart Functions • Kart Hooks • Kart Global Variables and Constants
Tutorials	Freeslots and Object resources • Custom player ability