Simple modding tutorial

Post Reply
Josselin2
Member
Posts: 102
Joined: Thu May 28, 2020 15:32
GitHub: axcore
In-game: Josselin
Location: Tunnelers' Abyss

Simple modding tutorial

by Josselin2 » Post

I put together a tutorial for writing simple mods, perhaps someone will find it useful.

From the introduction:
This tutorial is designed for anyone who wants to have a go at writing a simple Minetest mod.

You don't need to know anything about programming languages, because we will cover that.

You *will* need some basic computer skills. If you know how to open and close files and folders, how to move files from one place to another, and how to use a simple graphics application like Microsoft Paint, then this tutorial is for you!

If you already have some coding experience, or if you have elaborate plans for a Minetest mod, then you should ignore this tutorial and read rubenwardy's modding book instead.

We cover quite a lot of topics. Everyone should read Chapters 1-3. After that, you can read whichever chapters interest you.
Corrections and feedback welcome. In particular, I haven't yet worked out to describe the location of the mod folder for all operating systems and all installation methods, in just two sentences or less, so perhaps someone has some ideas about that.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: Simple modding tutorial

by Wuzzy » Post

My review of version 1.0 of this tutorial:
Sorry, I think it's really bad. It does only teach you very little. And the little it does teaches is tought so poor. The reader is contantly instructed to blindly copy code around while most of the interesting parameters aren't properly explained.
Also, it just gets many things wrong.
So I get this is meant to be a complete beginner's guide to modding, but I think it's currently not of much use. After reading all of it, the reader isn't really capable of much of anything. Many explanations are woefully inadequate and incomplete and leave the reader with more questions than answers.

Also, worst of all, the tutorial is really bland. There aren't any interesting examples that the reader is shown, there aren't any actual practical projects, (like adding a new tree or something), just some ugly example nodes and items, basically. Especially for a complete beginner's tutorial, I think that's not good. Screenshots are missing as well. Way too few screenshots.

The tutorial assumes modding for Minetest Game, which is actually *fine* IMHO. Minetest Game might be boring but it has a pretty good moddability (if we ignore the default bloat, AHEM!). But then the tutorial limits itself to Minetest features only. Like teaching how to add a new fence to MTG would be great way to introduce how to use game-specific APIs as well.

In this stage, I can't really recommend this to anyone. This tutorial needs like an almost full rewrite to be useful and interesting.


Now for some chapter notes:

General notes:
There's no introduction section, explaining what this is about, nor is there any mention as to which Minetest version this document applies to. But this is really important. There's no mention of lua_api.txt, which is a major blunder.
There's no technical introduction to mods and games, which isn't great either. There is no introduction to technical terminology.

Index
You will need some basic computer skills. If you know how to open and close files and folders, how to move files from one place to another, and how to use a simple graphics application like Microsoft Paint, then this tutorial is for you!
This recommends Microsoft Paint, a proprietary program. We shouldn't recommend proprietary programs, it's missing the point of Minetest, a free software. GIMP is better anyway. :P

Chapter 1:
Minetest is a graphical game,
Minetest on its own is not a game, you have to download games first to play.

I don't like how you don't actually explain the command or the hello world program. Note that the "minetest.log('some text')" syntax is deprecated which is not a great way to start a tutorial, and since it's deprecated, I'm not sure that Minetest gives any guarantee it will be printed to the chat in future versions … The hello world section should show something more reliable...

Chapter 2:

The chapter doesn't clarify for which game this mod can be used, but it makes assumptions that dirt, sand, etc. exist. I guess you assume Minetest Game but you never said that.
The chapter fails to mention the texture naming convention.
Images are normally 16 pixels (dots) high and 16 pixels wide.
This is unneccessary, games can theoretically choose whatever size if memory allows it. You shouldn't prescribe a given size.
minetest-game is a collection of mods.
First, it's "Minetest Game", not "minetest-game". Second, it's not exactly a "collection of mods". A collection of mods is called "modpack", but Minetest Game is technically a game (although a very disappointing one, but this is besides the point).

The chapter should have tought the player on how to manually add a sound instead of depending on default ...
tiles = {"happy.png"},
Your tutorial violates the texture naming convention.

The biggest disappointment is that this chapter doesn't talk about all the node properties. All it teaches is to add boring static full-cube nodes. With this knowledge you are still unable to add very basic:

- Plants
- Ladders
- Torches
- Signs
- Fences
- Glass
- Leaves
- Rails
- Rotatable chests
- ...

I think that's just too little even for a beginner's tutorial.

Chapter 3:
If you're feeling both adventurous and lucky, your changes will have worked first time; otherwise, you'll see an incomprehensible error message and Minetest will refuse to start your mod.
"incomprehensible error message". Seriously? What a great way to discourage people. The error messages are comprehensible if you know how to read them.
A string can be inside a pair of double quotes, or inside a pair of single quotes. (Choose the one you prefer and use it consistently.)
Wrong, a string can also be between [[ ... ]] and [=[ ... ]=] ... and [==[ ... ]==], and similar (with longer chains of equal signs).
The number represents the node's hardness.
That's not really true. Minetest doesn't know the concept of "hardness". These numbers ore more like conventions. Also the whole section is very shoddily written, it doesn't even clarify how the different numbers


Chapter 4:
This chapter is actually pretty okay. It's missing the output count, which is really important in my opinion, and also doesn't include burnzime and the other types like shapeless, fuel (VERY important) or toolrepair.

It's not made explicitly that "cooking recipe" means it's a recipe for the furnace.

Chapter 5:
Craftitems are things you can hold but not place on the ground.
This definition is kinda sorta correct but not quite. A craftitem is an item that you can have in an inventory. Also, craftitems actually CAN be placable with the on_place callback, but I think this is already advanced.
Now, let's talk about signals.
Wait, what? That's not a term used in Lua or Minetest Lua API. Please stick to correct terminology.
Whenever you want to create something edible, just copy and paste the on_use line. If you like, you can change the number: 1 will have very little effect on your player's hunger, but 5 would have a dramatic effect.
This is completely false. Minetest Game doesn't have hunger, so this directly increases your HP.
Also, just explain the number stands for the number of half-hearts you'll get, it's very easy.

Chapter 6:
The chapter fails to explain the crucial property of tools: wear and stack size of 1. Very important. Also, in Minetest, technically, the ONLY thing that is special about tools is that they can have wear and that they are forced to have stack size 1. Other than that, tools can be whatever the modder desires.

The chapter also is missing the hand as the special case.

The part where the example code for the wooden club is shown, almost none of the numbers is explained which is not helpful at all.

Chapter 7:
Lol, this chapter made me laugh. Jumping from tools straight to ... biomes? Weird learning curve.
But oh, you used clear_registered_biomes. Clever.
Minetest creates a world in which different areas have different temperatures. The coldest temperature is 0, the hottest temperature is 100.
Wrong, temperature can actually have temperatures beyond these values. The actual min and max values depend on the Perlin noise output. 0 and 100 are just guidelines.

Chapter 8:
Creating a schematic is outside the scope of this tutorial. (If you want to try, there are several mods than can help you - try this one, this one, this one or even this one.)
Of the linked things, I would only recommend schemedit and mtsedit (but this isn't a mod). The other ones are more like tools you use if you already have schematics, not tools to create new schematics, so they are wrong in this list).

Chapter 10:
It's so surreal to see the "if" statement appear that late in a tutorial, lol.

At the end it mentions "namespaces", which is again not really a term that Lua or Minetest uses ...

User avatar
Blockhead
Member
Posts: 1622
Joined: Wed Jul 17, 2019 10:14
GitHub: Montandalar
IRC: Blockhead256
In-game: Blockhead Blockhead256
Location: Land Down Under
Contact:

Re: Simple modding tutorial

by Blockhead » Post

Just to try to present corrections where Wuzzy only points out what's incorrect:

Signals in chapter 5 should be replaced with the term callbacks. The explanation of callbacks is that you register a function to do something when an event happens, and then Minetest guarantees that it will 'call you back' (think like telephone terminology) and arrange for you to handle the event. Your mod's code runs once when that mod is loaded, this is the initialization stage. This initialization code is meant to set up the registrations of nodes, entities, items etc. and the registration of callbacks for events that pertain to those. Some callbacks are global and not bound to particular entities as well, such as register_globalstep. After initialization, the mod code only runs through callbacks - when the Minetest Engine deems it necessary to call 'your mod back' so to speak.

As Wuzzy pointed out the tutorial is specific to Minetest Game. That's fine, but you should stick to unmodded Minetest Game, instead you seem to include reference to a hunger mod. I don't think a hunger mod is necessary but if you insist on it, you need to specify which one to install.

Namespaces - well, while these do perform a function that's like namespaces in that they put subordinate names under another name, they're actually just global tables. Come to think of it I can't think of a good conventional name for them, except 'API' (but they don't always meet that strict definition) But yes, the way that most mods work by good convention is to have one global table that contains functions and possibly data related to them. The set of public functions in such a table is best called the API (Application Programming Interface), which just means the set of functions that are meant for anyone to use. Application because it's not general purpose, programming obviously, and interface as opposed to internals. To deal with software with an interface you need only learn the interface, rather than the internals of it - some software has a better interface than others. For instance, Minetest has a better modding interface than Minecraft*.

*controversial I know because people get more done in Minecraft - but there's no official Minecraft API and even the unofficial ones drastically change and in some cases assume you will be replacing core logic in the program with your own, something you can't do in Minetest for reasons of it being a sane, non-reverse-engineered design. Even if replacing core parts means you can do more - that's more of Minetest's lack and Minecraft's hacked state rather than any brilliant design on the part of Minecraft.
/˳˳_˳˳]_[˳˳_˳˳]_[˳˳_˳˳\ Advtrains enthusiast | My map: Noah's Railyard | My Content on ContentDB ✝️♂

Josselin2
Member
Posts: 102
Joined: Thu May 28, 2020 15:32
GitHub: axcore
In-game: Josselin
Location: Tunnelers' Abyss

Re: Simple modding tutorial

by Josselin2 » Post

Thanks for your feedback. I updated the tutorial to: replace the placeholder image names (I forgot to do that), add an output count in the craft recipe section, tweak the definition of craftitems, clarified the maximum range for temperature/humidity, replace signals with callbacks, and a few other minor things.

Josselin2
Member
Posts: 102
Joined: Thu May 28, 2020 15:32
GitHub: axcore
In-game: Josselin
Location: Tunnelers' Abyss

Re: Simple modding tutorial

by Josselin2 » Post

Wuzzy wrote:
Thu Jan 20, 2022 00:54
Sorry, I think it's really bad. It does only teach you very little. And the little it does teaches is tought so poor. The reader is contantly instructed to blindly copy code around while most of the interesting parameters aren't properly explained.
I don't think we are on the same page about the target audience. My target audience is people like this guy viewtopic.php?f=9&t=27671, who try to write an extremely simple mod which doesn't work, and then they get discouraged and never try again.

Most of your complaints are variations on the theme of "there is not enough detail", but in order to include that much detail, the tutorial would be ten times bigger. That is not the objective, so most of the detail has been omitted.

I don't feel like getting into an endless argument, so I will just respond to a handful points in order to clarify my thinking, you can tell me if I'm on the wrong path completely.
Screenshots are missing as well. Way too few screenshots.
I re-read the tutorial this morning, and I didn't see any places that would be improved with more screenshots. But perhaps you have some concrete examples in mind.
nor is there any mention as to which Minetest version this document applies to
I think all the code examples should work for all version of Minetest going back to 0.4.16, but you can tell me if that's not so.
There's no mention of lua_api.txt, which is a major blunder.
I don't agree. The Lua API is entirely incomprehensible to absolute beginners (as it should be), I can't think of any good reason to recommend it to them. In any case, the introduction mentions rubenwardy's book as a next step, and the API is described there anyway.
There is no introduction to technical terminology.
Sorry, I don't follow. Which technical terms used in the tutorial do you think are not adequately explained?
This recommends Microsoft Paint, a proprietary program. We shouldn't recommend proprietary programs, it's missing the point of Minetest, a free software
Everyone knows what MS Paint is, about 0.01% of the human population knows what GIMP is, that's why I mention MS Paint and not GIMP.
Note that the "minetest.log('some text')" syntax is deprecated
It's in the API. When that changes I can update the tutorial.
This is unneccessary, games can theoretically choose whatever image size if memory allows it. You shouldn't prescribe a given size.
99% of mods use 16x16 textures, that's why the tutorial also does that.
The chapter should have tought the player on how to manually add a sound instead of depending on default ...
99% of mods re-use sound effects from default, that's why the tutorial also does that.

citaconrama
Member
Posts: 11
Joined: Thu Dec 16, 2021 10:36

Re: Simple modding tutorial

by citaconrama » Post

@Wuzzy, I admire your work and I am a really big fan of yours. But I think you are not getting the point here. I started minetesting three months ago and I think that documentation, tutorials and such things are not as helpful as they should be. It is really hard to understand for someone that just arrived. Maybe concepts that are obvious for people who have followed the development for years are not so easy for newbies.

I am working on something like Josseline2 has made, this is how I found this topic. My approach is a little bit more technical and I go into deeper details, but your post discourages me to publish it, since I do not know if someone who I admire is going to point out all my mistakes instead of helping me to improve the document. For example, you say that minetest.log("hello world") is deprecated, but the official documentation

https://minetest.gitlab.io/minetest/min ... e/#logging

does not say anything like that. How are we suppossed to know? Moreover, you can find print() in

https://rubenwardy.com/minetest_modding ... s/lua.html

Someone should start explaining that print() is not going to work in Minetest. Ruben Wardy's book is one of the few places where you can learn in a structured way, but sometimes is hard to follow. For example, in the same page that is telling you go and learn to program with Scratch explains variables scope. For me it is obvious that the reader who is ready to understand scopes is not the same that needs to learn Scratch from the beginning.

I think the answer of Blockhead is more helpful and encourages Josseline2 to keep the good work. Maybe the tutorial is not perfect, but I think it is a good idea to give some hints to someone who is starting right now. As I said, right now modding for beginners is very confusing because you find code with deprecated functions, few tutorials, incomplete or outdated information...

I hope this post doesn't bother you. My point is, the idea behind Josseline2 is great, maybe we can make it work instead of telling that the tutorial is really bad.

User avatar
Linuxdirk
Member
Posts: 3217
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Simple modding tutorial

by Linuxdirk » Post

citaconrama wrote:
Mon Mar 21, 2022 09:34
I started minetesting three months ago and I think that documentation, tutorials and such things are not as helpful as they should be.
Usefulness of documentation depends on the skill of the person reading that documentation (this is meant entirely non-judgemental!).

For people just starting with embedded coding or Lua in general, and never used the Minetest API before, the API documentation is just not the right place to start with. But the more skill you gain through coding, and testing, and experimenting with things, the better you can use the available documentation such as lua_api.txt.

This neither makes it entry level documentation like this one or the famous "Modding Book" better than the advanced documentation nor makes it the advanced documentation complicated.
citaconrama wrote:
Mon Mar 21, 2022 09:34
It is really hard to understand for someone that just arrived. Maybe concepts that are obvious for people who have followed the development for years are not so easy for newbies.
Exactly. lua_api.txt is simply not meant for those people.

It was the same for me. I learned Lua and Minetest modding by looking at other mods and Lua examples online. Now, a few years later I know most things and can easily look up and understand things in the available documentation.
citaconrama wrote:
Mon Mar 21, 2022 09:34
Someone should start explaining that print() is not going to work in Minetest.
Of course it is. You can easily use print('Foobar') to print something to stdout. In combination with dump() you can even get tables printed: print(dump(my_cool_table)). I use this constantly while developing or debugging stuff.

It is of course not being used to print something to the player. For this minetest.chat_send_player() or minetest.chat_send_all() all can be used (you can even use dump() here to have funny in-game debugging output 🤣).

User avatar
rubenwardy
Moderator
Posts: 6972
Joined: Tue Jun 12, 2012 18:11
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy
Location: Bristol, United Kingdom
Contact:

Re: Simple modding tutorial

by rubenwardy » Post

citaconrama wrote:
Mon Mar 21, 2022 09:34
Moreover, you can find print() in

https://rubenwardy.com/minetest_modding ... s/lua.html

Someone should start explaining that print() is not going to work in Minetest.
print() does work in Minetest. The difference between print() and minetest.log is that print goes to the terminal only,
whereas minetest.log also goes to the log file.
citaconrama wrote:
Mon Mar 21, 2022 09:34
Ruben Wardy's book is one of the few places where you can learn in a structured way, but sometimes is hard to follow. For example, in the same page that is telling you go and learn to program with Scratch explains variables scope. For me it is obvious that the reader who is ready to understand scopes is not the same that needs to learn Scratch from the beginning.
Exactly, which is why I point towards Scratch.

I do appreciate any feedback you have towards the modding book, it's still being updated. Feedback from newcomers is very valuable
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

citaconrama
Member
Posts: 11
Joined: Thu Dec 16, 2021 10:36

Re: Simple modding tutorial

by citaconrama » Post

@rubenwardy, I appreciate your answer, I am also a very big fan of yours. Without your book, which I know it is a WIP, for me it would have been almost impossible, or at least very time-consuming, to understand MT modding.
rubenwardy wrote:
Tue Mar 22, 2022 12:15
citaconrama wrote:
Mon Mar 21, 2022 09:34
Moreover, you can find print() in

https://rubenwardy.com/minetest_modding ... s/lua.html

Someone should start explaining that print() is not going to work in Minetest.
print() does work in Minetest. The difference between print() and minetest.log is that print goes to the terminal only,
whereas minetest.log also goes to the log file.
Ok, it goes to the terminal. Where do I see the terminal? Is it explained somewhere you read when you are starting learning? Keep in mind that print("Hello world") is the first thing a newcomer is going to try. But you follow the steps, you download MT, you create the folder and the init.lua file, you type print("Hello") and... nothing. It is discouraging.
rubenwardy wrote:
Tue Mar 22, 2022 12:15
citaconrama wrote:
Mon Mar 21, 2022 09:34
Ruben Wardy's book is one of the few places where you can learn in a structured way, but sometimes is hard to follow. For example, in the same page that is telling you go and learn to program with Scratch explains variables scope. For me it is obvious that the reader who is ready to understand scopes is not the same that needs to learn Scratch from the beginning.
Exactly, which is why I point towards Scratch.

I do appreciate any feedback you have towards the modding book, it's still being updated. Feedback from newcomers is very valuable
IMHO, the target reader is not the one who needs to go to Scratch. As I said the modding book is THE book, but maybe there should be something in the middle between nothing and your work.

Linuxdirk wrote:
Tue Mar 22, 2022 08:55
citaconrama wrote:
Mon Mar 21, 2022 09:34
I started minetesting three months ago and I think that documentation, tutorials and such things are not as helpful as they should be.
Usefulness of documentation depends on the skill of the person reading that documentation (this is meant entirely non-judgemental!).

For people just starting with embedded coding or Lua in general, and never used the Minetest API before, the API documentation is just not the right place to start with. But the more skill you gain through coding, and testing, and experimenting with things, the better you can use the available documentation such as lua_api.txt.

This neither makes it entry level documentation like this one or the famous "Modding Book" better than the advanced documentation nor makes it the advanced documentation complicated.
Of course you don't start with the API documentation. That's why I say that something is missing.

What I really like about MT is precisely that you can read all the code and learn from it. But finding simple examples is not easy, and you find outdated examples all the time. For instance, you find depends.txt files in many popular mods. You google something and you end in the wiki with incomplete articles. You are, in fact, supporting my point of view: you learn with examples rather than reading tutorials.

rob123
Member
Posts: 105
Joined: Wed Mar 03, 2021 07:15
GitHub: qwerty123a2
In-game: joe and joergeg

Re: Simple modding tutorial

by rob123 » Post

citaconrama wrote:
Thu Mar 24, 2022 09:41
@rubenwardy, I appreciate your answer, I am also a very big fan of yours. Without your book, which I know it is a WIP, for me it would have been almost impossible, or at least very time-consuming, to understand MT modding.
rubenwardy wrote:
Tue Mar 22, 2022 12:15
citaconrama wrote:
Mon Mar 21, 2022 09:34
Moreover, you can find print() in

https://rubenwardy.com/minetest_modding ... s/lua.html

Someone should start explaining that print() is not going to work in Minetest.
print() does work in Minetest. The difference between print() and minetest.log is that print goes to the terminal only,
whereas minetest.log also goes to the log file.
Ok, it goes to the terminal. Where do I see the terminal? Is it explained somewhere you read when you are starting learning? Keep in mind that print("Hello world") is the first thing a newcomer is going to try. But you follow the steps, you download MT, you create the folder and the init.lua file, you type print("Hello") and... nothing. It is discouraging.
rubenwardy wrote:
Tue Mar 22, 2022 12:15
citaconrama wrote:
Mon Mar 21, 2022 09:34
Ruben Wardy's book is one of the few places where you can learn in a structured way, but sometimes is hard to follow. For example, in the same page that is telling you go and learn to program with Scratch explains variables scope. For me it is obvious that the reader who is ready to understand scopes is not the same that needs to learn Scratch from the beginning.
Exactly, which is why I point towards Scratch.

I do appreciate any feedback you have towards the modding book, it's still being updated. Feedback from newcomers is very valuable
IMHO, the target reader is not the one who needs to go to Scratch. As I said the modding book is THE book, but maybe there should be something in the middle between nothing and your work.

Linuxdirk wrote:
Tue Mar 22, 2022 08:55
citaconrama wrote:
Mon Mar 21, 2022 09:34
I started minetesting three months ago and I think that documentation, tutorials and such things are not as helpful as they should be.
Usefulness of documentation depends on the skill of the person reading that documentation (this is meant entirely non-judgemental!).

For people just starting with embedded coding or Lua in general, and never used the Minetest API before, the API documentation is just not the right place to start with. But the more skill you gain through coding, and testing, and experimenting with things, the better you can use the available documentation such as lua_api.txt.

This neither makes it entry level documentation like this one or the famous "Modding Book" better than the advanced documentation nor makes it the advanced documentation complicated.
Of course you don't start with the API documentation. That's why I say that something is missing.

What I really like about MT is precisely that you can read all the code and learn from it. But finding simple examples is not easy, and you find outdated examples all the time. For instance, you find depends.txt files in many popular mods. You google something and you end in the wiki with incomplete articles. You are, in fact, supporting my point of view: you learn with examples rather than reading tutorials.
Windows only: to view the console go the settings tab, click All settings, click graphics, Advanced, Enable console window,edit,enable.
Mac: go to the install folder(the one with minetest) right click on minetest.app, show package contents, contents,Macos,minetest

Linux: do not have linux installed as it makes my mac(2010) frezze up after it uses up 4 GB ram. No peppermint linux does not fix it, I tried it.
If my post says something, it is a opinion and not fact unless i say so

citaconrama
Member
Posts: 11
Joined: Thu Dec 16, 2021 10:36

Re: Simple modding tutorial

by citaconrama » Post

rob123 wrote:
Thu Mar 24, 2022 20:43
Windows only: to view the console go the settings tab, click All settings, click graphics, Advanced, Enable console window,edit,enable.
Mac: go to the install folder(the one with minetest) right click on minetest.app, show package contents, contents,Macos,minetest

Linux: do not have linux installed as it makes my mac(2010) frezze up after it uses up 4 GB ram. No peppermint linux does not fix it, I tried it.
Thanks!!! I think this supports my point of view: I do not see that enabling the console is straight-forward for someone who just arrived and is trying a simple print("Hello world").

Does not anybody think that some low level tutorials are missing?

Post Reply

Who is online

Users browsing this forum: Ahrefs [Bot], ROllerozxa and 20 guests