Tutorial no longer working.

[Soyweiser]

I read somewhere the tutorial is bad. So I tried running it. It is broken. It gives a very large amount of errors when starting. I could list them here, but that would add nothing of value to the issue. (it complains about it not finding missions, items, cars, and more).

Related issues: #1324 and #9086, and #17985 (mentioning them so they can be closed after the tutorial is fixed. Which imho should be part of the 0.D milestone).

[Zilenan91]

There probably shouldn't even be a tutorial. Cataclysm is more fun if you just jump in when you're new.

[ghost]

I believe that we should design a new tutorial before 0.D comes out, or a release without tutorial system, or a bugged incomplete tutorial, is pretty fragmentary. On the forum, @Wuzzy2 posted his completely redesigned tutorial, and I love that : http://smf.cataclysmdda.com/index.php?topic=6238.0.

[Soyweiser]

Either sounds fine. But if nobody implements a new tutorial, the current one should be commented out from the menu.

[ghost]

Yes, if nobody implements it, the only option is to bring the original one out.

[Soyweiser]

Sadly yeah. :(

[Wuzzy2]

Throwing out the tutorial would be really sad. Excpecting the player to figure out everything alone is pretty lame since the game/sandbox (take your pick :P) is very complex. Tutorials are a very important starting point _especially_ for complex games/sandboxes like this. Throwing out the tutorial entirely only because it is incomplete is a no-go since CDDA is incomplete, too. CDDA has had many versions with that incomplete tutorial.

On the other hand, the current tutorial has become outdated over the time as important things like vehicles are missing. But at least it is a good starting point.

The only options without a tutorial are to read the (shallow) in-game help (I mean about the basic topics) or the wiki but the wiki has too many spoilers. I am never happy with game documentation rotting around only in some wiki as I think in-game help is much more spot-on and also easier to maintain. Luckily this is mostly not case for CDDA. Just think of all the in-game item descriptions C:DDA has.

If the tutorial is going to die, maybe at least the in-game help on basic topics (using the map, using weapons and items, etc.) should be made complete enough in order to play the game; i.e. also stuff like vehicles should be included (if they aren't already).

[Zireael07]

How many people are using the tutorial, though?

I saw it when I started, it was broken even then, so I just jumped in. Forums/wiki/let's do this-experimentation seem the way 99% of players start.

[Wuzzy2]

I used the tutorial. And your number of 99% looks like you have just pulled it out directly out of the ass. :P

And forum/wiki are not good sources because they are unreliable and get outdated quickly. A wiki has to be constantly maintained in addition to the game, and basically the wiki is pretty redundant anyway. And as I said, there's a huge risk of spoilers. In-game documentation is the best form of documentation since it easier to use, more up to date is closely tied to the game. Just build on that.

IIRC I used the wiki only once because I didn't know how vehicles work (I had no other choice). Everything else I learned from inside the game which should be the way it works.

[mugling]

In-game documentation is the best form of documentation since it easier to use, more up to date is closely tied to the game.

Both the tutorial and in-game help are very dated so this argument isn't at all true.

It's a lot of work to update the tutorial and there are a very limited number of people who undertake this. We should encourage instead participation on the wiki.

[ghost]

A thorough and helpful tutorial helps reduce the difficulty for a completely newbie player to fit in the game. Without it, freshmen would find the game extremely difficult and unfamiliar, as he/she barely knows the controls, the monsters, the items, and couldn't even survive for a day, according to my knowledge and observation to some newcomers trying to play this game I know.

[ghost]

The lack of help system could form a thick barrier from attracting new players to come in.

[mugling]

Does anyone have either working code or an intention to submit some? An idea need to be practical to implement for it to have any reasonable chance of traction.

[Wuzzy2]

mugling: No, we shouldn't encourage wiki participation for stuff which is basically already covered in-game. This is a huge amount of wasted worktime which would be better suited in something else. All a wiki can do is to repeat what the game already knows. Technical stuff like installation help etc. makes sense in a wiki, or supplemental stuff like tips and tricks, but long item lists are barely maintainable on a wiki. I know it from experience by having maintained and edited another game wiki for a long time. I just edit and edit and edit and I still find a tiny somewhere which is inconsistent with the game. And this starts over for every version. Sadly, this game has no in-game help at all and I have mostly given up on contributing to that wiki, since I feel like most of the information I write could just be automatically generated. The game in question is Minetest Game.

Stuff like damage, weight, and all other simple but important numbers are much better suited to be shown in-game and C:DDA already does a very good job at this, how can you think any of this is outdated? o_O IMO a wiki is already redundant by principle. With in-game documentation I also mean all the item descriptions and the generated texts which includes the hard numbers like damage, weight, etc. The game intrinsically does a better job than a wiki since it can just take the numbers it knows and turn it into text automatically, while in a wiki this job is mostly manual, time consuming, redundant and (of course) inconsistent with the actual game numbers. And I never needed the CDDA wiki except for vehicles which just proofs my point. (Vehicles could be handled by adding another help page).

If you just meant the basic help screen you find in the main menu, well, I think this can be updated easily, just write more text. If you have the feeling that at some point the wiki is actually more up to date, we might just copy that. IMO in-game should be the primary form of documentation, not a “last resort” form of documentation. And just because you think it may be outdated now does not mean we should drop it altogether. If we decide to drop it in favor of the wiki, I predict the overall quality of available documentation will slowly degrade.

Also, a tutorial isn't the only way of help, but its just VERY helpful for a complex game like this.

And the actual issue here is that the tutorial is broken. Maybe just try to fix it first to it works at least? And then we could discuss how to update the tutorial as such. Or is the tutorial broken beyond repair?

[mugling]

IMO a wiki is already redundant by principle.

Dwarf Fortress has an excellent wiki.

Does anyone have either working code or an intention to submit some? An idea need to be practical to implement for it to have any reasonable chance of traction.

As above. If you'd like to work on the tutorial nobody would object. Otherwise wiki documentation is something that can be more practically achieved.

[cainiaowu]

I recall DFwiki has a good bot to read RAW and turn them into wiki pages, we could have one on CDDA wiki. But then there are many hardcoded thing, like overmaps.

[mugling]

Note --dump-stats could easily be extended to dump wiki markup if anyone expressed an interest in collaborating on this. Who maintains the wiki?

[Zireael07]

@Soyweiser is the most active contributor recently and he has a github account. As for the coding part, there was a guy called BMAc something who did some amazing stuff, but he's AWOL now.

[Wuzzy2]

I recall DFwiki has a good bot to read RAW and turn them into wiki pages, we could have one on CDDA wiki. But then there are many hardcoded thing, like overmaps.

I would have nothing against online documentation which is automatically generated from raw data directly from the game. In fact, that would be a great idea. But the result can probably hardly called a wiki anymore, I guess. ;-)

As above. If you'd like to work on the tutorial nobody would object.

I don't object. Thanks for your offer to help.

[mugling]

I don't object. Thanks for your offer to help.

???

[Wuzzy2]

I you would help making the tutorial work again, that would be great and I would be grateful.

[mugling]

I think you misread - If you want to work on it go ahead but nobody else is doing so at present.

[Wuzzy2]

Oops, I actually misread.

[Soyweiser]

Yeah, I'm doing stuff at the wiki. And yes it is possible to generate wiki data from files. One issue with this is that it goes out of date very quickly. And while generating and updating pages is easy, seeing which issues have changed is not. Already fixed a few places where the wrong item names were used.

But, a thing I added a year ago was to use references to the item browser to several templates. Which makes the being out of date thing less of a problem. If people realized they should look at the item browser.

But yeah, I'm doing what I can, but also trying hard to not tackle to big problems at once, which just make me burn out, and get major feature creep. (I'm now (manually) looking over the mutations). Will look into some automation after that (prob).

Note --dump-stats could easily be extended to dump wiki markup if anyone expressed an interest in collaborating on this.

Well, not sure if it will be easy. But thanks for the tip. Don't know about what --dump-stats does. (But I can guess: command line parameter that is made to dump the stats to the console).

But, this is not the place to talk about maintaining wiki. It is the place to talk about the tutorial, and to defend both the wiki and the tutorial. And I agree that the tutorial is important.

As for why to the wiki is important, the game doesn't know everything inside the game. Did you know that the 'psychopath' and 'sapiovore' traits influence how you feel about eating human flesh for example? (Ran into that in the code yesterday). Or how combat stumbles work?

There is a difference between what you can learn ingame, where stuff can be incharacter and obtuse on purpose, and the code, where all is clear. If you are into reading code, and finding out what stuff does. As not everybody is able to read code, wiki can be good documentation of those things. It is also the place people have put down guides, spoiler information etc.

And yeah, I don't think the wiki should have a lot of the ingame statistics btw. Esp not those that can be read from the raws. Ideally, you would use a system like the item browser for those, and read them into the wiki dynamically.

And yeah, I heard mediawiki has an api that can be used for automation. Which the bot probably used. (I have the code for the bot from the old developer who worked on it. (He used C# and Microsoft Visual C#), have not looked at that).

[Wuzzy2]

One issue with this is that it goes out of date very quickly.

The same is true when editing everything by hand (even more so), so what's your point? I actually thought of not only generating it from game data but also running some bot of some sorts which regularily updates stuff. Otherwise its rather useless, of course. But IMO a wiki would be poorly suited for this, better to spit out raw HTML (or whatever format is suitable) directly.

As for why to the wiki is important, the game doesn't know everything inside the game. Did you know that the 'psychopath' and 'sapiovore' traits influence how you feel about eating human flesh for example? (Ran into that in the code yesterday). Or how combat stumbles work?

Well, then it's an issue with poor in-game documentation which should be fixed in the game. Duh! This is nothing which sounds like it would be impossible to explain properly in the game. The same is true for basically everything else. Player doesn't know how to farm? Improve item description for seeds and other required items. Player doesn't know how to build a vehicle? Add a help page about building vehicles. And so on. You have a point when you are talking about spoilery or outright cheaty texts which shouldn't be added directly to the game.

I am not completely against a wiki, I am just against seeing it as the “prime form” of documentation which it simply cannot be or is simply hard to maintain. My point is that it is not the most efficient way to document a game. Of course it is possible, but there are better ways IMO. I am fine with adding supplemental (read: non-essential) information about the game as you suggested, but I am strongly opposed to make it mandatory to read some wiki (outdated or not) to even get started or to learn how to do XYZ. IMO wiki should be optional for players to use, especially because of spoilers.

[Soyweiser]

The same is true when editing everything by hand (even more so), so what's your point?

I meant the code that generates the pages on the wiki. Even now for example, we have the item browser not being up to date with the game content often enough. (And in the case of the item browser, iirc some new editions can just make it crash). And I actually don't like that the items are on the wiki, or at least not in the current form. But I don't know how to fix it. (well, I know, but don't know if I can do it (coding skills + time + energy)). And well, I also don't have the privileges to do several things on the wiki. I only edit.

Another pro wiki point. It is easy to edit. A lot easier than creating a pr, cloning the github etc. And I disagree with your point on it is all just ingame documentation. Adding ingame that the '"You miss and stumble with the momentum." means you reached the maximum of 60 additional time units due to missing is silly and break immersion, but some people still want to know that.

But yeah, I agree with the mandatory, and spoiler points.

[BorkBorkGoesTheCode]

Seriously, it's counterproductive to have a malfunctioning tutorial. It should be removed.

[BrettDong]

Is there anybody else working on making a fresh new tutorial system? If there isn't, I might be doing this a few weeks later.

[codemime]

@BrettDong That would be great!

[Leland]

Note that #20827 states that the tutorial also crashes on save. Considering how broken the tutorial is right now, thought it would be prudent to just combine it here.

[taiyu-len]

i dunno if its cause im running a debug build, but it seems to be working now more or less. valgrind reports a lot of Conditional jump or move depends on uninitialised value(s) though. mostly stuff to do with the weather and such things like body temperature.

and now for what i was here for. i found a funny bug. start the tutorial, quit it via debug menu, start a game, and you get tutorial messages in the game!

maybe just replace the current tutorial system with an ingame version that gives you tutorial messages as you play like this bug does. would be much more helpful then the current tutorial tbh, it could probably cover more stuff.

[Wuzzy2]

There has been a lot of discussion over this. But I think the most important thing it to make the tutorial at least STABLE.

I think a tutorial redesign is another beast, it should better go in another issue.

Current problem withs tutorial:

• Quitting and saving and re-loading the TUTORIAL world is buggy, the game is aware of this
• Starting tutorial again and saving and qutting overwrites old TUTORIAL world
• The message system is very weird, the messages appear at unexpected times
• Zombies don't spawn anymore
• If a message is gone, it is gone forever. You are forced to restart the entire tutorial to read it again
• Tutorial world spawns in a generated world
• A huge chunk of the world is revealed on the overmap (spoilers!)
• You can die

Well yeah. Perhaps it would be best to throw away the current tutorial and start over. Will post a new issue soon.

EDIT: New issue here: #23395

[wapcaplet]

Tested Tutorial mode in 0.E-6177-g 9f4a1b841d - I have not seen any errors at all, but the messages often refer to ASCII symbols that may not be displayed in tileset mode, and the other shortcomings mentioned above are still relevant.

However, those appear to be covered by the newer issue #23395 (still open). Since the tutorial is now "working" (for some definition of "working"), I am closing this issue.