The Battle for Wesnoth Wiki - User contributions [en]

User talk:Shadowm/PatchSubmissionGuidelines

2012-12-28T09:14:23Z

Boucman: Created page with '1.2: you could also mention RELEASE_NOTES as "if needed, you may also add something in the RELEASE_NOTES" 1.3: copyright notices ? 2.1: FIXME: in that case come and bug us on IR…'

1.2: you could also mention RELEASE_NOTES as "if needed, you may also add something in the RELEASE_NOTES"
1.3: copyright notices ?
2.1: FIXME: in that case come and bug us on IRC
2 : we may ask to rewrite the patch entirely if the generic idea is good, but we don't like how it's done and/or it can be generalized/designed in a better way in the grand scheme of things

--[[User:Boucman|Boucman]] 09:14, 28 December 2012 (UTC)

SoC Ideas Particle Engine 2012

2012-03-09T07:54:21Z

Boucman: Created page with '{{Template:SoC2012Idea}} = Description = <h2>Implement a particle engine in the animation engine</h2> Page for the idea: SoC Ideas Particle Engine {{#dpl: |resultsheader=''…'

{{Template:SoC2012Idea}}
= Description =
<h2>Implement a particle engine in the animation engine</h2>
Page for the idea: [[SoC Ideas Particle Engine]]

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no student proposals for this idea''
|category=Summer of Code 2012 Student Page&SoC Ideas ¨Particle Engine
|notcategory=SoC 2012 Not Submitted To Google
|include=#Description
|nottitlematch=SoC2012_Template_of_Student_page
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

=Additional Information=

A particle engine allows to draw pixel per pixel where each pixel's position is given by a piece of code or a mathematical fomula. This is used to display interesting physical phenomenoms like water flow, explosions or fire

The aim of the project is to add such an engine within the animation engine and, if time permits, within the terrain engine.

A good understanding of the animation engine will be needed, but the particle engine will fit quite nicely in the existing structure

for performance reasons the formulas will probaly have to be given in LUA, but other approches could be interesting

there will probably be some needs to go into the wesnoth-SDL infrastructure for the display part

googling for "particle engine" and "particle engine SDL" should provide lots of groundwork for writing proposals

=Whom to ask about this=
boucman on irc.

Fosdem2012

2011-12-15T15:14:55Z

Boucman: /* Schedule/Plans */

== General information ==
This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2012. That is everyone attending should please list him/herself in the list of arrivals and stuff like this. FOSDEM 2012 will take place at the first weekend in Febuary 2012, on Saturday 4th and Sunday 5th.

* Fosdem - http://fosdem.org/2012/

== Schedule/Plans ==
{| border="1" width="100%"
|-
! (nick)name(s)
! Arrival
! Departure
! Accomodation
|-
| Ivanovic
| Fri, 3rd, "afternoon" (~15:00 at "chokopolis"; not 100% sure yet)
| Sun, 5th, leaving right from ULB campus
| 2go4?
|-
| AI
| Friday?
| Sunday?
| 2go4?
|-
| Crab
| Fri, 3rd, "afternoon"
| Sun, 5th
| 2go4?
|-
| Boucman
| Fri, 3rd
| Sun, 5th
| not sure, to be confirmed
|-
|}

For accommodations please keep in mind that parking in the center of Brussels is really problematic. It might make sense to drive to the University where FOSDEM takes place, park there and take the bus into the town center (where some of the hotels/hostels are).

Possible hostels that we at least contacted over the last years (some of them might already be booked out by now!):
* [http://www.chab.be/ CHAB]
* [http://www.2go4.be/ 2go4] Note: groups bigger 6 are not allowed, so we can (officially) not form a complete Wesnoth group at this hostel, got to meet somewhere in town/at the university...
* [http://www.jeugdherbergen.be/brusselE.htm Bruegel YH]

On the official FOSDEM page [http://www.fosdem.org/2012/practical/accommodation some more possible hotels/hostels] are listed.

== Maps ==
* [http://tinyurl.com/3a65gr Bruegel YH]
* [http://tinyurl.com/35br9c Brussels Central (Train Station) → Bruegel YH]
* [http://tinyurl.com/37d9v4 Bruegel YH → Brussels Central (Train Station) → Novotel Grand Place]
* [http://tinyurl.com/2mzns6 Novotel Grand Place]
* [http://tinyurl.com/3dggg3 CrownePlaza (Europa)]
* [http://tinyurl.com/36epxj FOSDEM]
* [http://tinyurl.com/2w4bms Novotel Grand Place -> FOSDEM]

== Transportation ==
Information about how to reach the FOSDEM is listed at the [http://www.fosdem.org/2012/transportation official transportation subpage].

Short version of how to get there for those that reside in Bruegel YH and Novotel Grand Place (basically town center):

* Enter Bus 71 (Debrouckere - Central Station ("Gare Centrale") - Delta) somewhere at 'Central Station'
* Leave the bus at "ULB" (crossroads Ave. Adolphe Buyl - Sq. Deveze)
* Walk down Ave. Paul Heger on your right hand.

== Wesnoth Hacking Room ==

Wesnoth will not have a room of its own (though there will be the open source game dev devroom on Sunday where hopefully many Wesnoth devs will participate). Instead we will use one of the "general hacking rooms". So far it is not sure which room it will be, if we do it like the last three years, it will be room number 115 in the building AW1. Last year this was the smaller of the two hacking rooms and we had no real problem with conquering (and holding) the first row in this room. There were not too many power outlets, so this year at least Ivanovic will bring one multi-outlet power strip plus some extension cable (5m or something like this). Mordante will (hopefully) also bring a multi-outlet power strip and a 20m extension cable. There is no wired network, everything wireless (and sometimes rather/very unstable!). Beside this you should bring laptops since there are no computers available for hacking.

Short version:
AW1 - Room 115 (at least on Saturday)

== Discussions and Results ==
We usually discuss all sorts of things at FOSDEM, this section is basically a (really short) summary of things that were discussed including their results. First are the discussions that were done "in plenum" with basically all attendees around. At the bottom is an area meant for discussions that were held in sub groups that not all devs might be aware of that were around.

Please make sure to list any topics you want to talk about below. The GameDev Room topic might serve as sample...

===Wesnoth presence in the GameDev Room===
Since Ivanovic is responsible for organizing the Open Source Game Development Devroom which takes place on Sunday 5th, there will at least be one Wesnoth Dev busy with this room. Though several other will hopefully support Ivanovic in this effort and be around to listen to many interesting talks and presentations.

== Group Picture ==
Has to be taken first.

== Previous Years ==
* [http://www.wesnoth.org/wiki/Fosdem2011 FOSDEM 2011 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2010 FOSDEM 2010 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2009 FOSDEM 2009 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2008 2008 wiki page], [http://www.wesnoth.org/forum/viewtopic.php?p=283649#p283649 Forum topic (with group photo)], [https://mail.gna.org/public/wesnoth-dev/2008-02/msg00078.html Summary of FOSDEM 2008 results]

[[Category:Development]]
[[Category:Wesconf]]

AnimationWML

2011-06-12T16:52:31Z

Boucman: /* Optimization */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''directional_x''': x offset applied to the frame in the direction the unit is facing
** '''directional_y''': y offset applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SoC Ideas Sprite Sheets2011

2011-03-31T21:54:18Z

Boucman: /* Additional Information */

{{Template:SoC2011Idea}}

= Description =
<h2>Allow wesnoth to support spritesheets</h2>
Page for the idea: [[SoC_Ideas_Sprite_Sheets2011]]

Currently, all the Wesnoth unit animations are based on thousands of small png
images, each image representing the unit in a single pose. For terrains the
situation is the same, it has a base image with a lot of transitions to other
terrains, which are now stored as seperate images.

In a sprite sheet approach, each unit is represented by a single, huge, image
where all the unit images are put on a mosaïc pattern and the game knows where
to look for a given image.

The advantage of having a large image with all positions is that it's more
efficient in memory. Also one large file is more effecient on the harddisk and
faster to load than a lot of smaller files. So the change to spritesheets will
have a lot of advantages.

Regarding the implementation the student is free to come up with his/her own
solution and discuss that with the developers during the application period.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas Sprite Sheets2011
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

= Additional Information =
* How to build those huge sheets from our current images set?
* Wesnoth does not have a fixed number of frames per unit, nor does it have a fixed size for each unit frame. A naïve approach to the problem will not work.
== Small mail sent on the dev ML but of general interest for any student studying that proposal ==
The big problem with spritesheets is that a unit is made of lots of
images each with different sizes, and we would like to be able to work
with spritesheed in a non-tedious manner
* not tedious for artists that want to work with single images, which means either a tool to automate building spritesheets or being able to mix frames from images and from spritesheets or both. being able to re-split a spritesheet would probably be usefull too
* not tedious for animation developers, i.e never have to calculate coordinates and sizes to fill WML data, it could either be generated from the spritesheet, or the spritesheet could somehow contain the information (like a pink border around frames)
* not tedious (of course) for artists that like working directly with spritesheets. I don't know very well what their constraints would be
* not having to change the current WML would be a plus

your proposal doesn't really explain how to solve all these problems,nor did you show that you studied how images are currently loaded in wesnoth, and now current code would be impacted. Hint: that's all in src/image.?pp

here is an idea on how to do it, though you should build on it, not just redescribe what i'm putting below.

WML is unchanged, i.e WML refer to image files without any special information
* in every image directory we add an image with a special name that is the spritesheet for that directory, and a WML file that matches filenames from that directory with the position in the spritesheet
* when the game is looking for an image, if the file exists it loads the file, if not it loads it from the spritesheet
* a tool is provided to take all images in a directory and make the spritesheet + WML (a reverse tool could be usefull but not mandatory)

So, if an artist edits a spritesheet, the new image is loaded correctly, if an artist would rather use the image instead, he just has to add the image in the directory and it would complement the spritesheet or replace what's on the spritesheet transparently.

As part of the release packaging, spritesheets would be regenerated so distributed content would be spritesheet based

there are a few problems remaining with that, but i'll let you and any other potential student find them out and solve them :)

= Whom to ask about this =
* Boucman (developer for the unit animation engine)
* thespaceinvader (artist, for usability questions)

EasyCoding

2011-03-18T21:30:10Z

Boucman: /* Option to disable terrain animations globally */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

== WML related features ==

=== Make map-related FormulaAI functions accessible to WML ===
As described in this forum post [http://forums.wesnoth.org/viewtopic.php?p=481087#p481087],
some of the FormulaAI functions should be made available as core functions instead of AI only functions, e.g. distance_between(). Full list of FormulaAI functions is available here: [http://wiki.wesnoth.org/FormulaAI_Functions]

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]. Patch submitted: [https://gna.org/patch/index.php?1162] (gabba)

--[[User:Boucman|Boucman]] 08:56, 28 February 2010 (UTC) : this is postponed for 1.8, can be considered reserved

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

--[[User:Boucman|Boucman]] 08:58, 28 February 2010 (UTC) Patch seems abandonned, but can be used for further work feel free to take over the FR

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
--[[User:Endercoaster|endercoaster]] 30, March 2010. I'm gonna give this one a try.

=== Support for standalone multiplayer scenarios ===
There used to be support for standalone scenarios in the userdata tree, in reorganising the trees this feature got lost and an add-on is now required to add a scenario.
Re-add this feature. It is probably a good idea to mirror the mainline multiplayer tree.

=== Support variable recall cost in wml ===
see https://gna.org/bugs/?16538

the syntax needs to be discussed and refined, but the overall idea is good

make sure to update whiteboard to handle this correctly

Ask Boucman

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to AI ==

Fix some todos, add new formula functions, or do minor improvements to the formula language. Make it easier to debug the formula language, add more ai components.

Please discuss these with Crab, Dragonking, Sirp or Boucman

=== AI Batch testing ===

Finish patch #1169 [https://gna.org/patch/?1169]

=== Add more ai actions ===

Add an ai action (and add formula_ai function to do that) to set a goto on a unit

Add an ai action (and add formula_ai function to do that) to send a chat message to a player

Add an ai action to set formula ai variable (convert existing code from formula_ai)

Add an ai action to set formula ai unit variable (convert existing code from formula_ai)

Add an ai action (and add formula_ai function to do that) to fire a WML event

=== write a (fai or c++ or lua) candidate action for leader control ===

=== write a (fai or c++ or lua) candidate action for using leadership/illuminate ===
special handling of units with leadership to have them support units. Only do it if it actually is useful (less hits needed to kill the unit) and ability to help multiple units in a single turn (assuming enough MP)

=== write a (fai or c++ or lua) candidate action for healer control ===
Handle units with healing power, moving them at places where they can provide the most healing

=== berserker improvement ===
The default AI's strategy of attacking as much as possible is very bad with berserker... A simple AI that would prevent the berserker from attacking (and keeping him close to fight without being exposed) and attack when the chance to kill is high enough would be an interesting addition

=== power projection improvement ===
AI sometimes wants to calculate 'how much firepower can enemy bring on location X'. in doing so, it considers enemy possible moves, time of day, attacks, enemy defense, etc.
There is specific problem with 'time_of_day' used in that calculation -sometimes, it's really needed to check 'time of day for NEXT turn', not time of day for THIS turn.(since the time of day might change next turn).

power_projection must be fixed to account for the possibility of time_of_day being different.

Note that some enemies might go after us (so, still on THIS turn), and some - before us (so, their next turn will be on NEXT turn).

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature
=== Story Screen improvements ===
see http://www.wesnoth.org/forum/viewtopic.php?p=439346#p439346 for the suggestion and https://gna.org/patch/?1587 for a patch that already touched that area heavily

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

At the moment there are no easy tasks available.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

Euschn 24/03/2009

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)
=== Option to disable terrain animations globally ===
see https://gna.org/bugs/?15976

please think a little about use cases (editor, game etc...)

ask boucman for details

=== Add a cycle parameter to the unit animation WML ===

Animations have a "cycle" internal parameter that decides if the animation loops when it finishes.

Right now that parameter is decided purely by the engine depending on the circumstances, but it would make sense to move it to a frame paramter.

This task is mainly to add a new boolean parameter in the particle class and using/exposing it to WML in a way similar to a unit_frame

ask boucman for details

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

SoC Ideas Simple Content Manager

2011-03-09T21:34:52Z

Boucman: /* Whom to ask about this */

{{SoC2011Idea}}

=Description=
<h2>Create a simple content manager frontend for non-technical users</h2>
More info at [[SoC_Ideas_Simple_Content_Manager]]

Wesnoth has all sorts of contributors that are not coders (translators, graphists, multiplayer developers, musicians, etc)

A large part of these users don't know how to use content managers (git, svn, etc...) and are not interested in learning. Wesnoth has been looking for a simple frontend to the most common content managers for those developers but none of these are simple enough for our use case.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas IDEA NAME
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

=Additional information=

This task would be to develop a front end for the most common SCM that would mask completely the underlying tool and would target people that want to contribute to open source, are not technically inclined, and don't want to learn. This tool would implement a minimal subset of SCM features with the philosophy that the user has the support of technicall people to do complicated tasks

the following feature list is here to help understand the use-case for the tool

'''things the tool might do'''
* update repository wrt distant repository
* commit to distant repository
* prepare a bundle to attach to a mail
* switch branch
* resolve merge conflicts
* build a report on the underlying SCM situation to allow debugging by someone else
* register as a handler to svn:// and git://

'''things the tool shouldn't do''
* create a new project (if you want to do that, you should learn the real tool)
* create a new branch (a person with the real tool can do that on the repository for you in the rare case it's needed)

'''other misc constraints'''
* python is the prefered language (all of wesnoth tool are in python) java could be used too (we already have some java code, so maintainability should be ok)
* it should be SCM agnostic (the point is to lower the barrier to entry for non-technical users)
* the UI should not be frightening to non-technical people (I.E give some thought to UI design in your proposal)
* it should integrate as properly as possible into the OS
* it should work on windows, Mac and linux

= Whom to ask about this =
* Boucman (original idea)

SoC Ideas Sprite Sheets2011

2011-03-09T21:34:14Z

Boucman: /* Whom to ask about this */

SoC Information for Google

2011-03-09T21:20:15Z

Boucman: /* If you are a large organization who is vouching for a small organization applying to GSoC for their first time this year, please list their name and why you think they'd be good candidates for GSoC here: */

{{Template:SoC2011}}

== SoC Information for Google ==
This is the info that we submit to google as Application in Summer of Code (current status: 2010). The submitter automatically becomes primary Admin. Most entries are mandatory and have to be filled out before the application can be submitted.

==== Organization Name: ====
Battle for Wesnoth

==== Description: ====
''Battle for Wesnoth'', or simply ''Wesnoth'', is a free, turn-based strategy game with role-playing elements that was designed in June 2003 by David White (Sirp).

Although the core rules are fairly simple and meant to be easily learned[1], they provide interesting gameplay and rich tactical options. A major strength of the project is the Wesnoth Markup Language (WML) for writing scenarios. Programming skills are not required to compose with it, and a large WML-modding community has generated a great deal of user-maintained content. We polish the best of this content and lift it into our official release tree.

The first stable release (1.0) was on October 2, 2005, and the latest stable release (1.8) happened in april 2010. Version 1.8 is a major stable checkpoint, and 1.10 is not anticipated before the end of 2011. The currentdevelopment cycle (1.9, leading to 1.10) will premier significant changes in gameplay, UI, and development tools, with many new concepts being introduced. That makes this year probably one of the best years for a SoC student to join, since the open-ended 1.9 will mean much more space to develop novel ideas

''Wesnoth'' is one of the most successful open-source game projects in existence, with an exceptionally large developer base and user community:

* According to Ohloh, a site that collects activity statistics on open-source projects, the ''Wesnoth'' development effort is in the top 2% of largest and most active projects.
* We support two multiplayer game servers (stable and development) with a usual minimum load of more than a hundred players.
* More than two thousands downloads a day
* 4.5 million downloads via SourceForge; many more via various mirrors of Linux distributions
* Best rated game at the Linux Game Tome[2]
* Game of the year 2007, 2008, 2009, and 2010 at LinuxQuestions.org[3][4]
* In general, ''Wesnoth'' tends to show up in the first or second position whenever anyone compiles a list of top open-source games.

''Wesnoth'''s most notable features include:

* A mature project with continuing active development and frequent improvements
* High quality artwork: both original graphics and music
* Well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after six years of development and with a very solid, fun product already created, there are still plenty of new developers; the number of commits to Subversion is still increasing
* Strong support of internationalization with many supported languages, thus experience in working with non-native English speakers. In fact, more than half of our developers are not native English speakers.

[1] http://www.wesnoth.org/wiki/WesnothPhilosophy

[2] http://www.happypenguin.org/list?sort=avg_rating

[3] http://www.linuxquestions.org/questions/linux-news-59/2009-linuxquestions.org-members-choice-award-winners-788028/

[4] http://www.linuxquestions.org/questions/2010-linuxquestions-org-members-choice-awards-93/open-source-game-of-the-year-855937/

==== Home page: ====
http://www.wesnoth.org/

==== Main Organization License: ====
GNU General Public License version 2.0 (GPLv2) [Dropdown box answer!]

==== Why is your organization applying to participate in GSoC 2011? What do you hope to gain by participating? ====
Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

Our previous SoC experience shows that a motivated, full-time, student can be brought up to date in any area fairly quickly.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that are currently lagging behind.

Moreover, our previous experiences has shown us that SoC developers tend to stay after the end of the Summer of Code and become valuable members of our community. This has been a win in all directions and we want it to happen again.

==== If accepted, would this be your first year participating in GSoC? ====
No

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation. ====
2008 results:
Wesnoth participated in GSoC 2008 with four students. Out of these, two were great successes (that is they became full-fledge developers before the actual start of GSoC), did huge improvement during GSoC (A new recruitment algorithm for the AI and the basic structure for a new map editor, the student finished this work after the summer), and are still active developers in the Wesnoth community.

Of the two other, one of them was very active for the first half of GSoC and provided some useful infrastructure for AI development that we used as base in GSoC 2009, but was much less active and didn't reach expectations for the second half of GSoC. The lesson we learned is that great students should be left on their own, that's the best way to have them work, but average students should be monitored much more closely than we did. If things seems to start to go wrong, it's important to react very quick, to meet with other mentors and get things back on track early.

Timezone problems were also a serious barrier for student/mentor communication, and we will take that more into account when pairing mentors and students

For our other students, multiple problems collectively led to failure
* We should enforce IRC communication, E-mail is a barrier. This applies both for students and mentors. Both should be on IRC several hours a day, with overlapping hours.
* We should be more strict about mid-term evaluation. If the student is slightly lacking at mid-term we should give a clear message that he needs to get back on track.

2009 results:
In 2009 we mentored 6 students as part of Summer of Code. Out of these 5 projects were a success. From those 5 developers 3 are still part of our core development group and still maintain and improve the work they submitted as part of Summer of Code. One of the students even became the "head" of our AI development department and mentored a student this year. For a summary of the 2009 results have a look at [1].

Sadly one student was not able to continue his work past midterm due to his computer failing completely as well as personal problems that we won't delve into further here. It was not a salvageable situation.

2010 results:
In 2010 we mentored 4 students as part of Summer of Code, all the projects were a success. from those 4 developers, 1 is still part of our code development team and maintains the work he has done as part of Summer of Code.

[1] http://forums.wesnoth.org/viewtopic.php?f=5&t=26955

==== If your organization participated in past GSoCs, please let us know the ratio of students passing to students allocated, e.g. 2006: 3/6 for 3 out of 6 students passed in 2006. ====
2008: 2/4
2009: 5/6
2010: 4/4

==== What is the URL for your ideas page? ====
http://wiki.wesnoth.org/SummerOfCodeIdeas

==== What is the main development mailing list for your organization? This question will be shown to students who would like to get more information about applying to your organization for GSoC 2011. If your organization uses more than one list, please make sure to include a description of the list so students know which to use. ====
The main development mailing list is "wesnoth-dev@gna.org". Our main means of communications is our IRC channel on freenode. If you have questions you should ask them in #wesnoth-dev on irc.freenode.net and wait for a reply (might take some hours!). The Wesnoth related channels are logged in public and the logs tend to be read by developers.

==== What is the main IRC channel for your organization? ====
#wesnoth-dev on irc.freenode.net

==== Does your organization have an application template you would like to see students use? If so, please provide it now. Please note that it is a very good idea to ask students to provide you with their contact information as part of your template. Their contact details will not be shared with you automatically via the GSoC 2011 site. ====
We plan mainly to meet potential students through our IRC channel, but the following questions are Wesnoth specific and are worth pondering for any student, even if we don't need a formal answer. So please beside just answering these questions consider visiting us in IRC: #wesnoth-dev on irc.freenode.net. This is where most of our work takes place and participating in IRC is mandatory for GSoC students participating with Wesnoth. Our experience is that this is the easiest way to communicate and solve problems that come up.

If you want to participate in GSoC as a student please copy http://wiki.wesnoth.org/SoC2011_Template_of_Student_page to a new page and fill it with the answers to the following questions

Again, participating on IRC will be highly considered, you should not hesitate to ask any questions there, including how to fill a good proposal. We highly value your capacity to communicate and work in a team, so help other students, actively ask for proposal criticism, this can only help your proposal

1) Basics

1.1) Write a small introduction to yourself.

1.2) State your preferred email address.

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?

1.5) What are you studying, subject, level and school?

1.6) What country are you from, at what time are you most likely to be able to join IRC?

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.

2) Experience

2.1) What programs/software have you worked on before?

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.

2.5) Gaming experience - Are you a gamer?

2.5.1) What type of gamer are you?

2.5.2) What type of games?

2.5.3) What type of opponents do you prefer?

2.5.4) Are you more interested in story or gameplay?

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.

We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.

3.2) What spoken languages are you fluent in?

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

3.5) Do you receive advice well?

3.6) Are you good at sorting useful criticisms from useless ones?

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

4.5) Include as much technical detail about your implementation as you can

4.6) What do you expect to gain from this project?

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?
* Subversion (used for all commits)
* C++ (language used for all the normal source code)
* STL, Boost, Sdl (C++ libraries used by Wesnoth)
* Python (optional, mainly used for tools)
* build environments (eg cmake/autotools/scons)
* WML (the wesnoth specific scenario language)
* Lua (used in combination with WML to create scenarios)

5.2) Which tools do you normally use for development? Why do you use them?

5.3) What programming languages are you fluent in?

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!

In general please try to be as verbose as possible in your answers and feel free to elaborate.

==== What criteria did you use to select the individuals who will act as mentors for your organization? Please be as specific as possible. ====
Our first criterion was that all the people had to be volunteers. According to other open source projects and our experience from the last two years, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the Art Contribution[1] section of the wiki (now deprecated) and the WML Reference Manual[2]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org that has created the new developer process we currently use. Boucman was a mentor in 2008, 2009 and 2010.

Iurii Chernyi (Crab) has joined the team in 2009, taking part in Google Summer of Code 2009, and staying with the project as a developer after successful completion of GSoC. He's an expert on all aspects of current Wesnoth AI codebase (having fully reorganized it as part of GSoC 2009), and has fixed numerous bugs all over Wesnoth. He was a GSoC mentor and a GCI mentor and administrator in 2010. He is experienced in teaching other people, in areas like programming languages and math.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring and polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base. He is currently completing a rewrite of the Wesnoth GUI library, making all windows configurable through WML. This should make it easier to use Wesnoth on different resolutions, from small handheld devices to large 30 inch screens. Mordante was a mentor in 2008, 2009 and 2010.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of "people who to contact" [3] for an easy reference. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can and will directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

[1] http://wiki.wesnoth.org/UnsortedContrib

[2] http://wiki.wesnoth.org/ReferenceWML

[3] http://wiki.wesnoth.org/SoC_People_to_bug_on_IRC

==== What is your plan for dealing with disappearing students? ====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensitive about criticism and our community is used to people being sensitive to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, their mentor will be in charge of recontacting the student to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to them, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors? ====
All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We observed in during the last years the amount of time required to mentor, and our mentors accepted the job knowing the amount of work it involved. All of this years mentors mentored last year as well.

However, should it happen, we would continue to mentor as a developer community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program? ====
Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two (non trival) patches... you're in". With other words, anybody that is able to get two non-trivial patches applied is offered commit privileges.
We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our EasyCoding pages [1] (these projects are usually a couple of hours long and hve been chosen to provide easy access to the respective area of code). This year, we also have added some simple coding tasks directly related to our GSoC ideas to be able to test students more specifically on their future project

Usually, patches go back and forth a couple of times, to make sure that all secondary things are in place (indenting, coding style, modified buildfiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to keep our project alive.

If the student is proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

In 2008, 2009 and 2010 all students that were accepted (and a couple more) managed to have commit access before the start of the coding phase. We consider that this policy was successful and we plan to keep it this year.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can sometimes be rough.

Last, our experience from previous years is that students that participate in the community during the evaluation period will stay active in the community after that period. In previous years this has been a discriminating criterias for students of similar level, and overall we never had problems of students working "behind a black wall." Our selection process tend to favor students who participate, and participation hasn't been a problem so far.

[1] http://wiki.wesnoth.org/EasyCoding

==== If you are a small or new organization applying to GSoC, please list a larger, established GSoC organization or a Googler that can vouch for you here. ====

==== If you are a large organization who is vouching for a small organization applying to GSoC for their first time this year, please list their name and why you think they'd be good candidates for GSoC here: ====
* Darktable:
Darktable (see http://darktable.sourceforge.net/ and https://sourceforge.net/apps/trac/darktable/wiki/GSOC) is an open source raw development tool.

There are currently no major open source raw development tools. Multiple tools cover the need (ufraw, rawtherapee etc...) but most of them are targeting technical users with interest in photography or signal processing experts rather than "normal" photographer.

Darktable has a very good UI designed around what most photographers expects. It is also a project which is at this interesting stage where there is a solid infrastructure and it needs developer to do the fun part of adding new feature. This is the stage of a project which is the most interesting for developers to join.

The Darktable development community is rather small (3 active developers plus occasional contributors). It could use the extra manpower but is large enough to mentor a student into a core developer pretty fast.

Chances of a student finding it interesting are high, chances of the student bringing major contributions to the project are very high

One of the experienced wesnoth mentor (boucman) is an active member of the Darktable community and has been spearheading the GSoC effort for that community and will offer advice and participation for the new mentors in that community. Wesnoth has had a dedicated IRC channel for mentor discussion which could be used by smaller projects for advice if the need arise

* Unknown Horizons:
Unknown Horizons (http://www.unknown-horizons.org/) is a 2D realtime strategy simulation with an emphasis on economy and city building.

This is a smaller open source game project with a really dedicated core team of developers. During our talks with the dev who wants to work as admin it was easy to see that they do think about what they do and got some well working infrastructure. Even though the team is rather small at the moment, they are well suited to handle some students and the project has a proven record of being able to actually release something and continue working on the code. Beside their abilities it is always good to support open source gaming, especially when it comes to rather underrepresented areas like real time strategy games.

==== Anything else you'd like to tell us? ====
There is nothing more to say.

==== Backup Admin (Link ID): ====
noy

==== Admin Agreement: ====
(some terms of service by Google that have to be agreed upon)

SoC Information for Google

2011-03-09T21:17:08Z

Boucman: /* What steps will you take to encourage students to interact with your project's community before, during and after the program? */

{{Template:SoC2011}}

== SoC Information for Google ==
This is the info that we submit to google as Application in Summer of Code (current status: 2010). The submitter automatically becomes primary Admin. Most entries are mandatory and have to be filled out before the application can be submitted.

==== Organization Name: ====
Battle for Wesnoth

==== Description: ====
''Battle for Wesnoth'', or simply ''Wesnoth'', is a free, turn-based strategy game with role-playing elements that was designed in June 2003 by David White (Sirp).

Although the core rules are fairly simple and meant to be easily learned[1], they provide interesting gameplay and rich tactical options. A major strength of the project is the Wesnoth Markup Language (WML) for writing scenarios. Programming skills are not required to compose with it, and a large WML-modding community has generated a great deal of user-maintained content. We polish the best of this content and lift it into our official release tree.

The first stable release (1.0) was on October 2, 2005, and the latest stable release (1.8) happened in april 2010. Version 1.8 is a major stable checkpoint, and 1.10 is not anticipated before the end of 2011. The currentdevelopment cycle (1.9, leading to 1.10) will premier significant changes in gameplay, UI, and development tools, with many new concepts being introduced. That makes this year probably one of the best years for a SoC student to join, since the open-ended 1.9 will mean much more space to develop novel ideas

''Wesnoth'' is one of the most successful open-source game projects in existence, with an exceptionally large developer base and user community:

* According to Ohloh, a site that collects activity statistics on open-source projects, the ''Wesnoth'' development effort is in the top 2% of largest and most active projects.
* We support two multiplayer game servers (stable and development) with a usual minimum load of more than a hundred players.
* More than two thousands downloads a day
* 4.5 million downloads via SourceForge; many more via various mirrors of Linux distributions
* Best rated game at the Linux Game Tome[2]
* Game of the year 2007, 2008, 2009, and 2010 at LinuxQuestions.org[3][4]
* In general, ''Wesnoth'' tends to show up in the first or second position whenever anyone compiles a list of top open-source games.

''Wesnoth'''s most notable features include:

* A mature project with continuing active development and frequent improvements
* High quality artwork: both original graphics and music
* Well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after six years of development and with a very solid, fun product already created, there are still plenty of new developers; the number of commits to Subversion is still increasing
* Strong support of internationalization with many supported languages, thus experience in working with non-native English speakers. In fact, more than half of our developers are not native English speakers.

[1] http://www.wesnoth.org/wiki/WesnothPhilosophy

[2] http://www.happypenguin.org/list?sort=avg_rating

[3] http://www.linuxquestions.org/questions/linux-news-59/2009-linuxquestions.org-members-choice-award-winners-788028/

[4] http://www.linuxquestions.org/questions/2010-linuxquestions-org-members-choice-awards-93/open-source-game-of-the-year-855937/

==== Home page: ====
http://www.wesnoth.org/

==== Main Organization License: ====
GNU General Public License version 2.0 (GPLv2) [Dropdown box answer!]

==== Why is your organization applying to participate in GSoC 2011? What do you hope to gain by participating? ====
Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

Our previous SoC experience shows that a motivated, full-time, student can be brought up to date in any area fairly quickly.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that are currently lagging behind.

Moreover, our previous experiences has shown us that SoC developers tend to stay after the end of the Summer of Code and become valuable members of our community. This has been a win in all directions and we want it to happen again.

==== If accepted, would this be your first year participating in GSoC? ====
No

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation. ====
2008 results:
Wesnoth participated in GSoC 2008 with four students. Out of these, two were great successes (that is they became full-fledge developers before the actual start of GSoC), did huge improvement during GSoC (A new recruitment algorithm for the AI and the basic structure for a new map editor, the student finished this work after the summer), and are still active developers in the Wesnoth community.

Of the two other, one of them was very active for the first half of GSoC and provided some useful infrastructure for AI development that we used as base in GSoC 2009, but was much less active and didn't reach expectations for the second half of GSoC. The lesson we learned is that great students should be left on their own, that's the best way to have them work, but average students should be monitored much more closely than we did. If things seems to start to go wrong, it's important to react very quick, to meet with other mentors and get things back on track early.

Timezone problems were also a serious barrier for student/mentor communication, and we will take that more into account when pairing mentors and students

For our other students, multiple problems collectively led to failure
* We should enforce IRC communication, E-mail is a barrier. This applies both for students and mentors. Both should be on IRC several hours a day, with overlapping hours.
* We should be more strict about mid-term evaluation. If the student is slightly lacking at mid-term we should give a clear message that he needs to get back on track.

2009 results:
In 2009 we mentored 6 students as part of Summer of Code. Out of these 5 projects were a success. From those 5 developers 3 are still part of our core development group and still maintain and improve the work they submitted as part of Summer of Code. One of the students even became the "head" of our AI development department and mentored a student this year. For a summary of the 2009 results have a look at [1].

Sadly one student was not able to continue his work past midterm due to his computer failing completely as well as personal problems that we won't delve into further here. It was not a salvageable situation.

2010 results:
In 2010 we mentored 4 students as part of Summer of Code, all the projects were a success. from those 4 developers, 1 is still part of our code development team and maintains the work he has done as part of Summer of Code.

[1] http://forums.wesnoth.org/viewtopic.php?f=5&t=26955

==== If your organization participated in past GSoCs, please let us know the ratio of students passing to students allocated, e.g. 2006: 3/6 for 3 out of 6 students passed in 2006. ====
2008: 2/4
2009: 5/6
2010: 4/4

==== What is the URL for your ideas page? ====
http://wiki.wesnoth.org/SummerOfCodeIdeas

==== What is the main development mailing list for your organization? This question will be shown to students who would like to get more information about applying to your organization for GSoC 2011. If your organization uses more than one list, please make sure to include a description of the list so students know which to use. ====
The main development mailing list is "wesnoth-dev@gna.org". Our main means of communications is our IRC channel on freenode. If you have questions you should ask them in #wesnoth-dev on irc.freenode.net and wait for a reply (might take some hours!). The Wesnoth related channels are logged in public and the logs tend to be read by developers.

==== What is the main IRC channel for your organization? ====
#wesnoth-dev on irc.freenode.net

==== Does your organization have an application template you would like to see students use? If so, please provide it now. Please note that it is a very good idea to ask students to provide you with their contact information as part of your template. Their contact details will not be shared with you automatically via the GSoC 2011 site. ====
We plan mainly to meet potential students through our IRC channel, but the following questions are Wesnoth specific and are worth pondering for any student, even if we don't need a formal answer. So please beside just answering these questions consider visiting us in IRC: #wesnoth-dev on irc.freenode.net. This is where most of our work takes place and participating in IRC is mandatory for GSoC students participating with Wesnoth. Our experience is that this is the easiest way to communicate and solve problems that come up.

If you want to participate in GSoC as a student please copy http://wiki.wesnoth.org/SoC2011_Template_of_Student_page to a new page and fill it with the answers to the following questions

Again, participating on IRC will be highly considered, you should not hesitate to ask any questions there, including how to fill a good proposal. We highly value your capacity to communicate and work in a team, so help other students, actively ask for proposal criticism, this can only help your proposal

1) Basics

1.1) Write a small introduction to yourself.

1.2) State your preferred email address.

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?

1.5) What are you studying, subject, level and school?

1.6) What country are you from, at what time are you most likely to be able to join IRC?

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.

2) Experience

2.1) What programs/software have you worked on before?

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.

2.5) Gaming experience - Are you a gamer?

2.5.1) What type of gamer are you?

2.5.2) What type of games?

2.5.3) What type of opponents do you prefer?

2.5.4) Are you more interested in story or gameplay?

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.

We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.

3.2) What spoken languages are you fluent in?

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

3.5) Do you receive advice well?

3.6) Are you good at sorting useful criticisms from useless ones?

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

4.5) Include as much technical detail about your implementation as you can

4.6) What do you expect to gain from this project?

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?
* Subversion (used for all commits)
* C++ (language used for all the normal source code)
* STL, Boost, Sdl (C++ libraries used by Wesnoth)
* Python (optional, mainly used for tools)
* build environments (eg cmake/autotools/scons)
* WML (the wesnoth specific scenario language)
* Lua (used in combination with WML to create scenarios)

5.2) Which tools do you normally use for development? Why do you use them?

5.3) What programming languages are you fluent in?

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!

In general please try to be as verbose as possible in your answers and feel free to elaborate.

==== What criteria did you use to select the individuals who will act as mentors for your organization? Please be as specific as possible. ====
Our first criterion was that all the people had to be volunteers. According to other open source projects and our experience from the last two years, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the Art Contribution[1] section of the wiki (now deprecated) and the WML Reference Manual[2]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org that has created the new developer process we currently use. Boucman was a mentor in 2008, 2009 and 2010.

Iurii Chernyi (Crab) has joined the team in 2009, taking part in Google Summer of Code 2009, and staying with the project as a developer after successful completion of GSoC. He's an expert on all aspects of current Wesnoth AI codebase (having fully reorganized it as part of GSoC 2009), and has fixed numerous bugs all over Wesnoth. He was a GSoC mentor and a GCI mentor and administrator in 2010. He is experienced in teaching other people, in areas like programming languages and math.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring and polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base. He is currently completing a rewrite of the Wesnoth GUI library, making all windows configurable through WML. This should make it easier to use Wesnoth on different resolutions, from small handheld devices to large 30 inch screens. Mordante was a mentor in 2008, 2009 and 2010.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of "people who to contact" [3] for an easy reference. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can and will directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

[1] http://wiki.wesnoth.org/UnsortedContrib

[2] http://wiki.wesnoth.org/ReferenceWML

[3] http://wiki.wesnoth.org/SoC_People_to_bug_on_IRC

==== What is your plan for dealing with disappearing students? ====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensitive about criticism and our community is used to people being sensitive to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, their mentor will be in charge of recontacting the student to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to them, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors? ====
All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We observed in during the last years the amount of time required to mentor, and our mentors accepted the job knowing the amount of work it involved. All of this years mentors mentored last year as well.

However, should it happen, we would continue to mentor as a developer community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program? ====
Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two (non trival) patches... you're in". With other words, anybody that is able to get two non-trivial patches applied is offered commit privileges.
We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our EasyCoding pages [1] (these projects are usually a couple of hours long and hve been chosen to provide easy access to the respective area of code). This year, we also have added some simple coding tasks directly related to our GSoC ideas to be able to test students more specifically on their future project

Usually, patches go back and forth a couple of times, to make sure that all secondary things are in place (indenting, coding style, modified buildfiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to keep our project alive.

If the student is proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

In 2008, 2009 and 2010 all students that were accepted (and a couple more) managed to have commit access before the start of the coding phase. We consider that this policy was successful and we plan to keep it this year.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can sometimes be rough.

Last, our experience from previous years is that students that participate in the community during the evaluation period will stay active in the community after that period. In previous years this has been a discriminating criterias for students of similar level, and overall we never had problems of students working "behind a black wall." Our selection process tend to favor students who participate, and participation hasn't been a problem so far.

[1] http://wiki.wesnoth.org/EasyCoding

==== If you are a small or new organization applying to GSoC, please list a larger, established GSoC organization or a Googler that can vouch for you here. ====

==== If you are a large organization who is vouching for a small organization applying to GSoC for their first time this year, please list their name and why you think they'd be good candidates for GSoC here: ====
* Darktable:
Darktable (see http://darktable.sourceforge.net/ and https://sourceforge.net/apps/trac/darktable/wiki/GSOC) is an open source raw development tool.

There are currently no major open source raw development tools. Multiple tools cover the need (ufraw, rawtherapee etc...) but most of them are targeting technical users with interest in photography or signal processing experts rather than "normal" photographer.

Darktable has a very good UI designed around what most photographers expects. It is also a project which is at this interesting stage where there is a solid infrastructure and it needs developer to do the fun part of adding new feature. This is the stage of a project which is the most interesting for developers to join.

The Darktable development community is rather small (3 active developers plus occasional contributors). It could use the extra manpower but is large enough to mentor a student into a core developer pretty fast.

Chances of a student finding it interesting are high, chances of the student bringing major contributions to the project are very high

* Unknown Horizons:
Unknown Horizons (http://www.unknown-horizons.org/) is a 2D realtime strategy simulation with an emphasis on economy and city building.

This is a smaller open source game project with a really dedicated core team of developers. During our talks with the dev who wants to work as admin it was easy to see that they do think about what they do and got some well working infrastructure. Even though the team is rather small at the moment, they are well suited to handle some students and the project has a proven record of being able to actually release something and continue working on the code. Beside their abilities it is always good to support open source gaming, especially when it comes to rather underrepresented areas like real time strategy games.

==== Anything else you'd like to tell us? ====
There is nothing more to say.

==== Backup Admin (Link ID): ====
noy

==== Admin Agreement: ====
(some terms of service by Google that have to be agreed upon)

SoC Information for Google

2011-03-09T21:08:50Z

Boucman: /* Does your organization have an application template you would like to see students use? If so, please provide it now. Please note that it is a very good idea to ask students to provide you with their contact information as part of your template. T

{{Template:SoC2011}}

== SoC Information for Google ==
This is the info that we submit to google as Application in Summer of Code (current status: 2010). The submitter automatically becomes primary Admin. Most entries are mandatory and have to be filled out before the application can be submitted.

==== Organization Name: ====
Battle for Wesnoth

==== Description: ====
''Battle for Wesnoth'', or simply ''Wesnoth'', is a free, turn-based strategy game with role-playing elements that was designed in June 2003 by David White (Sirp).

Although the core rules are fairly simple and meant to be easily learned[1], they provide interesting gameplay and rich tactical options. A major strength of the project is the Wesnoth Markup Language (WML) for writing scenarios. Programming skills are not required to compose with it, and a large WML-modding community has generated a great deal of user-maintained content. We polish the best of this content and lift it into our official release tree.

The first stable release (1.0) was on October 2, 2005, and the latest stable release (1.8) happened in april 2010. Version 1.8 is a major stable checkpoint, and 1.10 is not anticipated before the end of 2011. The currentdevelopment cycle (1.9, leading to 1.10) will premier significant changes in gameplay, UI, and development tools, with many new concepts being introduced. That makes this year probably one of the best years for a SoC student to join, since the open-ended 1.9 will mean much more space to develop novel ideas

''Wesnoth'' is one of the most successful open-source game projects in existence, with an exceptionally large developer base and user community:

* According to Ohloh, a site that collects activity statistics on open-source projects, the ''Wesnoth'' development effort is in the top 2% of largest and most active projects.
* We support two multiplayer game servers (stable and development) with a usual minimum load of more than a hundred players.
* More than two thousands downloads a day
* 4.5 million downloads via SourceForge; many more via various mirrors of Linux distributions
* Best rated game at the Linux Game Tome[2]
* Game of the year 2007, 2008, 2009, and 2010 at LinuxQuestions.org[3][4]
* In general, ''Wesnoth'' tends to show up in the first or second position whenever anyone compiles a list of top open-source games.

''Wesnoth'''s most notable features include:

* A mature project with continuing active development and frequent improvements
* High quality artwork: both original graphics and music
* Well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after six years of development and with a very solid, fun product already created, there are still plenty of new developers; the number of commits to Subversion is still increasing
* Strong support of internationalization with many supported languages, thus experience in working with non-native English speakers. In fact, more than half of our developers are not native English speakers.

[1] http://www.wesnoth.org/wiki/WesnothPhilosophy

[2] http://www.happypenguin.org/list?sort=avg_rating

[3] http://www.linuxquestions.org/questions/linux-news-59/2009-linuxquestions.org-members-choice-award-winners-788028/

[4] http://www.linuxquestions.org/questions/2010-linuxquestions-org-members-choice-awards-93/open-source-game-of-the-year-855937/

==== Home page: ====
http://www.wesnoth.org/

==== Main Organization License: ====
GNU General Public License version 2.0 (GPLv2) [Dropdown box answer!]

==== Why is your organization applying to participate in GSoC 2011? What do you hope to gain by participating? ====
Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

Our previous SoC experience shows that a motivated, full-time, student can be brought up to date in any area fairly quickly.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that are currently lagging behind.

Moreover, our previous experiences has shown us that SoC developers tend to stay after the end of the Summer of Code and become valuable members of our community. This has been a win in all directions and we want it to happen again.

==== If accepted, would this be your first year participating in GSoC? ====
No

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation. ====
2008 results:
Wesnoth participated in GSoC 2008 with four students. Out of these, two were great successes (that is they became full-fledge developers before the actual start of GSoC), did huge improvement during GSoC (A new recruitment algorithm for the AI and the basic structure for a new map editor, the student finished this work after the summer), and are still active developers in the Wesnoth community.

Of the two other, one of them was very active for the first half of GSoC and provided some useful infrastructure for AI development that we used as base in GSoC 2009, but was much less active and didn't reach expectations for the second half of GSoC. The lesson we learned is that great students should be left on their own, that's the best way to have them work, but average students should be monitored much more closely than we did. If things seems to start to go wrong, it's important to react very quick, to meet with other mentors and get things back on track early.

Timezone problems were also a serious barrier for student/mentor communication, and we will take that more into account when pairing mentors and students

For our other students, multiple problems collectively led to failure
* We should enforce IRC communication, E-mail is a barrier. This applies both for students and mentors. Both should be on IRC several hours a day, with overlapping hours.
* We should be more strict about mid-term evaluation. If the student is slightly lacking at mid-term we should give a clear message that he needs to get back on track.

2009 results:
In 2009 we mentored 6 students as part of Summer of Code. Out of these 5 projects were a success. From those 5 developers 3 are still part of our core development group and still maintain and improve the work they submitted as part of Summer of Code. One of the students even became the "head" of our AI development department and mentored a student this year. For a summary of the 2009 results have a look at [1].

Sadly one student was not able to continue his work past midterm due to his computer failing completely as well as personal problems that we won't delve into further here. It was not a salvageable situation.

2010 results:
In 2010 we mentored 4 students as part of Summer of Code, all the projects were a success. from those 4 developers, 1 is still part of our code development team and maintains the work he has done as part of Summer of Code.

[1] http://forums.wesnoth.org/viewtopic.php?f=5&t=26955

==== If your organization participated in past GSoCs, please let us know the ratio of students passing to students allocated, e.g. 2006: 3/6 for 3 out of 6 students passed in 2006. ====
2008: 2/4
2009: 5/6
2010: 4/4

==== What is the URL for your ideas page? ====
http://wiki.wesnoth.org/SummerOfCodeIdeas

==== What is the main development mailing list for your organization? This question will be shown to students who would like to get more information about applying to your organization for GSoC 2011. If your organization uses more than one list, please make sure to include a description of the list so students know which to use. ====
The main development mailing list is "wesnoth-dev@gna.org". Our main means of communications is our IRC channel on freenode. If you have questions you should ask them in #wesnoth-dev on irc.freenode.net and wait for a reply (might take some hours!). The Wesnoth related channels are logged in public and the logs tend to be read by developers.

==== What is the main IRC channel for your organization? ====
#wesnoth-dev on irc.freenode.net

==== Does your organization have an application template you would like to see students use? If so, please provide it now. Please note that it is a very good idea to ask students to provide you with their contact information as part of your template. Their contact details will not be shared with you automatically via the GSoC 2011 site. ====
We plan mainly to meet potential students through our IRC channel, but the following questions are Wesnoth specific and are worth pondering for any student, even if we don't need a formal answer. So please beside just answering these questions consider visiting us in IRC: #wesnoth-dev on irc.freenode.net. This is where most of our work takes place and participating in IRC is mandatory for GSoC students participating with Wesnoth. Our experience is that this is the easiest way to communicate and solve problems that come up.

If you want to participate in GSoC as a student please copy http://wiki.wesnoth.org/SoC2011_Template_of_Student_page to a new page and fill it with the answers to the following questions

Again, participating on IRC will be highly considered, you should not hesitate to ask any questions there, including how to fill a good proposal. We highly value your capacity to communicate and work in a team, so help other students, actively ask for proposal criticism, this can only help your proposal

1) Basics

1.1) Write a small introduction to yourself.

1.2) State your preferred email address.

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?

1.5) What are you studying, subject, level and school?

1.6) What country are you from, at what time are you most likely to be able to join IRC?

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.

2) Experience

2.1) What programs/software have you worked on before?

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.

2.5) Gaming experience - Are you a gamer?

2.5.1) What type of gamer are you?

2.5.2) What type of games?

2.5.3) What type of opponents do you prefer?

2.5.4) Are you more interested in story or gameplay?

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.

We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.

3.2) What spoken languages are you fluent in?

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

3.5) Do you receive advice well?

3.6) Are you good at sorting useful criticisms from useless ones?

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

4.5) Include as much technical detail about your implementation as you can

4.6) What do you expect to gain from this project?

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?
* Subversion (used for all commits)
* C++ (language used for all the normal source code)
* STL, Boost, Sdl (C++ libraries used by Wesnoth)
* Python (optional, mainly used for tools)
* build environments (eg cmake/autotools/scons)
* WML (the wesnoth specific scenario language)
* Lua (used in combination with WML to create scenarios)

5.2) Which tools do you normally use for development? Why do you use them?

5.3) What programming languages are you fluent in?

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!

In general please try to be as verbose as possible in your answers and feel free to elaborate.

==== What criteria did you use to select the individuals who will act as mentors for your organization? Please be as specific as possible. ====
Our first criterion was that all the people had to be volunteers. According to other open source projects and our experience from the last two years, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the Art Contribution[1] section of the wiki (now deprecated) and the WML Reference Manual[2]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org that has created the new developer process we currently use. Boucman was a mentor in 2008, 2009 and 2010.

Iurii Chernyi (Crab) has joined the team in 2009, taking part in Google Summer of Code 2009, and staying with the project as a developer after successful completion of GSoC. He's an expert on all aspects of current Wesnoth AI codebase (having fully reorganized it as part of GSoC 2009), and has fixed numerous bugs all over Wesnoth. He was a GSoC mentor and a GCI mentor and administrator in 2010. He is experienced in teaching other people, in areas like programming languages and math.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring and polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base. He is currently completing a rewrite of the Wesnoth GUI library, making all windows configurable through WML. This should make it easier to use Wesnoth on different resolutions, from small handheld devices to large 30 inch screens. Mordante was a mentor in 2008, 2009 and 2010.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of "people who to contact" [3] for an easy reference. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can and will directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

[1] http://wiki.wesnoth.org/UnsortedContrib

[2] http://wiki.wesnoth.org/ReferenceWML

[3] http://wiki.wesnoth.org/SoC_People_to_bug_on_IRC

==== What is your plan for dealing with disappearing students? ====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensitive about criticism and our community is used to people being sensitive to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, their mentor will be in charge of recontacting the student to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to them, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors? ====
All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We observed in during the last years the amount of time required to mentor, and our mentors accepted the job knowing the amount of work it involved. All of this years mentors mentored last year as well.

However, should it happen, we would continue to mentor as a developer community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program? ====
Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two (non trival) patches... you're in". With other words, anybody that is able to get two non-trivial patches applied is offered commit privileges.
We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our EasyCoding pages [1] (these projects are usually a couple of hours long and hve been chosen to provide easy access to the respective area of code).

Usually, patches go back and forth a couple of times, to make sure that all secondary things are in place (indenting, coding style, modified buildfiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to keep our project alive.

If the student is proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

In 2008, 2009 and 2010 all students that were accepted (and a couple more) managed to have commit access before the start of the coding phase. We consider that this policy was successful and we plan to keep it this year.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can sometimes be rough.

[1] http://wiki.wesnoth.org/EasyCoding

==== If you are a small or new organization applying to GSoC, please list a larger, established GSoC organization or a Googler that can vouch for you here. ====

==== If you are a large organization who is vouching for a small organization applying to GSoC for their first time this year, please list their name and why you think they'd be good candidates for GSoC here: ====
* Darktable:
Darktable (see http://darktable.sourceforge.net/ and https://sourceforge.net/apps/trac/darktable/wiki/GSOC) is an open source raw development tool.

There are currently no major open source raw development tools. Multiple tools cover the need (ufraw, rawtherapee etc...) but most of them are targeting technical users with interest in photography or signal processing experts rather than "normal" photographer.

Darktable has a very good UI designed around what most photographers expects. It is also a project which is at this interesting stage where there is a solid infrastructure and it needs developer to do the fun part of adding new feature. This is the stage of a project which is the most interesting for developers to join.

The Darktable development community is rather small (3 active developers plus occasional contributors). It could use the extra manpower but is large enough to mentor a student into a core developer pretty fast.

Chances of a student finding it interesting are high, chances of the student bringing major contributions to the project are very high

* Unknown Horizons:
Unknown Horizons (http://www.unknown-horizons.org/) is a 2D realtime strategy simulation with an emphasis on economy and city building.

This is a smaller open source game project with a really dedicated core team of developers. During our talks with the dev who wants to work as admin it was easy to see that they do think about what they do and got some well working infrastructure. Even though the team is rather small at the moment, they are well suited to handle some students and the project has a proven record of being able to actually release something and continue working on the code. Beside their abilities it is always good to support open source gaming, especially when it comes to rather underrepresented areas like real time strategy games.

==== Anything else you'd like to tell us? ====
There is nothing more to say.

==== Backup Admin (Link ID): ====
noy

==== Admin Agreement: ====
(some terms of service by Google that have to be agreed upon)

SoC Information for Google

2011-03-09T20:59:15Z

Boucman: /* Description: */

{{Template:SoC2011}}

== SoC Information for Google ==
This is the info that we submit to google as Application in Summer of Code (current status: 2010). The submitter automatically becomes primary Admin. Most entries are mandatory and have to be filled out before the application can be submitted.

==== Organization Name: ====
Battle for Wesnoth

==== Description: ====
''Battle for Wesnoth'', or simply ''Wesnoth'', is a free, turn-based strategy game with role-playing elements that was designed in June 2003 by David White (Sirp).

Although the core rules are fairly simple and meant to be easily learned[1], they provide interesting gameplay and rich tactical options. A major strength of the project is the Wesnoth Markup Language (WML) for writing scenarios. Programming skills are not required to compose with it, and a large WML-modding community has generated a great deal of user-maintained content. We polish the best of this content and lift it into our official release tree.

The first stable release (1.0) was on October 2, 2005, and the latest stable release (1.8) happened in april 2010. Version 1.8 is a major stable checkpoint, and 1.10 is not anticipated before the end of 2011. The currentdevelopment cycle (1.9, leading to 1.10) will premier significant changes in gameplay, UI, and development tools, with many new concepts being introduced. That makes this year probably one of the best years for a SoC student to join, since the open-ended 1.9 will mean much more space to develop novel ideas

''Wesnoth'' is one of the most successful open-source game projects in existence, with an exceptionally large developer base and user community:

* According to Ohloh, a site that collects activity statistics on open-source projects, the ''Wesnoth'' development effort is in the top 2% of largest and most active projects.
* We support two multiplayer game servers (stable and development) with a usual minimum load of more than a hundred players.
* More than two thousands downloads a day
* 4.5 million downloads via SourceForge; many more via various mirrors of Linux distributions
* Best rated game at the Linux Game Tome[2]
* Game of the year 2007, 2008, 2009, and 2010 at LinuxQuestions.org[3][4]
* In general, ''Wesnoth'' tends to show up in the first or second position whenever anyone compiles a list of top open-source games.

''Wesnoth'''s most notable features include:

* A mature project with continuing active development and frequent improvements
* High quality artwork: both original graphics and music
* Well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after six years of development and with a very solid, fun product already created, there are still plenty of new developers; the number of commits to Subversion is still increasing
* Strong support of internationalization with many supported languages, thus experience in working with non-native English speakers. In fact, more than half of our developers are not native English speakers.

[1] http://www.wesnoth.org/wiki/WesnothPhilosophy

[2] http://www.happypenguin.org/list?sort=avg_rating

[3] http://www.linuxquestions.org/questions/linux-news-59/2009-linuxquestions.org-members-choice-award-winners-788028/

[4] http://www.linuxquestions.org/questions/2010-linuxquestions-org-members-choice-awards-93/open-source-game-of-the-year-855937/

==== Home page: ====
http://www.wesnoth.org/

==== Main Organization License: ====
GNU General Public License version 2.0 (GPLv2) [Dropdown box answer!]

==== Why is your organization applying to participate in GSoC 2011? What do you hope to gain by participating? ====
Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

Our previous SoC experience shows that a motivated, full-time, student can be brought up to date in any area fairly quickly.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that are currently lagging behind.

Moreover, our previous experiences has shown us that SoC developers tend to stay after the end of the Summer of Code and become valuable members of our community. This has been a win in all directions and we want it to happen again.

==== If accepted, would this be your first year participating in GSoC? ====
No

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation. ====
2008 results:
Wesnoth participated in GSoC 2008 with four students. Out of these, two were great successes (that is they became full-fledge developers before the actual start of GSoC), did huge improvement during GSoC (A new recruitment algorithm for the AI and the basic structure for a new map editor, the student finished this work after the summer), and are still active developers in the Wesnoth community.

Of the two other, one of them was very active for the first half of GSoC and provided some useful infrastructure for AI development that we used as base in GSoC 2009, but was much less active and didn't reach expectations for the second half of GSoC. The lesson we learned is that great students should be left on their own, that's the best way to have them work, but average students should be monitored much more closely than we did. If things seems to start to go wrong, it's important to react very quick, to meet with other mentors and get things back on track early.

Timezone problems were also a serious barrier for student/mentor communication, and we will take that more into account when pairing mentors and students

For our other students, multiple problems collectively led to failure
* We should enforce IRC communication, E-mail is a barrier. This applies both for students and mentors. Both should be on IRC several hours a day, with overlapping hours.
* We should be more strict about mid-term evaluation. If the student is slightly lacking at mid-term we should give a clear message that he needs to get back on track.

2009 results:
In 2009 we mentored 6 students as part of Summer of Code. Out of these 5 projects were a success. From those 5 developers 3 are still part of our core development group and still maintain and improve the work they submitted as part of Summer of Code. One of the students even became the "head" of our AI development department and mentored a student this year. For a summary of the 2009 results have a look at [1].

Sadly one student was not able to continue his work past midterm due to his computer failing completely as well as personal problems that we won't delve into further here. It was not a salvageable situation.

2010 results:
In 2010 we mentored 4 students as part of Summer of Code, all the projects were a success. from those 4 developers, 1 is still part of our code development team and maintains the work he has done as part of Summer of Code.

[1] http://forums.wesnoth.org/viewtopic.php?f=5&t=26955

==== If your organization participated in past GSoCs, please let us know the ratio of students passing to students allocated, e.g. 2006: 3/6 for 3 out of 6 students passed in 2006. ====
2008: 2/4
2009: 5/6
2010: 4/4

==== What is the URL for your ideas page? ====
http://wiki.wesnoth.org/SummerOfCodeIdeas

==== What is the main development mailing list for your organization? This question will be shown to students who would like to get more information about applying to your organization for GSoC 2011. If your organization uses more than one list, please make sure to include a description of the list so students know which to use. ====
The main development mailing list is "wesnoth-dev@gna.org". Our main means of communications is our IRC channel on freenode. If you have questions you should ask them in #wesnoth-dev on irc.freenode.net and wait for a reply (might take some hours!). The Wesnoth related channels are logged in public and the logs tend to be read by developers.

==== What is the main IRC channel for your organization? ====
#wesnoth-dev on irc.freenode.net

==== Does your organization have an application template you would like to see students use? If so, please provide it now. Please note that it is a very good idea to ask students to provide you with their contact information as part of your template. Their contact details will not be shared with you automatically via the GSoC 2011 site. ====
We plan mainly to meet potential students through our IRC channel, but the following questions are Wesnoth specific and are worth pondering for any student, even if we don't need a formal answer. So please beside just answering these questions consider visiting us in IRC: #wesnoth-dev on irc.freenode.net. This is where most of our work takes place and participating in IRC is mandatory for GSoC students participating with Wesnoth. Our experience is that this is the easiest way to communicate and solve problems that come up.

1) Basics

1.1) Write a small introduction to yourself.

1.2) State your preferred email address.

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?

1.5) What are you studying, subject, level and school?

1.6) What country are you from, at what time are you most likely to be able to join IRC?

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.

2) Experience

2.1) What programs/software have you worked on before?

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.

2.5) Gaming experience - Are you a gamer?

2.5.1) What type of gamer are you?

2.5.2) What type of games?

2.5.3) What type of opponents do you prefer?

2.5.4) Are you more interested in story or gameplay?

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.

We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.

3.2) What spoken languages are you fluent in?

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

3.5) Do you receive advice well?

3.6) Are you good at sorting useful criticisms from useless ones?

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

4.5) Include as much technical detail about your implementation as you can

4.6) What do you expect to gain from this project?

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?
* Subversion (used for all commits)
* C++ (language used for all the normal source code)
* STL, Boost, Sdl (C++ libraries used by Wesnoth)
* Python (optional, mainly used for tools)
* build environments (eg cmake/autotools/scons)
* WML (the wesnoth specific scenario language)
* Lua (used in combination with WML to create scenarios)

5.2) Which tools do you normally use for development? Why do you use them?

5.3) What programming languages are you fluent in?

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!

In general please try to be as verbose as possible in your answers and feel free to elaborate.

==== What criteria did you use to select the individuals who will act as mentors for your organization? Please be as specific as possible. ====
Our first criterion was that all the people had to be volunteers. According to other open source projects and our experience from the last two years, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the Art Contribution[1] section of the wiki (now deprecated) and the WML Reference Manual[2]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org that has created the new developer process we currently use. Boucman was a mentor in 2008, 2009 and 2010.

Iurii Chernyi (Crab) has joined the team in 2009, taking part in Google Summer of Code 2009, and staying with the project as a developer after successful completion of GSoC. He's an expert on all aspects of current Wesnoth AI codebase (having fully reorganized it as part of GSoC 2009), and has fixed numerous bugs all over Wesnoth. He was a GSoC mentor and a GCI mentor and administrator in 2010. He is experienced in teaching other people, in areas like programming languages and math.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring and polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base. He is currently completing a rewrite of the Wesnoth GUI library, making all windows configurable through WML. This should make it easier to use Wesnoth on different resolutions, from small handheld devices to large 30 inch screens. Mordante was a mentor in 2008, 2009 and 2010.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of "people who to contact" [3] for an easy reference. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can and will directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

[1] http://wiki.wesnoth.org/UnsortedContrib

[2] http://wiki.wesnoth.org/ReferenceWML

[3] http://wiki.wesnoth.org/SoC_People_to_bug_on_IRC

==== What is your plan for dealing with disappearing students? ====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensitive about criticism and our community is used to people being sensitive to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, their mentor will be in charge of recontacting the student to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to them, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors? ====
All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We observed in during the last years the amount of time required to mentor, and our mentors accepted the job knowing the amount of work it involved. All of this years mentors mentored last year as well.

However, should it happen, we would continue to mentor as a developer community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program? ====
Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two (non trival) patches... you're in". With other words, anybody that is able to get two non-trivial patches applied is offered commit privileges.
We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our EasyCoding pages [1] (these projects are usually a couple of hours long and hve been chosen to provide easy access to the respective area of code).

Usually, patches go back and forth a couple of times, to make sure that all secondary things are in place (indenting, coding style, modified buildfiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to keep our project alive.

If the student is proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

In 2008, 2009 and 2010 all students that were accepted (and a couple more) managed to have commit access before the start of the coding phase. We consider that this policy was successful and we plan to keep it this year.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can sometimes be rough.

[1] http://wiki.wesnoth.org/EasyCoding

==== If you are a small or new organization applying to GSoC, please list a larger, established GSoC organization or a Googler that can vouch for you here. ====

==== If you are a large organization who is vouching for a small organization applying to GSoC for their first time this year, please list their name and why you think they'd be good candidates for GSoC here: ====
* Darktable:
Darktable (see http://darktable.sourceforge.net/ and https://sourceforge.net/apps/trac/darktable/wiki/GSOC) is an open source raw development tool.

There are currently no major open source raw development tools. Multiple tools cover the need (ufraw, rawtherapee etc...) but most of them are targeting technical users with interest in photography or signal processing experts rather than "normal" photographer.

Darktable has a very good UI designed around what most photographers expects. It is also a project which is at this interesting stage where there is a solid infrastructure and it needs developer to do the fun part of adding new feature. This is the stage of a project which is the most interesting for developers to join.

The Darktable development community is rather small (3 active developers plus occasional contributors). It could use the extra manpower but is large enough to mentor a student into a core developer pretty fast.

Chances of a student finding it interesting are high, chances of the student bringing major contributions to the project are very high

* Unknown Horizons:
Unknown Horizons (http://www.unknown-horizons.org/) is a 2D realtime strategy simulation with an emphasis on economy and city building.

This is a smaller open source game project with a really dedicated core team of developers. During our talks with the dev who wants to work as admin it was easy to see that they do think about what they do and got some well working infrastructure. Even though the team is rather small at the moment, they are well suited to handle some students and the project has a proven record of being able to actually release something and continue working on the code. Beside their abilities it is always good to support open source gaming, especially when it comes to rather underrepresented areas like real time strategy games.

==== Anything else you'd like to tell us? ====
There is nothing more to say.

==== Backup Admin (Link ID): ====
noy

==== Admin Agreement: ====
(some terms of service by Google that have to be agreed upon)

SoC Ideas Whiteboard 2011

2011-03-09T20:50:09Z

Boucman: /* Whom to ask about this */

{{Template:SoC2011Idea}}

= Description =
<h2>Improve Wesnoth's Whiteboard</h2>

More info at [[SoC_Ideas_Whiteboard_2011]]

A whiteboard planning UI was implemented last year for GSoC

This years project would be to continue the work by polishing what was done last year and making it network aware so allies can see each other's plan

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas Whiteboard 2011
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

= Implement the networked part of the Whiteboard =

The [[GSoC-WesnothWhiteboard_Gabba|Whiteboard]] is an interface project that was started during GSoC 2010. It has several goals:

1. Provide players a means to visually test out sequences of actions, especially for those which can't be undone such as attacks, or for moves which uncover shroud and thereby prevent undos.

2. Allow players to plan out recruits, recalls and even attacks and moves, while they are waiting for their turn.

3. Replace features such as waypoints (still present) and Delay Shroud Updates (present in 1.8, disabled but not removed from the code in 1.9). DSU in particular complicates life a lot for WML developers.

''4. Allow allies to see each other's plans in multiplayer (and possibly to suggest moves to each other and to the AI).''

5. Provide advanced interface features building on the work above, such as chance to kill calculations taking into account several attacks on the same unit planned through the whiteboard.

1 and 2 as well as the DSU part of 3 were finished during GSoC 2010, even though they need a lot of tweaking and bugfixing. 4 is the focus of this project.

== Specifications ==

The plans for the networked part are [[GSoC-WesnothWhiteboard_Gabba#Engine|laid out in this part of the Whiteboard GSoC 2010 page]].
Regarding last year's GSoC page, be aware that there are differences between those initial plans and the implementation currently in Wesnoth's code. [[GSoC-WesnothWhiteboard_Gabba#Calendar|This calendar]] will help you understand what was implemented and what was left out.

== Additional Information ==

* The whiteboard interface is not set in stone and might still undergo some important changes; the network part should therefore be decoupled from the UI and visuals as much as possible.

== Resources ==

* The devs who know the whiteboard best are Gabba (wrote most/all of it during GSoC 2010) and Boucman (mentored the GSoC project).

* Gabba will be very sparingly available during april, but should be generally available to answer questions for most of the summer. Plan accordingly.

* A good way of getting aquainted with the code is to fix [https://gna.org/bugs/index.php?group=wesnoth&func=browse&bug_group_id=117 some of the whiteboard bugs].

* Feedback and ongoing discussion of the whiteboard's future goes on [http://forums.wesnoth.org/viewtopic.php?f=15&t=31338 in this thread].

= Whom to ask about this =
Gabba and Boucman on #wesnoth-dev
= possible pre-soc tasks =
* Provide a way for WML to set and remove arrows using the arrow framework used in the whiteboard
* Provide a way for the AI to set and remove arrows using the framework used by whiteboard

SoC Ideas LuaAI 2011

2011-03-09T20:44:36Z

Boucman: /* Possible pre-gsoc tasks */

{{Template:SoC2011Idea}}

=Description=
<h2>Extend Wesnoth's Lua AI support and improve Wesnoth's AI</h2>

More info at [[SoC_Ideas_LuaAI_2011]]

It is very important for Wesnoth to have a way of scripting AI without modifying the c++ source code. Some time ago, it was possible to use Python to code AIs, but it was removed due to security issues. Now, we have added Lua as a new way to script AI. The core capabilities were already added, but we need to integrate Lua AI scripts better.

Wesnoth AI consists of different components. Each component is a c++ object, which provides an interface to allow the ai to delegate part of the turn sequence to that c++ object. But, that c++ object can be a proxy for code written in different language, such as formula_ai or lua. So, we have a lua engine - a c++ class which is responsible with creating c++ proxies for lua code snippets. This lua engine must provide access to all the information that the c++ AI knows - caches like 'attacks' and 'possible moves', values of aspects such as 'aggression' and 'caution', etc. So, there's a large number of AI support functions which we need to expose to lua code.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas Lua AI
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

=Required knowledge=
The student has to know or learn:
* Lua C++ api (src/scripting/lua.cpp is the example file)
* Basic WML (Wesnoth Markup language)
* Basic Lua
* Wesnoth game concepts. Gameplay experience is very important to have or gain.

=Implementation plan=
To quote from Alpha Centauri, "Technological advance is an inherently iterative process. One does not simply take sand from the beach and produce a Dataprobe. We use crude tools to fashion better tools, and then our better tools to fashion more precise tools, and so on. Each minor refinement is a step in the process, and all of the steps must be taken. ".
* So, we firstly want to expose existing c++ things to lua.
* Then, we want to build a lua-based 'wesnoth lua ai standard library', a library of functions useful to an ai developer.
* Then, we want to build a library of high-level functions which will be directly usable by scenario developer, with the level of complexity like 'drop this 1-line macro here, set this unit variable there, and voila - the unit is now controlled by lua ai according to your wishes'
* example of such behavior are 'patrol', 'retreat', and 'guard' behaviors
* then, we want to improve the ai directly, areas like recruiting with multiple leaders, actually ''defending'' something, handling concepts like leadership,skirmish, illuminate, and other, even, created-from-WML, concepts
* then, we want to make sure that multiple ais can coordinate between themselves, and stick to a certain strategy in battle,as determined by situation and whims of scenario creator

== First step: expose existing c++ things to lua ==
* we need to expose AI aspects to lua
* we need to expose AI movement maps to lua ( std::multimap<map_location, map_location> , four of them)
* we need to expose AI target lists to lua (target is a marker on the game map)

when exposing things, we should make sure we provide a accessor which does the converted version and caches the converted version.
== Second step: wesnoth lua ai standard library ==
* we need to check and document ways for the AI author to include lua ai code in the scenario. for that, we should provide ways for the code to be injected by scenario, by era, by race, etc.
* we need to ensure that our .lua library code can be easily loaded by the AI engine. preferably, ensure that each library is only loaded once.

=Useful links=

* [[Customizing_AI_in_Wesnoth_1.8]]
* [[AI_Module]]
* [[LuaAI]]
* [[LuaWML]]

=Definition of Done=
All information that is possible to use in c++ AI, is possible to use in Lua AI with relatively same level of complexity for AI author.

=Whom to ask about this=
Ask Crab_ on #wesnoth-dev

=Possible pre-gsoc tasks=
We want to make it easy to write Lua AI. The best way to ensure that is to try to write some AI components, and see what's easy, what's hard, and what's missing. So, here are a few things that can be done to get you started and to allow to code some useful lua/c++ code which can be included in wesnoth lua ai standard library.

* Write the AI which can complete Scenario 1 of the '''Heir to the Throne''' campaign on easy difficulty.
* Write the AI which can complete Scenario 1 of '''The Hammer of Thursagan''' campaign on easy difficulty.
* Write a recruitment procedure for the AI which uses with multiple leaders intelligently
* Write a system to attach 'behavior instructions written in lua' to specific units
* Write a patrol formula in Lua
* Write a basic attack routine which allows to inject a Lua 'rate attack combination' function into it.
* Write a peacefull mob AI (independant units that flee all other unit and graze peacefully when far enough)
* Re-implement useful formula ai functions in lua.

SoC Ideas Simple Content Manager

2011-03-07T18:47:59Z

Boucman: Created page with '{{SoC2011Idea}} = Submitted proposals: = {{#dpl: |resultsheader=''There are %PAGES% submitted student proposals for this idea'' |oneresultheader=''There is 1 submitted studen…'

{{SoC2011Idea}}

= Submitted proposals: =

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas IDEA NAME
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

=Description=
<h2>Create a simple content manatger frontend for non-technical users</h2>
Wesnoth has all sorts of contributors that are not coders
* translators
* graphists
* MP developers
* musicians
* etc...

A large part of these users don't know how to use content managers (git, svn, etc...) and are not interested in learning. Wesnoth has been looking for a simple frontend to the most common content managers for those developers but none of these are simple enough for our use case.

This task would be to develop a front end for the most common SCM that would mask completely the underlying tool and would target people that want to contribute to open source, are not technically inclined, and don't want to learn. This tool would implement a minimal subset of SCM features with the philosophy that the user has the support of technicall people to do complicated tasks

the following feature list is here to help understand the use-case for the tool

'''things the tool might do'''
* update repository wrt distant repository
* commit to distant repository
* prepare a bundle to attach to a mail
* switch branch
* resolve merge conflicts
* build a report on the underlying SCM situation to allow debugging by someone else
* register as a handler to svn:// and git://

'''things the tool shouldn't do''
* create a new project (if you want to do that, you should learn the real tool)
* create a new branch (a person with the real tool can do that on the repository for you in the rare case it's needed)

'''other misc constraints'''
* python is the prefered language (all of wesnoth tool are in python) java could be used too (we already have some java code, so maintainability should be ok)
* it should be SCM agnostic (the point is to lower the barrier to entry for non-technical users)
* the UI should not be frightening to non-technical people (I.E give some thought to UI design in your proposal)
* it should integrate as properly as possible into the OS
* it should work on windows, Mac and linux

SoC Information for Google

2011-03-05T19:19:34Z

{{Template:SoC2010}}

== SoC Information for Google ==
This is the info that we submit to google as Application in Summer of Code (current status: 2010). The submitter automatically becomes primary Admin. Most entries are mandatory and have to be filled out before the application can be submitted.

==== Organization Name: ====
Battle for Wesnoth

==== Description: ====
''Battle for Wesnoth'', or simply ''Wesnoth'', is a free, turn-based strategy game with role-playing elements that was designed in June 2003 by David White (Sirp).

Although the core rules are fairly simple and meant to be easily learned[1], they provide interesting gameplay and rich tactical options. A major strength of the project is the Wesnoth Markup Language (WML) for writing scenarios. Programming skills are not required to compose with it, and a large WML-modding community has generated a great deal of user-maintained content. We polish the best of this content and lift it into our official release tree.

The first stable release (1.0) was on October 2, 2005, and the latest stable release (1.8) is anticipated in the next few weeks. Version 1.8 is intended to be a major stable checkpoint. We expect the following development cycle (1.9, leading to 1.10) to premier significant changes in gameplay, UI, and development tools, with many new concepts being introduced. That makes this year probably one of the best years for a SoC student to join, since the open-ended 1.9 will mean much more space to develop novel ideas

''Wesnoth'' is one of the most successful open-source game projects in existence, with an exceptionally large developer base and user community:

* According to Ohloh, a site that collects activity statistics on open-source projects, the ''Wesnoth'' development effort is in the top 2% of largest and most active projects.
* We support two multiplayer game servers (stable and development) with a usual minimum load of more than a hundred players
* More than two thousands downloads a day
* 3 million downloads via SourceForge; many more via various mirrors of Linux distributions
* Best rated game at the Linux Game Tome[2]
* Game of the year 2007, 2008, and 2009 at LinuxQuestions.org[3]
* In general, ''Wesnoth'' tends to show up in the first or second position whenever anyone compiles a list of top open-source games.

''Wesnoth'''s most notable features include:

* A mature project with continuing active development and frequent improvements
* High quality artwork: both original graphics and music
* Well-balanced by a tireless team of playtesters
* Fun, unique gameplay
* Even after six years of development and with a very solid, fun product already created, there are still plenty of new developers; the number of commits to Subversion is still increasing
* Strong support of internationalization with many supported languages, thus experience in working with non-native English speakers. In fact, more than half of our developers are not native English speakers.

[1] http://www.wesnoth.org/wiki/WesnothPhilosophy

[2] http://www.happypenguin.org/list?sort=avg_rating

[3] http://www.linuxquestions.org/questions/linux-news-59/2009-linuxquestions.org-members-choice-award-winners-788028/

==== Home page: ====
http://www.wesnoth.org/

==== Main Organization License: ====
GNU General Public License version 2.0 (GPLv2) [Dropdown box answer!]

==== Why is your organization applying to participate in GSoC 2011? What do you hope to gain by participating? ====
Most of our developers have particular areas of interest in which they work. Though they are efficient in their areas, there are other, presently uncovered, areas of the code with a need for improvements but a high barrier to entry for casual contributors.

Our previous SoC experience shows that a motivated, full-time, student can be brought up to date in any area fairly quickly.

By bringing new people in and allowing them to be actively responsible for an area of code, we hope to kickstart some areas of the project that are currently lagging behind.

Moreover, our previous experiences has shown us that SoC developers tend to stay after the end of the Summer of Code and become valuable members of our community. This has been a win in all directions and we want it to happen again.

==== If accepted, would this be your first year participating in GSoC? ====
No

==== Did your organization participate in past GSoCs? If so, please summarize your involvement and the successes and challenges of your participation. ====
2008 results:
Wesnoth participated in GSoC 2008 with four students. Out of these, two were great successes (that is they became full-fledge developers before the actual start of GSoC), did huge improvement during GSoC (A new recruitment algorithm for the AI and the basic structure for a new map editor, the student finished this work after the summer), and are still active developers in the Wesnoth community.

Of the two other, one of them was very active for the first half of GSoC and provided some useful infrastructure for AI development that we used as base in GSoC 2009, but was much less active and didn't reach expectations for the second half of GSoC. The lesson we learned is that great students should be left on their own, that's the best way to have them work, but average students should be monitored much more closely than we did. If things seems to start to go wrong, it's important to react very quick, to meet with other mentors and get things back on track early.

Timezone problems were also a serious barrier for student/mentor communication, and we will take that more into account when pairing mentors and students

For our other students, multiple problems collectively led to failure
* We should enforce IRC communication, E-mail is a barrier. This applies both for students and mentors. Both should be on IRC several hours a day, with overlapping hours.
* We should be more strict about mid-term evaluation. If the student is slightly lacking at mid-term we should give a clear message that he needs to get back on track.

2009 results:
In 2009 we mentored 6 students as part of Summer of Code. Out of these 5 projects were a success. From those 5 developers 3 are still part of our core development group and still maintain and improve the work they submitted as part of Summer of Code. One of the students even became the "head" of our AI development department and wants to mentor a student this year. For a summary of the 2009 results have a look at [1].

Sadly one student was not able to continue his work past midterm due to his computer failing completely as well as personal problems that we won't delve into further here. It was not a salvageable situation.

[1] http://forums.wesnoth.org/viewtopic.php?f=5&t=26955

==== If your organization participated in past GSoCs, please let us know the ratio of students passing to students allocated, e.g. 2006: 3/6 for 3 out of 6 students passed in 2006. ====
2008: 2/4
2009: 5/6
2010: 4/4

==== What is the URL for your ideas page? ====
http://wiki.wesnoth.org/SummerOfCodeIdeas

==== What is the main development mailing list for your organization? This question will be shown to students who would like to get more information about applying to your organization for GSoC 2011. If your organization uses more than one list, please make sure to include a description of the list so students know which to use. ====
The main development mailing list is "wesnoth-dev@gna.org". Our main means of communications is our IRC channel on freenode. If you have questions you should ask them in #wesnoth-dev on irc.freenode.net and wait for a reply (might take some hours!). The Wesnoth related channels are logged in public and the logs tend to be read by developers.

==== What is the main IRC channel for your organization? ====
#wesnoth-dev on irc.freenode.net

==== Does your organization have an application template you would like to see students use? If so, please provide it now. Please note that it is a very good idea to ask students to provide you with their contact information as part of your template. Their contact details will not be shared with you automatically via the GSoC 2011 site. ====
We plan mainly to meet potential students through our IRC channel, but the following questions are Wesnoth specific and are worth pondering for any student, even if we don't need a formal answer. So please beside just answering these questions consider visiting us in IRC: #wesnoth-dev on irc.freenode.net. This is where most of our work takes place and participating in IRC is mandatory for GSoC students participating with Wesnoth. Our experience is that this is the easiest way to communicate and solve problems that come up.

1) Basics

1.1) Write a small introduction to yourself.

1.2) State your preferred email address.

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?

1.5) What are you studying, subject, level and school?

1.6) What country are you from, at what time are you most likely to be able to join IRC?

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.

2) Experience

2.1) What programs/software have you worked on before?

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.

2.5) Gaming experience - Are you a gamer?

2.5.1) What type of gamer are you?

2.5.2) What type of games?

2.5.3) What type of opponents do you prefer?

2.5.4) Are you more interested in story or gameplay?

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.

We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.

3.2) What spoken languages are you fluent in?

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

3.5) Do you receive advice well?

3.6) Are you good at sorting useful criticisms from useless ones?

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

4.5) Include as much technical detail about your implementation as you can

4.6) What do you expect to gain from this project?

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?
* Subversion (used for all commits)
* C++ (language used for all the normal source code)
* STL, Boost, Sdl (C++ libraries used by Wesnoth)
* Python (optional, mainly used for tools)
* build environments (eg cmake/autotools/scons)
* WML (the wesnoth specific scenario language)
* Lua (used in combination with WML to create scenarios)

5.2) Which tools do you normally use for development? Why do you use them?

5.3) What programming languages are you fluent in?

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!

In general please try to be as verbose as possible in your answers and feel free to elaborate.

==== What criteria did you use to select the individuals who will act as mentors for your organization? Please be as specific as possible. ====
Our first criterion was that all the people had to be volunteers. According to other open source projects and our experience from the last two years, being a SoC mentor takes a lot of time and the person has to be ready to spend quite some time with the student.

Boucman is one of the oldest active developers around. He has rewritten the whole animation engine and made it an easily pluggable system allowing artists to easily specify exactly how they want the units to appear. He also started many community oriented projects like the Art Contribution[1] section of the wiki (now deprecated) and the WML Reference Manual[2]. He is responsible for dispatching and sorting the patches at http://patches.wesnoth.org that has created the new developer process we currently use. Boucman was a mentor in 2008 and 2009.

Yurii Chernyi (Crab) has joined the team in 2009, taking part in Google Summer of Code 2009, and staying with the project as a developer after successful completion of GSoC. He's an expert on all aspects of current Wesnoth AI codebase (having fully reorganized it as part of GSoC 2009), and has fixed numerous bugs all over Wesnoth. He is experienced in teaching other people, in areas like programming languages and math.

Mordante is one of the most active developers on our IRC channel. Not only has he done preliminary studies and coding in multiple areas that are candidates for Summer of Code ideas, he also is one of the coders with the best overview of the Wesnoth code. A large part of his work involves refactoring and polishing existing code. Next to that he's very active with fixing bugs which leads him to all areas in the code base. He is currently completing a rewrite of the Wesnoth GUI library, making all windows configurable through WML. This should make it easier to use Wesnoth on different resolutions, from small handheld devices to large 30 inch screens. Mordante was a mentor in 2008 and 2009.

All other developers listed in the ideas page are the leading capacities we do have for the respecting areas. Have a look at our list of "people who to contact" [3] for an easy reference. In general all our developers will mentor all students. That is, questions should just be asked in our IRC channel, where basically every developer who has an idea can and will directly answer.

When choosing the mentors, we have kept in mind that most developers can answer most technical questions, and we have chosen people that are well known for interacting with new-comers/external developers and can provide general guidance and design advice, more than people with specific technical knowledge.

[1] http://wiki.wesnoth.org/UnsortedContrib

[2] http://wiki.wesnoth.org/ReferenceWML

[3] http://wiki.wesnoth.org/SoC_People_to_bug_on_IRC

==== What is your plan for dealing with disappearing students? ====
The first thing to do is to avoid this situation altogether.

Wesnoth is a game, and as such has lots of developers that are not coders. In particular, artists are well known in the Wesnoth community for being very sensitive about criticism and our community is used to people being sensitive to critics.

We will try to choose students that accept criticism and are able to filter constructive criticism from useless one. The Wesnoth developer community is used to judging people according to these criteria and the special title we are going to give to applicants will allow us to easily spot any such problems and discuss them before they grow out of control.

If a student disappears, their mentor will be in charge of recontacting the student to see what is going wrong (available time, tension with other developers, with members of the community etc...). Depending on the actual problem, the mentor and the student will have to agree on possible ways to defuse the problem.

If a student disappears completely and there is no way to get back to them, there is little the project can do except salvaging whatever can be salvaged from the code (the students will have SVN write access, so most of the work will be committed either to trunk or to a specific branch) and find a core developer to take on the job. This will probably be slower and less effective for the project, but it's the best we can do.

==== What is your plan for dealing with disappearing mentors? ====
All our mentors are long time developers that volunteered for the job, so we don't expect that to happen. We observed in 2008 the amount of time required to mentor, and our mentors accepted the job knowing the amount of work it involved. Most of them were mentors last year too.

However, should it happen, we would continue to mentor as a developer community the student until we find a new "official" mentor to take on the job.

==== What steps will you take to encourage students to interact with your project's community before, during and after the program? ====
Wesnoth has a particularly healthy community, both for developers and for players.

Our general policy regarding new coders has always been "two (non trival) patches... you're in". With other words, anybody that is able to get two non-trivial patches applied is offered commit privileges.
We have a developer responsible for applying patches and guiding new developers into our community. This is a well known and effective process we plan to apply to students, directing them to our EasyCoding pages [1] (these projects are usually a couple of hours long and hve been chosen to provide easy access to the respective area of code).

Usually, patches go back and forth a couple of times, to make sure that all secondary things are in place (indenting, coding style, modified buildfiles etc.) The idea is that coder education should take place before the coder gets commit rights, but that getting new coder in is one of the most important things to keep our project alive.

If the student is proactive and ready to join IRC, all the developers are usually very welcoming, and good at directing newcomers to quickly give useful results.

In 2008 and 2009 all students that were accepted (and a couple more) managed to have commit access before the start of the coding phase. We consider that this policy was successful and we plan to keep it this year.

We also plan to give a special forum title to any students. This will allow all forum members to tell them apart from normal users and give them read/write access to the developer only forums. This will also allow us to quickly spot any problem they might have interacting with the player community. We have a very mature developer community, but our player community is made of all sort of people of all age and education, and it can sometimes be rough.

[1] http://wiki.wesnoth.org/EasyCoding

==== If you are a small or new organization applying to GSoC, please list a larger, established GSoC organization or a Googler that can vouch for you here. ====

==== If you are a large organization who is vouching for a small organization applying to GSoC for their first time this year, please list their name and why you think they'd be good candidates for GSoC here: ====

Darktable (see http://darktable.sourceforge.net/ and https://sourceforge.net/apps/trac/darktable/wiki/GSOC) is an open source raw developement tool.

There are currently no major open source raw developement tools. Multiple tools cover the need (ufraw, rawtherapee etc...) but most of them are targetting technical users with interest in photography or signal processing experts rather than "normal" photographer.

Darktable has a very good UI designed around what most photographers expects. It is also a project which is at this interesting stage where there is a solid infrastructure and it needs developer to do the fun part of adding new feature. This is the stage of a project which is the most interesting for developers to join.

The Darktable developement community is rather small (3 active developers plus occasional contributors). It could use the extra manpower but is large enought to mentor a student into a core developer pretty fast.

Chances of a student finding it interesting are high, chances of the student bringing major contributions to the project are very high

==== Anything else you'd like to tell us? ====
There is nothing more to say.

==== Backup Admin (Link ID): ====
noy

==== Admin Agreement: ====
(some terms of service by Google that have to be agreed upon)

SoC Ideas Whiteboard 2011

2011-02-27T11:48:10Z

Boucman: /* Description */

{{Template:SoC2011Idea}}
= Submitted proposals: =

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2011 Student Page&SoC Ideas Whiteboard 2011
|notcategory=SoC 2011 Not Submitted To Google
|include=#Description
|mode=userformat
|format=,,<br/>See [[%PAGE%|%TITLE%]] for more information.<br/><br/>,
}}

= Description =
<h2>Whiteboard</h2>

A whiteboard planning UI was implemented last year for GSoC

This years project would be to continue the work by polishing what was done last year and making it network aware so allies can see each other's plan

Page for the idea: [[SoC_Ideas_Whiteboard_2011]]

= Implement the networked part of the Whiteboard =

The [[GSoC-WesnothWhiteboard_Gabba|Whiteboard]] is an interface project that was started during GSoC 2010. It has several goals:

1. Provide players a means to visually test out sequences of actions, especially for those which can't be undone such as attacks, or for moves which uncover shroud and thereby prevent undos.

2. Allow players to plan out recruits, recalls and even attacks and moves, while they are waiting for their turn.

3. Replace features such as waypoints (still present) and Delay Shroud Updates (present in 1.8, disabled but not removed from the code in 1.9). DSU in particular complicates life a lot for WML developers.

''4. Allow allies to see each other's plans in multiplayer (and possibly to suggest moves to each other and to the AI).''

5. Provide advanced interface features building on the work above, such as chance to kill calculations taking into account several attacks on the same unit planned through the whiteboard.

1 and 2 as well as the DSU part of 3 were finished during GSoC 2010, even though they need a lot of tweaking and bugfixing. 4 is the focus of this project.

== Specifications ==

The plans for the networked part are [[GSoC-WesnothWhiteboard_Gabba#Engine|laid out in this part of the Whiteboard GSoC 2010 page]].
Regarding last year's GSoC page, be aware that there are differences between those initial plans and the implementation currently in Wesnoth's code. [[GSoC-WesnothWhiteboard_Gabba#Calendar|This calendar]] will help you understand what was implemented and what was left out.

== Additional Information ==

* The whiteboard interface is not set in stone and might still undergo some important changes; the network part should therefore be decoupled from the UI and visuals as much as possible.

== Resources ==

* The devs who know the whiteboard best are Gabba (wrote most/all of it during GSoC 2010) and Boucman (mentored the GSoC project).

* Gabba will be very sparingly available during april, but should be generally available to answer questions for most of the summer. Plan accordingly.

* A good way of getting aquainted with the code is to fix [https://gna.org/bugs/index.php?group=wesnoth&func=browse&bug_group_id=117 some of the whiteboard bugs].

* Feedback and ongoing discussion of the whiteboard's future goes on [http://forums.wesnoth.org/viewtopic.php?f=15&t=31338 in this thread].

Fosdem2011

2010-12-18T10:33:32Z

Boucman: /* Schedule/Plans */

== General information ==
This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2011. That is everyone attending should please list him/herself in the list of arrivals and stuff like this. FOSDEM 2011 will take place at the first weekend in Febuary 2011, on Saturday 5th and Sunday 6th.

* Fosdem - http://fosdem.org/2011/

== Schedule/Plans ==
{| border="1" width="100%"
|-
! (nick)name(s)
! Arrival
! Departure
! Accomodation
|-
|-
| Ivanovic
| Fri, 4th
| Sun, 6th
| 2go4, not booked yet
|-
|-
| Boucman
| Fri, 4th
| Sun, 6th
| 2go4, not booked yet
|-
|}

For accomodations please keep in mind that parking in the center of Brussels is really problematic. It might make sense to drive to the University where FOSDEM takes place, park there and take the bus into the town center (where some of the hotels/hostels are).

Possible hostels that we at least contacted over the last years (some of them might already be booked out by now!):
* [http://www.chab.be/ CHAB]
* [http://www.2go4.be/ 2go4] Note: groups bigger 6 are not allowed, so we can (officially) not form a complete Wesnoth group at this hostel, got to meet somewhere in town/at the university...
* [http://www.jeugdherbergen.be/brusselE.htm Bruegel YH]

On the official FOSDEM page [http://www.fosdem.org/2011/practical/accommodation some more possible hotels/hostels] are listed.

== Maps ==
* [http://tinyurl.com/3a65gr Bruegel YH]
* [http://tinyurl.com/35br9c Brussels Central (Train Station) → Bruegel YH]
* [http://tinyurl.com/37d9v4 Bruegel YH → Brussels Central (Train Station) → Novotel Grand Place]
* [http://tinyurl.com/2mzns6 Novotel Grand Place]
* [http://tinyurl.com/3dggg3 CrownePlaza (Europa)]
* [http://tinyurl.com/36epxj FOSDEM]
* [http://tinyurl.com/2w4bms Novotel Grand Place -> FOSDEM]

== Transportation ==
Information about how to reach the FOSDEM is listed at the [http://www.fosdem.org/2011/transportation official transportation subpage].

Short version of how to get there for those that reside in Bruegel YH and Novotel Grand Place (basically town center):

* Enter Bus 71 (Debrouckere - Central Station ("Gare Centrale") - Delta) somewhere at 'Central Station'
* Leave the bus at "ULB" (crossroads Ave. Adolphe Buyl - Sq. Deveze)
* Walk down Ave. Paul Heger on your right hand.

== Wesnoth Hacking Room ==

Wesnoth will not have a room of its own. Instead we will use one of the "general hacking rooms". So far it is not sure which room it will be, if we do it like the last three years, it will be room number 115 in the building AW1. Last year this was the smaller of the two hacking rooms and we had no real problem with conquering (and holding) the first row in this room. There were not too many power outlets, so this year at least Ivanovic will bring one multi-outlet power strip plus some extension cable (5m or something like this). There is no wired network, everything wireless (and sometimes rather/very unstable!). Beside this you should bring laptops since there are no computers available for hacking.

Short version:
AW1 - Room 115

== Planned discussion ==
We usually discuss all sorts of things at FOSDEM, this section is here to have a small bullet list of things that we actively want to discuss at FOSDEM.
* GSOC 2011: finding mentors, organizing the submission etc..
* GCI 2010/2011: was it good, should we try to do it again next year ?
* FOSDEM 2012 : trying to get a dev room with other games ?
* [wanted: discussion topics!]

== Group Picture ==

to be linked here after FOSDEM

== FOSDEM 2010 ==
We were already at FOSDEM 2010, here something as reference:

* [http://www.wesnoth.org/wiki/Fosdem2010 FOSDEM 2010 wiki page]

== FOSDEM 2009 ==
We were already at FOSDEM 2009, here something as reference:

* [http://www.wesnoth.org/wiki/Fosdem2009 FOSDEM 2009 wiki page]

== FOSDEM 2008 ==
We were already at FOSDEM 2008, here something as reference:

* [http://www.wesnoth.org/forum/viewtopic.php?p=283649#p283649 Forum topic (with group photo)]
* [http://www.wesnoth.org/wiki/Fosdem2008 2008 wiki page]
* [https://mail.gna.org/public/wesnoth-dev/2008-02/msg00078.html Summary of FOSDEM 2008 results]

[[Category:Development]]
[[Category:Wesconf]]

Fosdem2011

2010-12-18T10:29:31Z

Boucman: Created page with '== General information == This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2011. That is everyone attending should please list him/herself in the…'

== General information ==
This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2011. That is everyone attending should please list him/herself in the list of arrivals and stuff like this. FOSDEM 2011 will take place at the first weekend in Febuary 2011, on Saturday 5th and Sunday 6th.

* Fosdem - http://fosdem.org/2011/

== Schedule/Plans ==
{| border="1" width="100%"
|-
! (nick)name(s)
! Arrival
! Departure
! Accomodation
|-
|}

For accomodations please keep in mind that parking in the center of Brussels is really problematic. It might make sense to drive to the University where FOSDEM takes place, park there and take the bus into the town center (where some of the hotels/hostels are).

Possible hostels that we at least contacted over the last years (some of them might already be booked out by now!):
* [http://www.chab.be/ CHAB]
* [http://www.2go4.be/ 2go4] Note: groups bigger 6 are not allowed, so we can (officially) not form a complete Wesnoth group at this hostel, got to meet somewhere in town/at the university...
* [http://www.jeugdherbergen.be/brusselE.htm Bruegel YH]

On the official FOSDEM page [http://www.fosdem.org/2011/practical/accommodation some more possible hotels/hostels] are listed.

== Maps ==
* [http://tinyurl.com/3a65gr Bruegel YH]
* [http://tinyurl.com/35br9c Brussels Central (Train Station) → Bruegel YH]
* [http://tinyurl.com/37d9v4 Bruegel YH → Brussels Central (Train Station) → Novotel Grand Place]
* [http://tinyurl.com/2mzns6 Novotel Grand Place]
* [http://tinyurl.com/3dggg3 CrownePlaza (Europa)]
* [http://tinyurl.com/36epxj FOSDEM]
* [http://tinyurl.com/2w4bms Novotel Grand Place -> FOSDEM]

== Transportation ==
Information about how to reach the FOSDEM is listed at the [http://www.fosdem.org/2011/transportation official transportation subpage].

Short version of how to get there for those that reside in Bruegel YH and Novotel Grand Place (basically town center):

* Enter Bus 71 (Debrouckere - Central Station ("Gare Centrale") - Delta) somewhere at 'Central Station'
* Leave the bus at "ULB" (crossroads Ave. Adolphe Buyl - Sq. Deveze)
* Walk down Ave. Paul Heger on your right hand.

== Wesnoth Hacking Room ==

Wesnoth will not have a room of its own. Instead we will use one of the "general hacking rooms". So far it is not sure which room it will be, if we do it like the last three years, it will be room number 115 in the building AW1. Last year this was the smaller of the two hacking rooms and we had no real problem with conquering (and holding) the first row in this room. There were not too many power outlets, so this year at least Ivanovic will bring one multi-outlet power strip plus some extension cable (5m or something like this). There is no wired network, everything wireless (and sometimes rather/very unstable!). Beside this you should bring laptops since there are no computers available for hacking.

Short version:
AW1 - Room 115

== Planned discussion ==
We usually discuss all sorts of things at FOSDEM, this section is here to have a small bullet list of things that we actively want to discuss at FOSDEM.
* GSOC 2011: finding mentors, organizing the submission etc..
* GCI 2010/2011: was it good, should we try to do it again next year ?
* FOSDEM 2012 : trying to get a dev room with other games ?
* [wanted: discussion topics!]

== Group Picture ==

to be linked here after FOSDEM

== FOSDEM 2010 ==
We were already at FOSDEM 2010, here something as reference:

* [http://www.wesnoth.org/wiki/Fosdem2010 FOSDEM 2010 wiki page]

== FOSDEM 2009 ==
We were already at FOSDEM 2009, here something as reference:

* [http://www.wesnoth.org/wiki/Fosdem2009 FOSDEM 2009 wiki page]

== FOSDEM 2008 ==
We were already at FOSDEM 2008, here something as reference:

* [http://www.wesnoth.org/forum/viewtopic.php?p=283649#p283649 Forum topic (with group photo)]
* [http://www.wesnoth.org/wiki/Fosdem2008 2008 wiki page]
* [https://mail.gna.org/public/wesnoth-dev/2008-02/msg00078.html Summary of FOSDEM 2008 results]

[[Category:Development]]
[[Category:Wesconf]]

InterfaceActionsWML

2010-11-29T22:59:26Z

Boucman: /* Other interface tags */

{{WML Tags}}
== Interface actions ==

Interface actions are actions that do not have an effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>'''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': {{DevFeature1.9}} Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
It can also be used to overwrite the starting objectives mid-scenario.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''gold_carryover_string''' {{DevFeature1.9}}: Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''' {{DevFeature1.9}}: Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''' {{DevFeature1.9}}: If set to yes, displays the number of turns remaining in the scenario. Only works if '''condition'''=lose. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only. {{DevFeature}}
* '''[gold_carryover]''' {{DevFeature1.9}}: describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''' {{DevFeature1.9}}: describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''description''': the text of the note.

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.

== Other interface tags ==

The following tags are also action tags:
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
** '''x''', '''y''': the location to place the item.
** '''image''': the image (in ''images/'' as .png) to place on the hex.
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
** '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
** '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''[removeitem]''': removes any graphical items on a given hex. (In version 1.9.2, this was renamed to '''[remove_item]''')
** '''x''', '''y''': the hex to remove items off
** '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)
* '''[print]''': displays a message across the screen. The message will disappear after a certain time.
** '''text''': (translatable) the text to display.
** '''size''': (default=12) the pointsize of the font to use
** '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
** '''type''': the type of the unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''gender''': the gender of the fake unit. Example: gender=female
** '''variation''': the variation of the fake unit. Example: variation=undead
* '''[move_units_fake]''': {{DevFeature1.9}} moves multiple images of units along paths on the map. These units are moved in lockstep.
** '''[fake_unit]''': A fake unit to move
*** '''type''': the type of unit whose image to use
*** '''x''': a comma-separated list of x locations to move along
*** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
*** '''side''': the side of the fake unit, used for team-coloring the fake unit
*** '''skip_steps''': the number of steps to skip before this unit starts moving
* '''[hide_unit]''': temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
** {{DevFeature1.9}}: '''[hide_unit]''' accepts a [[StandardUnitFilter]] as argument and can disable several units at once.
* '''[unhide_unit]''': stops the currently hidden units from being hidden.
** {{DevFeature1.9}}: '''[unhide_unit]''' accepts a [[StandardUnitFilter]] as argument.
* '''[scroll]''': Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
** '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''[scroll_to]''': Scroll to a given hex
** '''x''', '''y''': the hex to scroll to
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[scroll_to_unit]''' Scroll to a given unit
** [[StandardUnitFilter]]
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[select_unit]''': {{DevFeature1.9}} Selects a given unit
** [[StandardUnitFilter]]
** '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no'').
** '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').
* '''[sound]''': Plays a sound
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
** '''repeat''': repeats the sound for a specified additional number of times (default=0)
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
** '''id''': a unique identification key of the sound source
** '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
** '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
** '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
** '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
** '''check_shrouded''': {{DevFeature}} possible values "true" and "false" - if true the source will not play if its locations are shrouded
** '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
** '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
** '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
** '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)
* '''[remove_sound_source]''': Removes a previously defined sound source.
** '''id''': the identification key of the sound source to remove
* '''[music]''': Switches to playing different music
** '''name''': the filename of the music to play (in ''music/'' as .ogg)
** see [[MusicListWML]] for the correct syntax
* '''[volume]''': {{DevFeature1.9}} Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
** '''music''': Changes the music volume.
** '''sound''': Changes the sound volume.
* '''[colour_adjust]''': tints the color of the screen. {{DevFeature1.9}}: now named '''[color_adjust]'''.
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
* '''[delay]''': pauses the game
** '''time''': the time to pause in milliseconds
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around
** '''x''', '''y''': the location of the unit to overlay on
** '''image''': the image to place on the unit
** {{DevFeature1.9}}: '''[unit_overlay]''' accepts a [[StandardUnitFilter]] as argument
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit
** '''x''', '''y''': the location of the unit to remove an overlay from
** '''image''': the image to remove from the unit
** {{DevFeature1.9}}: '''[remove_unit_overlay]''' accepts a [[StandardUnitFilter]] as argument
* '''[animate_unit]''': Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
** '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
** '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
** '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
** '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
** '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
** '''text''': a text to hover during the animation
** '''red''': red value for the text color (0-255)
** '''green''': green value for the text color
** '''blue''': blue value for the text color
** '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
** '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
** '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated
* '''[label]''' places a label on the map.
** '''x''', '''y''': the location of the label
** '''text''': what the label should say
** '''team_name''': if specified, the label will only be visible to the given team.
** '''colour''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255. {{DevFeature1.9}}: now named '''color'''.
** '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
** '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
** '''immutable''': whether this label is protected from being removed or changed by players. Default yes. {{DevFeature1.9}}
* '''[floating_text]''': {{DevFeature1.9}} floats text (similar to the damage and healing numbers) on the given locations.
** [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
** '''text''': the text to display.
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
** '''message''': the message to show.
* '''[wml_message]''' outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
** '''message''': the message to show.
** '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.
* '''[open_help]''' opens the in-game help.
** '''topic''': the id of the topic to open
* '''[show_objectives]''': {{DevFeature}} refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
** '''side''': the side to show the objectives. If not set, all sides are used.
* '''[chat]''' displays a message in the chat area. {{DevFeature1.9}}
** '''speaker''': The sender of the message. Normally this is a string. However if you enter the name of a variable in which a unit is stored (such as ''second_unit'') it will display that unit's name instead.
** '''message''': The message that should be displayed
** '''side''': A comma separated list of sides to show the message to. If the same machine controls multiple sides that are in this list, then the message will only be displayed once. If left blank the message will be send to all sides.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor like screenshake and plays <soundfile>. ('''{TREMOR}''' is a deprecated version, equivalent to '''{QUAKE (rumble.ogg)}''')
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

GCI/Playtesting

2010-11-24T09:40:29Z

Boucman: /* Wesnoth 1.9.2 Playtesting */

= Wesnoth 1.9.2 Playtesting =
Download from here: http://wiki.wesnoth.org/Download#Development_.281.9_branch.29

Wesnoth 1.9 ships with 16 campaigns which total over 200 scenarios, each one with varying amounts of events, dialogue, cutscenes, special gameplay mechanics, and so on. It's inevitable that many scenarios contain bugs which have gone unnoticed or unreported. Also, most scenarios were originally written a long time ago when the game engine was much less versatile, meaning that some scenario mechanics don't function as naturally and conveniently as they could.

This task involves picking a mainline campaign on a specific difficulty level, playing through it and reporting in as much detail as possible all bugs and glitches encountered as well as suggestions for improvement. Campaigns with scenario branching should get all their branches tested.

Requirements

Reasonably familiar with Wesnoth campaigns, so as to be able to identify bugs and suggest realistically doable gameplay-enhancing changes in detail. No coding in WML or otherwise required.

Difficulty

Depending on the student's skill medium to low. Students able to learn WML and fix bugs would increase the difficulty.

Deliverable/expected proof
you should get latest version of wesnoth 1.9 or trunk

- complete a report (wiki page, like GCI/Playtesting/Legend_of_Wesmere/Normal ) of what you've found

- submit all bugs to bugs.wesnoth.org and link to them in your report

- include answers to the following questionnaire for each scenario :

- submit a package with end of scenario savegames

(1) What difficulty levels and what version of Wesnoth have you played the scenario on?

(2) How difficult did you find the scenario? (1-10)

(3) How clear did you find the scenario objectives?

(4) How clear and interesting did you find the dialog and storyline of the scenario?

(5) What were your major challenges in meeting the objectives of the scenario?

(6) How fun do you think the scenario is? (1-10)

(7) What, if any, are changes you would have made to the scenario to make it more fun?

(8) Was there any event that caused you to lose the game and forced you to reload or
restart the scenario?

(9) If you know a bit of the Wesnoth Markup Language - do you think that the WML of this scenario is clear and well commented? If not which part would you like to be documented better?

Here is a short list of the sort of bugs we are interested in

* obvious bugs (crashes, scenario not working etc...)
* bad wordings/spelling mistakes/ typos
* terrain bugs (in particular missing transitions in mainline maps)
* unit animation bugs (animation glitches or wrong animation played. Note that missing animations are not considered bugs)
* inconsistent namings/backstory/ of characters

some usefull wiki links
* [[DebugMode]]
* [[CommandMode]]

GCI/Playtesting

2010-11-24T09:37:02Z

Boucman: /* Wesnoth 1.9.2 Playtesting */

AnimationWML

2010-10-29T15:16:03Z

Boucman: /* Field Description */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''directional_x''': x offset applied to the frame in the direction the unit is facing
** '''directional_y''': y offset applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AnimationWML

2010-10-29T15:14:01Z

Boucman: /* Syntax summary */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''directional_x''': x offset applied to the frame in the direction the unit is facing
** '''directional_y''': y offset applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

GCI

2010-10-24T17:25:08Z

Boucman: Created page with '== Google Code In task list == This page is a list of task ideas for the google code-in (see http://code.google.com/gci) exemple of tasks from previous year http://code.google…'

== Google Code In task list ==

This page is a list of task ideas for the google code-in (see http://code.google.com/gci)

exemple of tasks from previous year
http://code.google.com/p/google-highly-open-participation-gnome/issues/list

=== Task Template ===
One paragraph description of task

requirement (expected technical knowledge)

expected time for completion

difficulty

deliverable/expected proof

AnimationWML

2010-10-02T10:29:01Z

Boucman: /* Syntax summary */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''directional_x''': x offset applied to the frame in the direction the unit is facing
** '''directional_y''': y offset applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AnimationWML

2010-10-02T10:27:59Z

Boucman: /* Field Description */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''directional_x''': x offset applied to the frame in the direction the unit is facing
** '''directional_y''': y offset applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AnimationWML

2010-10-02T10:27:14Z

Boucman: /* Syntax summary */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EffectWML

2010-08-29T19:10:59Z

Boucman: /* the [effect] tag */

{{WML Tags}}
== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit.
Any number of [effect] tags can be used to describe a complete
modification.
Modifications are permanent changes to a unit;
currently there is no way of removing a modification.
Effects can contain a [filter] tag which applies the effect only if it matches.
See [[StandardUnitFilter]] for details.

The following keys are always recognized for [effect]:
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list)
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list)
* '''times''': describes how much time the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML]] for explanations about defense_weight.
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitTypeWML]] for describing a unit type
* '''defense''': Sets unit chance to be hit in specific terrain (100 - defense value)
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[defense]''': a subtag that describes the new defense just like in [[UnitTypeWML]] for describing a unit type
* '''resistance''': Sets percent damage taken from combat
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitTypeWML]] for describing a unit type
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (0=disable, other=enable).
* '''profile''': customize the profile for this unit type
** '''portrait''': new image to display when the unit speaks
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, {{DevFeature1.9}} and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster
* '''image_mod''': modify the image path function([[ImagePathFunctionWML]]) of all the unit's frames
** '''replace''': the image path function to be used, e.g. "RC(magenta>red)"
* '''ellipse''': Change the image used for the unit's ellipse
**'''ellipse''' : the new image to use

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

EffectWML

2010-08-29T16:41:04Z

Boucman: /* See Also */

{{WML Tags}}
== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit.
Any number of [effect] tags can be used to describe a complete
modification.
Modifications are permanent changes to a unit;
currently there is no way of removing a modification.
Effects can contain a [filter] tag which applies the effect only if it matches.
See [[StandardUnitFilter]] for details.

The following keys are always recognized for [effect]:
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list)
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list)
* '''times''': describes how much time the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML]] for explanations about defense_weight.
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitTypeWML]] for describing a unit type
* '''defense''': Sets unit chance to be hit in specific terrain (100 - defense value)
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[defense]''': a subtag that describes the new defense just like in [[UnitTypeWML]] for describing a unit type
* '''resistance''': Sets percent damage taken from combat
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitTypeWML]] for describing a unit type
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (0=disable, other=enable).
* '''profile''': customize the profile for this unit type
** '''portrait''': new image to display when the unit speaks
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit
* '''image_mod''': modify the image path function([[ImagePathFunctionWML]]) of all the unit's frames
** '''replace''': the image path function to be used, e.g. "RC(magenta>red)"
* '''ellipse''': Change the image used for the unit's ellipse
**'''ellipse''' : the new image to use

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

AnimationWML

2010-08-29T12:11:50Z

Boucman: /* Layering */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': {{DevFeature1.9}} : a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EasyCoding

2010-08-27T13:06:44Z

Boucman: /* Support for standalone multiplayer scenarios */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]. Patch submitted: [https://gna.org/patch/index.php?1162] (gabba)

--[[User:Boucman|Boucman]] 08:56, 28 February 2010 (UTC) : this is postponed for 1.8, can be considered reserved

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

--[[User:Boucman|Boucman]] 08:58, 28 February 2010 (UTC) Patch seems abandonned, but can be used for further work feel free to take over the FR

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
--[[User:Endercoaster|endercoaster]] 30, March 2010. I'm gonna give this one a try.

=== Support for standalone multiplayer scenarios ===
There used to be support for standalone scenarios in the userdata tree, in reorganising the trees this feature got lost and an add-on is now required to add a scenario.
Re-add this feature. It is probably a good idea to mirror the mainline multiplayer tree.

=== Support variable recall cost in wml ===
see https://gna.org/bugs/?16538

the syntax needs to be discussed and refined, but the overall idea is good

make sure to update whiteboard to handle this correctly

Ask Boucman

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to AI ==

Fix some todos, add new formula functions, or do minor improvements to the formula language. Make it easier to debug the formula language, add more ai components.

Please discuss these with Crab, Dragonking, Sirp or Boucman

=== AI Batch testing ===

Finish patch #1169 [https://gna.org/patch/?1169]

=== Add more ai actions ===

Add an ai action (and add formula_ai function to do that) to set a goto on a unit

Add an ai action (and add formula_ai function to do that) to send a chat message to a player

Add an ai action to set formula ai variable (convert existing code from formula_ai)

Add an ai action to set formula ai unit variable (convert existing code from formula_ai)

Add an ai action (and add formula_ai function to do that) to fire a WML event

=== write a (fai or c++ or lua) candidate action for leader control ===

=== write a (fai or c++ or lua) candidate action for using leadership/illuminate ===
special handling of units with leadership to have them support units. Only do it if it actually is useful (less hits needed to kill the unit) and ability to help multiple units in a single turn (assuming enough MP)

=== write a (fai or c++ or lua) candidate action for healer control ===
Handle units with healing power, moving them at places where they can provide the most healing

=== berserker improvement ===
The default AI's strategy of attacking as much as possible is very bad with berserker... A simple AI that would prevent the berserker from attacking (and keeping him close to fight without being exposed) and attack when the chance to kill is high enough would be an interesting addition

=== power projection improvement ===
AI sometimes wants to calculate 'how much firepower can enemy bring on location X'. in doing so, it considers enemy possible moves, time of day, attacks, enemy defense, etc.
There is specific problem with 'time_of_day' used in that calculation -sometimes, it's really needed to check 'time of day for NEXT turn', not time of day for THIS turn.(since the time of day might change next turn).

power_projection must be fixed to account for the possibility of time_of_day being different.

Note that some enemies might go after us (so, still on THIS turn), and some - before us (so, their next turn will be on NEXT turn).

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature
=== Story Screen improvements ===
see http://www.wesnoth.org/forum/viewtopic.php?p=439346#p439346 for the suggestion and https://gna.org/patch/?1587 for a patch that already touched that area heavily

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

At the moment there are no easy tasks available.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

Euschn 24/03/2009

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)
=== Option to disable terrain animations globally ===
see https://gna.org/bugs/?15976

please think a little about use cases (editor, game etc...)

ask boucman for details

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

PreprocessorRef

2010-08-20T19:12:29Z

Boucman: /* The WML preprocessor */

{{WML Tags}}
== The WML preprocessor ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''.
However the WML preprocessor allows to include more files.
Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string-expansions known as "macros." A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will
be parsed for macros, and after macro expansion will be parsed for macros
again, and so on. As a result, you should not write a recursive macro,
because it will cause errors
(but, alas, not necessarily error messages).

The following directives are used to create and use ''macros'',
i.e. shortcuts which reduce repetition of information.
See [[UtilWML]], [[UsefulWMLFragments]] for examples and [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the predefined core macros.
* '''#define ''symbol'' [''parameters''] ''newline'' ''substitution'' #enddef''' all subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by ''substitution'' with all occurences of any parameter {''parameter''} within ''substitution'' replaced by the parameter's corresponding value in ''arguments''. For example, the UNIT macro used below would be defined:

#define UNIT TYPE X Y## the ordering is important here;
## since WML does not distinguish
## data into different types, only
## the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE}## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See [[SingleUnitWML]] for information on creating units using WML.)
* '''{''symbol'' [''arguments'']}''' if ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' is defined as, using ''arguments'' as parameters. You can create multiple word arguments by using parentheses to restrain the argument. For example, while '''{UNIT Wolf Rider 18 24}''' will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, the macro '''{UNIT (Wolf Rider) 18 24}''' will create a "Wolf Rider" at (18,24) as it should. ('''UNIT''' is defined above). See the ''#define'' preprocessor instruction above for information on defining symbols, including symbols with arguments. Several symbols are defined in the normal game code; for reference they are listed in [[UtilWML]].

Note: Using the name-string of an existing macro as the name-string of a macro argument will always overwrite the original definition of the macro, e.g.:
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

Unlike the other preprocessor directives, #ifdef and #ifndef are not
mere conveniences.
They are necessary to distinguish between different modes of play.
* '''#ifdef ''symbol'' ''substitution-if-stored'' [#else ''substitution-if-not-stored''] #endif''' If ''symbol'' has been stored, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available. ''symbol'' can take the following values:
** a campaign difficulty level. Usually '''EASY''', '''NORMAL''', or '''HARD''', it is decided by the key ''difficulties'' (see [[CampaignWML]]).
** a campaign ID. Each campaign stores a preprocessor ID. See ''define'', [[CampaignWML]].
** '''MULTIPLAYER''' is stored when the player is playing or setting up a multiplayer game (i.e. a game with '''scenario_type=multiplayer''').
** '''DEBUG_MODE''' is stored when the player has launched wesnoth in debug mode (i.e. with '''-d''')
** '''TUTORIAL''' is stored when the player is playing the tutorial.
** '''APPLE''' is stored if the computer Wesnoth is being run on is an Apple. (this one is only available to the configuration of the game)
** '''LOW_MEM''' {{DevFeature1.9}} The binary was compiled with the LOW_MEM option
** '''TINY''' The binary was compiled with the TINY_GUI option
* '''#ifndef''' behaves exactly like '''#ifdef''', except that it inverts the test sense; guarded text is included only if ''symbol'' has not been stored.
''#undef'' can be useful too if ''#ifdef'' is not enough.
* '''#undef ''symbol'' ''' erases ''symbol''
* '''#ifhave''' {{DevFeature1.9}} checks for the existence of a file.
* '''#ifnhave''' {{DevFeature1.9}} is the inverted version of '''#ifhave'''.

These directives expand a file by including other files, ''filename'' may not contain '..' or the directive will be skipped:
* '''{''filename''}''' if ''filename'' isn't a predefined symbol (see above), Wesnoth will assume it's a path to a file in the main '''data/''' subdirectory of Wesnoth and include the file it points to here "as is". Forward slashes('''/''') should be used to separate directories from their elements, even if your platform uses a different symbol such as colon (''':''') or backslash ('''\''').
* '''{~''filename''}''' similar to above, but the preprocessor assumes that the filename is relative to '''data/''' subdirectory of the user data directory. The ''user data directory'' varies depending on platform. See [[EditingWesnoth#Where_is_my_user_data_directory.3F|Where_is_my_user_data_directory?]]

* '''{./''filename''}''' is similar to the '''{''filename''}''' directive, but is assumed to be relative to the directory which contains the file in which this appears. For example, if used in game.cfg, it is equivalent to '''{''filename''}'''.
* If ''filename'' points to a directory, the preprocessor will include all files in the directory ''filename'', non-recursively and in alphabetical order. Starting in 1.3.3, some files in such directories are handled specially.

If there is a file named ''dir/_main.cfg'' in a directory referenced as '''{''dir''}''', only that ''_main.cfg'' file is processed; it may include other files in itself, of course . This feature is useful for creating WML directories that are self-contained WML packages with their own initializations (like campaigns). This can replace the older convention of having a ''dir.cfg'' at the same level as ''dir'' which does '''{''dir''}''' somewhere in itself.

If there are files named ''dir/*/_main.cfg'' in a directory referenced as '''{''dir''}''', where * is any subdirectories ''dir'', then they all are processed (except if there is also a file named ''dir/_main.cfg''). This means that if you have a layout like this:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Then '''{dir}''' will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.

If there is a file named ''dir/_final.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_final.cfg'' is guaranteed to be processed ''after'' all other files in the directory.

If there is a file named ''dir/_initial.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_initial.cfg'' is guaranteed to be processed ''before'' all other files in the directory.

Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.

{{DevFeature1.9}} Including non-existent file is now a fatal error and halts the preprocessing. Use #ifhave to test for the existence of files that aren't a part of your own add-on.

== The preprocessor command line ==
{{DevFeature1.9}}

As of wesnoth 1.9, there are some new command line arguments available for the wesnoth executable:
--preprocess
--preprocess-input-macros
--preprocess-output-macros

Commands details:

===--preprocess===

--preprocess[=define1,define2,...] <file/folder> <target directory>
or the short form:
-p[=define1,define2,...] <file/folder> <target directory>

The define1,define2,... is a list of defines, to be added ''before'' anything is preprocessed.

The preprocess command will '''preprocess first''' the common config files in ''data/core'', and afterwards, the specified ones. You can specifiy a single file to be preprocesses (if you want to preprocess multiple separate files, you have to invoke the command separately), or an entire folder (this will be preprocessed on the known preprocessor rules).

The resulted preprocessed files will be written in the target directory. There will be 2 types of files: the .cfg files and .plain files (this contain the line symbols and textdomain changes)

If <file/folder> and <target directory> are not in ''absolute path'' form, they will be treated like relative to the wesnoth's executable path.

Some examples:
-p ~/wesnoth/data/campaigns/tutorial ~/result
will preprocess entire tutorial folder, and write the resulted files in the ~/result folder
-p=MULTIPLAYER data/campaigns/my_campaign/some_scenario.cfg data/result
will add the ''MULTIPLAYER'' define in defines list and then preprocess the scenario config file
-p=SINGLEPLAYER,HARD ~/wesnoth/data/campaigns/my_campaign ~/result
will add the ''SINGLEPLAYER'' and ''HARD'' defines before preprocessing the files.

Note! As you saw in the examples, the '=' character is mandatory if you want to specify any auxiliar defines

===--preprocess-input-macros===
--preprocess-input-macros <file>
This command will take the specified file, parse the defines in it, and will use them when preprocessing the resource with --preprocess. The file must contain only [preproc_define]s. This is different than adding defines to --preprocess, as it contains the macro information.

===--preprocess-output-macro===
--preprocess-output-macro [<file>]
Outputs the defines_map resulted from preprocessing. This is will include (if any) --preprocess-input-macro file's content.

If you want a more detailed log, you can simply add the command: "--log-debug=all" or "--log-info=all" before the preprocessing command, so you will see how things are parsed,etc.

== See Also ==
* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

PreprocessorRef

2010-08-20T18:30:38Z

Boucman: /* The WML preprocessor */

{{WML Tags}}
== The WML preprocessor ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''.
However the WML preprocessor allows to include more files.
Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string-expansions known as "macros." A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will
be parsed for macros, and after macro expansion will be parsed for macros
again, and so on. As a result, you should not write a recursive macro,
because it will cause errors
(but, alas, not necessarily error messages).

The following directives are used to create and use ''macros'',
i.e. shortcuts which reduce repetition of information.
See [[UtilWML]], [[UsefulWMLFragments]] for examples and [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the predefined core macros.
* '''#define ''symbol'' [''parameters''] ''newline'' ''substitution'' #enddef''' all subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by ''substitution'' with all occurences of any parameter {''parameter''} within ''substitution'' replaced by the parameter's corresponding value in ''arguments''. For example, the UNIT macro used below would be defined:

#define UNIT TYPE X Y## the ordering is important here;
## since WML does not distinguish
## data into different types, only
## the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE}## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See [[SingleUnitWML]] for information on creating units using WML.)
* '''{''symbol'' [''arguments'']}''' if ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' is defined as, using ''arguments'' as parameters. You can create multiple word arguments by using parentheses to restrain the argument. For example, while '''{UNIT Wolf Rider 18 24}''' will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, the macro '''{UNIT (Wolf Rider) 18 24}''' will create a "Wolf Rider" at (18,24) as it should. ('''UNIT''' is defined above). See the ''#define'' preprocessor instruction above for information on defining symbols, including symbols with arguments. Several symbols are defined in the normal game code; for reference they are listed in [[UtilWML]].

Note: Using the name-string of an existing macro as the name-string of a macro argument will always overwrite the original definition of the macro, e.g.:
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

Unlike the other preprocessor directives, #ifdef and #ifndef are not
mere conveniences.
They are necessary to distinguish between different modes of play.
* '''#ifdef ''symbol'' ''substitution-if-stored'' [#else ''substitution-if-not-stored''] #endif''' If ''symbol'' has been stored, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available. ''symbol'' can take the following values:
** a campaign difficulty level. Usually '''EASY''', '''NORMAL''', or '''HARD''', it is decided by the key ''difficulties'' (see [[CampaignWML]]).
** a campaign ID. Each campaign stores a preprocessor ID. See ''define'', [[CampaignWML]].
** '''MULTIPLAYER''' is stored when the player is playing or setting up a multiplayer game (i.e. a game with '''scenario_type=multiplayer''').
** '''DEBUG_MODE''' is stored when the player has launched wesnoth in debug mode (i.e. with '''-d''')
** '''TUTORIAL''' is stored when the player is playing the tutorial.
** '''APPLE''' is stored if the computer Wesnoth is being run on is an Apple. (this one is only available to the configuration of the game)
** '''LOW_MEM''' {{DevFeature1.9}} The binary was compiled with the LOW_MEM option
** '''USE_TINY_GUI''' {{DevFeature1.9}} The binary was compiled with the TINY_GUI option
* '''#ifndef''' behaves exactly like '''#ifdef''', except that it inverts the test sense; guarded text is included only if ''symbol'' has not been stored.
''#undef'' can be useful too if ''#ifdef'' is not enough.
* '''#undef ''symbol'' ''' erases ''symbol''
* '''#ifhave''' {{DevFeature1.9}} checks for the existence of a file.
* '''#ifnhave''' {{DevFeature1.9}} is the inverted version of '''#ifhave'''.

These directives expand a file by including other files, ''filename'' may not contain '..' or the directive will be skipped:
* '''{''filename''}''' if ''filename'' isn't a predefined symbol (see above), Wesnoth will assume it's a path to a file in the main '''data/''' subdirectory of Wesnoth and include the file it points to here "as is". Forward slashes('''/''') should be used to separate directories from their elements, even if your platform uses a different symbol such as colon (''':''') or backslash ('''\''').
* '''{~''filename''}''' similar to above, but the preprocessor assumes that the filename is relative to '''data/''' subdirectory of the user data directory. The ''user data directory'' varies depending on platform. See [[EditingWesnoth#Where_is_my_user_data_directory.3F|Where_is_my_user_data_directory?]]

* '''{./''filename''}''' is similar to the '''{''filename''}''' directive, but is assumed to be relative to the directory which contains the file in which this appears. For example, if used in game.cfg, it is equivalent to '''{''filename''}'''.
* If ''filename'' points to a directory, the preprocessor will include all files in the directory ''filename'', non-recursively and in alphabetical order. Starting in 1.3.3, some files in such directories are handled specially.

If there is a file named ''dir/_main.cfg'' in a directory referenced as '''{''dir''}''', only that ''_main.cfg'' file is processed; it may include other files in itself, of course . This feature is useful for creating WML directories that are self-contained WML packages with their own initializations (like campaigns). This can replace the older convention of having a ''dir.cfg'' at the same level as ''dir'' which does '''{''dir''}''' somewhere in itself.

If there are files named ''dir/*/_main.cfg'' in a directory referenced as '''{''dir''}''', where * is any subdirectories ''dir'', then they all are processed (except if there is also a file named ''dir/_main.cfg''). This means that if you have a layout like this:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Then '''{dir}''' will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.

If there is a file named ''dir/_final.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_final.cfg'' is guaranteed to be processed ''after'' all other files in the directory.

If there is a file named ''dir/_initial.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_initial.cfg'' is guaranteed to be processed ''before'' all other files in the directory.

Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.

{{DevFeature1.9}} Including non-existent file is now a fatal error and halts the preprocessing. Use #ifhave to test for the existence of files that aren't a part of your own add-on.

== The preprocessor command line ==
{{DevFeature1.9}}

As of wesnoth 1.9, there are some new command line arguments available for the wesnoth executable:
--preprocess
--preprocess-input-macros
--preprocess-output-macros

Commands details:

===--preprocess===

--preprocess[=define1,define2,...] <file/folder> <target directory>
or the short form:
-p[=define1,define2,...] <file/folder> <target directory>

The define1,define2,... is a list of defines, to be added ''before'' anything is preprocessed.

The preprocess command will '''preprocess first''' the common config files in ''data/core'', and afterwards, the specified ones. You can specifiy a single file to be preprocesses (if you want to preprocess multiple separate files, you have to invoke the command separately), or an entire folder (this will be preprocessed on the known preprocessor rules).

The resulted preprocessed files will be written in the target directory. There will be 2 types of files: the .cfg files and .plain files (this contain the line symbols and textdomain changes)

If <file/folder> and <target directory> are not in ''absolute path'' form, they will be treated like relative to the wesnoth's executable path.

Some examples:
-p ~/wesnoth/data/campaigns/tutorial ~/result
will preprocess entire tutorial folder, and write the resulted files in the ~/result folder
-p=MULTIPLAYER data/campaigns/my_campaign/some_scenario.cfg data/result
will add the ''MULTIPLAYER'' define in defines list and then preprocess the scenario config file
-p=SINGLEPLAYER,HARD ~/wesnoth/data/campaigns/my_campaign ~/result
will add the ''SINGLEPLAYER'' and ''HARD'' defines before preprocessing the files.

Note! As you saw in the examples, the '=' character is mandatory if you want to specify any auxiliar defines

===--preprocess-input-macros===
--preprocess-input-macros <file>
This command will take the specified file, parse the defines in it, and will use them when preprocessing the resource with --preprocess. The file must contain only [preproc_define]s. This is different than adding defines to --preprocess, as it contains the macro information.

===--preprocess-output-macro===
--preprocess-output-macro [<file>]
Outputs the defines_map resulted from preprocessing. This is will include (if any) --preprocess-input-macro file's content.

If you want a more detailed log, you can simply add the command: "--log-debug=all" or "--log-info=all" before the preprocessing command, so you will see how things are parsed,etc.

== See Also ==
* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

PreprocessorRef

2010-08-20T18:27:42Z

Boucman: /* The WML preprocessor */

{{WML Tags}}
== The WML preprocessor ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''.
However the WML preprocessor allows to include more files.
Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string-expansions known as "macros." A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will
be parsed for macros, and after macro expansion will be parsed for macros
again, and so on. As a result, you should not write a recursive macro,
because it will cause errors
(but, alas, not necessarily error messages).

The following directives are used to create and use ''macros'',
i.e. shortcuts which reduce repetition of information.
See [[UtilWML]], [[UsefulWMLFragments]] for examples and [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the predefined core macros.
* '''#define ''symbol'' [''parameters''] ''newline'' ''substitution'' #enddef''' all subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by ''substitution'' with all occurences of any parameter {''parameter''} within ''substitution'' replaced by the parameter's corresponding value in ''arguments''. For example, the UNIT macro used below would be defined:

#define UNIT TYPE X Y## the ordering is important here;
## since WML does not distinguish
## data into different types, only
## the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE}## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See [[SingleUnitWML]] for information on creating units using WML.)
* '''{''symbol'' [''arguments'']}''' if ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' is defined as, using ''arguments'' as parameters. You can create multiple word arguments by using parentheses to restrain the argument. For example, while '''{UNIT Wolf Rider 18 24}''' will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, the macro '''{UNIT (Wolf Rider) 18 24}''' will create a "Wolf Rider" at (18,24) as it should. ('''UNIT''' is defined above). See the ''#define'' preprocessor instruction above for information on defining symbols, including symbols with arguments. Several symbols are defined in the normal game code; for reference they are listed in [[UtilWML]].

Note: Using the name-string of an existing macro as the name-string of a macro argument will always overwrite the original definition of the macro, e.g.:
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

Unlike the other preprocessor directives, #ifdef and #ifndef are not
mere conveniences.
They are necessary to distinguish between different modes of play.
* '''#ifdef ''symbol'' ''substitution-if-stored'' [#else ''substitution-if-not-stored''] #endif''' If ''symbol'' has been stored, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available. ''symbol'' can take the following values:
** a campaign difficulty level. Usually '''EASY''', '''NORMAL''', or '''HARD''', it is decided by the key ''difficulties'' (see [[CampaignWML]]).
** a campaign ID. Each campaign stores a preprocessor ID. See ''define'', [[CampaignWML]].
** '''MULTIPLAYER''' is stored when the player is playing or setting up a multiplayer game (i.e. a game with '''scenario_type=multiplayer''').
** '''DEBUG_MODE''' is stored when the player has launched wesnoth in debug mode (i.e. with '''-d''')
** '''TUTORIAL''' is stored when the player is playing the tutorial.
** '''APPLE''' is stored if the computer Wesnoth is being run on is an Apple. (this one is only available to the configuration of the game)
** '''LOW_MEM''' {{DevFeature1.9}} The binary was compiled with the LOW_MEM option
* '''#ifndef''' behaves exactly like '''#ifdef''', except that it inverts the test sense; guarded text is included only if ''symbol'' has not been stored.
''#undef'' can be useful too if ''#ifdef'' is not enough.
* '''#undef ''symbol'' ''' erases ''symbol''
* '''#ifhave''' {{DevFeature1.9}} checks for the existence of a file.
* '''#ifnhave''' {{DevFeature1.9}} is the inverted version of '''#ifhave'''.

These directives expand a file by including other files, ''filename'' may not contain '..' or the directive will be skipped:
* '''{''filename''}''' if ''filename'' isn't a predefined symbol (see above), Wesnoth will assume it's a path to a file in the main '''data/''' subdirectory of Wesnoth and include the file it points to here "as is". Forward slashes('''/''') should be used to separate directories from their elements, even if your platform uses a different symbol such as colon (''':''') or backslash ('''\''').
* '''{~''filename''}''' similar to above, but the preprocessor assumes that the filename is relative to '''data/''' subdirectory of the user data directory. The ''user data directory'' varies depending on platform. See [[EditingWesnoth#Where_is_my_user_data_directory.3F|Where_is_my_user_data_directory?]]

* '''{./''filename''}''' is similar to the '''{''filename''}''' directive, but is assumed to be relative to the directory which contains the file in which this appears. For example, if used in game.cfg, it is equivalent to '''{''filename''}'''.
* If ''filename'' points to a directory, the preprocessor will include all files in the directory ''filename'', non-recursively and in alphabetical order. Starting in 1.3.3, some files in such directories are handled specially.

If there is a file named ''dir/_main.cfg'' in a directory referenced as '''{''dir''}''', only that ''_main.cfg'' file is processed; it may include other files in itself, of course . This feature is useful for creating WML directories that are self-contained WML packages with their own initializations (like campaigns). This can replace the older convention of having a ''dir.cfg'' at the same level as ''dir'' which does '''{''dir''}''' somewhere in itself.

If there are files named ''dir/*/_main.cfg'' in a directory referenced as '''{''dir''}''', where * is any subdirectories ''dir'', then they all are processed (except if there is also a file named ''dir/_main.cfg''). This means that if you have a layout like this:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Then '''{dir}''' will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.

If there is a file named ''dir/_final.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_final.cfg'' is guaranteed to be processed ''after'' all other files in the directory.

If there is a file named ''dir/_initial.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_initial.cfg'' is guaranteed to be processed ''before'' all other files in the directory.

Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.

{{DevFeature1.9}} Including non-existent file is now a fatal error and halts the preprocessing. Use #ifhave to test for the existence of files that aren't a part of your own add-on.

== The preprocessor command line ==
{{DevFeature1.9}}

As of wesnoth 1.9, there are some new command line arguments available for the wesnoth executable:
--preprocess
--preprocess-input-macros
--preprocess-output-macros

Commands details:

===--preprocess===

--preprocess[=define1,define2,...] <file/folder> <target directory>
or the short form:
-p[=define1,define2,...] <file/folder> <target directory>

The define1,define2,... is a list of defines, to be added ''before'' anything is preprocessed.

The preprocess command will '''preprocess first''' the common config files in ''data/core'', and afterwards, the specified ones. You can specifiy a single file to be preprocesses (if you want to preprocess multiple separate files, you have to invoke the command separately), or an entire folder (this will be preprocessed on the known preprocessor rules).

The resulted preprocessed files will be written in the target directory. There will be 2 types of files: the .cfg files and .plain files (this contain the line symbols and textdomain changes)

If <file/folder> and <target directory> are not in ''absolute path'' form, they will be treated like relative to the wesnoth's executable path.

Some examples:
-p ~/wesnoth/data/campaigns/tutorial ~/result
will preprocess entire tutorial folder, and write the resulted files in the ~/result folder
-p=MULTIPLAYER data/campaigns/my_campaign/some_scenario.cfg data/result
will add the ''MULTIPLAYER'' define in defines list and then preprocess the scenario config file
-p=SINGLEPLAYER,HARD ~/wesnoth/data/campaigns/my_campaign ~/result
will add the ''SINGLEPLAYER'' and ''HARD'' defines before preprocessing the files.

Note! As you saw in the examples, the '=' character is mandatory if you want to specify any auxiliar defines

===--preprocess-input-macros===
--preprocess-input-macros <file>
This command will take the specified file, parse the defines in it, and will use them when preprocessing the resource with --preprocess. The file must contain only [preproc_define]s. This is different than adding defines to --preprocess, as it contains the macro information.

===--preprocess-output-macro===
--preprocess-output-macro [<file>]
Outputs the defines_map resulted from preprocessing. This is will include (if any) --preprocess-input-macro file's content.

If you want a more detailed log, you can simply add the command: "--log-debug=all" or "--log-info=all" before the preprocessing command, so you will see how things are parsed,etc.

== See Also ==
* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

TerrainMacrosWML

2010-07-10T17:28:21Z

Boucman: /* DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''overlay-connect-@R*''' : used for bridges, the bridge on this tile. The bridge "actually has" an "exit direction" in the @R direction indicated.
* '''overlay-away-@R*''' : used for bridges, the bridge does NOT have an exit on the given direction, but would be expected to...

'''A note about ''overlay-@R'' and ''overlay-away-@R'' flags '''

Suppose we have a ''n->s'' bridge hex who's ''ne'' neighbour is a ''ne->sw'' bridge. This mean that the ''n->s'' is actually a turn in the bridge that should use a graphic depicting a ''s->ne'' corner.

In that case the tile will have ''overlay-s'' and ''overlay-ne'' set (the directions where the bridge actually exits) and ''overlay-away-n'' (the direction where the bridge would exit according to terrain codes, but doesnt because of overall layout)

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''

== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related.
* All images are named as if they were ROTATION macros since they are all side related
* There is no SINGLE variation since it doesn't make sense to have it (a side is always relative to two hex)
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Track Type macros ==

These macros handle anything that is layed in a connected way over multiple tiles (typically bridges and tiles)

=== the TRACK macro ===

'''TRACK_''LF'' <NWSEterrain> <NSterrain> <NESWterrain> <basename'''

This macro will add the base terrain on the three terrains corresponding to the three directions.This macro will awlays take random variations, and defaults to layer -80 with flag=overlay

The images used are named
* base#-ns.png : non-connected on a north-south orientation,
* base#-nesw.png : non connected on a north-east south-west orientation
* base#-senw.png : non connected on a south-east north-west orientation
* base#-<connections> : tile used when the bridge is connected on the corresponding sides (separated by '-', ordered clockwise starting with north)

'''NOTE:''' the engine will use the straight tile when it doesn't find any fitting tile

'''NOTE:''' if some connection tiles don't seem to be used properly, please post a screenshot from the editor with terrain names enabled and contact boucman

'''NOTE''' you will notice that there is no builder. Builders are incompatible with bridges (in other word,the IMAGE_SINGLE builder is hardwired)

=== Transition related macros ===
Bridges are tricky because you usually don't want the same transitions depending if the bridge ends on a given edge or not.

The following macros help

'''TRACK_BORDER_RESTRICTED_''PLF'' <terrain> <adjacent> <IMAGE>'''

Will match only if terrain is a bridge, on the side matching adjacent, and if the bridge does have a connection or ending on the given side.

Note that adjacent can be a bridge too, but this macro won't check that adjacent exits on the corresponding side

the image will be drawn on the <terrain> hex with the orientation appended to it

'''TRACK_BORDER_RESTRICTED_RANDOM_''LF''''' similar, with random variations

TerrainMacrosWML

2010-07-10T17:05:02Z

Boucman: /* Terrain Specific */

TerrainMacrosWML

2010-07-10T17:04:44Z

Boucman: /* Terrain Specific */

EasyCoding

2010-07-01T21:36:15Z

Boucman: /* GUI related features */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]. Patch submitted: [https://gna.org/patch/index.php?1162] (gabba)

--[[User:Boucman|Boucman]] 08:56, 28 February 2010 (UTC) : this is postponed for 1.8, can be considered reserved

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

--[[User:Boucman|Boucman]] 08:58, 28 February 2010 (UTC) Patch seems abandonned, but can be used for further work feel free to take over the FR

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
--[[User:Endercoaster|endercoaster]] 30, March 2010. I'm gonna give this one a try.

=== Support for standalone multiplayer scenarios ===
There used to be support for standalone scenarios in the userdata tree, in reorganising the trees this feature got lost and an add-on is now required to add a scenario.
Re-add this feature. It is probably a good idea to mirror the mainline multiplayer tree.

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to AI ==

Fix some todos, add new formula functions, or do minor improvements to the formula language. Make it easier to debug the formula language, add more ai components.

Please discuss these with Crab, Dragonking, Sirp or Boucman

=== AI Batch testing ===

Finish patch #1169 [https://gna.org/patch/?1169]

=== Add more ai actions ===

Add an ai action (and add formula_ai function to do that) to set a goto on a unit

Add an ai action (and add formula_ai function to do that) to send a chat message to a player

Add an ai action to set formula ai variable (convert existing code from formula_ai)

Add an ai action to set formula ai unit variable (convert existing code from formula_ai)

Add an ai action (and add formula_ai function to do that) to fire a WML event

=== write a (fai or c++ or lua) candidate action for leader control ===

=== write a (fai or c++ or lua) candidate action for using leadership/illuminate ===
special handling of units with leadership to have them support units. Only do it if it actually is useful (less hits needed to kill the unit) and ability to help multiple units in a single turn (assuming enough MP)

=== write a (fai or c++ or lua) candidate action for healer control ===
Handle units with healing power, moving them at places where they can provide the most healing

=== berserker improvement ===
The default AI's strategy of attacking as much as possible is very bad with berserker... A simple AI that would prevent the berserker from attacking (and keeping him close to fight without being exposed) and attack when the chance to kill is high enough would be an interesting addition

=== power projection improvement ===
AI sometimes wants to calculate 'how much firepower can enemy bring on location X'. in doing so, it considers enemy possible moves, time of day, attacks, enemy defense, etc.
There is specific problem with 'time_of_day' used in that calculation -sometimes, it's really needed to check 'time of day for NEXT turn', not time of day for THIS turn.(since the time of day might change next turn).

power_projection must be fixed to account for the possibility of time_of_day being different.

Note that some enemies might go after us (so, still on THIS turn), and some - before us (so, their next turn will be on NEXT turn).

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature
=== Story Screen improvements ===
see http://www.wesnoth.org/forum/viewtopic.php?p=439346#p439346 for the suggestion and https://gna.org/patch/?1587 for a patch that already touched that area heavily

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

At the moment there are no easy tasks available.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

Euschn 24/03/2009

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)
=== Option to disable terrain animations globally ===
see https://gna.org/bugs/?15976

please think a little about use cases (editor, game etc...)

ask boucman for details

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

TerrainMacrosWML

2010-06-24T14:24:30Z

Boucman: /* Flag Management */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''overlay-connect-@R*''' : used for bridges, the bridge on this tile. The bridge "actually has" an "exit direction" in the @R direction indicated.
* '''overlay-away-@R*''' : used for bridges, the bridge does NOT have an exit on the given direction, but would be expected to...

'''A note about ''overlay-@R'' and ''overlay-away-@R'' flags '''

Suppose we have a ''n->s'' bridge hex who's ''ne'' neighbour is a ''ne->sw'' bridge. This mean that the ''n->s'' is actually a turn in the bridge that should use a graphic depicting a ''s->ne'' corner.

In that case the tile will have ''overlay-s'' and ''overlay-ne'' set (the directions where the bridge actually exits) and ''overlay-away-n'' (the direction where the bridge would exit according to terrain codes, but doesnt because of overall layout)

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''

== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related.
* All images are named as if they were ROTATION macros since they are all side related
* There is no SINGLE variation since it doesn't make sense to have it (a side is always relative to two hex)
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-18T17:50:01Z

Boucman: /* Flag Management */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''overlay-@R*''' : used for bridges, the bridge on this tile. The bridge "actually has" an "exit direction" in the @R direction indicated.
* '''overlay-away-@R*''' : used for bridges, the bridge does NOT have an exit on the given direction, but would be expected to...

'''A note about ''overlay-@R'' and ''overlay-away-@R'' flags '''

Suppose we have a ''n->s'' bridge hex who's ''ne'' neighbour is a ''ne->sw'' bridge. This mean that the ''n->s'' is actually a turn in the bridge that should use a graphic depicting a ''s->ne'' corner.

In that case the tile will have ''overlay-s'' and ''overlay-ne'' set (the directions where the bridge actually exits) and ''overlay-away-n'' (the direction where the bridge would exit according to terrain codes, but doesnt because of overall layout)

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''

== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related.
* All images are named as if they were ROTATION macros since they are all side related
* There is no SINGLE variation since it doesn't make sense to have it (a side is always relative to two hex)
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-18T15:22:45Z

Boucman: /* Image Names */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge "actually has" an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction, but would be expected to...

'''A note about ''angle_'' and ''angleaway_'' flags '''

Suppose we have a ''n->s'' bridge hex who's ''ne'' neighbour is a ''ne->sw'' bridge. This mean that the ''n->s'' is actually a turn in the bridge that should use a graphic depicting a ''s->ne'' corner.

In that case the tile will have ''angle_s'' and ''angle_ne'' set (the directions where the bridge actually exits) and ''angleaway_n'' (the direction where the bridge would exit according to terrain codes, but doesnt because of overall layout)

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''

== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related.
* All images are named as if they were ROTATION macros since they are all side related
* There is no SINGLE variation since it doesn't make sense to have it (a side is always relative to two hex)
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-18T14:15:31Z

Boucman: /* Flag Management */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge "actually has" an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction, but would be expected to...

'''A note about ''angle_'' and ''angleaway_'' flags '''

Suppose we have a ''n->s'' bridge hex who's ''ne'' neighbour is a ''ne->sw'' bridge. This mean that the ''n->s'' is actually a turn in the bridge that should use a graphic depicting a ''s->ne'' corner.

In that case the tile will have ''angle_s'' and ''angle_ne'' set (the directions where the bridge actually exits) and ''angleaway_n'' (the direction where the bridge would exit according to terrain codes, but doesnt because of overall layout)

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''

== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related, they are always transition like
* All images are named as if they were ROTATION macros (since they are painting on a side
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* the non-RESTRICTED variations don't exist, they don't really make sense
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-13T17:12:08Z

Boucman: /* Image Names */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''

== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related, they are always transition like
* All images are named as if they were ROTATION macros (since they are painting on a side
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* the non-RESTRICTED variations don't exist, they don't really make sense
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-13T17:11:51Z

Boucman:

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''
== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related, they are always transition like
* All images are named as if they were ROTATION macros (since they are painting on a side
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* the non-RESTRICTED variations don't exist, they don't really make sense
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-13T16:37:51Z

Boucman: /* Generic Functions */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''
== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related, they are always transition like
* All images are named as if they were ROTATION macros (since they are painting on a side
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* the non-RESTRICTED variations exist, they will apply unconditionnaly, whatever the neighbour is... This is usually not what you want
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
* the COMPLETE variant looks as follows

#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{BORDER_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
{BORDER_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

TerrainMacrosWML

2010-06-13T16:36:56Z

Boucman: /* TO BE DOCUMENTED */

TerrainMacrosWML

2010-06-13T09:58:50Z

Boucman: /* Generic Functions */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''
== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related, they are always transition like
* All images are named as if they were ROTATION macros (since they are painting on a side
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
* the non-RESTRICTED variations exist, they will apply unconditionnaly, whatever the neighbour is... This is usually not what you want
* for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

== TO BE DOCUMENTED ==
=== misc.cfg ===
#meta-macro WALL_TRANSITION TERRAIN ADJACENT P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM
#meta-macro WALL_TRANSITION2 TERRAIN1 TERRAIN2 ADJACENT P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM
#meta-macro WALL_TRANSITION3 TERRAIN1 TERRAIN2 TERRAIN3 P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM

#define SIMPLE_OVERLAY_TERRAIN TERRAINLIST RESTRICTING IMAGESTEM

=== bridges.cfg ===
#define IMAGE_L_N LAYER NAME
#define DOCK_END IMAGESTEM WATER_TERRAIN_NAME BRIDGETYPE_NAME BEACHSIDE_AFFIX X Y
#define RAMP_BRIDGE IMAGESTEM BRIDGETYPE_NAME BRIDGES_VALUE R0 R1 R2 R3 R4 R5 S0 S1 S2 S3 S4 S5
#define RAMP_END IMAGESTEM WATER_TERRAIN_NAME NOTERM_AFFIX BRIDGETYPE_NAME R0 R1 R2 R3 R4 R5 X Y
#define BRIDGE_Y BRIDGETYPE1_NAME BRIDGETYPE2_NAME BRIDGETYPE3_NAME Y_IMAGE R0 R1 R2 R3 R4 R5 S0 S1 S2 S3 S4 S5
#define BRIDGECONNECT BRIDGETYPE_NAME R0 R1 R2 R3 R4 R5 X Y
#define CORNER ANGLE_IMAGE BRIDGETYPE1_NAME BRIDGETYPE2_NAME A1 A2 A3 A4 A5 A6 S0 S1 S2 S3 S4 S5
#define BRIDGE SE_NW_VALUE N_S_VALUE NE_SW_VALUE WATER_TERRAIN_NAME NOTERM_AFFIX IMAGESTEM

=== canyon.cfg ===
#define TRANS_0 TERRAIN
#define TRANS_1 TERRAIN
#define TRANS_2 TERRAIN
#define TRANS_3 TERRAIN
#define TRANS_4 TERRAIN
#define TRANS_5 TERRAIN
#define CANYON TERRAIN IMAGESTEM
=== castles.cfg ===
#define TERRAIN_ADJACENT_CORNER_LAYER TERRAIN1 TERRAIN2 TERRAIN3 LAYER BASE_POSITION IMAGESTEM
#define TERRAIN_ADJACENT_CORNER TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION IMAGESTEM
#define TERRAIN_ADJACENT_CORNER_FLAG1 TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION FLAG IMAGESTEM
#define TERRAIN_ADJACENT_CORNER_PROB TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION IMAGESTEM PROB
=== foresetcastle.cfg ===
#define FORESTADJCASTLEA FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLES FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLEO FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLE FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJ FOREST_ID ID PROB TILE_IMAGE
#define MOUNTAINADJCASTLEA FOREST_ID ID PROB TILE_IMAGE
=== mountains.cfg ===
#define MOUNTAINS_2x2 TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_2x4_NW_SE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_2x4_SW_NE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_1x3_NW_SE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_1x3_SW_NE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAIN_SINGLE TERRAIN PROB FLAG IMAGESTEM
#define PEAKS_LARGE TERRAIN PROB FLAG IMAGESTEM
#define PEAKS_1x2_SW_NE TERRAIN PROB FLAG IMAGESTEM
=== rails.cfg ===
#define RAIL_SWITCH IMAGESTEM BRIDGETYPE_NAME BRIDGETYPE_JOIN_NAME SWITCHSIDE_AFFIX MAINRAIL_AFFIX SWITCH_REVERSE_AFFIX X Y
#define RAIL_END IMAGESTEM BRIDGETYPE_NAME TRACKSIDE_AFFIX X Y
#define RAILWAY SE_NW_VALUE N_S_VALUE NE_SW_VALUE IMAGESTEM

=== walls.cfg ===
#define IMAGE_NW BUILDER IMAGESTEM
#define IMAGE_N BUILDER IMAGESTEM
#define IMAGE_NE BUILDER IMAGESTEM
#define IMAGE_SE BUILDER IMAGESTEM
#define IMAGE_S BUILDER IMAGESTEM
#define IMAGE_SW BUILDER IMAGESTEM
#define IMAGE_NW_N BUILDER IMAGESTEM
#define IMAGE_N_NE BUILDER IMAGESTEM
#define IMAGE_NE_SE BUILDER IMAGESTEM
#define IMAGE_SE_S BUILDER IMAGESTEM
#define IMAGE_S_SW BUILDER IMAGESTEM
#define IMAGE_SW_NW BUILDER IMAGESTEM
#define IMAGE_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_S_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_NW_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_SW_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_NE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_SE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_NW_N_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_NE_SE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_SE_S_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_S_SW_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_SW_NW_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S_SW_NW BUILDER IMAGESTEM
#define WALL_1_VARIATION PROB TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_1 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_2_VARIATION PROB TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_2 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_3 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_4 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_5 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_6 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define DISABLE_WALLS TERRAIN1 TERRAIN2 TERRAIN3
#define WALL_ADJACENT TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM BASE_NAME

TerrainMacrosWML

2010-06-13T09:56:39Z

Boucman: /* Transition related macros */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''
== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==

=== Generic Functions ===
transitions have most of the macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TRANSITION'''
* '''PROB''' : 100
* '''LAYER''': -500
* '''FLAG''': ''transition-@<side>''
* '''BUILDER''': IMAGE_SINGLE

However, unlike all previous type of macros, they are related to a ''side'' instead of the whole hex. Thus the following rules

* There are no ROTATION macros. Since they are always side related, they are always transition like
* All images are named as if they were ROTATION macros (since they are painting on a side
* The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles
=== DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG ===
This macro will set all <FLAG>-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all <FLAG>-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

== TO BE DOCUMENTED ==
=== misc.cfg ===
#meta-macro WALL_TRANSITION TERRAIN ADJACENT P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM
#meta-macro WALL_TRANSITION2 TERRAIN1 TERRAIN2 ADJACENT P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM
#meta-macro WALL_TRANSITION3 TERRAIN1 TERRAIN2 TERRAIN3 P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM

#define SIMPLE_OVERLAY_TERRAIN TERRAINLIST RESTRICTING IMAGESTEM

=== bridges.cfg ===
#define IMAGE_L_N LAYER NAME
#define DOCK_END IMAGESTEM WATER_TERRAIN_NAME BRIDGETYPE_NAME BEACHSIDE_AFFIX X Y
#define RAMP_BRIDGE IMAGESTEM BRIDGETYPE_NAME BRIDGES_VALUE R0 R1 R2 R3 R4 R5 S0 S1 S2 S3 S4 S5
#define RAMP_END IMAGESTEM WATER_TERRAIN_NAME NOTERM_AFFIX BRIDGETYPE_NAME R0 R1 R2 R3 R4 R5 X Y
#define BRIDGE_Y BRIDGETYPE1_NAME BRIDGETYPE2_NAME BRIDGETYPE3_NAME Y_IMAGE R0 R1 R2 R3 R4 R5 S0 S1 S2 S3 S4 S5
#define BRIDGECONNECT BRIDGETYPE_NAME R0 R1 R2 R3 R4 R5 X Y
#define CORNER ANGLE_IMAGE BRIDGETYPE1_NAME BRIDGETYPE2_NAME A1 A2 A3 A4 A5 A6 S0 S1 S2 S3 S4 S5
#define BRIDGE SE_NW_VALUE N_S_VALUE NE_SW_VALUE WATER_TERRAIN_NAME NOTERM_AFFIX IMAGESTEM

=== canyon.cfg ===
#define TRANS_0 TERRAIN
#define TRANS_1 TERRAIN
#define TRANS_2 TERRAIN
#define TRANS_3 TERRAIN
#define TRANS_4 TERRAIN
#define TRANS_5 TERRAIN
#define CANYON TERRAIN IMAGESTEM
=== castles.cfg ===
#define TERRAIN_ADJACENT_CORNER_LAYER TERRAIN1 TERRAIN2 TERRAIN3 LAYER BASE_POSITION IMAGESTEM
#define TERRAIN_ADJACENT_CORNER TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION IMAGESTEM
#define TERRAIN_ADJACENT_CORNER_FLAG1 TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION FLAG IMAGESTEM
#define TERRAIN_ADJACENT_CORNER_PROB TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION IMAGESTEM PROB
=== foresetcastle.cfg ===
#define FORESTADJCASTLEA FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLES FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLEO FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLE FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJ FOREST_ID ID PROB TILE_IMAGE
#define MOUNTAINADJCASTLEA FOREST_ID ID PROB TILE_IMAGE
=== mountains.cfg ===
#define MOUNTAINS_2x2 TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_2x4_NW_SE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_2x4_SW_NE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_1x3_NW_SE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_1x3_SW_NE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAIN_SINGLE TERRAIN PROB FLAG IMAGESTEM
#define PEAKS_LARGE TERRAIN PROB FLAG IMAGESTEM
#define PEAKS_1x2_SW_NE TERRAIN PROB FLAG IMAGESTEM
=== rails.cfg ===
#define RAIL_SWITCH IMAGESTEM BRIDGETYPE_NAME BRIDGETYPE_JOIN_NAME SWITCHSIDE_AFFIX MAINRAIL_AFFIX SWITCH_REVERSE_AFFIX X Y
#define RAIL_END IMAGESTEM BRIDGETYPE_NAME TRACKSIDE_AFFIX X Y
#define RAILWAY SE_NW_VALUE N_S_VALUE NE_SW_VALUE IMAGESTEM

=== walls.cfg ===
#define IMAGE_NW BUILDER IMAGESTEM
#define IMAGE_N BUILDER IMAGESTEM
#define IMAGE_NE BUILDER IMAGESTEM
#define IMAGE_SE BUILDER IMAGESTEM
#define IMAGE_S BUILDER IMAGESTEM
#define IMAGE_SW BUILDER IMAGESTEM
#define IMAGE_NW_N BUILDER IMAGESTEM
#define IMAGE_N_NE BUILDER IMAGESTEM
#define IMAGE_NE_SE BUILDER IMAGESTEM
#define IMAGE_SE_S BUILDER IMAGESTEM
#define IMAGE_S_SW BUILDER IMAGESTEM
#define IMAGE_SW_NW BUILDER IMAGESTEM
#define IMAGE_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_S_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_NW_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_SW_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_NE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_SE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_NW_N_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_NE_SE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_SE_S_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_S_SW_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_SW_NW_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S_SW_NW BUILDER IMAGESTEM
#define WALL_1_VARIATION PROB TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_1 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_2_VARIATION PROB TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_2 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_3 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_4 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_5 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_6 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define DISABLE_WALLS TERRAIN1 TERRAIN2 TERRAIN3
#define WALL_ADJACENT TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM BASE_NAME

TerrainMacrosWML

2010-05-30T15:10:04Z

Boucman: /* Flag Management */

{{DevFeature1.9}}
This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

== Flag Management ==
This section lists the common flags used by macros and their high level signification
* '''base''': is set on all hex when the base tile is set.
* '''overlay''': is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
* '''village''': is set when a village is added on a tile.
* '''transition-@R*''': is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: ''n,ne,nw,s,se,sw'' Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
* '''angle_@R*''' : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
* '''angleaway_@R*''' : used for bridges, the bridge does NOT have an exit on the given direction

== Layer Management ==
* '''-1000''': default layer for base tiles
* '''-80''': overlays that should always be drawn under units (like rails etc...)
* '''0''': default layer for overlays and villages
Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below
* '''1''': used by the base tile of castles/keeps
Flying/moving units are always drawn over terrain
== Precedence Management ==
TBSL
== Base Management ==
TBSL

== Macro naming convention ==
for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

=== Macro names ===
Type is the type of macros (like KEEP,OVERLAY etc...) we are using

* '''TYPE'''''_PLFB'' : puts an image on a tile
* '''TYPE_RANDOM'''''_LFB'' : puts an image from a random set on a tile
* '''TYPE_RESTRICTED[23]'''''_PLFB'': puts an image on a tile if the tile has one [two or three] neighbours of a given type
* '''TYPE_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above
* '''TYPE_ROTATION_RESTRICTED[23]'''''_PLFB'': combination of above + the images will be named according to where the neighbours are
* '''TYPE_ROTATION_RESTRICTED[23]_RANDOM'''''_PLFB'': combination of above

here ''_PLFB'' means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

=== Macro Parameters ===

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

* '''TERRAIN''' : the type of terrain to put the image on
* '''ADJACENT''' : ''only for restricted'' the type of neighbours to test for
* '''PROB''' : ''only for _P'' The probability of the rules generated by the macros of being applied. See the discussion in [[TerrainGraphicsTutorial#Cumulative_Probabilities]] for complications
* '''LAYER''' : ''only for _L'' The layer that will be used for the generated rules
* '''FLAG''' : ''only for _F'' A flag to test and set on the tile
* '''BUILDER''' : ''only for _B'' the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
* '''IMAGESTEM''': the basename on which filenames will be based.

=== Image Names ===
* '''_RANDOM_'''
** {{BUILDER} {IMAGESTEM} ()}
** {{BUILDER} {IMAGESTEM}2 ()}
** {{BUILDER} {IMAGESTEM}3 ()}
** ''etc up to 11''
* '''_ROTATION_'''
** '''1''' : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
** '''2''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
** '''3''' : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
* '''_RANDOM_ + _ROTATION_'''
** {{BUILDER} {IMAGESTEM}# (-@R#)} ''similar to above with all combinations''
== The TEST_COMPLETE macro ==

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
{TYPE_ROTATION_RESTRICTED3_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
{TYPE_ROTATION_RESTRICTED2_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
{TYPE_ROTATION_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
{TYPE_RESTRICTED_RANDOM_LFB ({TERRAIN}) ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
{TYPE_SINGLE_RANDOM_LFB ({TERRAIN}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

* If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
* if it has two neighbour or the correct image wasn't found, it will try two-sided variations
* if it has one neighbour or the correct image wasn't found, it will try one sided variations
* if it has still not found anything, it will try IMAGESTEM-small
* if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

== Image Builder macros ==
=== The problem ===
suppose we want to animate a transition with the following line
image=image1;image2;image3
Since it's a transition, we would like to write something like (simplified)
{TRANSITION_BASE <parameters> image1;image2;image3}
However, for a north transition, the macro would expand to something similar to
image=image1;image2;image3-n
Which is wrong, we want the prefix added to all images in the animation
image=image1-n;image2-n;image3-n
To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters
#define BUILDER IMAGESTEM POSTFIX
Which are in charge of returning what should be on the right side of the image= So, with the following macro
#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};
and the following code in the TRANSITION_BASE macro
image={{BUILDER} {IMAGESTEM} -n}
a call to
{TRANSITION_BASE_B <parameters> MY_BUILDER image}
would correctly expand.

=== Common parameters for all builders ===
All builders must have exactly the same parameters
* IMAGESTEM : the base name of the image from which to build
* POSTFIX : a postfix to add to all images

=== IMAGE_SINGLE IMAGESTEM POSTFIX ===
builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros
=== ANIMATION_03 IMAGESTEM POSTFIX ===
builds a Three image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
=== ANIMATION_04 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_10 IMAGESTEM POSTFIX ===
builds a ten image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
=== ANIMATION_15 IMAGESTEM POSTFIX ===
builds a fifteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
=== ANIMATION_04_140 IMAGESTEM POSTFIX ===
builds a four image animation, each image being displayed for 140 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
=== ANIMATION_18_70 IMAGESTEM POSTFIX ===
builds a eighteen image animation, each image being displayed for 100 ms
''' Images Used '''
* IMAGESTEM-A01
* IMAGESTEM-A02
* IMAGESTEM-A03
* IMAGESTEM-A04
* IMAGESTEM-A05
* IMAGESTEM-A06
* IMAGESTEM-A07
* IMAGESTEM-A08
* IMAGESTEM-A09
* IMAGESTEM-A10
* IMAGESTEM-A11
* IMAGESTEM-A12
* IMAGESTEM-A13
* IMAGESTEM-A14
* IMAGESTEM-A15
* IMAGESTEM-A16
* IMAGESTEM-A17
* IMAGESTEM-A18

== Base tile related macros ==

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''TERRAIN_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1000
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Overlay related macros==

Overlays have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''OVERLAY'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''overlay''
* '''BUILDER''': IMAGE_SINGLE

== Keep related macros ==

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''KEEP_BASE'''
* '''PROB''' : 100
* '''LAYER''': -1
* '''FLAG'''': ''base''
* '''BUILDER''': IMAGE_SINGLE

== Village related macros ==

villages have all the combinations of macros as described in the naming convention section with the following definition

* '''TYPE''' : the name for all macros starts with '''VILLAGE'''
* '''PROB''' : 100
* '''LAYER''': 0
* '''FLAG'''': ''village''
* '''BUILDER''': IMAGE_SINGLE

== Transition related macros ==
=== TRANSITION_BASE TERRAIN ADJACENT P=PROB=100 L=LAYER=-500 F=FLAG=transition B=BUILDER=IMAGE_SINGLE IMAGESTEM ===

This is the most basic form of transition, it will try to put a transition between the tile TERRAIN and ADJACENT

It will try to find the best matching image (with ''n,ne,se,s,sw,nw'' for @R flags)

i.e if your TERRAIN matches 2 ADJACENT tiles,
* it will not match for 4 sided and 3 sided images
* it will try 2 sided transitions with PROB (see also the FLAG discussion below)
* if it doesn't match it will 1 sided transition similarly

'''Images Used'''
* {{BUILDER} {IMAGESTEM} -@R0-@R1-@R2-@R3}
* {{BUILDER} {IMAGESTEM} -@R0-@R1-@R2}
* {{BUILDER} {IMAGESTEM} -@R0-@R1}
* {{BUILDER} {IMAGESTEM} -@R0}
'''Flag Management'''

This macro checks flags according to the common transition policy, i.e it will check that both this tile and the ADJACENT neighbours don't have the transition-@R# flags before applying.

suppose our TERRAIN has two ADJACENT on north and north east

it will check the following flags before adding {{BUILDER} {IMAGESTEM} -n-ne}
* TERRAIN has neither transition-n nor transition-ne set
* the north ADJACENT doesn't have transition-s set
* the north east ADJACENT doesn't have transition-sw set
if the conditions are met, it will apply the transition and set all the flags mentionned above

it will then try to apply {{BUILDER} {IMAGESTEM} -n} and check the following flags
* TERRAIN has neither transition-n set
* the north ADJACENT doesn't have transition-s set
(note that if the first rule applied, it will have set some flags and this rule will always fail)
again, if it can apply, it will set the flags mentionned above

it will then try to apply {{BUILDER} {IMAGESTEM} -ne} and check the following flags
* TERRAIN has neither transition-ne set
* the north ADJACENT doesn't have transition-sw set
(note that if the first rule applied, it will have set some flags and this rule will always fail, however this rule could be applied with the second rule above since no flag contradict)
again, if it can apply, it will set the flags mentionned above

=== DISABLE_BASE_TRANSITIONS TERRAINLIST ===
This macro will set all transition-@R* on the tile (''n,ne,se,s,sw'') thus preventing any other transition from being added

'''Flag Management'''
will set all transition-@R* on the TERRAINLIST tiles

== Terrain Specific ==
=== SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM ===

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else

''' Images Used '''
* IMAGESTEM-small
* IMAGESTEM-small2
* IMAGESTEM-small3
* IMAGESTEM-small4
* IMAGESTEM-small5
* IMAGESTEM-small6
* IMAGESTEM-small7
* IMAGESTEM-small8
* IMAGESTEM-small9
* IMAGESTEM
* IMAGESTEM2
* IMAGESTEM3
* IMAGESTEM4
* IMAGESTEM5
* IMAGESTEM6
* IMAGESTEM7
* IMAGESTEM8
* IMAGESTEM9

''' Parameters '''
* '''ADJACENT''': regexp of terrains that will use -small images

''' Flage management '''
this is technically an overlay. It is drawn on layer 0 with other overlays and test/set the overlay flag

== TO BE DOCUMENTED ==
=== misc.cfg ===
#meta-macro WALL_TRANSITION TERRAIN ADJACENT P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM
#meta-macro WALL_TRANSITION2 TERRAIN1 TERRAIN2 ADJACENT P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM
#meta-macro WALL_TRANSITION3 TERRAIN1 TERRAIN2 TERRAIN3 P=PROB=100 L=LAYER=0 F=FLAG=overlay IMAGESTEM

#define SIMPLE_OVERLAY_TERRAIN TERRAINLIST RESTRICTING IMAGESTEM

=== bridges.cfg ===
#define IMAGE_L_N LAYER NAME
#define DOCK_END IMAGESTEM WATER_TERRAIN_NAME BRIDGETYPE_NAME BEACHSIDE_AFFIX X Y
#define RAMP_BRIDGE IMAGESTEM BRIDGETYPE_NAME BRIDGES_VALUE R0 R1 R2 R3 R4 R5 S0 S1 S2 S3 S4 S5
#define RAMP_END IMAGESTEM WATER_TERRAIN_NAME NOTERM_AFFIX BRIDGETYPE_NAME R0 R1 R2 R3 R4 R5 X Y
#define BRIDGE_Y BRIDGETYPE1_NAME BRIDGETYPE2_NAME BRIDGETYPE3_NAME Y_IMAGE R0 R1 R2 R3 R4 R5 S0 S1 S2 S3 S4 S5
#define BRIDGECONNECT BRIDGETYPE_NAME R0 R1 R2 R3 R4 R5 X Y
#define CORNER ANGLE_IMAGE BRIDGETYPE1_NAME BRIDGETYPE2_NAME A1 A2 A3 A4 A5 A6 S0 S1 S2 S3 S4 S5
#define BRIDGE SE_NW_VALUE N_S_VALUE NE_SW_VALUE WATER_TERRAIN_NAME NOTERM_AFFIX IMAGESTEM

=== canyon.cfg ===
#define TRANS_0 TERRAIN
#define TRANS_1 TERRAIN
#define TRANS_2 TERRAIN
#define TRANS_3 TERRAIN
#define TRANS_4 TERRAIN
#define TRANS_5 TERRAIN
#define CANYON TERRAIN IMAGESTEM
=== castles.cfg ===
#define TERRAIN_ADJACENT_CORNER_LAYER TERRAIN1 TERRAIN2 TERRAIN3 LAYER BASE_POSITION IMAGESTEM
#define TERRAIN_ADJACENT_CORNER TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION IMAGESTEM
#define TERRAIN_ADJACENT_CORNER_FLAG1 TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION FLAG IMAGESTEM
#define TERRAIN_ADJACENT_CORNER_PROB TERRAIN1 TERRAIN2 TERRAIN3 BASE_POSITION IMAGESTEM PROB
=== foresetcastle.cfg ===
#define FORESTADJCASTLEA FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLES FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLEO FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJCASTLE FOREST_ID ID PROB TILE_IMAGE
#define FORESTADJ FOREST_ID ID PROB TILE_IMAGE
#define MOUNTAINADJCASTLEA FOREST_ID ID PROB TILE_IMAGE
=== mountains.cfg ===
#define MOUNTAINS_2x2 TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_2x4_NW_SE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_2x4_SW_NE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_1x3_NW_SE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAINS_1x3_SW_NE TERRAIN PROB FLAG IMAGESTEM
#define MOUNTAIN_SINGLE TERRAIN PROB FLAG IMAGESTEM
#define PEAKS_LARGE TERRAIN PROB FLAG IMAGESTEM
#define PEAKS_1x2_SW_NE TERRAIN PROB FLAG IMAGESTEM
=== rails.cfg ===
#define RAIL_SWITCH IMAGESTEM BRIDGETYPE_NAME BRIDGETYPE_JOIN_NAME SWITCHSIDE_AFFIX MAINRAIL_AFFIX SWITCH_REVERSE_AFFIX X Y
#define RAIL_END IMAGESTEM BRIDGETYPE_NAME TRACKSIDE_AFFIX X Y
#define RAILWAY SE_NW_VALUE N_S_VALUE NE_SW_VALUE IMAGESTEM

=== walls.cfg ===
#define IMAGE_NW BUILDER IMAGESTEM
#define IMAGE_N BUILDER IMAGESTEM
#define IMAGE_NE BUILDER IMAGESTEM
#define IMAGE_SE BUILDER IMAGESTEM
#define IMAGE_S BUILDER IMAGESTEM
#define IMAGE_SW BUILDER IMAGESTEM
#define IMAGE_NW_N BUILDER IMAGESTEM
#define IMAGE_N_NE BUILDER IMAGESTEM
#define IMAGE_NE_SE BUILDER IMAGESTEM
#define IMAGE_SE_S BUILDER IMAGESTEM
#define IMAGE_S_SW BUILDER IMAGESTEM
#define IMAGE_SW_NW BUILDER IMAGESTEM
#define IMAGE_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_S_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_NW_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_SW_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_NE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_SE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_NW_N_NE_SE_S BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S_SW BUILDER IMAGESTEM
#define IMAGE_NE_SE_S_SW_NW BUILDER IMAGESTEM
#define IMAGE_SE_S_SW_NW_N BUILDER IMAGESTEM
#define IMAGE_S_SW_NW_N_NE BUILDER IMAGESTEM
#define IMAGE_SW_NW_N_NE_SE BUILDER IMAGESTEM
#define IMAGE_N_NE_SE_S_SW_NW BUILDER IMAGESTEM
#define WALL_1_VARIATION PROB TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_1 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_2_VARIATION PROB TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_2 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_3 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_4 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_5 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define WALL_ADJACENT_6 TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM
#define DISABLE_WALLS TERRAIN1 TERRAIN2 TERRAIN3
#define WALL_ADJACENT TERRAIN_PATTERN ADJACENT BUILDER IMAGESTEM BASE_NAME