EnlivenMinetest

Resources

• doc/lua_api.txt on minetest.org (drastically improved over the original github version)

Tips

* In singleplayer, you have the `privs` privilege. You can give yourself all privileges by typing: "/grant singleplayer all" (The same can be done with your own username if you are hosting a world). You can use "/giveme itemname quantity" where quantity is optional and itemname can be found by pushing question mark at the bottom of inventory (i) then clicking the item on the crafting guide on the right (see also "Common Items for Moderators to Spawn" further down. * You can test small pieces of code using the "Run Lua" and "Formspec Tester" features of the CoderEdit or WorldEdit GUI if you have the privilege.

Introduction

There are other modding books out there, but they often just rehash the documentation of Minetest without explaining much. The Modding section of the ENLIVEN Getting Started guide is here to help explain some of the assumptions and jargon.

Modding is easy in Minetest, because it is designed to be modded. The Minetest client downloads the "game" (collection of mods and modpacks) each time you connect to a server, so you don't have to install anything yourself. Automatic "game" downloading also means that each server can be very different, but load quickly, offering you many experiences to try easily.

Anyone can make a "game" using Minetest by writing mods or combining existing mods. Most "games" are based on games that are included in the Minetest/games directory--however, some games that differ drastically in gameplay can be made if one heavily edits or replaces mods that provide core functionality. Must of Minetest's core functionality is written in Lua.

Examples are a good way to get started. Since mods are scripted in Lua, every mod is open source. Almost every one is released under some sort of public license as well, which usually allows you to modify, reuse, and redistribute the code (usually under the condition that you credit the original author). Some joke licenses exist but DO NOT protect your work in cases where they explicitly allow others to copy your work and claim it as their own especially if modified it in any way--they would just be doing what you said they could do.

The license file sometimes has no file extension, so you may have to pick a program to open it in Windows. You can open it (or any other text file) in Notepad. However, Geany is recommended since there is more than one undo step. For Lua programming, you can install ZeroBrane Studio (which is free) then install "MinetestIDE" which patches ZeroBrane Studio to provide code completion (a form of autocomplete with API usage tips for coding).

Every mod, at minimum, must have a file called init.lua. You should also add a description.txt describing it, a README.md or other readme file explaining more, and a LICENSE.md or other license file. The MIT License is used for Minetest itself, so that is recommended. Some people determine that using GPL v3 can prevent the program from being used on popular mobile devices, since the GPL v3 specifies that a user must be able to not only reprogram but also replace the program with their recompiled version--this may not be possible if your version shares a namespace and key with the application you are changing, and you may not have the same connectivity or functionality without using the same key. Therefore, components or mods using GPL v3 may prevent their inclusion into future version of Minetest "games", as several versions of Minetest (often by other names) are on Google Play and the iOS App Store. You can find the MIT License online and paste it into Notepad or Geany. Be sure to fill in your name and the year you created the mod. Having a license will make sure others know they are legally safe using, changing, and redistributing your mod if that's what you tell them in the license. Having others change and improve your mod will help you too, because all Lua is open source (is distributed in plain text form not compiled form normally) and you can normally utilize others' improvements if you pick a good license as suggested.

Debugging Errors

If you have an error or Minetest crashes when your mod is enabled, try looking at minetest/bin/debug.txt (in $HOME/minetest/bin/debug.txt if installed using EnlivenMinetest installer for GNU+Linux systems, but usually in C:\games\minetest\bin\debug.txt if using Windows)

Using the Minetest API and other mods with APIs. Try reading the last few lines of the file. Use Geany or ZeroBrane (above) instead of Notepad, as Notepad may crash or mangle text when using large files. You can also use Notepad++.

Delete or rename the debug.txt file by the current date (with Minetest closed) every so often so it doesn't get too long.

API stands for application programming interface. It is just the set of classes and/or functions you use to change the behavior of an existing program such as Minetest. Mods that add significant features, such as Mobs Redo or codermobs, usually have their own API. You can see all of the functions in the api.lua file if the author has followed naming conventions and placed public features there. In addition, many mods have a api.txt or similarly named files. You can start by opening up your minetest directory on your computer (after installing or otherwise installing Minetest) and doing a search for api, or just open the following files depending on what you want to do:

• minetest/doc/menu_lua_api.txt
• minetest/doc/fst_api.txt
• minetest/doc/lua_api.txt
• minetest/doc/client_lua_api.txt
• minetest/games/Bucket_Game/mods/codercore/areas/api.md
• minetest/games/Bucket_Game/mods/codercore/craft_guide/api_craft_guide.lua
• minetest/games/Bucket_Game/mods/codermobs/mobs/api_new.txt
• minetest/games/Bucket_Game/mods/codermobs/mobs/api.txt
• minetest/games/Bucket_Game/mods/coderbuild/hopper/api.txt
• minetest/games/Bucket_Game/mods/coderbuild/magmatools/textures/magmatools_tool_magmapick.png
• minetest/games/Bucket_Game/mods/coderbuild/castle/castle_gates/api.txt
• minetest/games/Bucket_Game/mods/coderbuild/ambience/api.txt
• minetest/games/Bucket_Game/mods/coderbuild/bonemeal/api.txt
• minetest/games/Bucket_Game/mods/coderbuild/flowerpot/api.md
• minetest/games/Bucket_Game/mods/coderfood/farming/api.txt

Remember, you can always look at examples as well. You can find a mod that does something similar to what you want, looking at all of the .lua files in a mod like that may help.

Knowing the Lua language well means you can make more advanced mods. Even if you know the API perfectly, you still need to understand both programming concepts and the Lua language to do well. If you don't yet know any languages, a software development concepts course on YouTube or in book or formal education will help you greatly, Lua or not. If you already know programming concepts, here are some Lua caveats that can help you get started:

• Everything other than primitive value types are tables. Tables are what all other languages call associative arrays or dictionaries.
• The concatenation operator (for adding strings together) is ..
• You can send self as the first param for function automatically using obj:do_something instead of obj.do_something. This is helpful for functions used as object methods, which make use of the self variable.
• Arrays start at 1 (unless you forcefully set a 0 or negative index). You must start the array at one for array functions to work. Prefilled arrays start at 1, and use curly braces: things = {"something", "something else"}.
• # is the length operator. if #minetest.find_nodes_in_area(pos0, pos1, "group:flora") > 3 then is legitimate code: it will cause the case to happen if the count of flora nodes in the 3D box is greater than 3.
• Though Lua guides will tell you there is no ternary operator, and that is technically true, you can do a ternary operation as follows: local gender = texture_name:find("_female") and "female" or "male" The code sets gender to either "female" or "male".
• 0 is true in Lua, but nil is false. This behavior is helpful when checking whether a setting is present: local radius = (tonumber(minetest.setting_get("protector_radius")) or 5) The code allows a zero value.
• Lua's tostring method does not have an underscore, and is a global function
• Lua can represent an object as a unique hash using tostring (for an example, see owner of arrow projectile object in mobs redo), but trying to append an object to a string will result in a fatal "not serializeable" error
• For-loops use a "do" keyword: for i=-5, 5 do
• Clauses (such as if, else and for) end with end

Minetest Lua functions unrelated to the engine's functionality:

• dump can convert a table to a string (a list of methods of an object, usually)

Changing Existing Mods

A public license allows you to change and rerelease the mod, in addition to just being "open source." Many mods are on GitHub, GitLab, or notabug.org to allow easy forking. Forking is when someone other than the project owner makes improvements or fixes (often forking implies keeping it separate and not having your changes pulled in to the project owner's version). If the changes are applicable to everyone, you would usually fork it by clicking "fork" which allows you to download your own copy of the mod with "GitHub Desktop" for GitHub on Windows or a public licensed program like "Git Cola." Then you would make or paste in your changes, go back to the program and stage all tracked and untracked changes (not required on GitHub Desktop), name the commit, click commit, then click push. Then you can go back to the repository online where you got the mod and click "pull request" comparing across forks to the "head" from your repository, allowing the owner to "accept" the request or comment on changes you need to make or regretfully decline. Usually pull requests are preceeded by discussion, often at an issue on the issue tracker. Unless you are fixing something, you likely will have to present something the project owner already wants or is trivial but helpful. If the owner declines, you can always keep your repository and use and distribute your version of the mod if the license allows that. In some cases, you can instead just make a mod that overrides an existing mod--that would require putting the mod in depends.txt, clearing crafting recipes, and other similar steps--see github.com/poikilos/homedecor_ua for an example.

Craftitems and Nodes

A node is drawn as a block, 3d mesh, or other drawtype and is placeable. A craftitem can't be placed, so the only way to get rid of it is to drop it, and like other things dropped it will become a floating sprite waiting to be picked up by clicking. There are also other types of entities in Minetest such as mobs and particles. All items that aren't nodes are called craftitems even if they aren't used in recipes. You can use the name of a node or craftitem when defining a crafting recipe. However, you must depend on the mod being used to ensure that it is loaded before your mod, if the item comes from a different mod. You can depend on another mod by adding its name to the depends.txt file in your mod.

Mobs

Creating passive or hostile Non-Player Characters or Enemy Characters requires a mob api such as Simple Mobs, Mobs Redo, or codermobs which share anestry in that order. Codermobs is included in Bucket_Game and hence new versions of ENLIVEN. Some other mob frameworks include: mobf, Jordan4Ibanez' OpenAI, and others.

Codermobs

Bucket_Game (the basis for ENLIVEN) has codermobs as the modding framework. It is a general purpose API based on Mobs Redo but with additional features and fixes. If you want to test your mob or do performance testing, you can spawn one or more mobs with one command:

    "/se" (or "/spawnentity") now supports all of the following modes.
    This feature will show up in the next snapshot. For now, you can see
    it working in the online copy of Wonder World.

    /se Ent
    /se Ent Num
    /se Ent Pos
    /se Ent Pos Num
    /se Ent Num Pos

    For example: /se codermobs:badger 5

    The Num parameter is presently limited to 10. The limit may be increased
    or decreased at a later date.

    Note: Spaces are permitted, though optional, before or after commas in
    positions.

-OldCoder

Making Mob Models

How to Use Blender

Many Blender tutorials exist on YouTube. However, they usually go into painful detail about consfusing options that do not help beginners, which are the audience of tutorials in the first place. To offset this lack of Blender information, I created a course for when I was teaching Blender. These free and public-licensed Tutorials are here (that is the Blender 2.5-2.7 directory--for 2.8, click "Index" at the top). To install Blender and the B3D exporter for Minetest, see "One-time Setup for 3D Modeling" below.

Scale

10 Blender units is 1 Minetest unit, so if your creature should be 1.6 meters tall (5 ft 3 in), then the model should be 16 Blender units tall.

• The visual_size specifies size for 2D sprites such as wielditem, in Minetest units (default 1 x 1 is 1 meter square).
• The visual_size specifies scale for meshes. For example: The mummy from tsm_pyramids is about 2 Blender units (also same for b3view), the visual_size in Lua is 8, result is looks like it is the expected 1.6 Minetest units high. 1.6 is the expected result since the 2 Blender units are divided by 10 resulting in .2--multiplied by visual_size 8 results in 1.6 Minetest units.

One-time Setup for 3D Modeling

1. Install Blender 2.79 from blender.org (or 2.8 if you don't need to export b3d).
2. If using Blender 2.79, set it to left click select (like most programs, and Blender 2.8):
   1. Open Blender
   2. Click "File," "User Preferences."
   3. Click the "Input" tab.
   4. Change "Select With" to "Left."
   5. Click "Save User Settings," then press x on the "Blender User Preferences" window.
3. If using Blender 2.79, install the B3D plugin. You can get a version for minetest that does not export the texture path with the model, reducing useless missing texture warnings in the debug log in some versions of minetest (click Save not open, so you can find it in Downloads later):
   Download
   1. Open Blender
   2. Click "File," "User Preferences."
   3. Click the "Add-ons" tab.
   4. Click "Install Add-on from File..."
   5. Choose the "B3DExport-master.zip" (or other B3D export plugin if not the one above) that you downloaded.
   6. Search for "B3D"
   7. If the "Import-Export: B3D (BLITZ3D) Model Exporter" box is not checked, click it and wait for it to become checked (clicking again will just cancel the enable add-on operation).
   8. Click "Save User Settings," then press x on the "Blender User Preferences" window.
4. OPTIONAL: If you need to import x files into Blender, repeat the steps above for github.com/limemidolin/directX_blender (2.79 fork of littleneo's DirectX Exporter):
   Download

Export

Minetest modding because 2.8 does not yet have a good b3d exporter, and b3d format is the preferred (most efficient) format for animated models. If you are creating static (non-animated) models, you can use Blender 2.8 then export to any model format supported by Irrlicht (Usually 3ds, obj, are good static formats--Irrlicht also supports other common formats such as ms3d and md3; uncommon formats; and x for animated 3D models but x is not as efficient in size as b3d).

Sounds

Sounds must be mono if you want 3D positional audio, such as for mob sounds (see "irrKlang 3d Sound Position" on the Irrlicht forum, and "The Modding Book").

Creating New Ores

Creating new ores or other blocks may be confusing after you learn the API. If you want about 48 blocks before you find another cluster of your ore, then the clust_scarcity should be 48*48*48 since the game is 3D. The chance of finding a cluster is 1 out of the clust_scarcity number. The cluster size (clust_size) only affects the size of the "vein" (though technically there are multiple shapes of clusters allowed and vein is not recommended since it is hundreds of times slower). Minetest uses the generic term cluster to refer to all patterns of ore deposits. The number of ores in the cluster is determined by clust_num_ores. If your clust_size is 3, then that would be a 3*3*3 cube (but you just specify 3, not 27 there) and the maximum number of ores you could set for clust_num_ores is 27, though that is not recommended because then the person would find a 3*3*3 area that is completely ore (that would give the person 27 ore each time they found a cluster). Generally, the ore is a node (drawn as a block) and the gem or metal is a craftitem (drawn as a sprite). You normally should set the drop of the ore to a separate craftitem (however, if it is something you have to smelt such as a metal, you could drop the ore node, then provide a "cooking" crafting recipe to get the metal).

the absheight option should only be used for ores that should appear in mountains. It forces an ore that occurs in a negative range to also appear in the corresponding positive range. Another confusing parameter of the register_ore function is y_min. Most programmers are more concerned with y_max, which is how deep a player must dig to have a chance of mining the ore. y_min is the value below which the ore stops. Sometimes people set this to a very low number that normally won't be reached, such as -31000. This number may be useful for certain cases where an ore shouldn't occur below a certain point, such as amber (all nodes generated in this way are called ores in Minetest even if they are not technically a metal or mineral ore and even if they cannot be smelted nor drop a mineral--they still use the minetest.register_ore function).

Appendices

Common Errors

ERROR[Server]: LuaEntity name "creatures:chicken" not defined

If you have the error above, you have removed a mod or customized a creature so it has a different name.

To convert the mob to some other mob, try something like:
mobs:alias_mob("creatures:chicken", "codermobs:chicken")
If you have an unknown node (you see blocks in the game that say "unknown node" on them), you may need an additional mod to support your world. If you removed a mod on purpose or a node was renamed in a later version (see nftools example below), you can use Minetest's builtin alias function to make a mod to convert the nodes:
minetest.register_alias("name", "convert_to")
Example content for init.lua:
minetest.register_alias("nftools:aquamarine_ore", "nftools:stone_with_turquoise")
In that case, your depends.txt must contain one line:
nftools

The alias function may be confusing: You are registering the alias parameter 1 for parameter 2, which means that you are defining parameter 1 as an alias--not a real item--but another name for convert_to. When the world is saved, only convert_to will be saved. If you are sure that all of the world was loaded that contained the problematic nodes (players visited all of those areas) then you can remove your transitional mod.

Common Items for Moderators to Spawn

(list of item names for /giveme itemname)

glass
default:obsidian_glass
moreblocks:wood_tile
technic:concrete
stairs:stair_desert_stonebrick
stairs:stair_wood
stairs:stair_goldblock
stairs:stair_lapis_brick

mossycobble lapis:lapis_brick

mesecons_lightstone:lightstone_red_off
mesecons_torch:mesecon_torch_on
wool:white
technic:stainless_steel_block

lapis:base_lazurite_block

#white seams:
lapis:column_lazurite_brick
lapis:base_lazurite_brick

#subtle seams:
lapis:column_lapis_brick
lapis:base_lapis_brick

lapis:base_lapis_block
lapis:column_lapis_block
default:fence_aspen_wood

Historical Resources

(may only apply to minetest.net (same as GitHub.com/minetest) releases which have a heavily changed API without backward compatibility)

• The Minetest Modding Book on rubenwardy.com