Automatic Boilerplate Generation
Perhaps the single most important capability of Et Cetera is to automatically generate all of the basic structure and functionality of a mod. This is achieved through a new higher-level API that wraps an entire mod and provides it with default functions and data values.
MOD REGISTRATION
To get started with Etc automation, the first thing you should to is add the following function call to your mod:etc.register_mod('mod_name', aliases...)
Where
mod_name
is a string containing the canonical name of your mod (the name used in mod.conf
) and aliases
are any number of strings that serve as additional names your mod and its' content can be referred to by; for example the canonical name of Etc is etcetera
and it has the alias etc
.For a mod named
myfirstmod
that you wish to be abbreviated both as mymod
and mfm
, you would use the following statement:etc.register_mod('myfirstmod', 'mymod', 'mfm')
Usually, the call to
etc.register_mod
will be the very first thing in your mod's init.lua
. Calling it will create a new global table with the same name as your mod, which will act as the general-purpose entry point for most things your mod will do. The function will also return this same table, so modname = etc.register_mod 'modname'
is equivalent to simply calling the function in case you'd like to be extra explicit about it.
Once registered, your mod will be initialized with a number of basic data values that are likely to be useful:
<mod>.name
is the original canonical name of your mod;<mod>.path
is the path to your mod's root folder, as returned byminetest.get_modpath(mod.name)
;<mod>.aliases
is an array containing all the aliases originally passed toetc.register_mod
.
MOD COMPONENTS
Having a global mod table is well and good, but it isn't useful without some default methods and perhaps a way to create new ones. Mod components exist for this purpose. They are values that are added to every mod registered with Etc, included those registered before the component was created. These values are not stored in the mod table itself, but are added to a shared metatable that allows them all to share component's values.When a component is overriden on a specific mod table, it is not overriden on the others. This allows setting defaults that can be changed easily without affecting the defaults of other mods.
etcetera.register_mod_component
Usage:etcetera.register_mod_component(name, data)
Create a new component available to ALL mods with the key name
name
and the value data
.
Predefined Components
The following components are provided by Etc and are always available.
load_script
Usage:mod: load_script(filepath)
Load a script relative to the
/scripts
folder in your mod's root directory. filepath
is the path from the scripts folder to the script file including the filename, with or without the file extension .lua
. Note that you can specify a file outside the scripts folder using ../filename
syntax, however this is NOT recommended as it is bad practice and is not guaranteed to work on all systems.
load_module
Usage:mod: load_module(filepath, ...)
Similar to
load_script
but relative to /scripts/modules
, and takes into account a set of dependencies (...
) when loading. The dependencies are formatted the same way as those used by etc.check_depends, and if any are unsatisfied the module will not load. Additionally, if an engine setting called <modname>.load_module_<filepath>
is defined and set to false
the module will not load.
translate
Usage:mod: translate(text, ...)
Equivalent to
minetest.get_translator(mod.name)(text, ...)
.
gettext
Usage:mod: gettext(text, text_type)
The gettext function used by item/node registration methods. When called by these methods,
text_type
will be set to either displayname
, description
, or statblock
.
register_node
Usage:mod: register_node(item_id, definition)
Register a node called
<mod.name>:<item_id>
with the given definition, and register aliases for it with all of the defined aliases for the mod (ex. <mod.aliases[1]>:<item_id>
...).This function uses
displayname
, description
, and stats
as special values rather than the simple description
field used by the engine. They will be passed through the mod: gettext
function (see above) and then concatenated in the following order:displayname
if present; description
if present preceded by a newline; each entry in the stats
array preceded by a newline, then a tab, then a bullet point (unicode U+2022
), then a space.The tooltip background color will be set to
mod.background_color
, which defaults to #22242d
.
register_item
Usage:mod: register_item(item_id, definition)
Same as
mod: register_node
, but registers a craftitem rather than a node.
register_tool
Usage:mod: register_tool(item_id, definition)
Same as
mod: register_node
, but registers a tool rather than a node.
inherit_item
Usage:mod: inherit_item(parent_item, item_id, new_definition)
Register a new item called
<mod.name>:<item_id>
with the definition of parent_item
merged with new_definition
. parent_item
can be an item name from any mod or an 'item prototype' from a registered Etc mod (see below).
register_item_prototype
Usage:mod: register_item_prototype(proto_id, base_definition)
Create an 'item prototype', which can be inherited from as if it were an item via
inherit_item(<mod.name>:<proto_id>
, ...)
but is not registered as an item itself. Can be used to efficiently create numerous variants of an item or node. The base_definition
must contain a type
field, which is a string containing one of the following:
node
tool
craftitem
craft
(short for craftitem)
Related Helpers
The following functions are not components, but perform related tasks.
smart_override_item
Usage:etc.smart_override_item(item, redef)
The same as
minetest.override_item
, but deep-merges values in the new definition with those of the same name in the old definition if both are tables. For example, minetest.override_item('default:dirt', {groups = {falling_node = 1}})
will remove all the previously defined groups in the item definition, whereas etc.smart_override_item('default:dirt', {groups = {falling_node = 1}})
will add the falling_node
group while keeping the rest intact.
register_rawitem_transformer
Usage:etc.register_rawitem_transformer(func)
Applies a function
func(mod, itemname, itemdef)
to every item registered with mod: register_node
, mod: register_item
, and mod: register_tool
. This is used, for example, to handle the displayname
, description
, and stats
special fields of items registered with these functions. The transformer will apply to every item registered with these functions by every registered Etc mod after the transformer is defined.
register_node_transformer
Usage:etc.register_node_transformer(func)
The same as
etc.register_rawitem_transformer
, but applies only to mod: register_node
.
register_item_transformer
Usage:etc.register_item_transformer(func)
The same as
etc.register_rawitem_transformer
, but applies only to mod: register_item
.
register_tool_transformer
Usage:etc.register_tool_transformer(func)
The same as
etc.register_rawitem_transformer
, but applies only to mod: register_tool
.