Minetest has a quite powerful modding API that claims to be simple. This is true from a technical point of view.  The problem is that there is no official beginner-friendly tutorial allowing people to learn the API step-by-step. Fortunately, some people took the time to create tutorials and documentations of the Minetest Lua API  on their own. I’m going to present three of them to you.

In case you don’t want to read everything, jump directly to the summary: #tldr

lua_api.txt

The lua_api.txt file is (to my knowledge) the most detailed documentation you can find. It sums up every single aspect of the Minetest Lua API on modest 4352 lines and 188kiB of plain text (16.02.2017). You can find it in every Minetest installation (minetest/doc/lua_api.txt) and of course also on GitHub.

The problem you might encounter with it is the lack of navigation. Being a plain text file, everything is linear without the possibility of using hyperlinks. You might find what you need by searching the file, but due to the fact that searching for node definition gives me 9 hits, it’s still a matter of luck to actually get what you expect.

If you are a complete beginner to the API, this one doesn’t help you much because it doesn’t have the structure that you would find in a tutorial. In my opinion, it’s best for advanced modders who already know the mechanics of the API and just need information on one specific topic, like the parameter list of the on_punch() callback of an entity. At least if you pay attention and don’t accidently grab the list of a node’s on_punch()

Pro Con
+ detailed – hard to navigate
+ many examples – linear structure
+ up-to-date – not beginner friendly
+ also available when offline

Minetest Developer Wiki

Minetest Developer Wiki ScreenshotThe Minetest Developer Wiki is a wiki-based approach to document Minetest. This breaks the linearity of lua_api.txt by splitting everything into pages and categories and connecting them with hyperlinks. That’s quite charming, isn’t it?

It has a quick introduction to the API teaching you the mod directory structure, naimg conventions and how to define nodes, craft recipes and ABMs. It’s short, but enough to write a complete yet simple mod.

What I don’t like about it is the fact that it still feels hard to navigate. Sometimes the articles are linked properly, sometimes not. Imagine you’re reading an article discussing a method dealing with the player. Of course there is an article explaining in detail what a player actually is, but if there is no link, it’s very likely that you won’t get information on the player object. Sure, you could use the search form. But would you scroll back to the top (and lose the paragraph you’re reading) to search for a keyword, navigate to another article  and come back to where you just stopped reading? I’m pretty sure the answer is no.

I totally understand that writing a wiki is hard work that not many people want to do. I know that because I used to write for multiple years in another wiki. Maybe it’s just my opinion and I might be alone with it, but in its current state it does not use its full potential.

The wiki does not only contain information on the modding API, but also on the C++ engine. This makes the whole project relatively huge and could be too much for a beginner.

If more community members would put effort into the wiki and use the full potential (detailed examples, more links, clearer structure), it would be the perfect modding reference for both beginners and advanced modders.

Pro Con
+ split into pages and categories – not beginner friendly
+ hyperlinks – does not use its potential
+ has a tutorial – not available when offline
– many incomplete articles

 

Minetest Modding Book

Minetest Modding Book ScreenshotThe Minetest Modding Book is a project started by rubenwardy in 2014. By the time of writing, it has 16 chapters explaining the basics and even some more complex principles of Minetest modding, like formspecs and HUD. Technically, it is a static website, that can be saved for offline use without any problems. There is also a download of the whole book available on its GitHub repository. The chapters are written in an easily understandable style and contain many examples, that are also available as a zip-download. It includes a formatted copy of lua_api.txt.

The book does not aim at being a complete reference, but at being a tutorial for modding beginners. It links to external resources here and there and ends with a Read more chapter. Due to this fact, it could make use of even more links inside the chapters themselves, e.g. to the wiki page of ItemStack when mentioning it for the first time.

If you are an advanced modder, you’re welcome to contribute.

needs more links to the wiki

Pro Con
+ beginner friendly (tutorial) – needs more inline links
+ easy structure and language – not useful for advanced modders
+ many examples with downloads
+ offline version available

 

TL;DR: Summary

The lua_api.txt is perfect for advanced modders knowing what they want to find out or feeling the need to try the latest features. It is too complicated for beginners.

The Minetest Developer Wiki could be useful for both beginners and advanced users if it had more authors filling and linking it.

The Minetest Modding Book is perfect for beginners looking for a tutorial that gives them enough knowledge to create feature-rich mods.

The wiki and lua_api.txt expect you to have a basic understanding of Lua or at least another programming language. When it comes to more dynamic code, it’s indispensable to know how to use control structures and data types. There are many Lua tutorials out there and this article is not going to discuss which one you should use. To give you at least a little starting point, take a look at these ones: Lua 5.1 Reference Manuallua-users wiki: Lua Tutorial

 

What about you?

What is your experience with the Minetest modding resources out there? How do you think about them? Is there something I missed or do you totally disagree? I’m looking forward to your opinion!