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]

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...

[Mark_Everson]

Hi Blakis Maximus:

Good to see you're intrigued Thanks for the encouraging words! How did you come upon Clash anyway?

If you email me at markeverson@mediaone.net I will mail you the source. It won't be runnable since there will be changes in a couple of days that will mean we'll no longer require the Xerces xml package to run. So I'd prefer for now just to send you the source and a couple of the xml ini files for you to look over. That way you won't need to get xerces etc. You can then look over where things are and whatever. If you absolutely want something runnable, I suggest you wait a few days.

The Clash equivalent of a city is a province, which is a city plus the other land. We clearly need an overall Province GUI at some point... There is no such view because we haven't gotten 'round to it yet. The econ screens do some of that stuff, as you probably know.

Probably the best up-to-date thing to look at is the D6 manual. Therein you can find the meaning of the power word ROI!

Looking forward to more fresh-eyes comments, and even More to putting you to work at some point in the future.

-Mark

[Blakis Maximus]

Hi Mark,

I sent you an email - thanks by the way. I peruse the threads here at Apolyton and Civilization Fanatics, mainly in the Customization and Creation sections since I feel Civ III is lacking in some important ways. I saw your response in one of the threads here with the link in your sig. Since then, I've been trying to read as much as I can about the project. I like what I see!

On a different note, have you implemented your own XML parser or are you scrapping XML and moving to something else?

Blakis

[Gary Thomas]

On a different note, have you implemented your own XML parser or are you scrapping XML and moving to something else?

We have our own XML parser which uses reflection in order to be very easy to use. We don't need the features of SAX or the general horrors of DOM. Zipped, our parser code is 8K...

Cheers

[Mark_Everson]

Originally posted by Blakis Maximus
I saw your response in one of the threads here with the link in your sig. Since then, I've been trying to read as much as I can about the project. I like what I see!

Good to see all the not-so-subtle plugging is paying off!

Blakis, could you copy your initial post over to the D6 thread? That way, the next time I sweep through it to update the bug and small feature lists, it will be there so I won't forget. If you can also tack on Gary's responses from this thread it'd be great. (In case you don't know how... Just edit his post so you can copy the whole thing including codes, and then tack it on to the end of your new post with something like "Gary Thomas' Responses:".)

[Blakis Maximus]

It's now posted in the Demo 6 Comments and Bug Reports thread...

[Mark_Everson]

Time to start thinking about this again as Demo 7 approaches. Chris W. was never able to do anything on the manual. We have a new guy who is going to give it a shot, who hopefully will be introducing himself soon. Please make any further comments on the manual here if you want your ideas included in the rewrite for D7.

Here are my high-level thoughts on the issue to get the discussion going again:

I think the best thing to do is that we aim for all of: a manual, tutorials, something like a civilopedia in civ, and an online tutorial. So if you can try and write the manual in small enough pieces it can be used in any of these, I think that's best. That said the questions that most come up in the D6 thread are obvious places to improve the manual.

See also: The On-line help system

Reworking our Demo Approach

and starting with Gary's post of 29-03-2002 17:07 in the
Planning for Demos 7 & 8 thread.

[axi]

Mark: I don't have much to say about the manual. I feel it should begin as a walkthrough and then have chapters explaining the various models. In-game help is out of my league.

[Erasmo_Ramos]

Hi everyone,

I'am the new guy who is going to give a shot at writing the manual. My main goal at writing this manual is to make it understandable and cover enough material so people playing won't get lost.

Right now I'am deciding on what the layout of the manual is going to be. My idea is simple:

1. Sections that give info on certain areas of the game.
2. At the end of each section give a small tutorial on how to use what the section talked about (I.E. How to move a unit)

I will also try to make a tutorial for those ppl that don't want to read.

[Mark_Everson]

Hi Erasmo, and Thanks for putting effort into this important area.

Axi's idea of starting with a walkthrough for each area seems good to me. The walkthrough parts could serve as a component of the online tutorials nicely also.

Looking forward to seeing what you come up with!

-Mark

[Mark_Everson]

I am beginning to work on the in-game tutorial for Dawn1 in Demo 7. (Erasmo has pulled out due to lack of time, leaving me as the sucker-by-default...) This will use Gary's Event system to display messages to the player when appropriate.

My immediate question for now is what is the best format to use for these messages. I need to know what I can use for D7, and also would like to have an idea of where we're headed longer-term.

1. Can they be HTML, or must they be plain text for now? Long-term I think we've agreed they should be HTML.

2. Must all messages be in individual files, or can we use a tagging system to put them all in an xml file? The former would work for now, but I think may quickly get out of hand. The latter is my long-term preference, but not based on a huge amount of thought.

[LDiCesare]

You can use message files with tags like <message id="">
Whatever is inside the message tags is shown to the player. The id allows to find the correct message in the file. Actually, it is a goos idea to load the file once and build a hashmpa of messages if you do it that way.

[Mark_Everson]

Thanks Laurent, that's good to know. I'll assume that's the way it'll be handled for now, pending hearing from Gary. I hope to have some examples soon that I can post and ask people if they're heading in the right direction for what we need for D7.

[Mark_Everson]

I just tried setting up my first tooltips for the old econ gui. In some cases I'd like them to be several lines long, for example to explain ROI's uses. When I put in a long text (several hundred characters) only a small part of the tooltip message ended up getting shown. Anyone know if there's an easy way to override this behavior so you could have a looong tooltip? I guess I'd need to override one of the ToolTip methods in JComponent or something like that. Anyone know offhand what the right way to do it is, since I need to get back to work anyway , and this is not urgent.

[LDiCesare]

I don't know much about tooltips, but I think long tooltips are bad from an ergonomy point of view.
Based on comments by Age Of Wonders designer, tooltips are slow to show and not very efficient for that reason: You put your mouse somewhere, then wait for the tip to appear. They used a text pane in the lower part of the screen to show tooltips instead of popping them up in that game. That means you would have a permanent text zone (in that game, it was one line but it spred the whole screen wodth) in which tips appear. We could use that, maybe make it 2 lines long if you really need long messages. Also, with such a text zone, you could have a Help/Details button or whatever which would launch the online help on the appropriate topic.
That would let you use one or two screen-width of characters, probably around 100-200 characters, plus maybe a scrollbar?

[Mark_Everson]

Hi Laurent, yeah I think you've got a point. Well, I'm using tooltips for now since they're easy. But tooltip-like comments could go in a dedicated area like you say. I thought the text box of maybe 6 rows at the bottom of the screen in EU2 was useful. Have to talk this one through, but so far your idea sounds good.