FOCS Scripting Details

From FreeOrionWiki
Revision as of 22:41, 19 July 2011 by Geoff the Medio (Talk | contribs) (List)

Jump to: navigation, search

This page describes the scripting language used to describe 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.

Conditions also have a few other uses, such as determining where buildings or ship parts or hulls can be produced, and where species focus settings can be used.

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)
ship_hulls.txt      | Ship Hulls
ship_parts.txt      | Ship Parts
species.txt         | Species

These files are structured as a list of descriptions of individual entries of their respective 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.

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". This might typically be done when unlocking a building with a tech, or adding or checking for the presence of a special to or on an object.

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 occurrence of "*/" (even if it occurs several lines later), and anything on a line after "//" will be ignored.

Scripting Format

EffectsGroup

EffectsGroup

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

Param Types:

DESCRIPTION    string
SCOPE          Condition
ACTIVATION     Condition
STACKINGGROUP  string
EFFECT         Effect

Describes the mechanism by which game content such as Techs, Buildings or Specials interacts with and alters the game state.

  • Consists primarily of:
    • One or more Effects
    • A Condition which indicates the objects in the scope of the Effect(s)
    • A Condition which indicates whether or not the Effect(s) will be executed on the objects in scope during the current turn.
  • The <description> element is optional. If it is left out, a description will be autogenerated. Presently, this works reasonably well for effects, but ranges from barely acceptable to awful for conditions. Leave the description out at your own risk.
  • DESCRIPTION strings should not be user-presentable text, such as DESCRIPTION="Adds 12 points to farming". Rather, they should instead be keys into a string table file.
  • Conditions start with a set of objects, and return subsets of this set according to whether the objects meet the criteria of the condition. For scope conditions, the entire game universe (or rather, all objects in it) are the initial set.
  • For activation conditions, the initial set is the source object of the effects group. This allows an EffectsGroup to be activated or suppressed based on the source object only (the object to which the EffectsGroup is attached). 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 that turn. 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.

Special

Special

  name = "NAME"
  description = "DESCRIPTION"
  effectsgroups = {EFFECTSGROUP|[     [optional -- may be left out]
       EFFECTSGROUP
       EFFECTSGROUP
       EFFECTSGROUP
  ]}

Param Types:

NAME           string
DESCRIPTION    string
EFFECTSGROUP   EffectsGroup

A specification for a Special, which is a definition of a predefined set of EffectsGroups with a unique name, which may be attached to an object in-game.

  • Specials used in the game are stored in specials.txt and planet_specials.txt.
    • specials.txt contains general specials that may be applied to objects using the AddSpecial effect.
    • planet_specials.txt contains specials that may be randomly applied to planets during universe generation.

BuildingType

BuildingType

   name = "NAME"
   description = "DESCRIPTION"
   buildcost = BUILDCOST
   buildtime = BUILDTIME
   maintenancecost = MAINTENANCECOST
   location = CONDITION
   effectsgroups = {EFFECTSGROUP|[    [optional -- may be left out]
       EFFECTSGROUP
       EFFECTSGROUP
       EFFECTSGROUP
   ]}
   graphic = "GRAPHICFILENAME"

Param Types:

NAME             string
DESCRIPTION      string
BUILDCOST        double
BUILDTIME        int
MAINTENANCECOST  double
LOCATION         Condition
EFFECTSGROUP     EffectsGroup
GRAPHICFILENAME  string

A specification for a building of a certain type.

  • BuildingTypes must each have a unique name.
  • BuildingTypes used in the game are stored in buildings.txt.
  • The note about Special name and description text also applies to BuildingTypes.
  • GRAPHICFILENAME 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

Item type = TYPE name = "NAME"

Param Types:

TYPE             UnlockableItemType
NAME             string

A specification for an unlockable item.

  • Item definitions appear within Tech definitions.
  • type defines the kind of thing to be unlocked, e.g. a Building, ShipHull, ShipPart, or Tech.
  • name is the name of the specific item of that kind to be unlocked, e.g. a "WonderFarm" building or a "MegaLaser" ship part.
  • The note about Special and BuildingType name and description text also applies to Items.

Tech Category

TechCategory name = "NAME" graphic = "GRAPHIC" colour = COLOUR

Param Type:

NAME string
GRAPHIC string
COLOUR colour

Specifies a technology category.

  • Techs are displayed by category in the UI
  • A category must be defined in techs.txt before a tech in that category may be defined (later in the same file)

Colour

(RED, GREEN, BLUE, ALPHA)

Param Type:

RED    int
GREEN  int
BLUE   int
ALPHA  int

Specifies a colour.

  • Brackets must surround the colour component numbers, which must also be separated by commas.
  • Colour components are specified in the range [0, 255]
  • Example: in a TechCategory definition, one might write:
colour = (116, 225, 107, 255)

FocusType

FocusType
    name = NAME
    description = DESCRIPTION
    location = CONDITION
    graphic = GRAPHICFILENAME

Specifies a focus setting for a planet.

  • Within each species, each FocusType must have a unique name. Two different species may have (the same or different) FocusTypes with the same name, however.
  • The location condition determines which planets on which the FocusType can be used.
  • The graphic determines the icon used to represent the FocusType in the UI.

Tech

Tech
   name = "NAME"
   description = "DESCRIPTION"
   short_description = "SHORT_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"

Param Types:

NAME               string
DESCRIPTION        string
SHORT_DESCRIPTION  string
TYPE               TechType
CATEGORY           string
RESEARCHCOST       double
RESEARCHTURNS      double
NAME               string
ITEM               Item
EFFECTSGROUP       EffectsGroup

A specification for a technology.

  • Techs must each have a unique name.
  • Each tech may optionally have one or more EffectsGroups associated with it.
    • Tech EffectsGroups are use as their source object the capitol planet of the empire that researches the tech.
  • All of a tech's prerequisites must be known before a Tech can be researched.
    • Theory techs can only depend on other Theory techs
    • Refinements cannot be prerequisites except for other refinements.
  • The note about Special and BuildingType name and description text also applies to Tech names, descriptions, and category names.
  • GRAPHICFILENAME 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".
  • Techs used in the game are stored in techs.txt. That file includes examples of theory techs with no effects or unlocked items, as well as applications that unlock buildings or which have effects of their own.

Ship Hull

Hull
   name = "NAME"
   description = "DESCRIPTION"
   speed = BATTLESPEED
   starlaneSpeed = STARLANESPEED
   fuel = FUEL
   stealth = STEALTH
   health = HEALTH
   buildCost = BUILDCOST
   buildTime = BUILDTIME
   location = CONDITION
   effectsgroups = {EFFECTSGROUP|[ [optional -- may be left out]
        EFFECTSGROUP
        EFFECTSGROUP
        EFFECTSGROUP
   ]}
   graphic = "GRAPHICFILENAME"

Param Types:

NAME               string
DESCRIPTION        string
BATTLESPEED        double
STARLANESPEED      double
FUEL               double
STEALTH            double
HEALTH             double
BUILDCOST          double
BUILDTIME          int
CONDITION          Condition
EFFECTSGROUP       EffectsGroup
GRAPHICFILENAME    string

A specification for a ship hull.

  • Hulls must each have a unique name.
  • Each hull may optionally have one or more EffectsGroups associated with it.
    • Hull EffectsGroups are use as their source object the ship in which the hull is located.
  • The note about Special and BuildingType name and description text also applies to Hull names and descriptions.
  • GRAPHICFILENAME 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".
  • Hulls used in the game are stored in ship_hulls.txt.

Ship Part

Part
   name = "NAME"
   description = "DESCRIPTION"
   class = CLASS
   {STATS  --  format depends on CLASS}
   buildCost = BUILDCOST
   buildTime = BUILDTIME
   mountableSlotTypes = {SLOTTYPE|[
        SLOTTYPE
        SLOTTYPE
        SLOTTYPE
   ]}
   location = CONDITION
   effectsgroups = {EFFECTSGROUP|[ [optional -- may be left out]
        EFFECTSGROUP
        EFFECTSGROUP
        EFFECTSGROUP
   ]}
   graphic = "GRAPHICFILENAME"

Param Types:

NAME               string
DESCRIPTION        string
CLASS              PartClass
SLOTTYPE           SlotType
CONDITION          Condition
EFFECTSGROUP       EffectsGroup
GRAPHICFILENAME    string

STATS is a series of parameters that depends on the CLASS of the part.


A specification for a ship part.

  • Parts must each have a unique name.
  • Each part may optionally have one or more EffectsGroups associated with it.
    • Part EffectsGroups are use as their source object the ship in which the part is located.
  • The note about Special and BuildingType name and description text also applies to Part names and descriptions.
  • GRAPHICFILENAME 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".
  • Hulls used in the game are stored in ship_parts.txt.

Species

Species
   name = "NAME"
   description = "DESCRIPTION"
   foci = {FOCUSTYPE|[             [optional -- may be left out]
       FOCUSTYPE
       FOCUSTYPE
       FOCUSTYPE
   ]}
   effectsgroups = {EFFECTSGROUP|[ [optional -- may be left out]
        EFFECTSGROUP
        EFFECTSGROUP
        EFFECTSGROUP
   ]}
   environments = {PLANETTYPEENVIRONMENT [optional -- may be left out]
       PLANETTYPEENVIRONMENT
       PLANETTYPEENVIRONMENT
       PLANETTYPEENVIRONMENT
   ]}
   graphic = "GRAPHICFILENAME"

Param Types:

NAME                   string
DESCRIPTION            string
FOCUSTYPE              FocusType
EFFECTSGROUP           EffectsGroup
PLANETTYPEENVIRONMENT  (see below)
GRAPHICFILENAME        string
  • Species must have a unique name.
  • PLANETTYPEENVIRONMENT has format:
type = PLANETTYPE environment = ENVIRONMENT

with param types:

PLANETTYPE         PlanetType
ENVIRONMENT        PlanetEnvironment

Types and Expressions

In the Conditions and Effects below, there are parameters that specify details about how the condition or effect functions. These parameters can be specified as a constant number (eg. 5) or value (Blue), or can be variables that depend on the gamestate. Variables may refer to the Source or Target objects (see below), a few independent values such as the number of the current game turn, or may refer to statistics about the gamestate that are calculated from multiple objects.

The Source object is the object to which the Effect is attached. For example, a building might have an effect that increases a planet's farming meter. When defining that building's effects, the building itself would be the Source object.

The Target object is the object that an Effect is modifying. In an effect that modifies at planet's farming meter, the planet would be the Target object.

Free Variables

There is currently just one variable that may be used without referring directly to the Target or Source objects. It is, and its type is:

CurrentTurn           int

CurrentTurn variable returns the current game turn.

Object Attributes

Object attributes are variables that are properties of the Source or Target objects.

List

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

Farming               double
TargetFarming         double
Industry              double
TargetIndustry        double
Research              double
TargetResearch        double
Trade                 double
TargetTrade           double
Mining                double
TargetMining          double
Construction          double
TargetConstruction    double
Health                double
TargetHealth          double
Population            double
TargetPopulation      double
MaxFuel               double
Fuel                  double
Supply                double
Stealth               double
Detection             double
Maxshield             double
Shield                double
MaxDefense            double
Defense               double
FoodConsumption       double
Tradestockpile        double
Mineralstockpile      double
Foodstockpile         double
DistanceToSource      double
PlanetSize            PlanetSize +
PlanetType            PlanetType +
PlanetEnvironment     PlanetEnvironment +
ObjectType            UniverseObjectType +!
StarType              StarType +
Focus                 string
Species               string
BuildingType          string
Owner                 int ++
ID                    int +++
CreationTurn          int
Age                   int
ProducedByEmpireId    int
DesignID              int
FleetID               int
PlanetID              int
SystemID              int
FinalDestinationID    int
NextSystemID          int
PreviousSystemID      int
NumShips              int


+ The valid values for these types are listed after the corresponding conditions below. These values may change however, so for the most up-to-date list, it may be necessary to consult the FreeOrion source code.
++ 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.

Value

As a special case, there is a utility variable available that is used like a free variable, but actually refers to the target object:

Value                 double, int, string, PlanetSize, PlanetType, StarType

The type returned by "Value" depend on the type of effect in which it is used. For meter-setting effects, or when setting an empire stockpile, Value will be a double. For SetPlanetSize, it will be a PlanetSize, and similarly for lanetType, PlanetEnvironment, StarType. For setting a planet's species, Value will be a string.

The value of "Value" is the initial value of whatever is being set. For example, in a SetStealth effect, "Value" would return the same as "Target.Stealth". For SetPlanetType, "Value" would return the same as "Target.PlanetType".

Statistics

Statistics are values calculated from a sampling of objects in the game universe, which may or may not include the Source and Target objects.

List

The available statistical calculations that can be performed on the property values of objects matching the sampling condition are:

Number
Sum
Mean
RMS
Mode
Max
Min
Spread
STDEV
Product

Mode may be used for any type of parameter, including enumerated types like PlanetSize and double or int or string. The other statistic types may be used only for parameters that are int or double.

Use

Constants

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.

Variables

Parameter values 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.

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

Parameter values may also be defined in terms of independent variables that are not associated with a particular object. In this case, the variable name is used without any object reference; for example, "CurrentTurn" returns the current game turn.

Parameter values for meter-altering effects may also refer to "Value" which is equivalent to referring to the meter of the target object that is being altered, depending which meter-setting effect is being used.

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 star 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 a special value representing an invalid value for enumerated type values. The special invalid value is guaranteed not to match the value of any actual object.

For example, if the source object is a System, Source.System.StarType will always return an invalid Star Type.

Similarly, Target.System.Farming makes no sense (since farming meters meters exist for Planets but not Systems), and so will return the double value 0.0.

Statistics

Parameter values may also be defined in terms of statistics calculated from the gamestate. A statistic returns a value based on the specified property, calculation and a condition to select objects in the game Universe.

In any place where a constant or variable could be specified, a statistic may be used instead. The format for a statistic calculation is:

StatisticType property = PropertyName condition = SamplingCondition

The "property =" and "condition =" may be omitted:

StatisticType PropertyName SamplingCondition

For example, to calculate the sum of all planets' populations,

Sum Population Planet

The result would return a double value, which will be used just as if a constant like 42.4 had been specified, or a variable like Target.Population had been specified.

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 enumerated types, with specific values. Each such value has a string associated with it, for instance the first valid StarType is 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 arbitrarily 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.Industry + 20", and Effect B sets the current industry meter to "Target.Industry * 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.Industry + 3" and "Target.Industry * 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 parameters that do not explicitly allow type-expressions cannot handle them.

Conditions

The syntax {a|b|c} below indicates 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 (except for with the And, Not and Or conditions, which do not have or allow such parameter names).

General

All

Matches all objects.


Source

Matches the Source object.


Target

Matches the target object of an effect. This can be used within effect definitions, but not within scope or activation condition definitions, as when those conditions are evaluated, the target object hasn't yet been determined.


Turn low = LOW high = HIGH

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


NumberOf number = NUMBER condition = CONDITION

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.


Number low = LOW high = HIGH condition = CONDITION

Matches all objects if the number of objects that match CONDITION is greater than or equal to LOW and less than HIGH. Objects matched may or may not themselves match CONDITION.


Random probability = PROB

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

Type

Building
Ship
Fleet
Planet
PopulationCenter
ProductionCenter
System 

Matches objects with the indicated type.

Scripted Items

Building name = {"NAME" | ["NAME0" "NAME1" "NAME2" ...]}

Matches buildings with the indicated name(s). NAME is as indicated in a particular building description, by: name = "NAME" or name = ["NAME0" "NAME1" "NAME2"] (etc.)


HasSpecial name = "NAME"

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

Containing Associations

Contains condition = CONDITION

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


ContainedBy condition = CONDITION

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


Planet / Star

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

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

Types are:

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


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

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

Sizes are:

Tiny
Small
Medium
Large
Huge
Asteroids
GasGiant


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

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

Environments are:

Uninhabitable
Hostile
Poor
Adequate
Good


HomeWorld
    name = {SPECIES|[SPECIES0 SPECIES1 ...]}     [optional -- may be left out]

Matches planets that are homeworlds. If no species are specified, the homeworld of any species will be matched.

SPECIES the name of a species in the game, as defined in species.txt


Capitol

Matches planets that are capitols of an (any) empire. Use in combination with OwnedBy for a specific empire's homeworld.


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

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

Types are:

Blue
White
Yellow
Orange
Red
Neutron
BlackHole

Infrastructure / Focus

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

Matches planets that have the indicated focus or any of the indicated foci.

FOCUS or FOCUS# are strings. Each species may have a different set of foci available, but typical focus options include "FOCUS_FARMING", "FOCUS_MINING", "FOCUS_INDUSTRY", "FOCUS_RESEARCH" and "FOCUS_TRADE"

MeterValue

TargetPopulation low = LOW high = HIGH
TargetHealth low = LOW high = HIGH
TargetFarming low = LOW high = HIGH
TargetIndustry low = LOW high = HIGH
TargetResearch low = LOW high = HIGH
TargetTrade low = LOW high = HIGH
TargetMining low = LOW high = HIGH
TargetConstruction low = LOW high = HIGH
MaxFuel low = LOW high = HIGH
MaxShield low = LOW high = HIGH
MaxStructure low = LOW high = HIGH
MaxDefense low = LOW high = HIGH
Population low = LOW high = HIGH
Health low = LOW high = HIGH
Farming low = LOW high = HIGH
Industry low = LOW high = HIGH
Research low = LOW high = HIGH
Trade low = LOW high = HIGH
Mining low = LOW high = HIGH
Construction low = LOW high = HIGH
Fuel low = LOW high = HIGH
Shield low = LOW high = HIGH
Structure low = LOW high = HIGH
Defense low = LOW high = HIGH
FoodConsumption low = LOW high = HIGH
Supply low = LOW high = HIGH
Stealth low = LOW high = HIGH
Detection low = LOW high = HIGH
Battlespeed low = LOW high = HIGH
Starlanespeed low = LOW high = HIGH

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

Object Owner

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

Matches objects owned by (OwnedBy) or owned only by (OwnedExclusivelyBy) an empire with the indicated affiliation to the indicated id EMPIRE. Typically EMPIRE is specified as a function of an object, such as Source.Owner, however a constant integer such as 2 may also be specified.


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

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.


OwnerHasTech name = "NAME"

Matches objects with exactly one owner, whose owner has the tech NAME.

Note: This is useful for refinements of technologies, where a refinement tech is indicated by NAME in an effects group of the item being refined.


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

Matches objects that are visible to the indicated empire(s).

Galaxy Map Position

WithinDistance distance = DISTANCE condition = CONDITION

Matches objects that are within the indicated Euclidean direct-line DISTANCE of any objects that matches CONDITION. The matched objects may or may not themselves match CONDITION.


WithinStarlaneJumps jumps = JUMPS condition = CONDITION

Matches objects that are within the indicated number of starlane jumps (crossings from one star to the next) of any objects that matches CONDITION. The matched objects may or may not themselves match CONDITION.


Stationary

Matches objects that are not moving. The only objects that move are fleets and ships. Objects are not stationary if they are going to move, so fleets ordered to move are not stationary, but fleets that arrive in a system are stationary on the turn after they arrive.

FleetSupplyableByEmpire empire = EMPIRE

Matched objects should be in systems where the empire with id EMPIRE can provide fleet supply.

ResourceSupplyConnectedByEmpire empire = EMPIRE condition = CONDITION

Matched objects should be in systems connected by resource sharing lines for the empire with id EMPIRE to at least one object that matches the sub-condition CONDITION. Objects outside systems shouldn't be matched, regardless of whether they're on a starlane that is connected to an object that matched the sub-condition.

Logical

Note: There are no optional "param =" indicators for And, Or, & Not.

And [CONDITION0 CONDITION1 CONDITION2 ...]
And [
 CONDITION0
 CONDITION1
 CONDITION2
]

Matches objects that match all of the indicated subconditions.


Or [CONDITION0 CONDITION1 CONDITION2 ...]
Or [
 CONDITION0
 CONDITION1
 CONDITION2
]

Matches objects that match at least one, or more, of the indicated subconditions.


Not CONDITION

Matches objects that do not match CONDITION.

Notes

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

And [
  Star type = Blue
  System
]

If you want all Ships in Systems with blue stars, you should use:

And [ Ship Star type = Blue ]

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 list of subconditions.

For instance, if "Star type = Blue" matches about 1000 objects,

And [ Source Star type = Blue ]

will be about 1000 times faster than

And [ Star type = Blue Source ]

This is because the former only has to look at the match from Source to see if it also is (or is inside of) a blue-starred System, whereas that latter has to look through the 1000 matches of objects that are or are in blue-starred systems, to see if any of them also matches Source.

Effects

SetMeter

Acting on ships:

SetTargetPopulation value = VALUE
SetTargetHealth value = VALUE
SetTargetFarming value = VALUE
SetTargetIndustry value = VALUE
SetTargetResearch value = VALUE
SetTargetTrade value = VALUE
SetTargetMining value = VALUE
SetTargetConstruction value = VALUE
SetMaxFuel value = VALUE
SetMaxShield value = VALUE
SetMaxStructure value = VALUE
SetMaxDefense value = VALUE
SetPopulation value = VALUE
SetHealth value = VALUE
SetFarming value = VALUE
SetIndustry value = VALUE
SetResearch value = VALUE
SetTrade value = VALUE
SetMining value = VALUE
SetConstruction value = VALUE
SetFuel value = VALUE
SetShield value = VALUE
SetStructure value = VALUE
SetDefense value = VALUE
SetFoodConsumption value = VALUE
SetSupply value = VALUE
SetStealth value = VALUE
SetDetection value = VALUE
SetBattleSpeed value = VALUE
SetStarlaneSpeed value = VALUE

Param Type:

VALUE double

Sets the appropriate meter to VALUE.

  • If the target of the Effect does not have the requested meter, nothing is done.
  • Typically, meter-setting effects do so by adding or subtracting form the same meter value of the Target. For example,
SetTargetResearch Target.TargetResearch + 5

or

SetHealth Value - 10

The value "Value" always refers to the present value of the meter being set, allowing incremental changes to meter values without the cumbersome use of references to the Target such as "Target.FoodConsumption" (for the Target's food consumption meter) which would instead be just "Value" when using the SetFoodConsumption effect.

When a "max" (eg. MaxStructure) or "target" (eg. TargetPopulation) meter value, or another meter for which there is no associated "max" or "target" meter (eg. Stealth), the change is non-presistant. This means that every turn, the meter is reset to 0, and all effects must re-act on the meter for it to retain a consistent value. If on a subsequent turn, the effect does not at on that target, the meter value will return to its previous value (or whatever value all other effects acting on it produce).

When a meter (eg. Structure) has an associated "max" or "target" meter (eg. MaxStructure), the meter value IS persistant. Repeatedly applying the same effect every turn will accumulate. If an effect reduced an object's Health meter by -2 every turn, the 2nd turn would have a net -4 reduction, the 3rd turn would have a net -6 reduction, etc. If an effect alters such a meter once, then does not act again, the meter stays reduced, until other effects increase or decrease it, or it increases or decreases itself over time towards its associated target or max value.


SetEmpireStockpile

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

Param Type:

VALUE double

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.

SetOwnerCapitol

SetOwnerCapitol

Sets the target object to be the capitol of its owner's empire. If the target is not a planet, or is not owned by a single empire, nothing is done.

SetPlanetType

SetPlanetType type = TYPE

Param Type:

TYPE PlanetType

Sets the planet type of the target to TYPE.

  • Has no effect on non-Planet targets.
  • Changing type from Asteroids or GasGiant to something else will also change its size to Tiny or Huge, respectively.
  • Changing type to Asteroids or GasGiant will also cause the size to change to Asteroids or GasGiant, respectively.

SetPlanetSize

SetPlanetSize size = SIZE

Param Type:

SIZE PlanetSize

Sets the planet size of the target to SIZE.

  • Has no effect on non-Planet targets.
  • Changing the size of a Asteroids or GasGiant planet will also change its type to Barren.
  • Changing size to Asteroids or GasGiant will also cause the type to change to Asteroids or GasGiant, respectively.

AddOwner

AddOwner empire = EMPIRE

Param Type:

EMPIRE int

Adds empire EMPIRE_ID as an owner of the target.

  • Has no effect if EMPIRE_ID was already an owner of the target object.

RemoveOwner

RemoveOwner empire = EMPIRE

Param Type:

EMPIRE int

Removes empire EMPIRE_ID as an owner of the target.

  • Has no effect if EMPIRE_ID was not already an owner of the target object.

CreatePlanet

CreatePlanet type = TYPE size = SIZE

Param Types:

TYPE PlanetType
SIZE PlanetSize

Creates a new planet at the location of the target object. If the target object is not located in a system, nothing is done. If there are no free orbit slots at the target object's system, nothing is done.

CreateBuilding

CreateBuilding name = NAME

Param Types:

NAME string

Creates a new building at the location indicated by the target object. If the target object is not a planet, nothing is done.

CreateShip

CreateShip
    designname = "NAME"
    empire = EMPIREID

ParamTypes

NAME string
EMPIREID int

Creates a new shipat the location of the target object. The design of the new ship is indicated by the NAME parameter, which looks up the design in premade_ship_designs.txt in the default folder. EMPIREID is the id of the empire who should own the newly created ship, which is probably the id of something related to the source or target objects.

Destroy

Destroy

Destroys the target object.

  • The Destroy effect will not destroy a System object, although any other objects in or outside a system can be destroyed.
  • Destroy effects are executed after all other effects.
  • Destroying a fleet will destroy its ships.
  • Destroying all the ships in a fleet will destroy the fleet.
  • Destroying a planet will destroy its buildings.

AddSpecial

AddSpecial name = "NAME"

Param Type:

NAME string

Adds the Special with the name NAME to the target object.

RemoveSpecial

RemoveSpecial name = "NAME"

Param Type:

NAME string

Removes the Special with the name NAME to the target object.

  • Has no effect if no such Special was already attached to the target object.

SetStarType

SetStarType type = TYPE

Param Type:

TYPE StarType

Sets the star type of the target to TYPE.

  • Has no effect on non-System targets.

MoveTo

MoveTo location = CONDITION

Param Type:

LOCATION Condition

Moves the target object to the location of one of the objects matched by LOCATION

  • If no objects match the location condition, nothing is done.
  • If more than one object matches the location condition, one object is chosen by the condition
  • If the target object is a ship and the location object is a fleet or a ship (in a fleet) owned by the same empire, the ship is inserted into the fleet.
  • If the target object is a ship and the location is not a fleet into which the ship can be inserted, a new fleet is created for the ship a the new location.
  • If the target object is a ship and its location is the same system but not a different fleet, nothing is done and the ship is left in its original fleet.
  • If the target object is a fleet and its location is a fleet or ship outside a system, and a fleet is moved to or created at the target location, the fleet will be moving to the same system as the taget object fleet.
  • If the target object is a building and the location object is a planet or a building on a planet, the building is added to the planet.
  • If the target object is a building and the location is not a planet or on a planet, nothing is done.
  • If the target object is a planet and the location object is not a system or in a system, nothing is done.
  • If the target object is a planet and the location system has no empty orbit slots, nothing is done.
  • If the target object is a system, nothing is done.
  • Any target object moved to the location of a system will be inserted into that system.

Tech Availability

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

Param Type:

NAME string

GiveTechToOwner and RevokeTechFromOwner makes the owner of the target object instantly research or unresearch the tech with the given name. A granted tech acts just as though it had been researched normally, and if a tech is revoked, the empire functions as if that tech had not been researched. Techs that have revoked techs as direct prerequisites cannot be researched, but already-researched techs whose prerequisites are revoked continue to be researched and function normally. Effects and unlocked items of revoked techs do not function and are re-locked, respectively.

UnlockTechItemsForOwner and LockTechItemsForOwner unlock and lock the unlocked items of a tech. This should function regardless of whether the tech in question has been researched. If more than one tech unlocks the same item, the most recent locking or unlocking overrides all previous unlockings or lockings.

Victory

Victory reason = "REASON"

Param Type

REASON string

Victory causes the owner of the target object to win the game. Losing human players (which is any player who has not won on the turn a player wins) are ejected from the game. The string REASON is displayed in a popup to all players, with the name of the winning empire inserted as the %1% parameter to the string.

AddStarlanes and RemoveStarlanes

AddStarlanes endpoint = CONDITION
RemoveStarlanes endpoint = CONDITION

Param Type

CONDITION condition

AddStarlanes adds starlanes between the target system and any system containing an object that matches CONDITION. RemoveStarlanes removes starlanes between the target system and any system containing an object that matches CONDITIONS. Adding a starlanes where one already exists, or removing a starlane wher none exists does nothing.

MoveTo

MoveTo destination = CONDITION

Param Type

CONDITION condition

MoveTo moves the target object to the location of the / one of the objects matched by the CONDITION parameter.

SetSpecies

SetSpecies name = "NAME"

Param Type

NAME string

SetSpecies sets the species of the target ship or planet to the indicated species 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, then effects from Ship Hulls, then effects from Ship Parts. The order of execution of Effects within these groups is deterministic, though not controllable.