Let's write in-game help for everything!

[Wuzzy]

Hi, modders. Minetest surely has lots of great mods and modders have lots of great ideas. However, many mods, especially the more complex ones are often lacking in useful documentation, explanations or any help whatsoever.

+ Long rant

Specifically, the problems I see with the current mod situation:

• Mod documentatition is often very lacking in Minetest mods
• Many items need an explanation before the player can do anything
• Existing documentation is scattered around the web, not at a centralized place where they are easy to find—It may be OK to go to the web for 1 or 2 mods. But ever joined a server with >9 mods you don't know yet? It would be a nightmare to hunt down the help (which may not exist in the first place) on the web!
• External documentation is not the final answer as it always breaks the flow of gameplay; it destroys immersion if you have to constantly “tab out” of Minetest
• Wikis are a very bad solution as 90% of wiki content just duplicates tons of item metadata and crafting recipes. This is bad as it is extremely error-prone. This stuff would be more effectively parsed automatically

A solution to these problems is by making an in-game help system. I strongly think having a good in-game help is a very crucial feature for a game's success. Especially if the game is very complex.

So I made the modpack “Help”. You find it here: viewtopic.php?f=9&t=15912&p=240152

This modpack is an extensible in-game help. It's been designed from the start to be extensible. Also, I also designed it to automate as much of the writing process as possible. For instance, you don't need to waste time for manually writing down the digging times of each tool, the Help already does that for you. Only nontrivial things such as “How do I use the boat?” need to be explained manually.
The modpack is currently strong with items and also covers the Minetest basics. But I hope later versions will also cover other aspects.

Now you, my fellow modders, come into play: You can use this modpack to add your own help texts to this, for the items (and other topics) which need more explanation.

Getting started with item documentation is easy: Just add specialized fields to the item definition, such as _doc_items_longdesc (for an arbitrary long description) or _doc_items_usagehelp (for an arbitrary long explanation on how to use an item) to the item definition.

Example:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

-- (...)
      minetest.register_node("dice2:dice_"..c, {
         description = dice2.descriptions[i],
         _doc_items_longdesc = S("A huge wooden dice with the numbers 1-6, just for fun."),
         _doc_items_usagehelp = S("Rightclick on a placed dice to “throw” it, which rotates it randomly."),
         tiles = {
            "dice2_dice_"..c.."_6.png", "dice2_dice_"..c.."_1.png",
            "dice2_dice_"..c.."_5.png", "dice2_dice_"..c.."_2.png",
            "dice2_dice_"..c.."_4.png", "dice2_dice_"..c.."_3.png" },
         groups = { choppy=2, flammable=1, dig_immediate=2 },
         paramtype2 = "facedir",
         sounds = {
            footstep = { name="dice2_dice_punchstep", gain = 0.75 },
            dig = { name="dice2_dice_punchstep", gain = 0.8325 },
            dug = { name="dice2_dice_punchstep", gain = 1 },
            place = { name="dice2_dice_place", gain = 1 }, },
         on_rightclick = dice2.throw,
         on_construct = dice2.construct,
         is_ground_content = false,
      })
-- (...)


Full source code: http://repo.or.cz/minetest_dice2.git/bl ... it.lua#l38

How this entry looks in the Help:


The first two sentences come from the code above. Of course, these texts can be as long as you like.

The other texts you see in this entry are automatically created, mostly by doc_items (for core item properties such as digging times, stack size, etc.). The sentence about flammability comes from doc_minetest_game because flammable is a group which comes from Minetest Game.

This was just a quick “taste” of the modpack. The Help modpack has many other features to offer. The core mod even allows you to add your own entries and categories from scratch. The modpack is very modular which should make integration into subgames easy.

As a good example, I already added support for the Help modpack for 13 of my own mods. And you can do this with your mods, too! :-)
The example above is a real-world example from [dice2]. You can find a list of supporting mods in the Help modpack thread.

If you're interested in providing in-game documentation for your mods, check out the developer information in the first post of the Help thread and read the README.md and API.md files of the mod.
I also wrote a simple example mod (doc_example) to help you with getting started very fast: http://repo.or.cz/minetest_doc_example.git

Use this thread if you have beginner questions in using the Help APIs or have comments about the idea of in-game documentation in general. Or if you just want to tell me you added Help support to one of your mods.
If you plan to integrate the Help modpack into a subgame (which I would very much appreciate), please let me know so I can give you some tips.

[firefox]

+1

i will add it to my ToDO-list for Sol Aureus =(^.^)=

[Wuzzy]

I am looking forward to it. :-)
You can ask me if you run into problems.

But I give a recommendation: For mods which you didn't write solely for your subgame but were mostly or completely copied from the forums (e.g. mtg_plus), it would be better to convince the original mod authors to add Help support in this mod. Then for the subgame, the only thing you need to do is to insert this updated mod into your subgame.

This has the benefit that all users of the mod can benefit from this improvement (including other subgame authors which seek to include it), and not just in your subgame.

[ExeterDad]

I have to hand it to you Wuzzy, this is excellent and much needed. Hopefully modders get on board with the idea and code accordingly.

[Nathan.S]

This is a neat idea, I'll need to check over my mods and see if any of them could benefit from using this.

I assume that the mod functions completely as usual if somebody doesn't have this mod installed. No reason that extra data in a node registration should change anything right?

[Wuzzy]

It depends what the mod wants to achieve. First of all, in principle, you can turn all mod dependencies to optional dependencies. Just add a check for the mod, and if it is not there, remove the functionality. Of course, for some mods this does not make really make sense if the mod ends up in doing absolutely nothing.

If a mod just wants to add item help for the items it adds, it surely gets away with an optional doc_items dependency.
But if the mod wants to add an entire help category, and the mod does not really add anything else, then a mandatory dependency on doc makes sense. In fact, doc_items is such an example, it depends on doc to add the item categories.

Also, the mod author will always have the last say on how the mod works (including dependencies), my doc modpack does not change that. ;-)