Difference between revisions of "FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
m (Content Files)
m (Use)
Line 77: Line 77:
 
===Use===
 
===Use===
  
Attributes can be referenced on the source or target object, but not alone.  So "Source.ID" and "Target.PlanetSize" are legal variables, but not "PlanetEnvironment". In addition, an object's containing object, if one exists, may be used in a variable.  For instance, if the source is a planet, "Source.System.StarType" represents the ster type of the source's system.  Planet may also be used in a similar fashion, as in "Target.Planet.PlanetEnvironment".
+
In item descriptions, parameter values such as LOW, HIGH, or NUMBER may be simple numbers, like 5 or 10, in which case all objects with the appropriate meter are treated the same by Turn.  LOW and HIGH may also be defined in terms of attributes (or "properties") of the Source or Target object.  In these cases, different objects may be differently matched or not, if the property used differs between them.
 +
 
 +
Attributes can be referenced on the source or target object, but not alone.  So "Source.ID" and "Target.PlanetSize" are legal variables, but "PlanetEnvironment" in isolation is not.
 +
 
 +
In addition, an object's containing object, if one exists, may be used in a variable.  For instance, if the source is a planet, "Source.System.StarType" represents the ster type of the source's system.  Planet may also be used in a similar fashion, as in "Target.Planet.PlanetEnvironment".
  
 
Nonsensical combinations of Target, Source, Planet, System, and the above attributes are allowed, but will always return 0 for numeric values, and INVALID_... for enumerated type values.  For instance, if the source is a System, Source.System.StarType will always return INVALID_STAR_TYPE, which is guaranteed not to match any actual System.  Similarly, Target.System.CurrentFarming makes no sense (since meters exist for Planets but not Systems), and so will return 0.0.
 
Nonsensical combinations of Target, Source, Planet, System, and the above attributes are allowed, but will always return 0 for numeric values, and INVALID_... for enumerated type values.  For instance, if the source is a System, Source.System.StarType will always return INVALID_STAR_TYPE, which is guaranteed not to match any actual System.  Similarly, Target.System.CurrentFarming makes no sense (since meters exist for Planets but not Systems), and so will return 0.0.

Revision as of 22:44, 20 May 2006

This page describes the scripting language used to descibe much of the content of FreeOrion. Scripted content includes scripted descriptions of technology, buildings, and specials.

A major component of content descriptions are effects groups, which contain Effects and Conditions. Effects change the game state and thereby give buildings, techs and specials their in-game purpose. Conditions determine when (the activation condition) and on what (the scope condition) effects act.

Content Files

FreeOrion content is described in content files located in the /default subdirectory of the main FreeOrion game directory (typically 'C:\Freeorion').

File                | Contents
--------------------+--------------------------------------
techs.txt           | Tech Categories and Technologies
buildings.txt       | Buildings
specials.txt        | Specials (general)
planet_specials.txt | Specials (randomly placed on planets)

These files are structured as a list of descriptions of individual entries of their resepective contents. buildings.txt is a list of Building descriptions (see below). specials.txt and planet_specials.txt are a list of special descriptions. techs.txt contains tech category and tech descriptions. The ordering of entries in the files do not matter, except for techs.txt, which requires that a particular tech category entries appear before any techs are listed as part of that category.

Parameter values such as LOW, HIGH, or NUMBER may be simple numbers, like 5 or 10, in which case all objects with the appropriate meter are treated the same by Turn. LOW and HIGH may also be defined as properties of the Source Target object, as in Target.MaxResearch or Source.Owner. In these cases, different objects may be differently matched or not, if the property used differs between them.

Whitespace is unimportant (spaces, tabs, and line endings), and capitalization is ignored for everything outside quotes.

Words in quotes, eg. "NAME" are case-sensitive names of scripted content items such as techs, buildings, or specials. The names of the items are defined in their description by their line:

name = "NAME"

These items may be referred to in other items' descriptions by "NAME".

Comments may be added to files using c/c++-style comment blocks. Anything in such blocks will be ignored when parsing the content files. Anything after "/*" will be ignored until the next occurence of "*/" (even if it occurs several lines later), and anything on a line after "//" will be ignored.

Types and Expressions

In the Conditions and Effects below, there are references to variables and expressions of various types. Variables refer to attributes of a source or target object. The source object is the object to which the Effect is attached, and the target object(s) is(are) the objects that are within an Effect's scope.

Object Attributes

List

Here is a comprehensive list of the attributes available, and their types (more on types later):

CurrentFarming        double
MaxFarming            double
CurrentIndustry       double
MaxIndustry           double
CurrentResearch       double
MaxResearch           double
CurrentTrade          double
MaxTrade              double
CurrentMining         double
MaxMining             double
CurrentConstruction   double
MaxConstruction       double
CurrentHealth         double
MaxHealth             double
CurrentPopulation     double
MaxPopulation         double
TradeStockpile        double
MineralStockpile      double
FoodStockpile         double
TradeProduction       double
FoodProduction        double
MineralProduction     double
IndustryProduction    double
ResearchProduction    double
PlanetSize            PlanetSize +
PlanetType            PlanetType +
PlanetEnvironment     PlanetEnvironment +
ObjectType            UniverseObjectType +!
StarType              StarType +
PrimaryFocus          FocusType +
SecondaryFocus        FocusType +
Owner                 int ++
ID                    int +++


+ See the FreeOrion sources for the valid values for these enumerated types. An unoffical list of valid values for most enumerated types can be found here, but this may not be always up to date and accurate, since the valid values may change periodically.
++ Owner will return -1 (instead of 0 like all other failures for numeric types) if there are no owners, or there are more than one, since this is guaranteed not to match any actual object.
+++ This is the unique integer numeric ID used to identify an object internally within FreeOrion.
! The types returned by ObjectType have some overlap. For instance, a Planet is also a PopCenter and a ProdCenter. In this case, Planet is returned before PopCenter or ProdCenter, since if you see a Planet, you know it is a ProdCenter, but seeing a ProdCenter, you have no idea if it is a Planet or something else that produces goods or resources, for instance a mining outpost. This principle guides the order in which type is determined when ObjectType is used.

Use

In item descriptions, parameter values such as LOW, HIGH, or NUMBER may be simple numbers, like 5 or 10, in which case all objects with the appropriate meter are treated the same by Turn. LOW and HIGH may also be defined in terms of attributes (or "properties") of the Source or Target object. In these cases, different objects may be differently matched or not, if the property used differs between them.

Attributes can be referenced on the source or target object, but not alone. So "Source.ID" and "Target.PlanetSize" are legal variables, but "PlanetEnvironment" in isolation is not.

In addition, an object's containing object, if one exists, may be used in a variable. For instance, if the source is a planet, "Source.System.StarType" represents the ster type of the source's system. Planet may also be used in a similar fashion, as in "Target.Planet.PlanetEnvironment".

Nonsensical combinations of Target, Source, Planet, System, and the above attributes are allowed, but will always return 0 for numeric values, and INVALID_... for enumerated type values. For instance, if the source is a System, Source.System.StarType will always return INVALID_STAR_TYPE, which is guaranteed not to match any actual System. Similarly, Target.System.CurrentFarming makes no sense (since meters exist for Planets but not Systems), and so will return 0.0.

Types

The "double" type listed above, is a double-precision floating point number, which is more or less any real number in the range [-10^300, 10^300]. The "int" type is an integer number, which is basically any whole number in the range [-2*10^9, 2*10^9]. The other types are enumerted types, with specific values. Each such value has a string associated with it, for instance the first valid StarType is STAR_BLUE.

In the Conditions and Effects below, certain parameters have types. It is illegal to provide a parameter of the wrong type, and it will result in a thrown exception (a purposeful crash of FreeOrion). There is one major exceptions to this. It is legal to provide a int value for any parameter of any type. This is mainly to support easy expression syntax, which is the next thing that needs to be addressed.

Instead of providing a singe variable or constant value (such as 3.14, 5, or STAR_BLUE), you can instead provide an arithmetic expression. Legal expressions may contain parentheses, +, -, *, and /. The - operator can be binary as in "3 - 4", or unary as in "-Source.MaxHealth". Whitespace (spaces, tabs, and newlines) is ignored. Expressions may be arbtrarily complex. The type of the entire expression must match the type of the parameter for which it is intended. For instance, it is illegal to supply "1 + 3.14" as a value for an int-type parameter, since 3.14 is not an int. As mentioned before, though, it is legal to supply "STAR_BLUE + 1" as a value for a StarType parameter, since integers are always ok.

Note that since arbitrarily complex expressions are allowed in Effects, and multiple Effects may affect a single target in a single turn, the order in which the Effects are applied to the target may matter. For instance, if Effect A sets the current industry meter to "Target.CurrentIndustry + 20", and Effect B sets the current industry meter to "Target.CurrentIndustry * 3", the answer could be X * 3 + 20 or (X + 20) * 3, depending on the order of execution. To minimize this, and in keeping with the guidelines for Effects in general, such Effects should have small magnitude, which will make the problem largely disappear. For instance, if "Target.CurrentIndustry + 3" and "Target.CurrentIndustry * 1.05" are used instead, the difference between X * 1.05 + 3 and (X + 3) * 1.05 is a negligible 0.15.

Note that some of the parameters in the Conditions and Effects below ask for a certain type, sometimes a type-expression. Those paramters that do not explicitly allow type-expressions cannot handle them.

Finally, note that in places below where a bool value is requested, you must enter a "1" for true or a "0" for false. "False", "True", "T", "F", etc., are not recognized.

Conditions

The syntax "{a|b|c}" below indcates a choice of values, exactly one of which must be selected. The brackets and vertical lines are not legal to use themselves.

"{a|[a b c ...]}" indicates that a single item may be specified ("a"), or multiple items in a list ("[a b c ...]").

"low = ", "high = ", etc., indicates an *optional* parameter name. All parameters must appear in the order indicated, so the names are not necessary to indicate which value is meant for which parameter. The name may be included, however.

Turn

Matches objects if the current game turn is greater than or equal to LOW and less than HIGH.

Turn low = LOW high = HIGH

NumberOf

Matches at most NUMBER objects that match CONDITION. If fewer than NUMBER objects match CONDITION, all such objects are matched. If more than NUMBER objects match CONDITION, NUMBER such objects are randomly selected and matched.

Note: If the value of NUMBER is specified as a property of Target, such as Target.MaxResearch, this is treated as if the source was the target. So, Target.Anything with resolve to Source.Anything.

NumberOf number = NUMBER condition = CONDITION

All

Matches all objects.

All

EmpireAffiliation

Matches objects owned by (OwnedBy) or owned exclusively by (OwnedExclusivelyBy) the empire with id EMPIRE_ID. Typically EMPIRE_ID would be specified as a function of an object, such as Source.Owner, however a constant number such as 2 may also be specified.

OwnedBy affiliation = {EnemyOf|AllyOf|TheEmpire} empire = EMPIRE
OwnedExclusivelyBy affiliation = {EnemyOf|AllyOf|TheEmpire} empire = EMPIRE

Self

Matches the Source object.

Source

Type

Matches objects with the indicated type. "Building" is equivalent to "ObjectType type = Building"

Building
Ship
Fleet
Planet
PopulationCenter
ProductionCenter
System 
ObjectType type = TYPE
/* Types are:
Building
Ship
Fleet
Planet
PopulationCenter
ProductionCenter
System 
*/

Building

Matches buildings with the indicated name. Name is as indicated in a particular building description, by: name = "NAME"

Building name = "NAME"

HasSpecial

Matches objects that contain the indicated special. Name is as indicated in a particular special description, by: name = "NAME"

HasSpecial name = "NAME"

Contains

Matches objects that contain one or more objects that match the indicated CONDITION

Contains condition = CONDITION

ContainedBy

Matches objects that are contained by one or more objects that match the indicated CONDITION

ContainedBy condition = CONDITION

PlanetType

Matches objects that are or are contained by planets that have the indicated type.

Planet type = {TYPE|[TYPE0 TYPE1 TYPE2 ...]}

Types are:

Swamp
Toxic
Inferno
Radiated
Barren
Tundra
Desert
Terran
Ocean
Gaia
Asteroids
GasGiant

PlanetSize

Matches objects that are or are contained by planets that are the indicated size.

Planet size = {SIZE|[SIZE0 SIZE1 SIZE2 ...]}

Sizes are:

Tiny
Small
Medium
Large
Huge
Asteroids
GasGiant

PlanetEnvironment

Matches objects that are or are contained by planets that have the indicated environment.

Planet environment = {ENV|[ENV0 ENV1 ENV2 ...]}

Environments are:

Uninhabitable
Terrible
Adequate
Superb
Optimal

FocusType

Matches planets that have the primary focus (PrimaryFocus) or secondary focus (SecondaryFocus).

PrimaryFocus focus = {FOCUS|[FOCUS0 FOCUS1 FOCUS2 ...]}
SecondaryFocus focus = {FOCUS|[FOCUS0 FOCUS1 FOCUS2 ...]}

Foci are:

Balanced
Farming
Industry
Mining
Research
Trade

StarType

Matches objects that are or are contained by systems that have the indicated star type.

Star type = {TYPE|[TYPE0 TYPE1 TYPE2 ...]}

Types are:

Blue
White
Yellow
Orange
Red
Neutron
BlackHole

Chance

Matches objects with a probability of PROB. That is, objects have a probability of PROB of being matched.

Random probability = PROB

MeterValue

Matches objects with the appropriate meter values that are greater than or equal to LOW and less than HIGH.

MaxPopulation low = LOW high = HIGH MaxFarming low = LOW high = HIGH MaxIndustry low = LOW high = HIGH MaxResearch low = LOW high = HIGH MaxTrade low = LOW high = HIGH MaxMining low = LOW high = HIGH MaxConstruction low = LOW high = HIGH MaxHealth low = LOW high = HIGH CurrentPopulation low = LOW high = HIGH CurrentFarming low = LOW high = HIGH CurrentIndustry low = LOW high = HIGH CurrentResearch low = LOW high = HIGH CurrentTrade low = LOW high = HIGH CurrentMining low = LOW high = HIGH CurrentConstruction low = LOW high = HIGH CurrentHealth low = LOW high = HIGH

EmpireStockpileValue

Matches objects with exactly one owner, whose owner's stockpile of the appropriate resource is greater than or equal to LOW and less than or equal to HIGH.

OwnerFoodStockpile low = LOW high = HIGH OwnerMineralStockpile low = LOW high = HIGH OwnerTradeStockpile low = LOW high = HIGH

OwnerHasTech

OwnerHasTech name = "NAME"

VisibleToEmpire

VisibleToEmpire empire = {EMPIRE|[EMPIRE0 EMPIRE1 EMPIRE2 ...]}

WithinDistance

WithinDistance distance = DISTANCE condition = CONDITION

WithinStarlaneJumps

WithinStarlaneJumps jumps = JUMPS condition = CONDITION

And

And [CONDITION0 CONDITION1 CONDITION2 ...]

/* Or, more naturally: And [

 CONDITION0
 CONDITION1
 CONDITION2

]

  • /

Or

Or [CONDITION0 CONDITION1 CONDITION2 ...]

/* Or, more naturally: Or [

 CONDITION0
 CONDITION1
 CONDITION2

]

  • /

Not

Not CONDITION

/* And, Or, and Not are exceptions in that there are no optional "param = " param names. */

Note: Implicit ContainedBy

Some Conditions that match an object's containing object will be returned, even though they at first seem to be nonsensical. For instance, if the target object is a Planet, StarType will match the type of the System in which the target is located. This means that StarType will match all objects in all Systems with the given star type, and the Systems themselves. Similarly, all objects on all Planets (and the Planets themselves) that match a PlanetType, PlanetSize, or PlanetEnvironment will be matched. This has an important implication; if you want all Systems with blue stars, you should use StarType=STAR_BLUE AND Type=OBJ_SYSTEM:

<Condition::And>
    <Condition::StarType>
        <StarType>STAR_BLUE</StarType>
    </Condition::StarType>
    <Condition::Type>
        <type>OBJ_SYSTEM</type>
    </Condition::Type>
</Condition::And>

If you want all Ships in Systems with blue stars, you should use StarType=STAR_BLUE AND Type=OBJ_SHIP:

<Condition::And>
    <Condition::StarType>
        <StarType>STAR_BLUE</StarType>
    </Condition::StarType>
    <Condition::Type>
        <type>OBJ_SHIP</type>
    </Condition::Type>
</Condition::And>


Note: And & Or Efficiency

The And and Or Conditions are designed to work as efficiently as possible, by only searching the objects that have not already been matched. So it is always best to put the most restrictive Condition first in an And Condition's operands. For instance, if StarType=STAR_BLUE matches about 1000 objects, And(Self, StarType=STAR_BLUE) will be about 1000 times faster than And(StarType=STAR_BLUE, Self), since the former only has to look at the match from Self to see if it also is (or is inside of) a blue-starred System, whereas that latter has to look through the 1000 matches from StarType=STAR_BLUE to see if any of them also matches Self.

Effects

SetMeter

SetMaxPopulation value = VALUE SetMaxFarming value = VALUE SetMaxIndustry value = VALUE SetMaxResearch value = VALUE SetMaxTrade value = VALUE SetMaxMining value = VALUE SetMaxConstruction value = VALUE SetMaxHealth value = VALUE SetCurrentPopulation value = VALUE SetCurrentFarming value = VALUE SetCurrentIndustry value = VALUE SetCurrentResearch value = VALUE SetCurrentTrade value = VALUE SetCurrentMining value = VALUE SetCurrentConstruction value = VALUE SetCurrentHealth value = VALUE

SetEmpireStockpile

SetOwnerFoodStockpile value = VALUE SetOwnerMineralStockpile value = VALUE SetOwnerTradeStockpile value = VALUE

SetPlanetType

SetPlanetType type = TYPE

SetPlanetSize

SetPlanetSize size = SIZE

AddOwner

AddOwner empire = EMPIRE

RemoveOwner

RemoveOwner empire = EMPIRE

Destroy

Destroy

AddSpecial

AddSpecial name = "NAME"

RemoveSpecial

RemoveSpecial name = "NAME"

SetStarType

SetStarType type = TYPE

SetTechAvailability

GiveTechToOwner name = "NAME" RevokeTechFromOwner name = "NAME" UnlockTechItemsForOwner name = "NAME" LockTechItemsForOwner name = "NAME"

Effect Evaluation & Application Ordering

Effects are evaluated and then applied while processing a FreeOrion turn. When this happens, all EffectsGroups' activation and scope conditions are evaluated before any effects are applied. The order of effects application is as follows: effects from Specials, then effects from Techs, then effects from Buildings. The order of execution of Effects within these groups is deterministic, though not controllable.

EffectsGroup

EffectsGroup

  scope = CONDITION
  activation = CONDITION [optional -- may be left out]
  stackinggroup = "STACKINGGROUP" [optional -- may be left out]
  effects = {EFFECT|[
      EFFECT
      EFFECT
      EFFECT
  ]}

Special

Special

  name = "NAME"
  description = "DESCRIPTION"
  effectsgroups = {EFFECTSGROUP|[
       EFFECTSGROUP
       EFFECTSGROUP
       EFFECTSGROUP
  ]}

BuildingType

BuildingType

   name = "NAME"
   description = "DESCRIPTION"
   buildcost = BUILDCOST
   buildtime = BUILDTIME
   maintenancecost = MAINTENANCECOST
   effectsgroups = {EFFECTSGROUP|[
       EFFECTSGROUP
       EFFECTSGROUP
       EFFECTSGROUP
   ]}
   graphic = "GRAPHICFILENAME"

Item

Item type = TYPE name = "NAME"


Tech Category

TechCategory "NAME"

Tech

Tech

   name = "NAME"
   description = "DESCRIPTION"
   techtype = TYPE
   category = "CATEGORY"
   researchcost = RESEARCHCOST
   researchturns = RESEARCHTURNS
   prerequisites = {"NAME"|[
       "NAME"
       "NAME"
       "NAME"
   ]}
   unlock = {ITEM|[
       ITEM
       ITEM
       ITEM
   ]}
   effectsgroups = {EFFECTSGROUP|[ [optional -- may be left out]
        EFFECTSGROUP
        EFFECTSGROUP
        EFFECTSGROUP
   ]}
   graphic = "GRAPHICFILENAME"


Effects - Old Version

SetMeter


Descr.: Sets the meter of the given kind to VALUE. The max value of the meter is set if MAX == true; otherwise the current value of the meter is set. If the target of the Effect does not have the requested meter, nothing is done. The meter to alter is indicated by its MeterType in the METER field.
XML format:

<Effect::SetMeter>
    <meter>METER</meter>
    <value>VALUE</value>
    <max>MAX</max>
</Effect::SetMeter>


Param Types:

METER MeterType
VALUE double-expression
MAX   bool


SetEmpireStockpile


Descr.: Sets the empire stockpile of STOCKPILE of the target's owning empire to VALUE. If the target does not have exactly one owner, nothing is done.
XML format:

<Effect::SetEmpireStockpile>
    <stockpile>STOCKPILE</stockpile>
    <value>VALUE</value>
</Effect::SetEmpireStockpile>


Param Types:

STOCKPILE StockpileType
VALUE     double-expression


SetPlanetType


Descr.: Sets the planet type of the target to TYPE. This has no effect on non-Planet targets. Note that changing the type of a PT_ASTEROID or PT_GASGIANT planet will also change its size to SZ_TINY or SZ_HUGE, respectively. Similarly, changing type to PT_ASTEROID or PT_GASGIANT will also cause the size to change to SZ_ASTEROID or SZ_GASGIANT, respectively.
XML format:

<Effect::SetPlanetType>TYPE</Effect::SetPlanetType>


Param Types:

TYPE PlanetSize-expression

SetPlanetSize


Descr.: Sets the planet size of the target to SIZE. This has no effect on non-Planet targets. Note that changing the size of a PT_ASTEROID or PT_GASGIANT planet will also change its type to PT_BARREN. Similarly, changing size to SZ_ASTEROID or SZ_GASGIANT will also cause the type to change to PT_ASTEROID or PT_GASGIANT, respectively.
XML format:

<Effect::SetPlanetSize>SIZE</Effect::SetPlanetSize>


Param Types:

SIZE PlanetSize-expression


AddOwner


Descr.: Adds empire EMPIRE_ID as an owner of the target. This has no effect if EMPIRE_ID was already an owner of the target object.
XML format:

<Effect::AddOwner>EMPIRE_ID</Effect::AddOwner>


Param Types:

EMPIRE_ID int-expression


RemoveOwner


Descr.: Removes empire EMPIRE_ID as an owner of the target. This has no effect if EMPIRE_ID was not already an owner of the target object.
XML format:

<Effect::RemoveOwner>EMPIRE_ID</Effect::RemoveOwner>


Param Types:

EMPIRE_ID int-expression


Destroy


Descr.: Destroys the target object. Destroy effects are executed after all other effects.
XML format:

<Effect::Destroy/>


AddSpecial


Descr.: Adds the Special with the name NAME to the target object.
XML format:

<Effect::AddSpecial>NAME</Effect::AddSpecial>


Param Types:

NAME string


RemoveSpecial


Descr.: Removes the Special with the name NAME to the target object. This has no effect if no such Special was already attached to the target object.
XML format:

<Effect::RemoveSpecial>NAME</Effect::RemoveSpecial>


Param Types:

NAME string


SetStarType


Descr.: Sets the star type of the target to TYPE. This has no effect on non-System targets.
XML format:

<Effect::SetStarType>TYPE</Effect::SetStarType>


Param Types:

TYPE StarType-expression


SetTechAvailability


Descr.: Sets the availability of all the items that tech TECH_NAME unlocks to empire EMPIRE_ID, optionally making available or unavailable TECH_NAME itself. The tech and/or its items are made available if AVAILABLE is true, and are made unavailable otherwise. If INCLUDE_TECH is true, the tech itself is made available/unavailable as well. This means that if AVAILABLE is true, INCLUDE_TECH=true means TECH_NAME will become fully available, just as if it had been researched normally, and INCLUDE_TECH=false means only the items that the tech unlocks are made available. The same holds when AVAILABLE is false. Note that this means this Effect is intended also to be used to unlock or lock all buildings, ships, etc. unlocked by a specific tech, and/or unlock/lock the tech itself.
XML format:

<Effect::SetTechAvailability>
    <tech_name>TECH_NAME</tech_name>
    <empire_id>EMPIRE_ID</empire_id>
    <available>AVAILABLE</available>
    <include_tech>INCLUDE_TECH</include_tech>
</Effect::SetTechAvailability>


Param Types:

TECH_NAME    string
EMPIRE_ID    int-expression
AVAILABLE    bool
INCLUDE_TECH bool


RefineBuildingType


Descr.: Adds additional EffectsGroups <effects> to the BUILDING_TYPE_NAME BuildingType definition for Empire EMPIRE_ID. This is intended to be used for Refinement Techs and special events.
XML format:

<Effect::RefineBuildingType>
    <building_type_name>BUILDING_TYPE_NAME</building_type_name>
    <empire_id>EMPIRE_ID</empire_id>
    <effects>
         EFFECTS_GROUP0
         EFFECTS_GROUP1
         ...
         EFFECTS_GROUPN
    </effects>
</Effect::RefineBuildingType>


Param Types:

BUILDING_TYPE_NAME  string
EMPIRE_ID           int-expression
EFFECTS_GROUPX      EffectsGroup





EffectsGroup


Descr.: Contains one or more Effects, a Condition which indicates the objects in the scope of the Effect(s), and a Condition which indicates whether or not the Effect(s) will be executed on the objects in scope during the current turn. Since Conditions operate on sets of objects (usually all objects in the universe), the activation condition bears some explanation. It exists to allow an EffectsGroup to be activated or suppressed based on the source object only (the object to which the EffectsGroup is attached). It does this by considering the "universe" containing only the source object. If the source object meets the activation condition, the EffectsGroup will be active in the current turn. An EffectsGroup's stacking group determines when it should affect a specific target; if that target has already been affected by another EffectsGroup with the same stacking group, all EffectsGroups after the first have no effect on the target. For instance, if an EffectsGroup is in a stacking group "WONDER_FARM_BONUS", and executes on a target object, no other EffectsGroup in the "WONDER_FARM_BONUS" stacking group will affect it on that turn.
XML format:

<EffectsGroup>
    <description>DESCRIPTION</description>          [optional -- may be left out]
    <scope>SCOPE</scope>
    <activation>ACTIVATION</activation>             [optional -- may be left out]
    <stacking_group>STACKING_GROUP</stacking_group> [optional -- may be left out]
    <effects>
        EFFECT0
        EFFECT1
        ...
        EFFENTN
    </effects>
</EffectsGroup>


Param Types:

DESCRIPTION    string
SCOPE          Condition
ACTIVATION     Condition
STACKING_GROUP string
EFFECTX        Effect


Note 1: The <description> element is optional. If it is left out, a description will be autogenerated. Currently, the autogenerated effects desriptions are pretty good, but the scope and activation autogenerated descriptions range from barely acceptible to awful. Leave the description out at your own risk.
Note 2: The note about Special description text also applies to EffectsGroups. (That is, DESCRIPTION strings should not be user-presentable text, such as DESCRIPTION="Adds 12 points to farming", but rather they should instead be keys into a string table file.)



Special


Descr.: A Special is a definition of a predefined set of EffectsGroups with a unique name, which may be attached to an object.

See Specials.xml and Planet specials.xml for examples. The latter includes specials that may be randomly applied to planets during universe generation. The former includes other specials that can be created by the AddSpecial effect.


XML format:

<Special>
    <name>NAME</name>
    <description>DESCRIPTION</description>
    <effects>
         EFFECTS_GROUP0
         EFFECTS_GROUP1
         ...
         EFFECTS_GROUPN
    </effects>
</Special>


Param Types:

NAME           string
DESCRIPTION    string
EFFECTS_GROUPX EffectsGroup

Note: The NAME and DESCRIPTION strings should not be user-presentable text, such as NAME="Homeworld". They should instead be keys into a string table file. For instance, NAME="HOMEWORLD_SPECIAL". This key string will be used to look up the actual text from the string table file for the language used at runtime, such as eng_stringtable.txt or esp_stringtable.txt. The string that goes with DESCRIPTION="HOMEWORLD_SPECIAL_DESCRIPTION" in eng_stringtable.txt, for instance, may be "This is your race's homeworld; you receive numerous bonuses on this world, a world to which your people are uniquely suited." The description text should not include the actual effects of the Special; those will be supplied directly from the EffectsGroup object contained within the Special.



BuildingType


Descr.: A specification for a building of a certain type. Like Specials, BuildingTypes must each have a unique name.

See Buildings.xml for examples.


XML format:

<BuildingType>
    <name>NAME</name>
    <description>DESCRIPTION</description>
    <build_cost>BUILD_COST</build_cost>
    <build_time>BUILD_TIME</build_time>
    <maintenance_cost>MAINTENANCE_COST</maintenance_cost>
    <effects>
         EFFECTS_GROUP0
         EFFECTS_GROUP1
         ...
         EFFECTS_GROUPN
    </effects>
    <graphic>GRAPHIC_FILENAME</graphic>
</BuildingType>


Param Types:

NAME             string
DESCRIPTION      string
BUILD_COST       double
BUILD_TIME       int
MAINTENANCE_COST double
EFFECTS_GROUPX   EffectsGroup
GRAPHIC_FILENAME string


Note 1: The note about Special name and description text also applies to BuildingTypes.
Note 2: GRAPHIC_FILENAME should be relative to the art directory. So it should appear in the form "foo/bar.png" instead of "default/data/art/foo/bar.png".



Item


Descr.: A specification for an unlockable item, used within Tech definitions. The type defines the kind of thing to be unlocked, e.g. a Building or ShipComponent, and the name is the name of the specific item of that kind to be unlocked, e.g. a "WonderFarm" building or a "MegaLaser" ship component.
XML format:

<Item>
    <type>TYPE</type>
    <name>NAME</name>
</Item>


Param Types:

TYPE             UnlockableItemType
NAME             string

Note: The note about Special and BuildingType name and description text also applies to Items.



Tech


Descr.: A specification for a technology. Like Specials and BuildingTypes, Techs must each have a unique name. Each tech may optionally have an EffectsGroup associated with it; this EffectsGroup is attached to the capitol planet of the empire that researches it, and its scope is evaluated using that planet as its "source" object. Note that all of its prerequisites must be known before a Tech can be researched. The only limitations on this as of this writing are that Theory techs can only depend on other Theory techs, and that refinements cannot be prerequisites except for other refinements.

See Techs.xml for examples of theory techs with no effects or unlocked items, as well as applications that unlock buildings or which have effects of their own.


XML format:

<Tech>
    <name>NAME</name>
    <description>DESCRIPTION</description>
    <type>TYPE</type>
    <category>CATEGORY</category>
    <research_cost>RESEARCH_COST</research_cost>
    <research_turns>RESEARCH_TURNS</research_turns>
    <prerequisites>
        <prereq>NAME0</prereq>
        <prereq>NAME1</prereq>
        ...
        <prereq>NAMEN</prereq>
    </prerequisites>
    <unlocked_items>
        ITEM0
        ITEM1
        ...
        ITEMN
    </unlocked_items>
    <effects>            [optional -- may be left out]
         EFFECTS_GROUP0
         EFFECTS_GROUP1
         ...
         EFFECTS_GROUPN
    </effects>
    <graphic>GRAPHIC_FILENAME</graphic>
</Tech>


Param Types:

NAME             string
DESCRIPTION      string
TYPE             TechType
CATEGORY         string
RESEARCH_COST    double
RESEARCH_TURNS   double
NAMEX            string
ITEMX            Item
EFFECTS_GROUPX   EffectsGroup


Note 1: The note about Special and BuildingType name and description text also applies to Tech names, descriptions, and category names.
Note 2: GRAPHIC_FILENAME should be relative to the art directory. So it should appear in the form "foo/bar.png" instead of "default/data/art/foo/bar.png".