WML Variables HowTo

The place to post your WML questions and answers.

Moderator: Forum Moderators

Forum rules
  • Please use [code] BBCode tags in your posts for embedding WML snippets.
  • To keep your code readable so that others can easily help you, make sure to indent it following our conventions.
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

WML Variables HowTo

Post by pyrophorus »

Hi there !

Here comes a new fruit of my collaboration with Adamant14. We tried here to survey all cases of variables use in WML with many examples.

The paper is intended for beginners, but we think more advanced users can find here some useful tips too.
WML-VariablesHowTo.pdf
(387.79 KiB) Downloaded 1199 times
Thanks to Adamant14, the paper is now available in the wiki, here

Comments and suggestions are welcomed.

Hope this will help...
Last edited by pyrophorus on November 11th, 2013, 6:49 am, edited 1 time in total.
User avatar
Heindal
Posts: 1343
Joined: August 11th, 2011, 9:25 pm
Location: Germany, Karlsruhe
Contact:

Re: WML Variables HowTo

Post by Heindal »

Very interesting! Thanks both of you for writing this and your time.

I think this manual can help newbies to work into the topic of variables. I learned a thing or two by reading this, so its definitely a good guide and manual for developers, too. It should definitely be added to the wiki.

I personally like a more straight forward approach with examples, for instance I'd start with an example or problem so the learners can visiualize the the topic.
For example how to make an adventure and that you can store for example items or an item status within a variable. But you did it different and it works for me ^_^.

You have created a reference to an existing adventure and your tutorial follows this one line. But you should bring a little structure into the whole manual.

Target - Problem - Solution

Several times you start with new pieces of source code, explaining it afterwards. This can be tricky if the reader expects a structure as shown above, as you started with that structure in first place. Well its just a small thingy: you have small typograhic mistakes in the script: for example the ? or the header 3. So much about my feedback.
The future belongs to those, who believe in the beauty of their dreams.
Developer of: Trapped, Five Fates, Strange Legacy, Epical, UR Epic Era
Dungeonmasters of Wesnoth, Wild Peasants vs Devouring Corpses, Dwarf Dwarfson Dwarvenminer
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

Re: WML Variables HowTo

Post by pyrophorus »

Heindal wrote:Very interesting! Thanks both of you for writing this and your time.

I think this manual can help newbies to work into the topic of variables. I learned a thing or two by reading this, so its definitely a good guide and manual for developers, too. It should definitely be added to the wiki.
Thanks for your appreciation !
Heindal wrote: I personally like a more straight forward approach with examples, for instance I'd start with an example or problem so the learners can visiualize the the topic.
For example how to make an adventure and that you can store for example items or an item status within a variable. But you did it different and it works for me ^_^.

You have created a reference to an existing adventure and your tutorial follows this one line. But you should bring a little structure into the whole manual.

Target - Problem - Solution
I'm not sure I understand clearly what you mean here with adventure. More of it, we tried to cover each kind of variables uses, giving detailed examples. But I fear using a problem/solution plan would give a much larger paper: if you list all the problems which can be solved using variables, you will get something really huge ! :D Anyway, if you have in mind some of those you think they miss badly, just tell me. We can of course add some more examples.

Friendly,
User avatar
Heindal
Posts: 1343
Joined: August 11th, 2011, 9:25 pm
Location: Germany, Karlsruhe
Contact:

Re: WML Variables HowTo

Post by Heindal »

I meant that you used a concept based on an existing scenario. Thats ok, I would rather have used to explain it on a not existing game.

With adventure I meant a simple textadventure.
For example:

You standing in front of a house. What do you want to do next?

A) Try to open the door! (Reaction: Unfortunately the door is locked!)
B) Look under the doormat! (Reaction: You find the key for the main door.)
C) Look into the garden! (Reaction: You just seen plain gras.)

With that concept you can easily teach people how to create games and use variables. For example that they have to set a variable to key=1 or key=yes, which will than allow them to unlock the door. This concept however is better when it comes to explain to create basic game mechanics, not variables alone. I think that people that like to code, will love and easily understand your manual. When it comes to People that don't like to code, they will stop after the first sentence or second sentence.
The future belongs to those, who believe in the beauty of their dreams.
Developer of: Trapped, Five Fates, Strange Legacy, Epical, UR Epic Era
Dungeonmasters of Wesnoth, Wild Peasants vs Devouring Corpses, Dwarf Dwarfson Dwarvenminer
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

Re: WML Variables HowTo

Post by pyrophorus »

Heindal wrote:I meant that you used a concept based on an existing scenario. Thats ok, I would rather have used to explain it on a not existing game.
I still don't see what you mean. Of course, some examples are directly taken from my campaign, mainly because this code has been tested and works.
Heindal wrote: <snip>
With that concept you can easily teach people how to create games and use variables. For example that they have to set a variable to key=1 or key=yes, which will than allow them to unlock the door. This concept however is better when it comes to explain to create basic game mechanics, not variables alone. I think that people that like to code, will love and easily understand your manual. When it comes to People that don't like to code, they will stop after the first sentence or second sentence.
I think what you say can be true, but it would be a different project. Actually, I tried to explain with some details what I had a hard time to discover through trial and error, about variables use. Which is not explaining how to code common behaviors and "adventures": actually, this involves much more than variables use: events, filtering and so on. I suspect you mean a general WML manual here. It can be a good idea, and if you're interested in writing one with me and other people, let's try it ! :D

Friendly,
User avatar
Dugi
Posts: 4961
Joined: July 22nd, 2010, 10:29 am
Location: Carpathian Mountains
Contact:

Re: WML Variables HowTo

Post by Dugi »

One thing that might need to be included.

Sometimes, classical variable substitutions aren't enough, because you need to make a variable substitution within the name of the substituting variable.

Let's say that you have an array that looks like this:

Code: Select all

[items]
 [sword]
  type=23
 [/sword]
 [sword]
  type=27
 [/sword]
 [axe]
  type=13
 [/axe]
 [axe]
  type=29
 [/axe]
 [belt]
  type=38
 [/belt]
...
and you need to know how many axes or swords or other items (let's say that there is 20 item types possible) the unit has, and then to cycle through them in a FOREACH-like cycle. The type of item you have to count is inside a variable, let's name it item_type.

You can't use this:

Code: Select all

message="There are $items.$item_type.length items of the $item_type sort."
The game would look up the length of the item_type variable, and because it is not an array, it would fail. You can do it easily in lua, but that is not to be discussed here. You might use macros for all possibilities, but macros used this way create a terrible bloat.

You cannot do this neither:

Code: Select all

message="There are $items.$item_type|.length items of the $item_type sort."
The game would look up $items.$item_type and write .length after it into the message. You have to first read it via set_variable with to_variable:

Code: Select all

[set_variable]
 name=quantity
 to_variable=items.$item_type|.length
[/set_variable]
[message]
 message="There are $quantity $item_type|s."
...
In this case, the variable is substituted into the string, that will be later used as a variable name, and not into a variable call directly.

If you need to use something like FOREACH, it would not work too. You will need something like this:

Code: Select all

[set_variable]
 name=quantity
 to_variable=items.$item_type|.length
[/set_variable]
{VARIABLE i 0}
[while]
 [variable]
  name=i
  less_than=quantity
 [/variable]
 [do]
  [set_variable]
   name=current_type
   to_variable=items.$item_type|[$i].type
  [/set_variable]
   #Now you can access the current_type variable.
  {VARIABLE_OP i add 1}
 [/do]
[/while]
User avatar
Heindal
Posts: 1343
Joined: August 11th, 2011, 9:25 pm
Location: Germany, Karlsruhe
Contact:

Re: WML Variables HowTo

Post by Heindal »

@pyrophorus Yeah we could make something like that and would be glad if you would join the team. But as this is yet annother project, I can't invest much time - even so I think it would be fun and it would help people to learn coding. And the concept could be used to explain any coding language, by just replacing the code (for example for the creation of a variable).
The future belongs to those, who believe in the beauty of their dreams.
Developer of: Trapped, Five Fates, Strange Legacy, Epical, UR Epic Era
Dungeonmasters of Wesnoth, Wild Peasants vs Devouring Corpses, Dwarf Dwarfson Dwarvenminer
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

Re: WML Variables HowTo

Post by pyrophorus »

@Dugi.
Yes, but IMHO, you're explaining how to deal with a poor data design. Why should we enclose the 'axe', 'sword', 'belt' and so on arrays in an 'items' block ? We can define those arrays separately, then the problem vanishes. Most often, (not only in WML) it's easier to change the data design than to find tricks and hacks to work it out.
Personnally, I don't go that way: when programming with some data structure becomes uneasy, I rework the data structure, not the algorithms.

@Heindal.
Ok, if you're interested in this, I think we could start writing a topics list, and ask other people (beginners included) to add items. We should then have a better idea of what to do. What do you think ?

Friendly,
User avatar
Dugi
Posts: 4961
Joined: July 22nd, 2010, 10:29 am
Location: Carpathian Mountains
Contact:

Re: WML Variables HowTo

Post by Dugi »

If you need to do some systematic change with weapon specials (or abilities), you cannot avoid having to cycle through arrays of [damage], [attacks], [drain], [slow], [dummy], [plague], [firststrike], [swarm], [chance_to_hit], [berserk] and [poison], and in that case, you'll need that in any case (let's say you need to to implement the [set_specials] effect yourself).
So, maybe in some cases it is caused by poor design, there are cases where you can't avoid this 'poor design' or you need it due to optimalisations.
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

Re: WML Variables HowTo

Post by pyrophorus »

Dugi wrote:If you need to do some systematic change with weapon
specials (or abilities), you cannot avoid having to cycle through
arrays of [damage], [attacks], [drain], [slow], [dummy], [plague],
[firststrike], [swarm], [chance_to_hit], [berserk] and [poison], and
in that case, you'll need that in any case.
If you were one of my students, I would summon you to prove (not only to assert) the solution you found is the only one.
Since you're not, I will only ask if you really think all this stuff is beginners main concern ?
You're speaking as if anyone should or would like to program things like you did in your campaign, and aren't clever enough to do so.

Good teaching in my mind, is not giving others a full bunch of recipes, ready for use in any situations or models to follow. It's not thinking in their place,
it's teaching how to think by themselves and find their solutions, which is much more difficult. This is the goal of my papers: to show how things work, not giving a solution to all problems. An introduction, not a cookbook.

Friendly,
User avatar
Dugi
Posts: 4961
Joined: July 22nd, 2010, 10:29 am
Location: Carpathian Mountains
Contact:

Re: WML Variables HowTo

Post by Dugi »

If you were one of my students, I would summon you to prove (not only to assert) the solution you found is the only one.
Unfortunately, this is not mathematics or any in-depth programming language like C where normal proofs can exist. I will try though:
You need to circle through variables with changing names. There is no facility designed for this, [set_variables] with merge does not help in this, so you need to construct the name of the variable to access yourself, and use the to_variable method to get a double variable substitution. Re-read the wiki to see that there is nothing else normally allowing this.
I wrote normally allowing this, because there are two more ways to do it, but one of them requires a huge macro bloat and the other one requires lua.

You're a teacher?
Since you're not, I will only ask if you really think all this stuff is beginners main concern ?
This is a valid argument. Really valid. But your pdf has 26 pages and explains relatively complicated stuff, so I thought that information about variable access in extreme cases might be useful there too, to make it really complete.
it's teaching how to think by themselves and find their solutions, which is much more difficult.
Wait a bit here. What I wrote was a minimum, on the simplest example I could imagine. Example of a case that can be avoided. Its practical usage would be a much longer code. The whole code where it was needed was this:
Spoiler:
You've read my arguments, no matter how you decide, it is your project and I am only an advisor. I can post this somewhere on the wiki if you decide negatively.
User avatar
Heindal
Posts: 1343
Joined: August 11th, 2011, 9:25 pm
Location: Germany, Karlsruhe
Contact:

Re: WML Variables HowTo

Post by Heindal »

Ok, even if I might understand what both of you wrote and proably could understand your pieces of code, I will not argue about that now. You, dugi definitely know your craft as well as you pyrophorus, but both of you have found an own way of coding and scenario writing and you are using different approaches. If you would work together the results will be amazing! I think that dugi is using variables in a way that could be interesting for your students.


Now now, how do we start with the adventure project? Shall we open a thread for that?
The future belongs to those, who believe in the beauty of their dreams.
Developer of: Trapped, Five Fates, Strange Legacy, Epical, UR Epic Era
Dungeonmasters of Wesnoth, Wild Peasants vs Devouring Corpses, Dwarf Dwarfson Dwarvenminer
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

Re: WML Variables HowTo

Post by pyrophorus »

Dugi wrote: You're a teacher?
I have been. For now I work in a company where I'm in charge of IT students coming for a work experience at the end of their studies.
Dugi wrote: You've read my arguments, no matter how you decide, it is your project and I am only an advisor. I can post this somewhere on the wiki if you decide negatively.
I did. And I still think this kind of example is not interesting, because it covers a too large topic. Yes, you tell exactly how you manipulate your data, but you don't explain why you chose to set-up them in this way, and the reader can't make an opinion because (s)he has not the complete problem description.

Anyway, you can even put this at the end of my paper when it will be wikified (most probably one day). There's no copyright there.
Heindal wrote: Now now, how do we start with the adventure project? Shall we open a thread for that?
Well, maybe it would be better. But, it's just as you like.

Friendly,
Wussel
Posts: 624
Joined: July 28th, 2012, 5:58 am

Re: WML Variables HowTo

Post by Wussel »

Nice guide! I finally getting an idea about variables.
I do have a current question, actually 3.

How do I read and edit save files? I found them (.gz), but my editor (np++) displays crazy signs.

I want to read out the portrait imagepath of $second_unit and add a teamcolor order to it:
image= ((portrait imagepath of $second_unit))~TC($second_unit.side, magenta)
How would the code be?

Can I use any id to access a unit in a start event? Say id is tony. could I write tony.side instead of not working $unit.side?
User avatar
pyrophorus
Posts: 533
Joined: December 1st, 2010, 12:54 pm

Re: WML Variables HowTo

Post by pyrophorus »

Wussel wrote:Nice guide! I finally getting an idea about variables.
Thanks, I'm happy to read this.
Wussel wrote: I do have a current question, actually 3.

How do I read and edit save files? I found them (.gz), but my editor (np++) displays crazy signs.
You've to extract them first: .gz are zipped files.
Wussel wrote: I want to read out the portrait imagepath of $second_unit and add a teamcolor order to it:
image= ((portrait imagepath of $second_unit))~TC($second_unit.side, magenta)
How would the code be?

Can I use any id to access a unit in a start event? Say id is tony. could I write tony.side instead of not working $unit.side?
Not directly in both cases. You must first store the unit into a variable:

Code: Select all

[store_unit]
    name=tonyStore
    [filter]
        id=tony
    [/filter]
[/store_unit]
then, you can use $tonyStore.side (and you must unstore_unit, if you make changes and want them to apply).

Friendly,
Post Reply