Difference between revisions of "Conditions"

From FreeOrionWiki
Jump to: navigation, search
(copied conditions info from Effects)
(No difference)

Revision as of 19:54, 11 November 2011

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.

Building / Special

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 have the indicated special.

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