Documentation: Manuals and Tutorials

[axi]

I agree with Laurent - a tooltip should be displayed in some sort of textbox.

[Gary Thomas]

I overlooked the discussion in this thread, so my comments will cover a fair bit of territory.

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.

I have an event display action which does all this. Any HTML in the text will be reproduced in the resulting dialog. It does not affect the computer code.

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.

I am not quite sure what is intended here. The messages will be, for the moment (hated phrase) embedded in the scenario xml file. Later I would hope they would be a tag reference to a message oin a resource bundle, for internationalization purposes.

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.

The format will be:

&ltaction&gt&ltmessage&gtThe text of the message&lt/message&gt&lt/action&gt

for a simple information message. I can provide a yes/no dialog, but that would also have to set a condition.

I am having something of a conceptual problem with conditions - something has to test them or they won't do anything. That part of the system is rather unclear at present.

On the subject of tooltips, they are not help messages, as Laurent says, they should be brief. The EU system is different and more akin to the information box system. My personal preference is for short tooltips, but a right button menu which always includes a help message.

Cheers

[Mark_Everson]

Thanks Gary, that's just the info I needed.

Originally posted by Gary Thomas
The messages will be, for the moment (hated phrase) embedded in the scenario xml file. Later I would hope they would be a tag reference to a message oin a resource bundle, for internationalization purposes.

Sounds good, but its gonna be a looong file for D7

for a simple information message. I can provide a yes/no dialog, but that would also have to set a condition.

I am having something of a conceptual problem with conditions - something has to test them or they won't do anything. That part of the system is rather unclear at present.

K, just let me know when you've got it figgured out, and what the tags are... For a first shot I think a "turn number" event tag is the most important since it'll allow at least a "slide show" type tutorial. We will also maybe need some definition of a turn 1a (first shown) vs turn 2b message.

On the subject of tooltips, they are not help messages, as Laurent says, they should be brief.

I settled on short tooltips for now. The code I just sent has them for the EconOrdersFrame. The tutorial will have to do the rest for now...

[Mark_Everson]

What we need for Events, a starter list.

I don't recall seeing a spec, but I assume events are composed of triggers and actions. Triggers are what the event looks for to activate itself, and actions are what it does. I'll try to get 'em in more or less priority order. This is a stream-of-burble list, so I"m sure I've missed things.

Triggers:
1. "turn number" We will also maybe need some definition of a turn 1a (first shown) vs turn 2b trigger (once 2a's action completed).
2. Population attained = x
3. Square visited or newly controlled by civ XXX (loss of control/gaining control of)
4. Economic Special discovered (can use 3 if map is predetermined)
5. First military unit built, or first of given type
6. First of a given type of economic infrastructure built (farm, road,...)
7. Meet first other civ, or meet particular civ

Actions:
1. Show an HTML dialog box, optionally with a choice for the player to make the choice is between two defined actions
2. Destroy infrastructure (or change its level)
3. Createte / Destroy units. Acutally, creating units is also very very used in scenarios.
4. Change terrain -- also used a lot, including destroying cities therein.
5. Enable or disable an infrastructure class in the econ gui
6. Enable or disable ROI characteristic in econ gui
7. Change diplomatic status

[edit] included Laurent's suggestions from post below

[LDiCesare]

There was a thread about events here . There are a few events summed up in it, so you can add:
Triggers:
Square newly controlled by civ XXX (loss of control/gaining control of)
Actions:
Destroy infrastructure (or change its level)
Destroy units. Acutally, creating units is also very very used in scenarios. Changing terrain is also used a lot, including destroying cities therein.
Win.
Lose.

[Mark_Everson]

Thanks Laurent, I'd forgotten about that thread!

I have updated the post above with your comments. I'm wondering if we shouldn't put the fairly small amount of events stuff here into the event-specific thread? Seems better long-term...

[Mark_Everson]

This is a cross-post of what I said to Dale in another thread on how to get him going on a tutorial for D7. This is the natural home for my points and any discussion on the topic.

[To Dale] Here is what I think you should do.

1. Download and play D6 and read the manual

2. Give any feedback you feel important on those

3. I will get you the "Clash testbed" code which has an early version of D7 that you can start writing a tutorial on.

4. You should skim the
Planning for Demos 7 & 8 thread to see the things we wanted the tutorial to do. The plan has evolved somewhat since the beginning, so read more carefully near the end.

5. Also look over the Documentation: Manuals and Tutorials thread, which is the main place for discussion of what the tutorials should have.

6. Once you get a chance to discuss what approach you'd like to take, and gotten some feedback, post an example of a few of the html blocks you would like to use for the tutorial, and what triggers them.

7. If you can't do 1-6 within the next 10 days or so, then I will need to take over the job, because Demo 7 can't wait forever for the tutorial...

After 6, try a draft of a complete tutorial for the Dawn scenario.

This job should get much more interesting for you with demo 8, for which I would like to have a map editor, and the capability for you to make up your own tutorial scenarios, and mods!

If you think you can't do this job at any time, Please let me know, so that I can start in on doing it myself. There isn't a lot of extra time to get the tutorial done considering the work needed.

I'm going to cross-post this in the Documentation thread, since that's where it really belongs. We should continue the discussion there.

Hope you can make this work! (Especially since I hate doing it )

Mark

[Dale]

Points 1-5 done already mate.

For the approach I'd like to take, I'll try to start a tutorial plan along the lines of what I described in this thread: http://apolyton.net/forums/showthrea...9&pagenumber=2

I'll get back to you when I've got a better draft of a tute convering what's in the testbed.

[Mark_Everson]

Hey Dale:

Glad to hear you are getting into this! I've got one issue with your approach though, in that you are ignoring the overall plan of making Dawn a tutorial scenario. I know that you don't agree with the slow-start tutorial philosophy as expressed in the Dawn scenario. Nonetheless, it is what pretty much the whole team agreed we should use for the tutorial. (Although many of us would like to spice it up a bit, as you can see from the discussion.) I'm also a bit concerned that if you go off designing your own tutorial scenario from scratch, that you might run out of time and leave us with no tutorial whatsoever .

So here's what I propose to bridge the difference between your desires/plan and the overall plan. First, do a little bit of the "introduce the interface" type tutorial frames for the Dawn scenario. Those should largely be able to be carried over to your preferred scenario anyway. This will give you something of substance as in what I had in my 6 above that you can show the group early. In parallel with that you can start designing your scenario and the tutorial you want to write for it. Again, most of the description of interface and introduction to model stuff will be common between the Dawn-based tutorial and the one you are doing per your spec. Since the Dawn-based tutorial will be simpler, I'd hope you could have that one pretty much finished first, while moving ahead on your handcrafted one. Does that sound like a workable compromise to you?

Catch you later,

Mark

[Dale]

Mark:

No probs mate. Dawn coming soon. Actually I like your point. Dawn could be like an introduction to Clash, and the Egyptian one I proposed could become Clash's first campaign. How's that sound?

[Mark_Everson]

Hey Dale, sounds good! We've achieved a plan

Can't wait to see it come together

With luck the event language will be up to a slideshow-tutorial scenario in a week or so. Y'know, first read slide 1, then read slide 2 and do what it tells you...

[Mark_Everson]

Dale, if you're out there...

Dale:

If you want to do the Dawn tutorial job, you've really got to start making further progress Now. I probably have an email virus, so I'm hoping you're checking the forum.

Gary has things at least close to ready to put html popups in the game. The time to act is now! If you can't do it reasonably fast, showing serious progress by the end of the weekend, I'm going to have to do your job. I would prefer not to!

Please let me know what your status is...

Thanks,

Mark

[Gary Thomas]

All that is done now. I sent Mark the code, and posted the scenario creation rules manual to the Demo 7 testbed thread.

Cheers

[Mark_Everson]

New shot at tutorial text, comments and criticisms welcome!

Here it is, just let me know what you think in terms of:

Too much, too little per turn?

Right depth in terms of features explained, too shallow, too deep?

Does the "story line" add enough given the screen room deditcated to it, should there be more or less...?

I'm really just getting started, so if you want a different approach, Now is the time to say so!



Dawn Tutorial Message Windows!

Note, I expect to put the advisor's comments in italics, or use some other means to distinguish them from the generic explanation text.

Opening screen:

Welcome

Thanks for trying out the Clash of Civilizations Demo 7! This version of the game is a demo of our design concepts. That’s so that we can get early suggestions from anyone who’s interested on what is working well, and what needs to be done differently. The demo is an alpha version that is maybe 10% of the way along to the final game. The most important feedback you can give the team is telling us if our approach for different parts of Clash seems to be going in the right direction or not!

Trigger: Begin Game.
Objective: None
Buttons: Next

Objective 1: Settle a Village (Screen 1)

“From the Chief Advisor:
As the leader of our people you must guide us to greatness in science, diplomacy, culture, economy, government and expansion. With my help, your humble Chief Advisor Juninga, you will do this.
Our goal is to settle this land and grow our people both in numbers and military strength. It is only through such strength that we can protect our people against the rampaging barbarians are rumored to be coming.


At present we have 5000 people who are currently being protected by our warrior horde unit. First we must find a suitable location to settle.”

Trigger: Begin Game.
Objective: None
Buttons: Next

Objective 1: (Screen 2)

“From the Chief Advisor:
The large window on the right which fills most of the screen is the Map Window, which represents the world as we know it. At the top left is the Units Window with the information about the units in the currently selected square on the map.


As you can see from the wagon icon on our warrior unit, that unit has settlers, our people, traveling with them. Right-click on our warriors in the Unit Window now. You will see that one of the available unit orders is, at the bottom, is Colonize. Click on this order and then OK to confirm the construction of a new settlement with our 5000 people. Once that is done, push the End Turn button at the top.

END OF TURN 1

Objective 2 Teach moving units: (Screen 1)

Great Chief, we have heard from other wandering tribes that in the hinterlands there are wondrous things that can aid our people to grow strong. They speak of powerful beasts that can aid in our war efforts, and grains that will make our farmers more productive. I humbly suggest it is time that our warriors be sent out to explore nearby lands.

Objective 2: (Screen 2)

To give the warriors orders as to where they should go, you use the Move button on the toolbar. Then click on the square on the map where you want the unit to go. This will show the movement path, and the number of turns it will take to get to each square. Don’t go too far for now, a few squares away is best. Movement is simultaneous in Clash, so the unit won't actually move until you press the New Turn button. If you want to examine a potential movement path before committing to it, right-clicking on a map square will do that. You can also enter move orders (and also cancel them) using the same right-click in the Units Window that you used to issue the colonize order. Now end the turn to see the unit move.

END OF TURN 2

Objective 3 various interface and auto-settlement: (Screen 1)

You will see that your unit has executed its movement, pushing back the black unknown territory. You should search to the north east of the original settlement, trying to find, and move into, a square containing a wheat icon.

On the main map, another square is outlined in blue, showing that your people have expanded your area of settlement! As the population of each square grows, hardy souls will fan out to adjacent lands and settle new villages if they see opportunities. They will do this automatically for you, so there is no need for population micro-management. You can find important information about individual map squares in the Detail Frame at lower left. It tells you about the population and other important information for the selected square. If you click on the newly-settled square, you'll see how much of your population has migrated there.

One other thing to note is that the Turn Events Window has popped up, displaying information on what happened in the previous turn. More on this later. For now you should just issue new orders to your warriors if needed, and end the turn.

END OF TURN 3

Objective 4 building a unit: (Screen 1)

Sir, I feel our settlement is in danger with our warriors afield exploring. Perhaps we should equip another group? With things going well, and the population expanding, it seems a good time to be prudent.

It's time to take the first look at issuing economic orders in Clash. Hit the button on the toolbar that says "Economics", and select "Civ Econ Orders". This will pop up two frames that constitute your economic control panel for the demo. One is the Econ Orders frame for the civ, and the other gives Econ Info on the sectors (like farming) of the economy. For now, focus on the Orders Frame. (Yes, we know the interface is ugly, it will be scrapped at some point soon ;-) )

Ran out of gas here!

[LDiCesare]

One other thing to note is that the Turn Events Window has popped up, displaying information on what happened in the previous turn. More on this later. For now you should just issue new orders to your warriors if needed, and end the turn.

I think this is useless. It makes for more text to read but gives little information.
I'd replace by nothing or:
"In the event windows that pops up you get information on what occurred this turn. You can double click on each line to get more details." and make it a separate window.

You will see that your unit has executed its movement, pushing back the black unknown territory. You should search to the north east of the original settlement, trying to find, and move into, a square containing a wheat icon.

Again, the player will see this, so it's no use telling them what they saw. I am not sure that it is useful to say something about the wheat at this point as it was hinted at before.

About Objective 4, split in 2 screens, one where you give the texwt (paragraph), one for the explanations.