help text - how?

[letsdance]

there are 2 basic options to add helptext:

1. it could just be text, all the information and flavor text stored as a separate text property in the xml and then displayed. this is quite easy to do and gives a result, that is good to read for users. it also means having to write the text to everything.

2. it could take all the variables (like building requirements, cost etc.) from the xml, and display them. the big advantage of this is, it always displays the correct data and you never have to update the description. it could create links to helptexts of things mentioned.
the problem is, everything has different variables, and not all variables have a description that means anything to someone who doesn't know the code. so we would additionally have to write a short description for each variable that is not self-explaining, often taking into acount parameters of the variable. example: GetPowerArgs IntValueModifyer 2 ADD. even if you do understand, or can guess, what it means, it's not nice to read. but writing code that transforms it to nicer language (adds 2 power) takes some work. additionally we could/should add a flavor text manually, like in 1. so this, in addition to more complicated code, this also requires writing a translation for many variables AND a description for everything. i don't think it's really worth it.

finally it could be a mix: take those things, that can be used easily from the xml (like building requirements or costs) and write a description for the rest. it probably requires a different helpfunction for every type of item, since everything has different variables and their display must be organised.

any other ideas?
i guess i'll just let the boss (VM) decide :D

[WhiteMage]

The top priorities are usability and user experience. The quality and speed of the received help should be high. After that we consider ease of long-term software maintenance by programmers and the ease of moddability by nonprogrammers. So for example if the cost of a unit changes or the list of prerequisites changes for a building, the user updates XML. Then the new help text should be generated automatically by the program. As much as possible should come from XML. The help narrative should be displayed in high quality English and later in other languages too, most or all coming from XML, possibly a single XML, where a variable ‘Lanuage’ would determine which text to use. I do not think that there will be too many dependencies to make it too much work upfront (you should spell out if you disagree). The time saved in the future will be greater than the time we put in upfront if reMOM comes out strong as I hope. So someone writes new text into XML, which populates numeric and prerequisite values from other fields in XML. This shows entire help in the game in English for the given feature (correctly).

The current Plight implementation for MOM that improved text help took a lot of efforts to make it work for a single version of MOM. At the end there were still many errors left even for the intended version. Worse, the modded versions by Kyrub and others caused Plight to go out of sync, which rendered it very confusing and almost useless. This is what we would get again if we would choose your option 1. We must design and code reMOM for future upgrades and moddability in mind.

As far as when help text is to show up: the current MOM has descriptions for spells, buildings, unit attributes, events, etc. We continue to have those. In addition, I support your idea of the right click for anything that is not annoying.

Regarding implementation, we start small scale. Proof of concept to see it if works as we imagine. If all good, then go large scale. Also, try to identify hardest case and see if we can handle that. So first do the easiest case and test, then the hardest case and test. Then do the rest.

[letsdance]

Worse, the modded versions by Kyrub and others caused Plight to go out of sync, which rendered it very confusing and almost useless. This is what we would get again if we would choose your option 1.

only if modders fail to do their job well. LRM has an updated helpfile.

basicly i agree with you, but i'm not sure the effort is really worth it at the moment. i also don't know the worst case, because it might not even be implemented yet :D for example spells will have an additional "layer" (type of spell = summoning, then summoned unit = hell hounds) automatically putting all this (for all possible combinations!) in good language from code snipets is quite a challenge.

the whole game is not really written in a translate-friendly way. there are strings all over the code. some of them are even in pictures (the buttons). i asked VM about this a wihle ago, and he doesn't see a problem. i personally am not a big fan of translations, i support the idea of everyone speaking english only :D

[WhiteMage]

only if modders fail to do their job well.

We want dummies to become effective modders for reMOM. Also, we want to make it easy for modders, which takes little time and hard to make errors.

LRM has an updated helpfile.

LRM as Language Reference Manual? For MOM or future reMOM? I don’t see that being the solution for modding. My point was to use XML only by users.

basicly i agree with you, but i'm not sure the effort is really worth it at the moment.

I agree about "at the moment", but help text was your choice of problem to work on, so I responded. It is a low priority at the moment since basic game functions are not yet programmed.

automatically putting all this (for all possible combinations!) in good language from code snipets is quite a challenge.

I am available to discuss further. If you wish to pursue this, start by estimating the number of combinations and give examples using current MOM rules and their expected range of modifications. We can create the most universal rule for each major type help text to be used, then use pointers to blanks in XML, which will lead to empty text generation. So the large number of combinations will be done by inserting blanks as needed. Sounds like a challenge to start it up, but after that it should be easy to follow the template we create. No need to be a programmer at that point.

the whole game is not really written in a translate-friendly way. there are strings all over the code.

If all displayed text will come from XML as it should, transtation should be manageable, but not trivial since grammars are different and order of material to be presented may not be the same. Nevertheless, we keep English clean and simple. String that is not displayed requires no work.

some of them are even in pictures

Pictures can be replaced by individual users, but I think that the programmers should only make it easy to do so. We do not spend time on this. We will get volunteers later once the game is up, like Wesnoth and C-Evo.

i personally am not a big fan of translations, i support the idea of everyone speaking english only

I agree that multiple language support is a very low priority at this time, but should not be ignored in design now. We do not want to limit our stellar, paradigm shifting game to less than 27% of the World’s population. Only 5.5% are native speakers.

[letsdance]

LRM, as "letsdances rebalance mod" :D

Pictures can be replaced by individual users

yes, but translators are not grafic modders, and translations are alot easier to make and distribute if they don't have to include pictures.