GAE/Reference

This page contains a reference for GAE-specific XML structures. As of December 4,2008, this is still missing information on pets and the patrol and guard commands. Although they are covered in the GAE Guide, their specification should be clearly defined here. =Introduction= Since there is no DTD, this section section will describe the expected XML format of newly added XML structures.

For the Pluralism column in the nested elements descriptions, the following is the legend for the notation: =Reference=

Appears In
&lt;skill&gt;

Attributes
none

Appears In
&lt;effects&gt;

&lt;static-modifiers&gt; and &lt;multipliers&gt;
These tags represent very core data structures that drive many aspects of GAE's design. They are used for levels, upgrades, effects and emanations. On the implementation level, static modifiers are implemented in the C++ UnitStatsBase class and multipliers are implemented in the EnhancementTypeBase class (a subclass of UnitStatsBase). Because multiples of these may be applied to a unit, it's important to understand how they are evaluated. Put briefly, multipliers are not applied (i.e., multiplied) against any other bonus, static modifier or multiplier, only against the base stat.

For the long explanation, the static modifiers and multipliers for every unit's level-ups, upgrades, effects and emanations are evaluated in the C++ member function Unit::recalculateStats. All multipliers for a given stat are [b]added[/b] together, rather than multiplied, and then the count minus one is subtracted.

totalMultiplier = multiplier1 + multiplier2 - (multiplier_count - 1);

Thus, if you have 1.3 and 1.5 multipliers for hit points, the final multiplier is 1.8 (1.3 + 1.5 -(2 - 1)). If multipliers were multiplied by each other, the total multiplier would be 1.95 (1.3 x 1.5) and successive multiplier bonuses or penalties would have an exponential effect. The final multiplier is applied to the base stat [b]only[/b], and then static modifiers are added to that result. Thus, if you have a unit with 500 hit points, and it gets a static-modifier bonus of +50 and a multiplier bonus of * 1.5, it is evaluated in this as "500 x 1.5 + 50 = 800" and not "(500 + 50) x 1.5 = 825". This behavior is important to keep in mind when designing mods where very low stats have multipliers applied against them, because the effect will be nominal, despite any static modifier bonuses.

Appears In
&lt;effect&gt;, &lt;emanation&gt;, &lt;skill&gt; or &lt;upgrade&gt;

Attributes
none

Nested Elements
Each nested element requires a single attribute named "value". For static modifiers, the value should be an integer and for multipliers the value should be a floating point number. If an element doesn't appear, the default value for static modifiers is zero and the default value for multipliers is 1.0.

&lt;flags&gt;
Flags effect various aspects of the "effect". Most flags are for AI use and are not yet used, but are hints to tell the AI how best to use skills with the effect. Each nested element has no attributes or children.

Appears In
&lt;effect&gt;, &lt;emanation&gt;

Attributes
none

&lt;fields-added&gt; and &lt;fields-removed&gt;
(not yet implemented) Specifies fields of travel that are added to or removed from the unit. This may be adding the ability for a unit to swim, or levitate or grounding an otherwise flying unit (forcing them to walk or become immobile). The only fields currently available are air and land. However, water, forest (i.e., travel through trees) and subterainian may be added in this mod.

Appears In
&lt;effect&gt;, &lt;emanation&gt;

Attributes
none

&lt;light&gt;
(not yet implemented) Causes light to emanate from the unit or changes the light if one already exists.

Appears In
&lt;effect&gt;, &lt;emanation&gt;

Nested Elements
none

&lt;sound&gt;
(not yet implemented)

Appears In
&lt;effect&gt;, &lt;emanation&gt;

Nested Elements
none

&lt;particle&gt;
(Initial implementation in GAE 0.3.0)

Appears In
&lt;effect&gt;, &lt;emanation&gt;

Nested Elements
none

Appears In
&lt;effect&gt;, &lt;emanation&gt;

Attributes
none

Nested Elements
none

&lt;emanations&gt;
May be optionally nested directly within a &lt;unit&gt;'s &lt;parameters&gt; node. Emanations are static condition that applies an effect to surrounding units every tick. In general, an emanation should use the  stacking value. The attributes and nested elements in an &lt;emanation&gt; node is identical to an &lt;effect&gt; node with the addition of a  attribute.

Attributes
none

Nested Elements
none

Attributes
Contains all attributes of &lt;effect&gt;, with the addition detailed below

Nested Elements
See &lt;effect&gt;.

&lt;level&gt;
This section describes the GAE implementation of the &lt;level&gt; node specified in a unit definition. In the original Glest, &lt;level&gt; tag contained two attribute specifying the name of the level and the number of kills require to achieve it. In GAE, a level can contain the same data specified for an upgrade, effect, emanation, etc. The level name and number of kills are still specified as attributes to the &lt;level&gt; node. In addition, the stats that are increased in the original Glest engine are set in GAE levels as default values, so not adding anything to the level is the equivalent of the following definition: ...           ....

Appears In
unit's &lt;properties&gt;

Attributes
Contains all attributes of &lt;effect&gt;, with the addition detailed below

Nested Elements
See &lt;effect&gt;.