Polls

Default Game Speed

Log in to vote!

Latest Posts

Topic: Content and looks of the new "cheap in-game help"

Astuur
Avatar
Joined: 2009-02-28, 10:08
Posts: 733
Ranking
One Elder of Players
Location: Frankfurt / Germany
Posted at: 2011-11-12, 07:44

Hello everybody!
SirVer has openend up a LUA based opportunity to add simple help text to each of the house windows, and I am volunteering to design and type the text for all of them.
I am opening up this thread so that everybody can utter his views on the content and layout of these text that are in the making.
I have choosen this forum, because it is my firm believe that an automatic translation of such help texts will not be adequate for this kind of writing; so I expect there is a good bit of work for the native speakers of those languages that WL is already supporting.
Referencing data from the game and maybe even some graphics will be done calling Lua functions, whereever appropriate, to keep the help system easy to maintain.
( as soon as I get some clues about how to do it face-smile.png )
Opening up a new forum for help texts might be better, but for now this place is the best I could think of.

I am myself a native German speaker, but given the importance of English help text, I am willing to similtainously write those, unless of course some native English speaker steps up to do the job within a reasonable time frame.

I will post of few topics here as they emerge and hope for some feedback from our regulars.
So - come on, express your thoughts!


Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top Quote
Astuur
Avatar
Joined: 2009-02-28, 10:08
Posts: 733
Ranking
One Elder of Players
Location: Frankfurt / Germany
Posted at: 2011-11-12, 08:55

Initially I had been suggesting multiple help pages that would cover the following topics, but this idea did not make it into the game.
An example of this initial layout can be found here, and those interested in the topic may want to read the entire bug report.
Since we obviously do not have separate windows, but one large window only, (check out bzr6093 or later, barbarian lumberjacks hut) we must decide which of the following logical "section" we can still include and present in a helpful fashion:

  • General: Explaining what this house and the worker therein do in a more general way meant for new players. Also possibly the coordinates of the individual house for reference in multiplayer games and bug reporting.
  • Input: Texts that would cover all wares that enter the building. Also working ranges (lumberjacks, quarry, forrester etc.)
  • Output: Explaining what this site is producing and where these wares are needed. Also statistical data on the average output you may expect from the site per minute. Perhaps also some hints about the numerical ratio to the sites that need the product.
  • Crew: Text about the worker(s) in the building, their tools, their minimal qualification levels and whether they are promoted.
  • Building: The section explaines what space requirement the building has (small, medium, large), what wares you will get back when dismantling it, wares needed for an upgrade of that building.

Obviously we must supply the newcomers by presenting the "general" section.
Given the fact that the help is linked to the building, I think we should also inlcude this section.

I am not sure about the others.
In parts it will depend how well we can represent a clear structure in the layout.
I freely admit, that I have come to regret SirVers decision to go for one window only, already in this preliminary stage of the planning.
I miss the added structure that tabs would have offered.
I fear that a lenghty text in a window that needs scrolling, is not what a typical user would want from an in-game help.
But "alia iacta est" and we should try to cope with the situation.
Any opinions and suggestions?

Edited: 2011-11-12, 08:59

Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top Quote
SirVer
Joined: 2009-02-19, 15:18
Posts: 1439
Ranking
One Elder of Players
Location: Germany - Munich
Posted at: 2011-11-12, 12:10

Astuur, I have designed the ingame help windwo with some flexibility in mind. If you take a look at the help.lua for lumberjacks you'll realize that it returns a lua table which is basically a colection of key->value pairs. Currently, only text = "is used":

return { text = _"Hello World" }

but nothing stops us from defining a syntax in a way that works like that

return {
  tabs = {
     {
        text = _"Text of the first tab",
        tab_picture = "pics/general_help.png", -- Graphic for the tab button
     },
     {
        text = _"Text of the second tab",
        tab_picture = "pics/blua_help.png",
     },
  }

}

I can deliver this if you really want that :). Note that there will be a lot of code duplication in the various buildings that have the same tabs (for example the pics reference), so the construction of the 'tabs' array could be moved into a lua function that could be moved into a common file.

function make_tabs_array(t1, t2) 
  return { {
        text = t1,
        tab_picture = "pics/general_help.png", -- Graphic for the tab button
     },
     {
        text = t2,
        tab_picture = "pics/blua_help.png",
     }
  } }
end

return {
  tabs = make_tabs_array(_"Text of first tab", _"text of second tab")

}

Also note the "_" in front of strings. This means that this string will get translated; every text will appear in the launchpad translations page for the tribe that defines the help and if it is translated and merged back the localized string will be used. This should work already.

I realize that this is quite a paradigm shift from the conf files we have for other stuff, we're not really talking static text here but rather a programmatic approach to the help. I will help to bridge this gap as good as I can.

I have designed with flexibility in mind; however I suggest to just get started with what is available now and then refining (in various tabs for example) in the light of discussion.


Top Quote
Astuur
Avatar
Joined: 2009-02-28, 10:08
Posts: 733
Ranking
One Elder of Players
Location: Frankfurt / Germany
Posted at: 2011-11-12, 15:27

Me not programmer, Master, you know...?

Whut's all that gibberish about??? face-wink.png

Okay, serious --- glad you had that foresight, Sirver. .. and I can take a look at those lines until my eyes pop out, and wont be any smarter. But I need not, as long as others can read that.

I have two working "no frills - all in one window" examples for you.

Just copying them into here.


use("aux", "formatting")

return {
text =
rt(
h1("The Barbarian Quarry") ..

h2("General:") ..
p(_
/wiki/the stone mason working at the quarry makes stones for your buildings out of rocks found lying in the landscape.klzzwxh:0055 klzzwxh:0050once they are gone, you need to find another stone field, or open up a granite mine. they do not regenerate.klzzwxh:0056 klzzwxh:0051only if a spot is totally cleared from these stones, it is ready for building new houses there.klzzwxh:0057 klzzwxh:0052the stonemason starts working outward, starting with the stones closest to his house up to the maximum range of 6. klzzwxh:0053note that he will change the heap he is working on and not continue at one until this is finished.klzzwxh:0058 klzzwxh:0054also keep in mind that stones of a different kind exist, that are not cut by the stonemason and will be blocking.) ..

h2("Building:") ..
p(_
/wiki/the quarry needs only a small plot, and cannot be upgraded into a more effective building. klzzwxh:0065 klzzwxh:0062it offers room for one stonemason only.the barbarian stonemason is needed at the quarries only.klzzwxh:0066 klzzwxh:0063to build a quarry, you will need: 4 trunks, klzzwxh:0067 klzzwxh:0064dismantling will yield 2 trunks) ..

h2("Output:") ..
p(_
/wiki/depending on the walking distance to the stones, the stonemason will fetch one tree every 40 to 60 seconds.klzzwxh:0072 klzzwxh:0071a granite mine will work more effective than a quarry, but it needs rations to work.) ..

h2("Worker:") ..
p(_
/wiki/the barbarian stonemason needs a pick. without one a new stonemason cannot be created.klzzwxh:0081 klzzwxh:0076although miners also use picks, they are a different profession and one cannot replace the other.klzzwxh:0082 klzzwxh:0077stonemasons are doing a perfect job from the very beginning and will not gain further experience.klzzwxh:0083 klzzwxh:0078clearing a large amount of stones is a slow and tedious work. build more than one quarry if possible and don't let klzzwxh:0079the walking distances get too long.))
}


use("aux", "formatting")

return {
text =
rt(
h1("The Barbarian Lumberjack") ..

h2("General:") ..
p(
/wiki/the lumberjack clears the landscape from trees enabling you to build new houses.klzzwxh:0029 klzzwxh:0008in doing so he also provides you with trunks, which are the barbarians' basic building material.klzzwxh:0030 klzzwxh:0009the lumberjack works outward starting with the tree closest to his house up to the maximum range of 10. klzzwxh:0010only fully grown specimen of all tree species are being felled.) ..
h2("Building:") ..
p(

/wiki/the lumberjack's hut needs only a small plot, and cannot be upgraded into a more effective building. klzzwxh:0031 klzzwxh:0014it offers room for one lumberjack only.klzzwxh:0032 klzzwxh:0015to build one, you will need: 3 trunks, klzzwxh:0033 klzzwxh:0016dismantling will yield 2 trunks) ..
h2("Output:") ..
p(
/wiki/the barbarian lumberjack is more effective than tree fellers os other tribes.klzzwxh:0034 klzzwxh:0020depending on the walking distance to the tree, he will fell one tree every 52 to 90 seconds.klzzwxh:0035 klzzwxh:0021one lumberjack will fell fewer trees than a ranger can plant.) ..
h2("Worker:") ..
p(

/wiki/the barbarian lumberjack needs a felling axe. without one a new lumberjack cannot be created.klzzwxh:0036 klzzwxh:0025the felling axe is a tool, not a weapon and can only be produced at the metalworks, not at an axefactory or war mill.klzzwxh:0037 klzzwxh:0026lumberjacks are fully trained from the very beginning and will not gain further experience.klzzwxh:0038 klzzwxh:0027trees are auto seeding. unless you have eradicated all trees in a larger area, keep one lumberjack to deal with the offspring.))
}


Give me your thoughts please, everyone as to style, content and the question whether this should be better tabbed for ease of use.

... and don't blame me for what I did to all the brackets, braces and parantheses -- I just fumbled about until it worked face-smile.png


Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top Quote
SirVer
Joined: 2009-02-19, 15:18
Posts: 1439
Ranking
One Elder of Players
Location: Germany - Munich
Posted at: 2011-11-12, 17:14

I like the General section, though I'd personally would love to see a short 'lore' like paragraph before diving into the details.

For the details however, I personally think that there is too little visual clues and to much running text. Whenever possible a short information should suffice. I suggest to show all information graphically and only ammend stuff via text.

For e: Finding information in this paragraph is rather tedious as you have to read through long sentences to find the information you search. I'd suggest a more visual clue; I worked on your example and redid the building section for the lumberjack (I stopped there, it is just to exemplify my point), see [1].

I also reworked this with some helper functions to also underline my point of simplifiying writing helps with lua from my former post. This is also just to convey the idea. See [2].

The result looks like this:

Screenshot

I realize that one feels quite handicapped with the current widelands rich text renderer, but for the moment it must do.

[1] https://gist.github.com/1360716
[2] https://gist.github.com/1360742


Top Quote
fuchur
Joined: 2009-10-07, 14:01
Posts: 184
Ranking
Widelands-Forum-Junkie
Location: Germany
Posted at: 2011-11-12, 17:34

I like the idea of the help texts and the provided samples. They are easy to understand for new players. The graphics for build costs suggested by SirVer make it even better.

There's one thing I'm not sure about, the range of the building. To give the number is ok, but maybe it will help to display it automatically by showing the blue spots while the help text is open. Yes, I know one can do this manually, but to have it visualized while reading the number makes it more clear.

When I think of more complex buildings like the trainingscamp I guess the help text will get longer. But I don't think that's a problem. If a player needs the information he won't have hab problem with scrolling down a bit.

Thanks for the efforts you're going to make!


Top Quote
Astuur
Avatar
Joined: 2009-02-28, 10:08
Posts: 733
Ranking
One Elder of Players
Location: Frankfurt / Germany
Posted at: 2011-11-12, 18:12

Hi fuchur - thanks for th comment For me the range is shown automatically whenever I open a relevant production site window.
Is this different for you?
I can switch it off, but it will again be shown the next time I open that window. So I think, we may not need an extra mechnism for that. But I think my texts should at least mention that feature: in that sense I will modify the writing.


Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top Quote
hjd
Joined: 2011-06-12, 20:24
Posts: 164
Ranking
At home in WL-forums
Location: bugs.launchpad.net/widelands
Posted at: 2011-11-12, 18:44

I like the General section, though I'd personally would love to see a short 'lore' like paragraph before diving into the details.

Could be interesting. Might want to make it italic or something to set it apart for people to easy find the "real" information.

Other random thoughts:

  • I think we would benefit from keeping the descriptions short and to the point. If the text is too long I unfortunately think people will not read it.

  • Would it make sense to place the house showing size after the main title of the name of the building? On the wishlist I'd like some breadcrumb system where you have something like "Barbarians > small > Lumberjack", though let's something basic up and running, before we start dreaming.

  • I am not 100% sure whether it makes sense to show build cost in the description. After all it is already built. :p I remember reading a suggestion about displaying it in the build-dialog when selecting builds (basically have the window extend and list the build cost), though was unable to find and link to it. Though, as there is currently no way to find build costs short of placing a new building, so it is ok for now. If the preview suggestion is ever implemented we might want to consider whether it is still needed. Dismantling info is perfectly ok though.


Ships!

Top Quote
Astuur
Avatar
Joined: 2009-02-28, 10:08
Posts: 733
Ranking
One Elder of Players
Location: Frankfurt / Germany
Posted at: 2011-11-12, 20:50

Well Sirver - time for a little clarification of standpoints and preferences. I feel it is necessary, even though it's kind of lengthy (again, I know face-wink.png ).
First and foremost - I thank you for the help and assistance you are giving.
Your support is much appreciated here - and in fact, I wouldn't even start to think about so complex structures, it it wasn't for that.
On the other hand, please try to understand, that I don't want to become a programmer.
I share the fascination about what you can achieve with knowledge and some tools, but it's the outcome I like, not bothering with
indented line, keywords or any form of syntax. I can see practically all our regulars now shaking their heads, but that's okay.
Having said that, I concede that the modest use of functions that you are introducing to show some trunks or build help symbols certainly is helpful - and I may learn how to use them sooner or later.
So far, so good.
What I really like you (and others) to understand is related, but still different.
I am sure you have followed most of the discussions about new graphics, houses in that case, that I had with Chuck.
We both agreed that the genuine charm of especially a game like Settlers or Widelands lies, among other things, in the attention that
is given to tiny little details. "Giving some love" to the work is more than a figure of speech.
And look how Chuck has succeeded in doing exactly that!
Recycling - as in "using the same thing again at different places and for a different purpose" may be something that coders go for, but when it shows, like in prefabricated blocks in houses, it becomes detrimental for the feeling of "love" being invested.
This is obvious in graphics, but IMO it becomes just as obvious when a text block is re-used over and over again.
So far, there has been not much chance for falling into that pit textwise with WL, since there has not been a lot of text in the game itsself. (except for the campaignes, where there is no redundant information).
In any case I'd like to keep my safe distance; i.e. when in doubt, write things twice in different words rather than using text blocks.

I am writing all this because I sense your tendency to keep things terse and structured - the way a programmer would.
Me, I'm more of a language man. I believe in the power (and the beauty) of language and I tend to rather write more for clarity, than less accepting ambiguity or incompleteness.
In fact, 2 years ago, I had even played with the idea of writing a WL handbook in a narrative style, something that would immerse the reader into the WL world including the tribes' history.
I had to give that up of course, because the history is yet undecided in major parts, but it helps to show you where my preferences are.
So...

I realize that one feels quite handicapped with the current widelands rich text renderer, but for the moment it must do.

Not at all, Sirver! I can live with the fact that the font is vanilla, bold and italic seems not to be available, as long as I have some means to not let the reading become too awkward. That is fine.
The real problem, however, is not about what I would like to do - I accept that this should be primarily informative - it is one of audience: Especially for the english language we must take into account, that we may have players who cannot use their native tongue because it isn't supported. They will most likely resort to English, and their command of this language may be minimal.
They won't give a damn for "beauty" but want info that they can decipher. I have tried to keep the writing simple for exactly this reason.
And it is at this point, that the structured graphical display you made possible is most welcome and useful.
So, all in all; though I really want this to look "handmade" and avoid any "auto-generated" feeling, I acknowledge the need for a
concise quick information at a glance, even for linguistically challenged players.
What would you think about tabs for "not so quick" or "in-depth" descriptive help with predominantly text?
For me nothing speaks against doing both: a quick help for forgotten details, and, behind tabs, some longer texts for more details.
I am not so sure what information you would expect in the "lore section" of a lumberjack? Please clarify!
What's the current schedule for the next official version? You want this in there, don't you?


Being no programmer, I apologize for all my suggestions that imply undue workload and for other misjudgements due to lack of expertise or relevant skills.
I am on Win32, have no means to compile, and rely on prefabricated distributions (Thanks to Tino).

Top Quote
hjd
Joined: 2011-06-12, 20:24
Posts: 164
Ranking
At home in WL-forums
Location: bugs.launchpad.net/widelands
Posted at: 2011-11-12, 21:40

Regarding the lore section, I cannot reply on behalf of SirVer, but I envisioned something like:

Lumberjack

"For as long as they can remember the vasts forests has sheltered and protected the barbarians. With the help of the large trees and the blessings of the wood spirits* their homes have been raised."

Description: The lumberjack clears the area from trees enabling you to build new houses....

*yes I know this is probably against the lore, but just an example of the top of my head.

It got me thinking about the Might and Magic games, which had a short paragraph with a description/story about every item in the game. I always thought this was really great because many of them hinted at parts of a larger story which helped flesh out and make the world believable. For instance you had a set of boots, helmet and gloves which were all made from the hide of the same animal which the descriptions wrote about how they were hunted and which country they lived in. MM also had an overarching story which spanned multiple games, but I digress.


Ships!

Top Quote