GAE/Reference

As of February 22, 2008, this section is missing information on subfactions, pets, patrol and guard commands, although they are covered in the Guide section above.

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:

Value	Meaning
?	zero or one
1	exactly one
*	zero or more
+	one or more

Reference

<effects>

An <effects> node may be embedded in a unit skill node.

Attributes

none

Nested Elements

Element	Pluralism	Description
<effect>	*	the effects

<effect>

Attributes

Attribute	Required?	Description
name	required	Name of the effect
image	optional	(not yet implemented) Path to an image used to display the effect (image not yet displayed, but effect name is)
bias	required	Primarily used by AI and must be either detrimental, neutral or beneficial.
stacking	required	Defines behavior when an additional effect of the same type hits the unit. Must be one of stack (the new effect is added in addition to the old one), extend (the duration of the original effect is extended), overwrite (the old effect is replaced with the new effect) or reject (the new effect is ignored).
target	optional	What units are effected by the effect. Must be one of ally, foe, pet, master or all. Default value is any.
chance	optional	The percent chance that the effect will be applied to the target. The default is 100%.
duration	required	The number of seconds the effect will last. Ignored if the flag "permanent" is specified.
damage-type	optional	When hp-regeneration is negative, this value (if present) is used to determine the appropriate multiplier to use for the target's armor. This is the data specified in <damage-multipliers> section of the techtree.xml file.

Nested Elements

Element	Pluralism	Description
<static-modifiers>	?	contains static, integral modifiers to a unit's attributes (e.g., +1)
<multipliers>	?	uses multipliers to modify a unit's attributes (e.g., x 1.25)
<flags>	?	special purpose flags that alter the effect, it's behavior or tells the AI how best to use a skill with this effect
<fields-added>	?	(not yet implemented) fields of travel that are added by the effect
<fields-removed>	?	(not yet implemented) fields of travel that are removed by the effect
<light>	?	light generated by the effect, emanating from the unit and replacing any previous light value
<sound>	?	(not yet implemented) a sound, optionally looping, caused by the effect
<particle>	?	(not yet implemented) particles caused by the effect
<recourse-effects>	?	secondary effects applied to the caster/attacker that caused the original effect

<static-modifiers> and <multipliers>

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.

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.

Element	Pluralism	Description
<max-hp>	?	maxiumum hit points
<max-ep>	?	maximum energy points
<hp-regeneration>	?	rate of hit point regeneration
<ep-regeneration>	?	rate of energy regeneration
<sight>	?	sight distance
<armor>	?	armor (protection from attacks)
<attack-strength>	?	base damage value when attacking
<attack-range>	?	maximum attack distance
<move-speed>	?	how fast the unit moves
<attack-speed>	?	the rate of attack (how often the unit attacks and how long each attack takes to execute)
<production-speed>	?	how long the unit takes to be produced, to morph or to research an upgrade
<harvest-speed>	?	how fast workers harvest/mine/chop wood

<flags>

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.

Attributes

none

Nested Elements

Element	Pluralism	Description
<effects-ally>	?	Will effect allies. This is also turned on when target="allies" or "both".
<effects-foes>	?	Will effect allies. This is also turned on when target="foes" or "both".
<not-effects-normal-units>	?	Will not effect normal units (i.e., not buildings). By default, normal units are effected and buildings aren't.
<effects-buildings>	?	Will effect buildings. By default, buildings are not effected.
<pets-only>	?	Will only effect the pets of the caster. This causes effects-ally, effects-foes, not-effects-normal-units and effects-buildings to be ignored.
<master-only>	?	Will only effect the master of the caster (i.e., the pet is the caster). This causes effects-ally, effects-foes, not-effects-normal-units and effects-buildings to be ignored.
<effects-non-living>	?	(not yet implemented)
<apply-splash-strength>	?	Scale the strength of the effect with the same formula used to determine splash damage, which is 1.0 ÷ (distance_from_target + 1) -- the further from the apex of the target, the weaker the effect will be. By default, all units within the splash radius of a skill with an effect are effected equally.
<ends-with-source>	?	The effect will end if the unit who caused the effect dies.
<recourse-ends-with-target>	?	Causes the recourse effect to end when the root (primary) effect ends, regardless the duration. Applies only to recourse effects.
<allow-negative-speed>	?	Adding negative values to the static-modifiers for move-speed can cause a unit to travel away from their destination, although they are facing their destination. While this is probably undesirable, this flag will allow it to happen anyway. The default behavior brings the unit's effective speed to zero if it would otherwise become negative.
<tick-immediately>	?	Causes Hp & Ep regeneration to take immediate effect as if tick() had been called. This can be used for effects that should immediately heal or damage units and is mostly useful for zero duration effects, causing it to take immediate effect and then terminate. Using this flag with a zero duration will render all other modifiers in the effect, other than Hp & Ep regeneration to become useless although sound and particle effects will still be played/rendered.
<permanent>	?	The effect has an infinite duration.
<damaged>	?	(not yet implemented) AI hint: use on damaged units.
<ranged>	?	(not yet implemented) AI hint: use on ranged units
<melee>	?	(not yet implemented) AI hint: use on short range (melee) units (perhaps range 2 or less)
<workers>	?	(not yet implemented) AI hint: use on worker units
<building>	?	(not yet implemented) AI hint: use on buildings
<heavy>	?	(not yet implemented) AI hint: use on heavy units
<scout>	?	(not yet implemented) AI hint: use on scouting units. This can be engaged as soon as the AI decides a unit should scout.
<combat-only>	?	(not yet implemented) AI hint: use only in combat (applies to beneficials). This should mean any allied unit who has visual on an enemy unit and is using an attack skill, or one who is not using an attack skill, but is being attacked (i.e., holding position).
<use-sparingly>	?	(not yet implemented) AI hint: use sparingly (i.e., save for when "big guns" are needed)
<use-liberally>	?	(not yet implemented) AI hint: use liberally (i.e., milk this one dry)

<fields-added> and <fields-removed>

(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.

Attributes

none

Nested Elements

Element	Pluralism	Description
<air>	?
<land>	?
<water>	?

<light>

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

Attributes

Attribute	Required?	Description
enabled	required	true or false
red	required if enabled is true	a value between 0.0 and 1.0
green	required if enabled is true	a value between 0.0 and 1.0
blue	required if enabled is true	a value between 0.0 and 1.0

Nested Elements

none

<sound>

(not yet implemented)

Attributes

Attribute	Required?	Description
enabled	required	true or false
start-time	required if enabled is true	number of seconds (in floating point) before playing the sound
loop	required if enabled is true	true if the sound should loop, false otherwise.
path	required if enabled is true	the sound file to play

Nested Elements

none

<particle>

(Initial implementation in GAE 0.3.0)

Attributes

Attribute	Required?	Description
enabled	required	true or false
path	required if enabled is true	the xml file defining the particle system

Nested Elements

none

<recourse-effects>

Attributes

none

Nested Elements

Element	Pluralism	Description
<effect>	*	The effect(s) which are applied to the originator (i.e., the unit attacking or casting a spell) as a recourse of the original or primary effect.

none

<emanations>

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

Attributes

none

Nested Elements

Element	Pluralism	Description
<emanation>	*	The emanation effect(s) which are applied to surrounding units each tick.

none

<emanation>

Attributes

Contains all attributes of <effect>, with the addition detailed below

Attribute	Required?	Description
radius	required	the radius (in tiles) the effect emanates from the source unit.

Nested Elements

See <effect>.

<level>

This section describes the GAE implementation of the <level> node specified in a unit definition. In the original Glest, <level> 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 <level> 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:

<unit>
  <properties>
    ...
    <levels>
      <level name="big_scary" kills="1">
        <multipliers>
          <max-hp value="1.5"/>
          <max-ep value="1.5"/>
          <sight value="1.2"/>
          <armor value="1.5"/>
        </multipliers>
      </level>
    </levels>
    ....

Attributes

Contains all attributes of <effect>, with the addition detailed below

Attribute	Required?	Description
name	required	the name of the level, which is also the prefix which is prepended to the unit's name in game play
kills	required	The number of kills require to achieve the level.

Nested Elements

See <effect>.