Conditions

From FreeOrionWiki
Jump to: navigation, search

Syntax

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 b c ...] indicates that multiple items in a list should be specified. At least two items should be listed; if only one item is needed, omit the enclosing [ ] brackets.

"low = ", "high = ", "number = ", etc., indicate an *optional* parameter name. All condition 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
Turn low = LOW
Turn high = HIGH

Matches objects if the current game turn is greater than or equal to LOW and less than or equal to HIGH. If LOW is omitted, the current game turn may be anything equal or less than HIGH. If HIGH is omitted, the current game turn may be anything equal or greater than LOW.


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.

MaximumNumberOf number = NUMBER sortkey = SORTKEY condition = CONDITION
MinimumNumberOf number = NUMBER sortkey = SORTKEY condition = CONDITION
ModeNumberOf number = NUMBER sortkey = SORTKEY condition = CONDITION

Matches up to NUMBER objects that match CONDITION. If more than NUMBER objects match CONDITION, the objects are ordered according to whether Maxmimum, Minimum, or Mode is specified, and the result of evaluating SORTKEY with each object treated as the local candidate. For example, MaximumNumberOf number = 2 sortkey = LocalCandidate.Farming condition = Planet will match the two planets with the highest farming meter in the universe.


Number low = LOW high = HIGH condition = CONDITION
Number high = HIGH condition = CONDITION
Number low = LOW 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. If LOW is omitted, objects are matched as long as at most HIGH objects match CONDITION. if HIGH is omitted, objects are matched as long as at least LOW objects 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 
Monster

Matches objects with the indicated type.


Building / Special

Building name = "NAME"
Building name = ["NAME1" "NAME2" "NAME3"]

Matches buildings with the indicated name(s).


HasSpecial name = "NAME"

Matches objects that have the indicated special.


HasSpecialSinceTurn name = "NAME" low = LOW high = HIGH
HasSpecialSinceTurn name = "NAME" high = HIGH
HasSpecialSinceTurn name = "NAME" low = LOW

Matches objects that had the indicated special added on a turn greater than or equal to LOW and less than or equal to HIGH. If LOW or HIGH are omitted, only the other range limit is applied.


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
Planet type = [TYPE1 TYPE2 TYPE3 ...]

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

Types are: Swamp Toxic Inferno Radiated Barren Tundra Desert Terran Ocean Asteroids GasGiant


Planet size = SIZE
Planet size = [SIZE1 SIZE2 SIZE3 ...]

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
Planet environment = [ENV1 ENV2 ENV3 ...]

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

Environments are: Uninhabitable Hostile Poor Adequate Good


Homeworld name = SPECIES
Homeworld name = [SPECIES1 SPECIES2 SPECIES3 ...]

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

SPECIES names are as defined in species.txt


Species
Species name = SPECIES
Species name = [SPECIES1 SPECIES2 SPECIES3 ...]

Matches planets that are populated by the indicated species.

SPECIES names are 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
Star type = [TYPE1 TYPE2 TYPE3 ...]

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
Focus focus = [FOCUS1 FOCUS2 FOCUS3 ...]

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

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

MeterName low = LOW high = HIGH
MeterName low = LOW
MeterName high = HIGH
MeterName

Matches objects that have the indicated MeterName with value equal or greater than LOW and equal or less than HIGH. If either LOW or HIGH are omitted, only the other range limit is checked. If both are omitted, any object with the indicated meter is matched.

Meters are: TargetConstruction TargetFarming TargetHealth TargetIndustry TargetMining TargetPopulation TargetResearch TargetTrade MaxDefense MaxFuel MaxShield MaxStructure MaxTroops Construction Farming Health Industry Mining Population Research Trade Defense Fuel Shield Structure Troops FoodConsumption Supply Stealth Detection BattleSpeed StarlaneSpeed

Object Owner / Producer

OwnedBy affiliation = AnyEmpire
OwnedBy affiliation = EnemyOf empire = EMPIRE
OwnedBy affiliation = AllyOf empire = EMPIRE
OwnedBy affiliation = TheEmpire empire = EMPIRE

Matches objects owned by 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
VisibleToEmpire empire = [EMPIRE1 EMPIRE2 EMPIRE3 ...]

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


ProducedByEmpire empire = EMPIRE

Matches buildings or ships produced by the empire with id indicated by 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. Note that ownership and who produced an object aren't necessary the same, particularly for buildings, which may be captured with planets from other empires.

Ship Design

Design name = "NAME"

Matches ships that have a design generated from the predefined designs in predefined_ship_designs.txt or space_monsters.txt

Design design = DESIGNID

Matches ships that have the specified ship design ID. Most likely this would be Source.DesignID

DesignHasHull name = "NAME"

Matches ships that have the indicated hull in their design.

DesignHasPart low = LOW high = HIGH name = "NAME"

Matches ships that have >= LOW and < HIGH of the part NAME in their design.

DesignHasPartClass low = LOW high = HIGH class = CLASS

Matches ships that have >= LOW and < HIGH of parts of the indicated PartClass in their design.

Armed

Matches ships that have weapons.

Monster

Matches space monsters.

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.