Mod interoperability

This page is aimed towards modders and lists a couple of mods and conventions which are known in the community.

The main goal is to improve interoperability between mods and reduce code duplication. Often it is better to use existing APIs rather than trying to reinvent the wheel to reduce code duplication, redundancy and overall chaos. Of course, deciding to not use existing APIs may still be aviable choice if they do not suit your needs.

This page will be a permanent work of progress since there are many different mods out there.

Mods

One way to ensure interoperability is to know what other mods exist out there. This section will show you mods which you can use to achieve a particular task or point you to mods which might need some “special treatment” for maximum interoperability.

Basics

This section is about mods and practices which apply to almost every mod.

Internationalization

Minetest itself can be translated (mostly the main menu), but Minetest does not support direct translation for mods. This feature has been requested in issue 2270. In the meanwhile, a few mods have emerged to enable internationalization. Note, however, that mod-based internationalization is rather limited. A major problem with the existing mods is that all clients connected to a server will always see the language used by the server, rather than the language used by the client.

These mods are known to enable internationalizaion (only use one mod at once):

• Internationalization Library [intllib]

TODO: Add more mods, there are more mods for this.

General gameplay

Status effects

If you want to add temporary or permanent status effects for players (such as poisoning), you can use this:

• Player Effects [playereffects]
• Player Monoids [player_monoids]

Mobs

Mobs are non-player creatures to interact with the world, they may be peaceful or attack on sight. Usually they are based on entities. Minetest does not support mods natively, but if you still want to add custom mods, you have various mods to choose from, each of them with somewhat different priorities. Most APIs are not compatible which each other, so in general you should only use the API which suits your needs in the best way. If you want to create a subgame, you have to be very careful with interoperability.

Note: Only mods with their own dedicated API are listed. Note: There are multiple mods with the short name “mobs”, you can only have one of these mods installed at once.

• Creatures Mob Engine [cme]
• Mobs Redo [mobs]

TODO: Add more API mods here

See also: Mobs page on the Community Wiki

Protection

“Protection” refers to a way to own a certain area in the world and preventing other players to make any changes in this area.

This section needs to be finished. Notes for general interoperability requirements/recommendations should be added by someone more experienced.

Other gameplay concepts

• Achievements [awards]: API for adding your own achievements
• Mana [mana]: Adds a new player attribute (mana), could be used as resource for magic spells, weapons, tools, etc.
• Treasurer [treasurer]: API for randomly selecting a treasure out of a pool of previously registered treasures

Nodes

Causing explosions

Whenever you want to cause an explosion which affects other nodes, make sure you to try to call the node's on_blast method first before using your own explosion handling. The reason for this is that e.g. your explosion could otherwise destroy a node which is normally immune to explosions.

Suffering explosions

If you are happy with what explosions caused by other mods do to your block (e.g. destroying it), you don't need to do anything. If you want to custumize the behaviour, define the on_blast method.

Indestructible nodes

Making a block truly indestructible in normal gameplay is not really obvious, so here's a tested and proven template which should prevent all well-programmed mods from destroying your block accidentally:

 minetest.register_node("example:indestructible", {
         description = "Indestructible Block",
         groups = {immortal=1},
         is_ground_content = false,
         on_blast = function() end,
         on_destruct = function () end,
         can_dig = function() return false end,
         diggable = false,
         drop = "",
 })

Note: There is no way a node can “defend” against minetest.remove_node. If a mod for gameplay directly calls this function without any checking, this is probably a bug in this mod, rather than the mod with the indestructible block.

Destroying nodes

Be very careful when you want to destroy a node by calling minetest.remove_node directly. There is no way a node can “defend” against such a call, so this needs to taken into consideration for interoperability.

You should only use minetest.remove_node directly for technical and/or debugging mods, but for actual gameplay, you should do some checks first. Otherwise, you might end up accidentally destroying blocks which are supposed to be indestructible (see above).

Recommendation: First check if any of the node's callback functions are appropriate to be called (e.g. call on_blast when you create an explosion). If you want to destroy a block in another manner, first check if the node is not indestructible (checking against the immortal group should normally suffice). If the block does not seem to be indestructible, calling minetest.remove_node should normally be safe.

Preventing pistons from pushing or pulling your node

The Mesecons modpack has pistons which are able to push and pull other blocks around. By default, this happens for pretty much all blocks. If you want to prevent this behaviour for your block, you have to explicitly exclude your block.

To do this for a node “example:myblock”, add the line “mesecons_mvps?” to depends.txt and the following code after the registration function of your node:

if minetest.get_modpath("mesecons_mvps") ~= nil then
        mesecon:register_mvps_stopper("example:myblock")
end

Matching patterns of nodes

The multiblock library provides functions for checking if some group of nodes form a certain structure, while returning "captures" of specific nodes within the structure.

Interface

Showing status information

If you create a new player attribute/stat (like health) and you want to expose it to the interface somehow, you can use:

• HUD Bars [hudbars]: Provides an API to add your own indicators like the “hearts” for health. Displayed in either a “progress bar”-like fashion or the classic statbars like in vanilla Minetest

Inventory enhancements

Some mods enhance or change the inventory and may provide an API to add buttons in the inventory. This can come in handy if you have made your own formspec and seek for ways to access them.

• Unified Inventory [unified_inventory]: Supports adding buttons for doing any action you want
• Inventory++ [inventory_plus]: Supports adding buttons for adding “sub-menus” to the inventory menu. Only minetest.set_inventory_formspec is supported. This mod may be a bit outdated

Decorational

Colors

If your mod provides blocks in multiple colors, there are various mods and conventions to consider for ensuring the best interopability.

It is strongly recommended you only use colors which follow an agreed-upon set of predefined colors. A basic set of 15 colors is defined in the “dye” mod in Minetest Game. Read the source code to learn more. Other mods provide an extended set of dyes. The mod Unified Dyes [unifieddyes] extends the set of colors to 90 colors.

Other specific mods for consideration:

• Colorization by crafting: Consider if you want to add crafting recipes by adding a dye and your item (like wool in Minetest Game, read it source code to learn how it works)
• Color Machine [colormachine]: Coloring support will be provided by the mod itself, as long as the authors update the mod. Your task would to to make sure that the names of the textures and nodes follow naming conventions
• Paint Roller [paint_roller]: Use the API of this mod to enable the paint roller to colorize your blocks
• mypaint [mypaint]: This mod allows to paint in arbitrary colors using paint buckets and brushes; internally it seems to work very different than the other mods

Groups

Another way for interopability is by using groups. If used properly, they can greatly increase ease-of-use when other modders want to work with our mod. The rule of thumb here is that you generally use groups which are already widely used if you can. Only if your needed group does not exist, you should define your own group.

On this wiki, the Groups/Custom groups page tries to document the usage of groups and lists some commonly used groups. If your mod defines its own groups and they are *not* just to be used internally, please edit the Groups page to help other modders.