Difference between revisions of "Conditions"

From FreeOrionWiki
Jump to: navigation, search
(Conditions)
Line 1: Line 1:
=Syntax=
+
==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.
 
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.
Line 29: Line 29:
 
  NumberOf number = NUMBER condition = CONDITION
 
  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.
 
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 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.
+
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.
  
  
Line 39: Line 45:
  
 
==Type==
 
==Type==
 
 
  Building
 
  Building
 
  Ship
 
  Ship
Line 51: Line 56:
  
 
==Building / Special==
 
==Building / Special==
 
 
  Building name = "NAME"
 
  Building name = "NAME"
 
  Building name = ["NAME1" "NAAME2" "NAME3"]
 
  Building name = ["NAME1" "NAAME2" "NAME3"]
Line 59: Line 63:
 
  HasSpecial name = "NAME"
 
  HasSpecial name = "NAME"
 
Matches objects that have the indicated special.
 
Matches objects that have the indicated special.
 +
  
 
  HasSpecialSinceTurn name = "NAME" low = LOW high = HIGH
 
  HasSpecialSinceTurn name = "NAME" low = LOW high = HIGH
Matches objecs
+
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==
 
==Containing Associations==
  
 
  Contains condition = CONDITION
 
  Contains condition = CONDITION
 
 
Matches objects that contain one or more objects that match the indicated CONDITION
 
Matches objects that contain one or more objects that match the indicated CONDITION
  
  
 
  ContainedBy condition = CONDITION
 
  ContainedBy condition = CONDITION
 
 
Matches objects that are contained by one or more objects that match the indicated CONDITION
 
Matches objects that are contained by one or more objects that match the indicated CONDITION
  
  
 
==Planet / Star==
 
==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).
  
Planet type = {TYPE|[TYPE0 TYPE1 TYPE2 ...]}
+
Types are: Swamp Toxic Inferno Radiated Barren Tundra Desert Terran Ocean Asteroids GasGiant
  
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 ...]}
 
  
 +
Planet size = SIZE
 +
Planet size = [SIZE1 SIZE2 SIZE3 ...]
 
Matches objects that are or are contained by planets that are the indicated size.
 
Matches objects that are or are contained by planets that are the indicated size.
  
Sizes are:
+
Sizes are: Tiny Small Medium Large Huge Asteroids GasGiant
Tiny
+
Small
+
Medium
+
Large
+
Huge
+
Asteroids
+
GasGiant
+
 
+
 
+
Planet environment = {ENV|[ENV0 ENV1 ENV2 ...]}
+
  
 +
Planet environment = ENV
 +
Planet environment = [ENV1 ENV2 ENV3 ...]
 
Matches objects that are or are contained by planets that have the indicated environment.
 
Matches objects that are or are contained by planets that have the indicated environment.
  
Environments are:
+
Environments are: Uninhabitable Hostile Poor Adequate Good
Uninhabitable
+
Hostile
+
Poor
+
Adequate
+
Good
+
 
+
  
HomeWorld
 
    name = {SPECIES|[SPECIES0 SPECIES1 ...]}    [optional -- may be left out]
 
  
 +
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.
 
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
 
SPECIES the name of a species in the game, as defined in species.txt
 
  
 
  Capitol
 
  Capitol
 
 
Matches planets that are capitols of an (any) empire.  Use in combination with OwnedBy for a specific empire's homeworld.
 
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 ...]}
 
  Star type = {TYPE|[TYPE0 TYPE1 TYPE2 ...]}
 
 
Matches objects that are or are contained by systems that have the indicated star type.
 
Matches objects that are or are contained by systems that have the indicated star type.
  

Revision as of 20:45, 11 November 2011

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" "NAAME2" "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 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 / Producer

OwnedBy affiliation = {EnemyOf|AllyOf|TheEmpire|AnyEmpire} [empire = EMPIRE]

Matches objects owned by (OwnedBy) an empire with the indicated affiliation to the indicated id EMPIRE. EMPIRE may be omitted with using AnyEmpire, which will match objects owned by any empire, regardless of what EMPIRE is specified (or not). 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).


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.