Modding Overview

From Minetest Developer Wiki
Jump to: navigation, search
Mbox information.png This page contains community-written advice, tips, tricks or recommendations about modding. Your mileage may vary.

This article is aimed at modding newcomers to help get a very broad overview over the Lua API of Minetest and get started with a couple of hands-on examples. This page is not official advice, not a complete tutorial in Lua, nor a reference. It does not replace the official Lua API documentation (lua_api.txt).


Modding Overview

Types of objects in Minetest

There are the three types of object that can be defined in Minetest. The type of the object is important as it plays a part in the properties of that object.

Mod packs and item names

Each Node, Tool and Craftitem needs a unique name to identify it in the API.

The name's format is like this: modname:itemname. In this case, the mod is called modname (name is preset by the folder name) and the block is called itemname. In this tutorial, we will make the node tutorial:decowood.

For example, default:dirt is the unique name for dirt.

Mod folder structure

The following describes the folder structure of a mod. The only required file is init.lua

    ├── modname
    │   ├── mod.conf
    │   ├── screenshot.png
    │   ├── settingtypes.txt
    │   ├── init.lua
    │   ├── models
    │   ├── textures
    │   │   ├── modname_stuff.png
    │   │   └── modname_something_else.png
    │   ├── sounds
    │   ├── media
    │   ├── locale
    │   ├──
    │   ├── depends.txt (deprecated)
    │   ├── description.txt (deprecated)
    │   └── <custom data>
    └── another
  • mods — Path to Minetest's mods.
  • modname — The name of your mod.
  • mod.conf — A key-value store of mod details:
name: The mod name. Allows Minetest to determine the mod name even if the folder is wrongly named.
description: A description of your mod to be shown in the Mods tab of the main menu (also used by mod managers). The first sentence should be less than 100 characters. It should be enough to describe the mod. Further information can be put into other sentences.
depends: A comma separated list of dependencies. These are mods that must be loaded before this mod.
optional_depends: A comma separated list of optional dependencies. Like a dependency, but no error if the mod doesn't exist.
  • screenshot.png — Screenshot of your mod (used by mod managers). It should be 3:2 with a minimum size of 300x200px.
  • settingtypes.txt — Mods settings displayed in the settings menu.
  • init.lua — Main Lua script.
    The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on Minetest calling the registered callbacks.
  • models — Models for entities or meshnodes.
  • textures, sounds, media — Media files (textures, sounds, whatever).
    These will be transferred to the client and will be available for use by the mod.
  • localeTranslation files for the clients.
  • — Markdown page describing and explaining your mod (for example if you are using github).
  • depends.txtDeprecated: you should use mod.conf instead. This file is used if there are no dependencies in mod.conf. A single line contains a single modname. Optional dependencies can be defined by appending a question mark to a single modname.
  • description.txtDeprecated: you should use mod.conf instead. This file is used if there is no description in mod.conf.

See lua_api.txt for up to date information about mod files.

Define a node

We are going to make a mod that adds a special kind of wood that can only be used for decoration.

First, create a folder called tutorial in the Minetest mods folder (see installing mods).

Next, create a file called init.lua and paste in the following:

minetest.register_node("tutorial:decowood", {
	tiles = {"tutorial_decowood.png"},
	groups = {snappy=1,choppy=2,oddly_breakable_by_hand=2,flammable=3},

You can download the image by right clicking tutorial_decowood.png and then click save as.

The function minetest.register_node(name, table) is responsible for adding new blocks to the game. Nodes are blocks as well as torches, signs, etc.

It takes 2 Parameters: The name of the new block tutorial:decowood, and a table containing the properties of the block.

The name of the block MUST start with the mod name, followed by a colon, eg. tutorial:.

In this example we define the following properties:

  • tiles — Sets the texture of the block; You can use only 1 texture or multiple textures, separated by commas {"tex1.png", "tex2.png", …}. The game checks for the texture files in ALL textures folders of the game.
  • groups — This sets attributes about the block including the time it takes to destroy the block, and the tool required. It also defines that the node will burn when is close to fire or lava.

Try it out

Launch the game now, and notice that the mods are automatically loaded and compiled.

This means when changing the code you simply have to "Exit to Menu" and "Start Game/Connect" again to try out the changes.

Let's try out our first mod! Open the chat window in-game (press t) and type /giveme tutorial:decowood 99. This will add 99 blocks of the decorative wood to your inventory!

Note: The "give" privilege is required for the /give and /giveme commands to work. In singleplayer you have this privilege by default. On servers a server admin has to execute /grant player_name give

Define a crafting recipe

Minetest also uses different crafting recipes. Therefore it is important to know what crafting means and how to code it.

Crafting means to create tools, blocks and other stuff. Minetest offers a 3 × 3 crafting grid by default with one output slot.

A stone pickaxe can be made out of 2 sticks and 3 cobblestone:

C C C     <--- S = stick, C = stone group (cobblestone, stone, desert stone, …)

Let's make a crafting recipe for the decorative wood.

Just add this to your init.lua file:

	output = 'tutorial:decowood 2',
	recipe = {
		{'default:wood', 'default:wood', ''},
		{'default:wood', 'default:wood', ''},
		{'', '', ''},

The function minetest.register_craft() registers a crafting process, it defines the recipe for something.

It takes 1 parameter which is a table that contains 2 properties: (and an optional third)

Let's define a cooking recipe to see how that works. This will allow the node to be placed in the top of a furnace which will convert it to another item. Fuel must be added to the bottom of the furnace for the craft to take effect.

	type = "cooking",
	recipe = "tutorial:decowood",
	output = "default:wood",

Let's also define a fuel recipe. This will allow the node to be placed in the furnace to fuel cooking recipes.

	type = "fuel",
	recipe = "tutorial:decowood",
	burntime = 7,

You can use the craft recipe checker when modding to check for typos.

Why are wooden planks not simply called wood but default:wood?
Indeed, The name of a node/tool/craftitem object must be modname:name (with two exceptions: air and ignore which are built-in). In this case, the mod is called tutorial (name is preset by the folder name) and the block is called decowood, so it's tutorial:decowood.
The default mod is the most important “mod” in Minetest, in fact Minetest itself is more like just a game engine, all the contents, materials, and other stuff are in several mods, like default (standard tools/blocks), bucket (Buckets: Lava/Water), and many more.
If you want to find out more about these mods and maybe use features they contain, just have a look in their init.lua!
Windows: Minetest/games/minetest_game/
GNU/Linux, run-in-place: ~/.minetest/games/minetest_game/
GNU/Linux, non-run-in-place (such as a package): /usr/share/minetest/games/minetest_game

Define an ABM

ABMs add actions to blocks. For instance, the tutorial-wood could become normal wood after a few seconds.

Append this code to your init.lua:

	nodenames = {"tutorial:decowood"},
	interval = 30,
	chance = 1,
	action = function(pos)
		minetest.add_node(pos, {name="default:wood"})

Try it out! It's really annoying to see all your decowood creations destroyed after 30 seconds, they simply become normal wood.

But how does this work? The function minetest.register_abm() registers an action for each block of the same type.

It contains the command minetest.add_node(). This takes two parameters:

First of all the position parameter (more information later) and also a table which defines the properties of the block, e.g. the name, the direction it faces. In this case the name is enough to define what block you can see.

So let's assume we want to create a mod that makes junglegrass grow above every dirt-with-grass block. This should be a slow process, one dirt-with-grass block after the other should be grown over. This is what we do:

	nodenames = {"default:dirt_with_grass"},
	interval = 2,
	chance = 100,
	action = function(pos)
		pos.y = pos.y + 1
		minetest.add_node(pos, {name="default:junglegrass"})

You should already know everything else but the line pos.y=pos.y+1. What is that for?

To understand it, you should know what a position variable in Minetest is a table made up out of 3 values: x, y and z.

x and z are forward/backward; left/right values. y is the up/down value. The player usually spawns near 0,0,0.

The line pos.y = pos.y + 1 manipulates the position to 1 block above the dirt-with-grass node.

There are some small other differences to our first abm. The interval is 1 in this case, but the chance (probability) is 100. Therefore the function is executed every second, but only in 1 of 100 cases. This makes your Minetest garden slowly been overgrown by junglegrass.

How to continue

That's it! You should now have a basic understanding on how the Lua API roughly works. Please note this article is not a complete tutorial. Read Modding Intro for a list of more useful links.

Retrieved from ""
Personal tools