Integrating a tutorial into Minetest

[Wuzzy]

Thanks to the overwhelming support for the Tutorial subgame+world, here’s the obvious feature request:

Add this tutorial to Minetest.

HOWEVER, it is not so straight-forward as you may think. I want this thread to focus on the neccessary integration work which needs to be done in order to include the tutorial as cleanly as possible. If you want to discuss about the tutorial itself, please write in the tutorial thread above.

The simplest solution would be to simply drop the tutorial and the subgame into Minetest and that’s it. It would work, but not really well.

For the tutorial to work, the following conditions have to be met:

• Singleplayer mode
• Damage is on
• Creative mode is off

This means, if the main menu keeps unchanged, a newbie has the following possibilities to mess the tutorial up:

• Delete Tutorial World
• Start tutorial in multiplayer mode
• Start it with damage off
• Start it with creative mode on
• Accidentally activate mods
• etc.

So there’s a good reason to alter the main menu.

Here are my ideas on how to change the main menu in a newbie-friendly way:

• Hide Tutorial World from the list of worlds
• Hide the tutorial subgame from all subgame lists
• Add a new tab “tutorial”:
  
  • It should be the selected tab on the very first start of Minetest
  • It has a very short description of the purpose of the tutorial
  • Initially it has a button “Start tutorial”
  • If the tutorial has been started earlier, instead there are two buttons “Continue tutorial” and “Reset tutorial”
• “Tutorial World” shall be made a reserved name. The GUI shall forbid to name any world “Tutorial World” manually

Now I’ll explain what I think should happen:
In a fresh Minetest installation, the subgame and the world are installed in fixed locations, not in the user dir (like “.minetest” under Unix-like systems). The system-wide world should never be directly available to Minetest nor should it be changed by Minetest, it only is there to be copied. Maybe it shall be called “Tutorial World Original” there, to avoid confusion for those who like to jump around directories. ;-)
When the user clicks “Start tutorial”, Minetest shall create a complete copy of Tutorial World Original and put it into the world directory in the Minetest user directory and name it “Tutorial World”. Minetest then will apply the settings “damage on” and “creative mode off” and start Tutorial World (that is, the local copy of Tutorial World Original) in singleplayer mode. Now the player can go through the tutorial like in any normal game and from this point on, Minetest treats the world as any other world. When the player leaves, the world is retained.
Now the tutorial tab has changed. There are now two buttons “Continue tutorial” and “Reset tutorial”. If the player clicks on “Continue tutorial”, the local copy of Tutorial World is loaded again, like a normal world (under the same settings as before, of course). If the player clicks on “Reset tutorial”, Minetest deletes the local copy of Tutorial World and updates the main menu formspec and returns to the initial state. Clicking the reset button should also open up the obligatory Y/N question.

How does Minetest know wheather the tutorial is resetted or not? Easy: Just check the user’s world dir: If it contains “Tutorial World”, the formspec should be in the “load/reset” stage, otherwise it is in the “start” stage.

However, hiding the game and tutorial world may be bad if someone want to edit things for fun. To cater to these needs, I suggest a minetest.conf setting “hide_tutorial” which is true by default. If “hide_tutorial” is false, both Tutorial World (local copy) and the subgame are now exposed by Minetest.

With Minetest and the main menu modified like this, we have achieved the following:

• Really easy way to directly start the tutorial: Just need to click “Start tutorial”
• Easy way to reset the tutorial for other people on the same computer
• No chance for newbies to mess up vital files

If I think about it, all that really needs to changed in Minetest for optimal integration (IMO) is basically just the main menu. And some files need to be copied and removed and that’s it.

[jin_xi]

i think there could be a way to 'put a game in a world' if said world is kind of fixed, as it seems useful for some type of game anyways, like desert island or logo skyblock kind of stuff.

then there would be just one world in a fresh minetest install, containing all that is needed for the tutorial in the right configurations. i hope the tutorial also mentions that there is no need for any additional stuff to play on a server!

[rubenwardy]

I think a suggestion that the devs would make is to allow multiple tutorials, and tutorials for different subgames.

Instead of storing the tutorial template in worlds/, it could be stored in games/minetest_game/tutorials.
Multiple tutorials could be in that folder, and could be selected via a list box in the tab.
Also, the tutorials tab should have a "discard" or such button to hide it from the main menu.

Even better, make the tutorial world into a schematic, and make a subgame out of it.

Also, I think using signs for tutorials is inappropriate. HUD would be better.

[MaxPower]

As mention before there is no need to change minetest engine.
Ruben have the proper term for that, use schematic to create your world so you don't have to ship the world, a user can create as many instance of the tutorial as he like. Admittedly I don't know how schematic work but it seems to solve all the "deployment" problems.

[rubenwardy]

I'm going to look at integration possibilities with the Minetest engine tomorrow, you'll be glad to know. The solution needs to allow subgames to have their own tutorial. I think the best way is to make each tutorial a separate subgame. I don't think a world will ever be merged with Minetest (database files not being appropriate for git), but a tutorial subgame may be.

I also think minimal should be removed

[philipbenr]

Agreed. It should be pushed to a different part of the minetest project like minetest_game.

Actually, I think they should swap places...

[Wuzzy]

Instead of storing the tutorial template in worlds/, it could be stored in games/minetest_game/tutorials.

Bad idea. The tutorial subgame is NOT minetest_game. It is just a fork of minetest_game, but I bet it is completely incompatible with it.
And how would this make any difference, anyways?

Also, the tutorials tab should have a "discard" or such button to hide it from the main menu.

Yeah, that makes sense. It should also of course include the obligatory Y/N question.

Even better, make the tutorial world into a schematic, and make a subgame out of it.

This has these downsides: 1) It makes it a pain in the ass to edit the world 2) It increases load time 3) It increases code overhead.
2) and 3) may be an acceptable price to pay, but especially if 1) is not going to be solved in a clean manner, I don’t like this much. :-(

Also, I think using signs for tutorials is inappropriate. HUD would be better.

So you say the signs are inappropriate, may I ask why? And I don’t even know what you are actually suggesting about the HUD. How is that HUD stuff supposed to work? Do you have any concrete ideas on that? Because I sure don’t have any, sorry.

Rubenwardy, I have the impression that you have never actively tried the tutorial. Is that correct?


If you are going to integrate it, that’s fine. But how can the tutorial including the world be updated later on? Because it surely shouldn’t be frozen from that moment on.

[kaeza]

Point 1 is not a problem. You would have a "development" version of the world, and some scripts (optionally distributed with the world) to automate the task of "converting" it to schematics.

Use one schematic per room/level/feature, and only generate them as needed (e.g. when the user enters/clicks a door/special node). It's not hard to make them or to place them in the world, and more or less spreads the loading time across the whole journey.

[twoelk]

I think I have changed my mind on this.
Previously I thought the Toturial should be as monolithic as possible.
I now think it might be quite usefull to have a "Tutorial-Game" that might even include some more of the mods or at least some features of them, mentioned in this thread: "Minetest Could Be An Educational Tool". The smiley of the Cutepie mod also sort of suggests itself usefull for a tutorial :-)

The reason is quite simple: Such a game may serve several Tutorials.
I have thus added the "game" to the List of Games on the Minetest.net Wiki.

While I still think the use of placing schematics may solve some issues and maybe make the implementation sleeker I now consider other aspects more vital. I think Wuzzy should take into account the idea of multible Tutorial Worlds/Maps making use of one Tutorial-Game. Choosing the Tutorial Game from the main menu could show several tutorials that aim to explain different issues of the game and might serve different levels of knowledge. Just as Wuzzy has allready mused himself to make a second tutorial for the "higher Minetest education" ;-P Besides from the problems of how a player may find these tutorials and what special tutorial button may be added to the main menu there should also be a sane and informative naming scheme for the different maps.

Although someday there might be a special "Educational Minetest Subgame" I think that the Tutorial-Game at the moment could be the logical choice a teacher might make to build some tutorial of his own to serve some of his own educational idea he might want to use Minetest for.
To make it clear I don't think the Tutorial-Game should be made into a functional normal game but rather a tool that other people might be able to use for their own purpose.

[Wuzzy]

I am probably not making large changes to the basic tutorial anymore. It is done. And it is already pretty large IMO. The subgame is not really re-usable either, it only makes sense to use with the world.

But that’s what I actually just wanted to achive: A tutorial which teaches the basics of Minetest. Not a tutorial which teaches everything. ;-)


For a generic tutorial subgame, as you suggest, it would have to be written from scratch; maybe some content can be forked off the current tutorial subgame, but not all of it. But my motivation to create even more tutorial worlds is now pretty low.
I also don’t think that new tutorials should be in the style of my basic tutorial. The basic tutorial was kinda controlled and closed, but following tutorials could be far more open than that, maybe just as a bunch of scripted events with maybe some very simple structures (nothing sophisticated as Tutorial World) in an otherwise normally generated world. Nothing too fance, more like a guide, actually. But it depends on the content, of course.
But whatever. Don’t expect more tutorials from me anytime soon. And I don’t care about that educational stuff, it feels off-topic.

When I think about it, trying to create tutorials for each and every subgame or even mod might be totally overkill. There might be better ways to introduce the concrete elements of the game. For example, the item tooltips could be extended to include tool capabilities, an usage description and many other important information about the item type. This little step alone would help a lot. Self-documentation should be the way to go. An existing example of self-documentation are also crafting guides. Another idea: Adding a “help” button to every non-obvious formspec. Does your mod have a weird furnace? Just add a “help” button to it. :) For tools with an unobvious usage (like the screwdriver), the tooltip might help. And, and, and, … The idea of self-documentation is to put all gameplay-relevant information into the subgame itself.
I suppose that, when using the idea of self-documentation, tutorials should not be needed for subgames.


@kaeza: This sounds good to me.

[leeminer]

Not that my opinion matters around here at all but for one I love the Wuzzy Tutorial. 2nd even better would be a tutorial for each subgame or even mod. **Not suggesting Wuzzy do this.

I really think the Tutorial Wuzzy made, makes the game more accessible and even adds a traditional gaming element to the game. Also, I think a tutuorial in general can showcase a mod or subgame and really wow people and at the same time show them how to use it.

Again not that my opinion matters but I really think this is something to look into. Tutorials really add something to the game. :)

[Don]

In my opinion all that is needed is a tutorial that shows hows the game is played. Trying to show how everything works is too much. Give a new player the basic info so they get the basics and then they figure the rest out on their own. That is just part of the fun.

The forum is what should be used to tell players how to use different mods. If anything, a way to add a link in the game would work much better then a tut for mods. The player could click a link and open the forum page in a browser. Not sure if possible.

[leeminer]

In my opinion all that is needed is a tutorial that shows hows the game is played. Trying to show how everything works is too much. Give a new player the basic info so they get the basics and then they figure the rest out on their own. That is just part of the fun.

The forum is what should be used to tell players how to use different mods. If anything, a way to add a link in the game would work much better then a tut for mods. The player could click a link and open the forum page in a browser. Not sure if possible.

I agree. I'm not saying make it a requirement. I'm just saying that its a cool feature. Its like sure the bare minimum is cool but this is the icing on the cake. Personally, when I finish my mod I will add a a tutorial. Having an official way to integrate it would be nice but I could just distribute the mod with the tutorial I make.

[ArguablySane]

When making mods I think it's better to include in-game documentation rather than a tutorial. Let the player spawn with a book which explains how to use your mod, or give them a simple menu option which shows the documentation. This is much easier than spending precious development time creating a fully interactive tutorial, and I suspect most users would find it much more convenient. I'd rather be able to get a recipe list from an in-game book than playing through a tedious tutorial.

[Don]

When making mods I think it's better to include in-game documentation rather than a tutorial. Let the player spawn with a book which explains how to use your mod, or give them a simple menu option which shows the documentation. This is much easier than spending precious development time creating a fully interactive tutorial, and I suspect most users would find it much more convenient. I'd rather be able to get a recipe list from an in-game book than playing through a tedious tutorial.

I agree. A help button in machines would be great and your book idea is nice.

[leeminer]

When making mods I think it's better to include in-game documentation rather than a tutorial. Let the player spawn with a book which explains how to use your mod, or give them a simple menu option which shows the documentation. This is much easier than spending precious development time creating a fully interactive tutorial, and I suspect most users would find it much more convenient. I'd rather be able to get a recipe list from an in-game book than playing through a tedious tutorial.

I agree. A help button in machines would be great and your book idea is nice.

I think a book is a good compromise. I'm still doing a tutorial ;)

[Wuzzy]

Ummmm, people: This thread is going way too far off-topic now. This thread is only about how to integrate my specific basic tutorial into Minetest, not some imaginary subgame tutorials which do not even exist yet. This thread is also not about books, although I find the idea very interesting. ;)

Now back to topic:

I recently had a short chat in #minetest-dev with celeron55 and asked what the chances are to include this tutorial into Minetest.

celeron55 said that this tutorial won’t go into 0.4.11 for sure. This does not surprise me, since 0.4.11 is under a feature freeze right now. The tutorial won’t be in Minetest before 0.4.12.
Celeron55 is obviously not opposed of the idea to include the tutorial, but I was also told that I should make some size optimizations, the current size over 1 MiB is already too much. Okay, I hope I can get this hurdle out of the way.

Celeron55 didn’t like my initial idea of treating the tutorial as special case. Instead, he proposed to use some sort of general-purpose code which can be used. The resetting of the worlds should be a feature which could be used for all kinds of worlds. When I think about it, this approach seems to be much more sane than my initial one.

Another idea was to introduce some kind of “fixed” world, as opposed to the procedurally generated worlds we have now.
Another thing which would be needed according to celeron55 was that worlds can be bundled with subgames. This would solve another integration problem with the tutorial, obviously.

But I guess since we have a feature freeze right now the priorities are somewhere else right now. ;)

[Wuzzy]

I did a quick packaging test with Tutorial 1.8.0: If I would package the tutorial (world+subgame) as .tar.xz, the archive size would be just about 768 KiB.

However, the unpacked version is pretty large: 6376 KiB.
Subgame alone: 2740 KiB
World alone: 3624 KiB.

[rubenwardy]

Template Worlds in Subgames

How about allowing subgames to have a template world? When a world for that subgame is created, the template world (eg: games/game/template_world) is copied into the world/ folder.

Tutorials don't need to be hidden from the world list, and progress can be saved. Worlds could be named tutorialsave_1 to make it clear.

And for displaying tutorials in main menu, you could specify that it is a tutorial in game.conf:

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

is_tutorial = true
tutorial_of = minetest_game
# ^ not sure about this. How should they see tutorial dialogs if they have multiple subgames with tutorials?


Advantages:

• Much cleaner. Tutorial is now all in one folder
• You don't have to use schematics, so is easier for you.

Disadvantages:

• Only one map gen seed can be used in a subgame (not a problem with your tutorial)
• Duplication of code and resources (both minetest_game and the tutorial contain much of the same textures and code, make sure you remove all unused mods, code, nodes and textures).

Tutorials in subgames

IMO, this is the better option. The tutorial world is contained in games/minetest_game/tutorial.
tutorial/worldmods/ contains the mods that are specific to that tutorial.

Advantages

• Much cleaner. Tutorial is now all in one folder
• Tutorial is maintained along with subgame
• It is obvious that a tutorial belongs with a subgame

Disadvantages

• Disabling unnecessary items and features. (I think it should be fully possible for a mods/ mod to disable subgame blocks and recipes. I am not sure if this is already possible.)
• What about two subgames sharing a tutorial? (they can just fork minetest_game and keep the tutorial, I guess).

[Wuzzy]

The 2 disadvantages for the first suggestion do not apply for my basic tutorial, I already have thrown away a lot of unneccessary stuff.

I wonder how your second suggestion would work with my generic tutorial? It is intentionally not designed towards any specific subgame. It has some similarities with minetest_game, but it is insufficient to understand minetest_game fully.

Also, I personally think that creating tutorials for each and every subgame might be overkill, unless your subgame breaks a lot of the basic concepts, i.e. if you throw away the entire crafting system and create your own with customized formspecs.

On the other hand, I think more in-game documentation might suffice to teach the subgame's contents. I don't think minetest_game is complex enough to deserve its own tutorial.
Even Lord of the Test is still not much more complex than minetest_game, because it does not negate Minetest's basic concepts. It is deeper than minetest_game, meaning that there is more content.
What I mean with in-game documentation are proper descriptions of items, how mob XYZ works etc.
For example an extension of item tooltips (for instance, a longer item and usage description) would already be a great improvement, but don't let us get too off-topic here.

Long story short: Tutorials to teach the basic game mechanics, in-game documentation to teach the concrete subgame content (nodes, crafting recipes, tool stats, etc.). If the subgame in question does not break the basic rules of Minetest, then there is probably no need for a tutorial.

[rubenwardy]

For most games the tutorial will be perfectly fine. For games like capture the flag, you'd need a different tutorial as well as the normal one to explain CTF specific things.

Howabout having a tutorial menu, where all the tutorials are listed? You could have the basic tutorial that you made, and then other tutorials.

The biggest concern for me is the redundancy of data. That could be solved by allowing sub games to depend on other subgames, but then you're going towards a 'common' arrangement. (Referencing that one Minetest version which allowed shared game mods).

However, I think that tool tips and nonblocking suggestiob bubbles is a much better way of teaching a user, lots of people skip tutorials because they are boring and restrictive.

[Wuzzy]

Sadly, it seems there is no real progress in integrating the Tutorial right now. I hope this changes some day.

In the meantime, I suggest that we could at least make the tutorial more visible maybe?
I have now written a wiki page about the tutorial with a step-to-step guide on how to start it:
http://wiki.minetest.net/Games/Tutorial

I also made some in-wiki links to the tutorial.

It would be great if the tutorial and the wiki page could also be listed on the official webpage: http://minetest.net/subgames
But I do not know to whom I should talk to.

If the tutorial is not allowed to be bundled with Minetest (yet), please at least increase the likelyhood that newbies at least know about its existance.

Rubenwardy: Pop-up bubbles are a nice idea, but they don't work to explain a couple of tricky concepts in Minetest. Pop-up bubbles are better suited for concrete subgames.

Also, can you back up your claim that “most users skip tutorials” with solid evidence?

[Wuzzy]

Well, a lot of time has passed, but there are some news for you!
First of all, my goal is still unchanged. I still want that tutorial to be included. :P

Recently I released Tutorial 2.0.1. This is a version only for the dev version of Minetest (after 0.4.13).
After a long back and forth I finally decided to use the schematic solution. It turned out to be the better solution instead of having a fixed world which may break.
Ferk coded for the tutorial a major change which makes Tutorial generate Tutorial World on the fly by loading it from a schematic (or something like that). When you create a new world, the tutorial world is generated automatically. There is no longer a seperation between subgame and world; the world is part of the subgame itself now, in form of a schematic. This reduces file size a lot and also has the plus that it is probably less a pain in the ass to maintain. Thanks to Ferk for the work on the tutorial, your contributions were greatly appreciated!

The zipped version of the tutorial (WITH the world schematic!) is now below 1 MiB.

Also, I noticed that the tutorial is now featured on minetest.net. That's a plus, but still not the goal of having the Tutorial shipped by default, obviously. :P

So, I still want to have it integrated, so here are my current suggestions on how to integrate the Tutorial:

• Add Tutorial subgame (obviously)
• Hide Tutorial subgame from the list of subgames (except in debug mode, maybe)
• Add a tutorial button or tab (not sure how to design this exactly, just some kind of widget stuff). There should at least be something like a “start tutorial” button either way, clicking on it will internally create a world in the tutorial subgame with all the correct settings (damage on, creative mode off), and start it. The generated tutorial world is saved in the worlds directory like any other world, but under a fixed and reserved name
• Add button to continue previously saved tutorial. This simply starts the tutorial world previously created
• Add a button to reset/restart tutorial (important for computers which are used by more than 1 person). This button just deletes the existing tutorial world
• Maybe show dialog and ask question about starting tutorial for first-time users

I hope this sounds much more realistic to implement, don't you? :-)
If I see it correctly, this boils down to adding the subgame and tweaking the main menu.

Reasoning for this list of suggestions: Basically, this is just a simplified interface for handling a particular world and a subgame. Technically, it is not needed. However, we know we can not expect the player to understand all the world and especially subgame (!) stuff at this point. The idea is to give the player the chance to learn Minetest easily as early as possible.
Besides, the world handling may be still pretty daunting for newbies. I am pretty sure not everyone knows the meaning of “Seed” and “mapgen”. ;-) The main menu is pretty WTF from a newbie standpoint anyways. But this is a different issue, it needs to be addressed seperately, the tutorial cannot fix it. There's no point in a “Minetest main menu tutorial”. xD

What do you think of the Tutorial now? Do you think it is ready for inclusion? If so, do you thinkmy list of integration suggestions sounds reasonable?

[Don]

I love your ideas. I hope the dev team backs you up and helps you with this.

[Fixerol]

Will be nice to have it as subgame with some nice Tutorial icon and background with short info about tutorial for noobs.

[sofar]

I would strongly suggest that if the "Tutorial" subgame is present, and the game is loaded for the first time, that a popup-dialog appears to invite the player to play the tutorial. After closing the tutorial game, another popup should appear that tells the user that if they want to go back to the tutorial, that it can be found under the "singleplayer" tab.

I think that restarting the tutorial should be doable *inside* the tutorial itself, possibly at load time.

[Wuzzy]

I was told in the IRC channel “#minetest-dev” to make an issue on GitHub. So I went ahead and created issue 3778: https://github.com/minetest/minetest/issues/3778

sofar: Your first suggestion was already my idea, you stole it, you thief!! xD haha, just kidding. Suggestion 2 sounds reasonable. Your last suggestion … hmmm, I don’t know if it would be worth the effort. It’s probably possible but probably also a lot of work.
Anyway, sooner or later I really should practice my non-existing LuaVoxelManipulator skills (not just for tutorial). ;-)

Fixerol: Tutorial IS a subgame with icon. There is also a background with instructions on how to start it but it is really just temporary and may be removed later since I want the tutorial to be treated in a way a tutorial should be treated like. ;-)
I don’t know if you noticed it, but I am talking about this one: viewtopic.php?f=9&t=10192

But I think the tutorial should be hidden as a subgame, it should be accessible with a special button or something like that (see my new integration plan). If you have a “Start tutorial” button, then having it as a subgame entry in the main menu is redundant and also inconvenient for long-time users. For the player, the tutorial subgame should not appear as a subgame.

[rubenwardy]

If you made the schematic be placed on mapgen time, you could just call minetest.delete_area or whatever it's called, then just teleport the player to the start and reset their inventory

[hajo]

Tutorial subgame+world, here’s the obvious feature request:
Add this tutorial to Minetest.

Seconded, and I also suggest to remove that "Minimal Development Test"-game
from the standard package.

It is not useful for normal users, and developers should be able to install it on their own.