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.

Player physics
Using  to change player physical attributes is potentially dangerous! This is because it always sets the raw value of e.g. player speed, thus destroying any previous changes made by other mods. This is poison for any attempt at mod interoperability and an open invitation to race conditions and lots of other potential bugs. So please be very cautions before you use. You should take other mods into account.

There's a mod that solves the problem of interoperability:


 * Player Physics API [playerphysics]: Lightweight API to modify player physics without interference. Setting the attributes directly is banned in this mod, instead mods can add and remove factors to speed, gravity and jump strength. The final physical attribute will be the product of all factors.

Note the idea of this mod requires that ALL mods use it. If even just one mod (except [playerphysics], of course) uses  directly, interoperability is destroyed.

For further discussion of the problem with, see here: https://github.com/minetest/minetest/pull/7269

Internationalization
Since version 5.0.0, the preferred way to make mods and games translatable is with help of the Lua API with. No additional mod is required. Refer to  to learn how it works.

Help
”Help” refers to any form of in-game help, explanations or other things which aim to aid the player in understanding the game.

Help modpack
The Help modpack is a sophisticated in-game help system. It allows you to write help texts for almost everything; it could be used to document items, mods or even an entire game, entirely within the game only.

The following Help mods are relevant for modding:


 * Item Help [doc_items]: Allows you to add long item explanations, an usage help and automatically generated help texts for items
 * Lookup Tool [doc_identifier]: The lookup tool opens up the appropriate help entry on almost everything it punches. It almost works out of the box, but manual intervention from the modder is required for any custom entity
 * Documentation System [doc]: Low-level core API (for advanced users). Allows you to add your own entries and even entire help categories from scratch. Also has many utility functions

To get started with this modpack quickly, there's an example mod to demonstrate how to use these mods: doc_example

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]

RPG-like elements
This includes things usually found in RPGs (role-playing games) like stats, leveling up, experience points, quests, etc.


 * Mana [mana]: Adds a new player attribute (mana), could be used as resource for magic spells, weapons, tools, etc.
 * Sunburn [sunburn]: Makes sunlight dangerous, by causing sunburn (damage in direct sunlight)
 * SkillsFramework [skillsframework] Skills
 * Quest framework [quests]: Quest framework
 * sys4_quests [sys4_quests]: Another quest framework, depends on [quests]

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 mobs natively, but if you still want to add custom mobs, 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 game, you have to be very careful with interoperability.

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


 * Mobs Redo [mobs] Fork of Simple Mobs, is backwards-compatible to Simple Mobs
 * Minetest MOB Framework [mobf] Very feature-rich Mob API. Probably best known for being used as part of Animals Modpack
 * Creatures Mob Engine [cme]
 * general base for mobs [mobapi]
 * Simple Mobs [mobs] One of the oldest mobs mods, many other mobs mods (including Mobs Redo) were forked from this mod.

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. There are mods which add protection nodes, which protect within a range around the placed node, and mods which allow protecting whole chunks.

Mods should use minetest.is_protected when testing whether a player owns a specific position. Protection mods simply override this function.

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
 * Treasurer [treasurer]: API for randomly selecting a treasure out of a pool of previously registered treasures
 * Skylayer [skylayer]: Utility mod to help manage sky layers; supports smooth transitions

Testing for pipeworks fake players
Pipeworks [pipeworks] provides automation and creates fake players for that purpose. If you need to, these can be distinguished from real players by the field  in their definition.

Templates
Many mods offer convenience functions to add new new nodes which follow a simple template, like a fence made from a different kind of wood.


 * Standalone mods
 * Furniture [furniture]: Tables, chairs and stools
 * more shelves [moreshelves]: Shelves
 * flower pots [flowerpots]: Flower pots
 * Minetest Game Plus [mtg_plus]: Cups
 * corrupt shapes [csh]: Additional shapes: Cylinders and related shapes
 * mymillwork [mymillwork]: Additional shapes: Crown moulds, beams, columns, baseboards
 * kaeza's/VanessaE's signs library [signs_lib]: Advanced signs
 * Biome library [biome_lib]: Growing plants
 * Display API [display_api]: Nodes with a dynamic display, e.g. digital clocks. See Display Modpack
 * Font API [font_api]: Make textures from text and fonts. See Display Modpack
 * Signs API [signs_api]: Combining Font API and Display API, easy creation of any kind of signs. See Display Modpack
 * Minetest Game
 * [default]: Fences
 * [beds]: Beds
 * [doors]: Doors and trapdoors
 * [farming]: Farming plants
 * [stairs]: Stairs and slabs
 * [tnt]: Explosives
 * [walls]: Walls
 * [xpanes]: Panes

Modifications
These mods extend the possibilities of node definitions:


 * More ways for nodes to fall. [falling_nodes]: Allows you to define nodes with different falling rules and behaviours
 * Walkover [walkover]: Adds callback function which is triggered when a player walks over the node

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",         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 VoxelManip. If a mod for gameplay directly uses this 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 fields like  and other fields mentioned above might usually work). 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  and the following code after the registration function of your node:

if minetest.global_exists(mesecon.register_mvps_stopper) 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.

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]: Add your own indicators like the “hearts” for health. Displayed in either a “progress bar”-like fashion, the classic statbars like in vanilla Minetest or a variant of the classic statbars with a simple background
 * HUD Monitors API [hud_monitors]: Simple API to add semi-permanent text messages on the player's screen

Messages
For showing messages to players.
 * Central Message [central_message]: Simple API to show messages at the center of the screen for a short time

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


 * Simple Fast Inventory [sfinv]: Part of Minetest Game, you can add custom tabs to the inventory menu. See https://rubenwardy.com/minetest_modding_book/en/chapters/sfinv.html
 * Simple Fast Inventory Buttons [sfinv_buttons]: Adds a new tab “More” to the inventory menu of Minetest Game, in which mods can add buttons for doing any action you want
 * Unified Inventory [unified_inventory]: Supports adding buttons for doing any action you want (undocumented API)
 * Inventory++ [inventory_plus]: Supports adding buttons for adding “sub-menus” to the inventory menu. This mod does not work well together with newer versions of Minetest Game but it may still be usable for some other games

Formspecs

 * Smart Formspecs [smartfs]: Simplification and enhancement of the formspec API
 * Select Item [select_item]: Dialog to select an item

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

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

Other

 * Font API [font_api]: A library for displaying text on entities. Part of Display Modpack

Groups
Another way for interoperability 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.