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: These are later used by methods of the mod object, for example when loading a file or registering an item.

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:

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.