Modding Tips

This page is a random collection of various tips and tricks, and solutions to common tasks/problems that occur frequently in mod/game development. See also: Modding FAQ

OOM errors
If your game or mod crashes due to an OOM error, it means that Minetest has ran out of memory (=OOM). This happens if your Lua code somewhere uses up a large amount of memory. This can happen if you construct large tables and fill them with lots of data and never free them, or you got a nice memory leak. Badly coded mapgens are a likely cause of OOM errors, if you implement a Lua API, you should always apply all Mapgen memory optimisations.

For users tha use LuaJIT, the memory limit is currently (5.0.0) pretty low, and users are not recommended to even use LuaJIT for now. So tell your users to not use LuaJIT.

“Irrlicht: PNG warning: iCCP: known incorrect sRGB profile”
If you debug log level is set to “warning” or lower, you probably ran into the warning “Irrlicht: PNG warning: iCCP: known incorrect sRGB profile” quite often. it means that *some* PNG file is bad. But this warning is useless for you because there's no file name mentioned.

If you want to track down which PNGs are broken, set the debug level to “verbose”. Now the log will show the PNG file name right above the warning. Now just fix the offending PNGs with your favourite image editor to get rid of these warnings.

Deprecated function calls
If you want to upgrade your mod or game from MT 0.4.x to MT 5.0.0, there's a bunch of deprecated features you must fix.

First, you can use [MT-replace-deprecated.sh]. This will already fix most (not all) deprecations.

Then, set “deprecated_lua_api_handling” to “error”. Now your game will error out instantly whenever a deprecated function call is found. Great for development.

Positional sounds are either full volume or completely silent
Problem: You want to play a sound at a position, but it's always at full volume when you're in range or completely silent if you're not. For example, you have a zombie that growls, but when it growls, somehow its growl is either at full volume or not hearable at all (if you're out of the sound range); there's no gradient at all. This can be annoying.

Reason: Your audio file is probably stereo. The fix is to make all positional sounds mono. You probably want to check ALL audio files then, it's very likely this wasn't the only one.

The documentation says:

For positional playing of sounds, only single-channel (mono) files are supported. Otherwise OpenAL will play them non-positionally.

Note that non-positional sounds do not have to be mono, so you don't have to touch them.

Improving Lua mapgen memory performance
If you created a Lua mapgen, it is strongly recommended to make sure you optimize the memory performance, otherwise you could quickly run into OOM (out-of-memory) errors. See Mapgen memory optimisations.

More optimization tips
For more optimization tips, go to Lua Optimization Tips.

Checking if a mod exists
If you want to check if a mod named “example” is currently loaded and actively used, use this code:

Now  will be true if the mod exists and false otherwise.

This works because  returns nil if the mod is not loaded.

Ensuring mod interopability
A good mod is one that still works when a lot of other mods are used. Read Mod_interoperability for a lot of useful hints.

Quality checklist
Here's a list of things to check in your game or mod to improve general quality and to avoid common pitfalls. Not all things might apply for your game, always use good judgement.

Note: Some of these can be checked quickly with QA-Block. See also: Development Tools.

Preventing crashes, exploits and bugs

 * In minetest.after, do you consider that any external variable or object might become nil or disappear in the meantime?
 * In formspecs, did you check for all Time Of Check is not Time Of Use vulnerabilities?
 * In formspecs, do you Never Trust User-Provided Data?
 * In formspecs, do you enclose all variable, unpredictable text in ?
 * Does the game behave properly when restarted?
 * Did you check if implementing mod security is neccessary? If yes, did you implement it?
 * For singleplayer games: Do you error out if someone tries to run your game in multiplayer?
 * Do you restrict detached inventories to players, where neccessary?

General code quality

 * Does the game/mod avoid polluting the global namespace with tons of identifiers?
 * All deprecated code removed/replaced?
 * Are all APIs (that are intended for external use) documented?

Performance

 * Do you use the “buffer” argument in the LuaVoxelManip and Perlin noise functions (like  or  )?
 * Do you avoid re-creating the same Perlin noise over and over again?

Entities/players

 * Do all entities still behave properly when they unload, and then load again?
 * If you change player physics anywhere, will it still work when another mod changes it?

Items and nodes

 * Is  set to false for all nodes that the cavegen should not destroy?
 * Do all nodes have appropriate sounds?
 * Do all nodes have appropriate selection boxes?
 * Do all items intented for use only in Creative Inventory have set the  group?
 * Do all crafts work?

Game/mod metadata

 * For games: Are all unsupported mapgens disabled in game.conf?
 * Does your game/mod have a name?
 * Is the name of the game/mod used consistently everywhere?
 * For games: Name, icon, header present?

Graphics, audio, text

 * Are all positional sounds mono?
 * Does the UI still work in higher scaling/DPI?
 * Are all required textures included?
 * Do all items that the player can legitimately get have  set?
 * Do all chat commands have  and parameter list set?
 * In the parameter list of chat commands, does it follow the format defined in ?
 * Do all items have unique descriptions (=no confusing duplicates, unless intentional for some reason)
 * Is the writing style consistent across the entire game?
 * No typos/grammar fails?
 * Do you use  instead of a custom transparent image?
 * Do all items have an appropriate item image that helps in keeping items apart?

Translations

 * Does the UI provide reasonably enough space for translations?
 * Was at least one translation playtested?
 * Do you avoid using string concatenation to include variable text?
 * Can all user-facing texts be translated?
 * Have all in-game images with baked-in, untranslatable texts, been replaced with text?