Documentation: Manuals and Tutorials

[Richard Bruns]

I think we desperately need a tutorial. When I opened up Clash I was confused. Even though I read the manual beforehand, I was confused. Despite the fact that I've been on the team for upwards of two years, I didn't know what to do. Mostly this was due to the fact that I have not been heavily involved with the military and econ models, the two main things the demo has.

The current trend nowadays in games is to open the game up and start playing. This is especially the case with demos. None of the professional demos I download have ever come with manuals. They come with a tutorial/walkthrough scenario with some advisor telling me what to do.

This system works. It works well. People expect it. We don't have it. I think that may be a big reason that people who try thr demo walk off confused.

I vote that all manual writing efforts be devoted entirely to creating a walkthrough scenario. Vets don't need a manual and if the walkthrough is good newbies won't either.

Someone would open the game, choose a scenario, and see: Tutorial: Romans. They'd click on it and a popup window would come up, introducing an advisor. Give him a name, like Proconsul Marcus. This advisor tells the player what the game is, what the missions are, and what to click to accomplish it.

He should probably start by introducing the economy, explaining civ orders and square orders. (These should probably be renamed to "city orders" for now.) He would tell the player what all the boxes mean and how to read them. He would direct the player to do something like increase kapital production.

When the game detected that the player did so, Marcus would tell the player how to build a road. The game then checks for completion of that before having the next tutorial come up.

Then the advisor would tell the player how to make units and how to move them around. He would guide the player, step by step, through the capture of a neutral city. Obviously this would require a premade map and not a random one. A real map of central italy, like the one in demo 4, would be great.

At that point the player should know the basics and could finish the scenario. I guarantee that if this is implemented in even a miminal fashion, people would be a lot more impressed with the game and will stick around to make comments.

[LDiCesare]

Richard, I agree with you. In fact I had proposed something along those lines to Mark.
Mark, I come back to my events-for-tutorial thingy.
The proposal was: Code a tutorial scenario (needs a map, an advisory button and some reactivity to the player moves).
At the beginning of every turn, checks are made to decide if the player needs some info.
For example on turn 1, they will be prompted to look at the civ econ orders window, and change the figures if they like, plus up some kapital. On turn 2, it could propose to open up province econ orders (or square) to up the unit production on the frontier.
On turn 3, a road orders could be proposed and indeed we can wait until it is built before we go on (or check that a few turns have passed and nothing is being done and reissue the window).
On first turn when an enemy appears somewhere, they will be prompted to up the military production in nearest city.
When the first new unit pops up, the player will be explained how to move it along.
When the second unit comes in, they will be explained how to add them to others to create task forces.
The advisory button I don't really know what to put behind, except a link to the doc.

[axi]

I propose that for now, we should just rewrite the manual and add a step by-step tutorial for one ore more scenarios in there.

IMHO, we are in a too preliminary phase right now to do such a thing, although eventually it is necessary.

[LDiCesare]

The point is: People don't read manuals.
I think changing a scenario into a tutorial is easy, so I'd vote for doing it.

[Mikael]

Yes, a tutorial scenario is needed. I myself am a bit confused with the way the econ model works, even though I read the documentation.

[Chris Wilkinson]

Guys,

I've just taken over the documentations part of the project (again) so I'm going to re-do the manual and start creating things like tutorials.

[LDiCesare]

ris, can you describe a tutorial scenario (what it should be) so that we can code it in (if Mark agrees that's a priority)?
I would like to be able to have a scenario with
1) pop-ups to help the player
2) links to an html reference doc.
(which kind of answers your question in another thread).

[Mark_Everson]

Hi All:

Laurent, sure, go ahead and go for it. It seems at least a reasonable fraction of people think its needed. You should discuss code architecture for the game events stuff with Gary first, just to agree on a robust overall approach. My take is we should use the same "scenario events" as for things like changes in diplomatic status on turn X that we were talking about by email. I Think that is what you intend, but I just want to make sure.

If the tutorial is written up in the manual, then it will only take a moderate amount of work to transcribe it to an in-game tutorial. It looks like you have things well in hand. I'll monitor this thread, and only speak up if I see something I think will be a problem. Hopefully Gary will see this too, since he was keen to get something similar (online help).

[LDiCesare]

My take is we should use the same "scenario events" as for things like changes in diplomatic status on turn X that we were talking about by email

Yes. That was my intent in the first place. Indeed, I will check with Gary about the architecture.
What about using the Demo4 Italy map? I think I can find the D4 code for it and adapt it for the scenario. Chris, when you have a paper/html tutorial, I'll try to plug it.

[Mark_Everson]

Posted for Gary Thomas (he can't post)

I have been keen on this for quite some time. It also ties in rather well
with the event system we have been talking about for scenarios. "Event, turn 1, display message1" or some such, or "when economics screen first opened display message 2".

I really do hope to have the scenario input system going very soon, so it
could be synchronized with that. D6.2 looms.

[edit]
Now My post:

Getting the old world map, or at least bits of it, working at some point is a good idea. Probably best done when we have a spec for reading maps into the program. It shouldn't be Too hard to get the map out of D4. But one issue you should know about is that the world map there was originally done in plain Cartesian coordinates, like Civ 1. I then rotated it in the software so that it matches the iso coordinates. When the time comes, if you need help, let me know.

[LDiCesare]

Getting the old world map, or at least bits of it, working at some point is a good idea. Probably best done when we have a spec for reading maps into the program. It shouldn't be Too hard to get the map out of D4. But one issue you should know about is that the world map there was originally done in plain Cartesian coordinates, like Civ 1. I then rotated it in the software so that it matches the iso coordinates. When the time comes, if you need help, let me know.

I found the relevant code and map. I will have to write some code to read the array of short into a D6 thingy. I guess translating into the persistent format would be good. I think I see where the terrain is, but don't know about the other info. This will wait till we have persistence done if Chris Maeda makes the load stuff soon. Meanwhile, I was wondering if a map editor wouldn't be handy... I am pretty sure it is too much work to considerate, but maybe Gary has some ideas about it, so I think it wise to begin talking about it.

[Gary Thomas]

When I started with Clash I remember pleading with Mark to let me work on a random map generator. He insisted that there were much more important things to do. Perhaps he was right.

As far as the data for a map is concerned, I feel that the data should be in at least two separate sections - the raw map and any improvements. The raw map will not change during the course of the game (see my incremental saves theory in the background?) and hence does not need to be saved.

In the immediate future, it is likely that the only improvements that will be encountered are: cities, roads, deforestation and cultivation (or settlement). Each of these has quite a limited amount of data, and nicely overlays the main map.

The substantive map consists of a rectangular grid of squares (no, I won't mention polygons again in this post). Each square has four (or fewer) parameters. The parameters are: x-coordinate, y-coordinate, landform, and landcover. So an xml file with entries like:

&ltsquare&gt
    &ltx&gt 11 &lt/x&gt
    &lty&gt 21 &lt/y&gt
    &ltbaseterrain&gt
        &ltlandform&gtflat&lt/landform&gt
        &ltlandcover&gtnone&lt/landcover&gt
    &lt/baseterrain&gt
&lt/square&gt

would cover it. It would be even tider as:

&ltsquare x=11 y=21 &gt
    &ltbaseterrain&gt
        &ltlandform&gtflat&lt/landform&gt
        &ltlandcover&gtnone&lt/landcover&gt
    &lt/baseterrain&gt
&lt/square&gt

By allowing defaults, this could shortened even further.

I would have the improvements in the form of:

&ltimprovement x=11 y=21 &gt
    &ltcivilization&gt roman &lt/civilization&gt
    &ltcity&gt 
        &ltpopulation&gtflat&lt/population&gt
    &lt/city&gt 
    &ltbaseterrain&gt
        &ltpercentagenatural&gt 0 &lt/percentagenatural&gt
    &lt/baseterrain&gt
&lt/square&gt

Writing a simple map editor for this sytem would be no big deal and just involve exporting and modifying the map frame, with a popup menu. Perhaps two day's work. Probably best if I do it, since I am most familiar with the gui. It would also be a step toward completing the xml read in system, which is my next job anyway.

The code to read this in is a really quick job using the parser.

Cheers

[Blakis Maximus]

Hi all,

I have been lurking for the past few days trying to read as many threads and models as possible (there is a lot out there - much of it outdated I believe). Seeing as how I first learned of Clash early this week, I have some observations and suggestions to make from a newbie's point of view. Hopefully most of this won't be old news/redundant.

1. First of all, let me say that I think this is a great project and has the potential to be far superior to Civ III or any other 4x game currently out on the market. You guys have made a lot of progress! Keep it up!

2. I have played around with Demo 6 and I think it would be great if there was an updated manual or in-game tutorial that explained how everything works. The economic model is ambitious and needs to be better explained (I still don't know what ROI means). I'm not saying dumb it down; the detail and complexity is great (traditional vs market economy - awesome!).

3. As I'm sure you know, the interface needs a lot of work to make it look more like a game and less like Microsoft Excel.

4. I've seen a lot of discussion on terrain and unit graphics and the like. Is there a reason you're not simply using all the great graphics from modpacks that have been created for Civ II and Civ III? It seems to me there are a lot of mature graphics out there that would work great here, and you could save yourselves a lot of time by not reinventing the wheel. The graphics in Demo 6 are nice but they aren't as polished as some of the stuff out there.

5. Tiles in the map that are double-clicked and right-clicked should show appropriate information. Correct me if I'm wrong, but I don't think there's the equivalent of a city view screen in Demo 6.

6. Why can't I just use the arrow keys to move a unit one tile at a time?

7. There needs to be keyboard shortcuts for everything. Using the mouse is slow.

8. Of course, this isn't necessary now but sound would be nice. Again, there are some great user-created sounds out there.

9. Showing the progress of a battle would be nice.

That's about it for now. I don't know if this is appropriate but have you guys thought about make your source code available. I would love to get the chance to look through it even though I don't have the time to actually add anything useful (I'm in the process of switching jobs, which is somewhat stressful). I'm a pretty good Java programmer and I think it's cool that you've chosen to develop with it...

[Gary Thomas]

Another Java programmer - quick, catch him before he gets away...

3. As I'm sure you know, the interface needs a lot of work to make it look more like a game and less like Microsoft Excel.

This is in the pipeline. It will still be tabular though, using swing tables.

4. I've seen a lot of discussion on terrain and unit graphics and the like. Is there a reason you're not simply using all the great graphics from modpacks that have been created for Civ II and Civ III? It seems to me there are a lot of mature graphics out there that would work great here, and you could save yourselves a lot of time by not reinventing the wheel. The graphics in Demo 6 are nice but they aren't as polished as some of the stuff out there.

We don't use them because:

1. They are not ours.
2. We haven't the time to find them and dig them out (volunteers?).
3. Many are in odd formats - we haven't the resources to do format conversions (voluneers?).

5. Tiles in the map that are double-clicked and right-clicked should show appropriate information.

In the plan.

Correct me if I'm wrong, but I don't think there's the equivalent of a city view screen in Demo 6.

Don't know what this means.

6. Why can't I just use the arrow keys to move a unit one tile at a time?

You can, unless it is broken. Too busy to check just now.

7. There needs to be keyboard shortcuts for everything. Using the mouse is slow.

Also in the plan.

8. Of course, this isn't necessary now but sound would be nice. Again, there are some great user-created sounds out there.

A long way down the track. Before that we need things like saving games...

9. Showing the progress of a battle would be nice.

Ditto.

Cheers

[Blakis Maximus]

The "City View" screen is just the window that pops up when you click on a city in games like Civ III. It shows the unit that is currently being built, the improvements in the city, etc.

A long way down the track. Before that we need things like saving games...

Ahh yes, saving would be good. Also, any word on releasing the source? Thanks...