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 ...