[NoGo] Tutorial ("Beginner Tutorial" in bananas)

[MinchinWeb]

Good news! An update!

I wrote two chapters - both with road vehicles. Number #3 sets up a goods service from the Oil Refinery used in the ship chapter to a near by town and discusses some industry chain stuff. Number #4 sets up a city bus service with four stops and talks about town growth.

So what is left is the railway chapter.

A couple of questions/notes/thoughts I had:

• - somewhere we should mention that fast planes need big airports
  - it would probably be good to place a sign above the station tile at the oil rig (in the ship chapter)
  - need a mention of buoys in the ship chapter
  - do we need more explanation of how to find more oil rigs (map? Industry list?) at the end of the ship chapter?
  - it's four stations a town needs to grow, right?
  - perhaps there should be an "advanced topics" chapter that includes feeder services

[Kogut]

5 AFAIK *checking* yes - http://wiki.openttd.org/Towns#General_C ... own_Growth

[Expresso]

The reason why I have proposed airplanes first, then ships, roads and finally railroads is that you can build on previous experience. If you start out with buses, the player already understands how road stations work. The player has less information to absorb before reaching something tangible.

Truck stops basically function exactly the same as bus stops, so when the player understands how bus stops work you can focus on road construction and shared orders when you want the player to build his first truck connection.

As for trains, the first focus should be to get a simple point-to-point connection, no switches, nothing special. You do this in order to get to construction of the first train as fast as possible. After that you might want to build a second train and deliberately crash it, so the player understands that trains can crash.

Then the player should be poked to build a new station and attach it to the existing network and give a new train orders for the station. Of course the train doesn't leave the depot, so this can be used to explain the normal signals.

While I do know how to use the "advanced" signals, I'm not sure how they can effectively be exlpained in the tutorial.

[Simn]

So far I've came up with two basic architectural ideas:

I realize I'm a little late to the party, but I just came across your tutorial on my quest for NoGo exploration. First of all, I love the idea of creating a tutorial using NoGo! I really hope you continue this.

Then, I was wondering why you didn't consider using Squirrel's yield/resume mechanic for your step architecture, as it seems tailormade for that. Here's an usage example:

Basic step class:

Code: Select all

class Step
{
	constructor(desc)
	{
		GSLog.Info(desc);
	}
}

function Step::IsDone()
{
	return true;
}

A step script:

Code: Select all

function CurrentChapter::Steps()
{
	local i = 1;
	yield Step("Step " +i);
	++i;
	yield Step("Step " +i);
	++i
	yield Step("Step " +i);
	return null;
}

The executor:

Code: Select all

function MyGS::Start()
{
	local steps = this.Steps();
	local x = resume steps;
	
	while (x != null)
	{
		this.Sleep(150);
		
		if (x.IsDone())
			x = resume steps;
	}
}

Then you can extend the Step class to define a more sophisticated IsDone() method, and easily create scripts as a series of Step-yielding statements, with arbitrary code between them.

[Zuu]

I was not aware of this yield framework. So that is why I haven't used it. Though, I don't know if it is a smart syntactic sugar or if it is an exotic feature that makes the code harder for someone new to read.

I really haven't had time and motivation yet to workout how to change the framework to address the last thoughts on how to organize the tutorial into parts so that it makes sense for:

• Tutorial writing
• Save/load
• End users
• more?

I'm someone with many ideas for hobby projects but only two hands and an exciting full time job. So if you think that you have a good idea on how to bring the tutorial forward, you are welcome to have additional thoughts and get a go on it. In that case I suggest that you browse the project page and take a look at this task. I don't have any additional code other than what has already been committed to the version control system for the project.

[Simn]

I was not aware of this yield framework. So that is why I haven't used it. Though, I don't know if it is a smart syntactic sugar or if it is an exotic feature that makes the code harder for someone new to read.

It's not that exotic, coroutines have been known for a while and are supported in many different languages, see http://en.wikipedia.org/wiki/Coroutine. They are a wonderful tool e.g. for asynchronous programming, which is just what you have when interacting with a GUI.

and take a look at this task.

Well this is a state problem. I take it you cannot reopen a closed window by script and thus lose the correct state of the application during a save/load process, right? This is a limitation of the API, it seems strange that you can close windows but not open them.

A solution is to assign to your steps an integer value: 0 for normal steps, 1 for steps which create an unrestorable state (like opening a window) and -1 for steps that make the state valid again (like closing the window). Each time you execute a step, you add the value to a variable, so you get chains like 000111221110. Then, save only if that variable is 0, i.e. the state is restorable. If the execution is interrupted, you can start at the last valid state, e.g. before opening that nasty window.

[Zuu]

I was not aware of this yield framework. So that is why I haven't used it. Though, I don't know if it is a smart syntactic sugar or if it is an exotic feature that makes the code harder for someone new to read.

It's not that exotic, coroutines have been known for a while and are supported in many different languages, see http://en.wikipedia.org/wiki/Coroutine. They are a wonderful tool e.g. for asynchronous programming, which is just what you have when interacting with a GUI.

Thanks for sharing. My objection or question was mainly that when you get to write code that others might get to work with you set a standard by how advanced coding features you use. I can see that if you are used to use elegant features, there is a an enjoyment of being able to have an elegant solution. On the other hand it is also an interest to stay away from "exotic" features that will make the code harder to understand for those who are not familiar with the features. That's always a trade off. From the wiki article I can see this is not a built in feature in more traditional languages as C++.

All that said, I still thank you for teaching me about this building block and I'll see when I'll use it.

and take a look at this task.

Well this is a state problem. I take it you cannot reopen a closed window by script and thus lose the correct state of the application during a save/load process, right? This is a limitation of the API, it seems strange that you can close windows but not open them.

A solution is to assign to your steps an integer value: 0 for normal steps, 1 for steps which create an unrestorable state (like opening a window) and -1 for steps that make the state valid again (like closing the window). Each time you execute a step, you add the value to a variable, so you get chains like 000111221110. Then, save only if that variable is 0, i.e. the state is restorable. If the execution is interrupted, you can start at the last valid state, e.g. before opening that nasty window.

I've had a though about doing something more "magic" like that to keep track of last place that can be restored to, or add to the code checks that see what have been accomplished that is ran quickly through all accomplished steps. On the other hand, I've also though that this all might be an over engineered solution and it might just be best to keep it as simple as possible and then these features could be added later on when there is something working.

[Yexo]

Be very careful when using co-routines in combination with GSCompanyMode and/or GSTestMode/GSExecMode etc.

[Zuu]

Yesterday I made some progress with the tutorial:

Sandsala Transport, 30th Jan 1950.png (77.16 KiB) Viewed 5408 times

• I kept the same framework as before with tutorial steps.
• The GUIHighlightStep will wait up to 74 ticks for the window to be highlighted to open, and then abort the waiting. (the old behaviour was to not wait at all giving problems where the Execute function got called just a tiny bit before the window was opened)
• The MessageStep has been renamed as a SignMessageStep and a new step has been introduced MessageWindowStep to show messages in a window with a continue button
• Both MessageWindowStep and GUIHighlightStep take a parameter if it should wait for the user or not.
• Most if not all parameters to the ***Step-constructors can now in addition to be literal values also be an instance of TableKey. The TableKey constructor takes one string that will be used as key in the chapter storage table. This way a step can do delayed access to the storage table. (Steps are constructed when the chapter is loaded, so they need to somehow delay reading of variable content)
• The MessageWindowStep now have a variable argument count for the constructor. After the wait parameter one can now supply additional parameters to the message assuming that it is a GSText instance. This way you can pass a TableKey instance to reference a variable that eg. contains a town index to be displayed in a message.
• New steps: CloseWindowStep, WaitOnWindowStep (with parameter to wait for close or open).
• Improved chapter organization in main.nut
• Removed chapter_bus.nut
• Added chapter_xyz.nut for intro, airplanes, ships, road_vehicles and trains.
• Added strings for intro and airplanes
• Coded intro and about half (if not more) of airplanes chapter.
• Made a OpenTTD feature request for GSOrder in order to be able to wait for aircraft orders.

If you are adventious and want to try it out, I've attached the current version. But be aware that you will make it crash at the end of the tutorial and that it is very much work in progress.

Known problems: (which I have quite a good idea on how to solve, but hadn't had time to do it yet)

• When you are asked to give an order to your aircraft, the tutorial ends with a crash on that the index ID doesn't exist. (it happens because I've introduced a function that it expects to find in all chapter classes but I have only added it in the intro + airplanes chapter so far.)
• If you close a message window with the "X"-button, the tutorial will just sit around and wait for the button click event and not detect that you have closed the window. [easy solvable in the code, just not done yet]
• Loading save games don't work. At least if you try the attached save game, OpenTTD will crash. I plan to make a proper bug report about this once I've ran OpenTTD in a debugger to get an idea on what in my code causes the problem

Wording changes
If you spot issues with how the messages are worded, please post suggestions. When you do so, please post a patch or a complete new string along with the entire string ID which starts with STR_ and can be found in lang/english.txt (attached in next post). Though, you are also welcome to in addition explain what part you changed, but for me to include the changes it helps a lot if I get the string ID to have the context.

I don't think yet it is time to translate the tutorial as the English strings will probably change a bit.

Tutorial-v3.tar

(65.5 KiB) Downloaded 143 times

GSTutorial Crash.sav

Warning: OpenTTD crashes when you load this savegame (at least when the tutorial script is available)

(444.59 KiB) Downloaded 138 times

[Zuu]

lang/english.txt

[planetmaker]

Very nice, Zuu!

I comitted a German translation to the repository.

[bokkie]

Wouldn't know how to commit (I guess I don't have rights either ) so here's a dutch translation.

I have almost no coding knowledge, but does OpenTTD understand in STR_AIRPLANES_1_2_2_BUILD that you mean two different towns?

[Zuu]

Thanks for translating. Though, as the English strings might need some more work to round out some edges, you will need to keep track of that work and possible update the translations too. That is why I would suggest delaying translations a bit. But if you want to commit to follow these changes and update the translations, I will not stop you. Just mind that there is no such system like for OpenTTD where you get a "string needs to be validated" message when a string changes.

The reason why I posted english.txt was to allow people to suggest improvements to the English strings. I've just copied them from the last chapters document and seen that some of them will probably need some work to improve the standard.

I don't think yet it is time to translate the tutorial as the English strings will probably change a bit.

So translate if you wish, but don't complain if the English strings get significant changes.

[planetmaker]

So translate if you wish, but don't complain if the English strings get significant changes.

Yes, I'm well aware of that. Actually when I translated it, I thought in a few places that it might be a good idea to slightly reword the English strings. But well... it's a start.

As for keeping up to date, there's a short bash script (run from the lang folder) which iirc mostly Terkhen wrote (and now will curse me) and which we use to check update necessity for translations for NML-based NewGRFs. As the text files have the same format, that will work here, too:
http://dev.openttdcoop.org/projects/new ... k_language
It requires (part of the) language file name as argument.

[Zuu]

Update - Version 4

Changes:

• Add: OrStep - a way to combine several steps that wait for the user and continue when only one condition is satisfied
• Add: All steps of the Aircraft chapter is now coded. (only exception is that OpenTTD doesn't (yet? ) let me code the steps that wait on an order to be created)
• Fix: save/load now works better (safe load points is not done yet, so only save at places when you don't have a window open (other than the tutorial window) for now)
• Fix: Detect when tutorial message windows are closed (eg. by hitting the delete button or clicking on the "X" button) and take that as the same signal as clicking on the continue button.
• Change: Display messages as a information dialog and not a question dialog (requires at least 1.2 beta 3 or the nightly that will be released tonight)
• Change: Use SuperLib 19
• Several changes to english.txt - so the translations are now broken as I warned you.

The bug in OpenTTD with the save game loading that caused OpenTTD to crash has been solved today by the OpenTTD developers and is included in 1.2 beta 3 and the nightly that will be created in a few hours.

OpenTTD requirement

• 1.2 beta 3
• r23829 or later (no nightly exist after this version when I write this)

Tutorial-v4.tar

Requires SuperLib 19 (nogo edition)

(76 KiB) Downloaded 180 times

Edit: As per suggestion by planetmaker, the attached english.txt and english.txt.diff have been removed. Instead you can find them directly in the repository:

• english.txt
• english.txt.diff

[Pingaware]

I've just re-drafted all of the English strings, using Zuu's strings as a base. Not a lot has changed really, but the syntax and use of words is now more consistent both with the tutorial itself and native speech. I also took the liberty of adding in a 'Close the orders window' instruction, as when running the tutorial through, it seemed like this was not obvious and could produce strange results for completely new users. Finally, is there any way of making quick order creation compulsory for the tutorial? I found that when following it through, without this setting on I did not create my orders when explicitly following instructions.

I'd be interested in all your comments.

Cheers,
Pinga

Edit: Also, does the game always start paused? That needs consideration as well

[Zuu]

Thanks for your work. I've added your strings to the tutorial. The only change I had to make was that the dash? and ' characters where not recognized as UTF8 characters so I had to fix that. Actually, I couldn't see which character you have used but hopefully my guess is correct.

Update - Version 5

Changes

• Add: Updates to english.txt by Pingaware
• Add: ConditionalStep
• Add: If quick_goto is off, tell the user to click on the GoTo button when it is needed
• Change: Show as "Beginner Tutorial" in the selection of game scripts. (unfortunately this means that those of you who have version 4 need to remove it manually from content_download in your file system in order to remove the "Game Tutorial" entry)
• Fix: Use the airport station ID and not the town ID as string parameter
• Fix: Update order instructions to suggest not to click on the hangar

Known bugs/limitations

• You must click continue after adding orders until FS#4994 is implemented and an update to the tutorial that uses GSOrder is released.
• There is no general indication on the window if clicking on "continue" is enough to continue or if you expect to do something.
• You can't go backward in the tutorial if you accidentally hit continue.
• In the future the tutorial will be connected to a scenario where the towns to connect will be hard-coded. Therefore the town selection is now completely random. (it uses town id 0 and 2)
• The tutorial is designed to be used without NewGRFs. Eg. the name of the aircraft model that is suggested is hard-coded into the string.

english.txt (for review or suggestions on how to further improve the English strings)

[Pingaware]

Thanks for your work. I've added your strings to the tutorial. The only change I had to make was that the dash? and ' characters where not recognized as UTF8 characters so I had to fix that. Actually, I couldn't see which character you have used but hopefully my guess is correct.

Thanks Zuu. Unfortunately, I've been highly critical of my work and have already done a further draft of the strings, this time changing any 'we' sentences to 'you' sentences, as this seemed most consistent with other game tutorials. As a result, I've uploaded a new draft below. I've included an MS Word copy of the strings, to make sure any unrecognized characters can be identified, although I didn't see any problems with the strings in my new play through.

Sorry for causing trouble so soon!

Cheers,
Pinga

Edit: And just to make clear, I actually enjoy doing stuff like this. So I'm not going to do anything like claim sole rights over the strings as they're not my rights to claim, but I warn you - I'll be updating these pretty frequently, and certainly whenever you add in significant new chapters and sections.

[Roujin]

Okay, so I have played through the tutorial in order to test it, and have taken the following notes. As always this is meant as constructive feedback, just assume that all things I don't mention are great

General suggestions:
1) Can you make the window pop up somewhere else than in the middle of the screen? It's obstructive there and it's irritating that you can move it somewhere else, but then once you click continue it will be in the center again. So I suggest to either remember where the previous window was, or at least display it somewhere in the top left. If neither is currently possible I would like to make a feature request to the OpenTTD devs to enable one of these two things.

2) General movement is never explained, e.g. how to move the window (right click and drag mouse, or use arrow keys). I know there are alternative movement schemes, but I'd say we can assume standard settings here.
I'd make a new chapter about this and show it before all others.
Things that could be shown in such a chapter:
- Moving the viewport
- Zooming out/in
- Using the map
- Using the town list to locate a specific town (conveniently, this could be the first town you use in the following chapter)
- But don't add any more / too much, to not make it boring before the "real" stuff starts.
In the following chapters you could then let the user navigate by himself more often. It's less disorienting than just jumping to the towns without warning. And if you must jump, tell the user beforehand: "Click continue to jump to XYZville".

3) Give a choice at the beginning which "chapter" to jump to instead of just displaying the chapters and then playing them in order.
You could write that it's recommended to do them in the given order, but if someone wants to learn about a specific thing, they can then do so.


Comments about the Airport tutorial:
1) For the order to the second airport, the tutorial mentions that you should not click on the hangar tile. It should explain that for the first order instead.

2) When the user is prompted to look at the station details, he is likely to click on the 2nd airport, which the plane has not yet visited at that time (except the user is suuuuuuuuuuper slow ). Per default settings (IIRC) there will be NO pax/mail piling up and no rating before the plane arrives there. This should be mentioned in the tutorial, or new users might be confused ("WHERE are the waiting passengers, WHERE is the rating? Am I looking in the wrong place?").

3) In the step "We are going to try to build an airport near this town. Please click on the highlighted buttons, starting on the main toolbar.", it only starts to blink once you've pressed "continue", which is inconsistent to other steps. Also, if you already click on the aircraft button before clicking continue (let's assume someone plays this who already knows where the airport button is), the tutorial gets broken. It will highlight the airport button once you click continue, but if you click the airport button then, the tutorial does not go on.


This is all for now. Hope it helps.

[Pingaware]

Comments about the Airport tutorial:
1) For the order to the second airport, the tutorial mentions that you should not click on the hangar tile. It should explain that for the first order instead.

I claim responsibility for this one. I must have accidentally deleted the hangar tile reference as it was certainly there originally.

Cheers,
Pinga

Edit: Updated strings below. Reflecting changes Zuu's made today.