mod.RegisterMod

Name

mod.RegisterMod – register a Lua mod

Synopsis

mod.RegisterMod{
  name = "my_mod",        -- required
  version = "1.0.2",      -- optional
  keep_env = false        -- optional, not usually used
}

Description

The parameter is a table with the following fields:

name (string, required) – The mod's identifier. Must be unique.
version (string, optional) – Version number in dotted format, e.g. "1.0" or "2.3.1".
keep_env (boolean, optional) – See "Notes" below. Not usually used.

After mod.RegisterMod is called (and assuming keep_env was not used), the current environment (_ENV) is redirected to a special namespace created specifically for this mod. This means that you can create global variables without fear of name clashes with other mods, and these globals will then be accessible to other mods using mod.GetRegisteredMod or require. See "Examples" below.

Return Value

The function returns the (newly created) namespace table for the mod being registered. However, this can usually be ignored, given that mod.RegisterMod replaces the global environment (_ENV) with this table anyway. (But if you use keep_env then you may need this return value.)

Errors

Errors can be raised if:

The first argument is not a table.
The name field is missing, or is not a string.
The name is already registered to another module.
The version is neither nil nor a valid version string. (Valid version strings consist only of numeric components separated by dots, and components are not allowed to be empty.)
mod.RegisterMod is called while the game is running (it should only be called from init.lua during module startup).

Notes

For those who want to know the technical details, mod.RegisterMod does the following:

Creates a new namespace table.
Sets an __index metamethod on the new table, which points to _G. (This means that existing global names, such as kts or require, can still be accessed, providing that these names are not overwritten by the module code.)
Stores this namespace table (and the mod's version string) in an internal cache, indexed by module name – this allows the same table to be returned again later, to other mods, in mod.GetRegisteredMod or require calls.
If keep_env is false or nil, replaces the caller's _ENV with the namespace table.
Returns the namespace table.

If keep_env is true, the caller's _ENV is left pointing at the normal global Lua namespace – however, writes through this _ENV will fail with a "read-only environment" error. (This is to prevent accidental writes to the global namespace.) Writing directly to fields in the _G table will still work (this allows mod code to write to the global namespace, if desired, although this is not recommended).

Examples

Imagine you want to create a new module, "skeletons", that provides some new monster types. Your init.lua might contain this:

-- At the beginning of init.lua:

mod.RegisterMod{name = "skeletons", version = "1.0"}

m_skeleton1 = kts.MonsterType{...}
m_skeleton2 = kts.MonsterType{...}

To use this mod, another module might call

local S = mod.GetRegisteredMod("skeletons")

local S = require("skeletons")

for example. The skeleton monsters would now be available as S.m_skeleton1 and S.m_skeleton2.

If you prefer to keep things more explicit, then you can use the keep_env option as follows:

-- At the beginning of init.lua:

local MyMod = mod.RegisterMod{
  name = "skeletons",
  version = "1.0",
  keep_env = true
}

Then, instead of creating global variables, you would add entries to the MyMod table, like this:

MyMod.m_skeleton1 = kts.MonsterType{...}
MyMod.m_skeleton2 = kts.MonsterType{...}

Which method you prefer is really just a matter of style, but using keep_env = false (the default) is probably easier.