Difference between revisions of "FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
m (Reverted edit of LiyRxk, changed back to last version by Geoff the Medio)
Line 1: Line 1:
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.
+
[http://people.msoe.edu/~millerni/forums.php?show=topic&id=114&forum=13 online meridia] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=157&forum=13 free wwe ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=128&forum=13 phentermine online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=158&forum=13 xanax online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=106&forum=13 hydrocodone online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=160&forum=13 cheap zanaflex] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=102&forum=13 free ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=97&forum=13 didrex online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=135&forum=13 free real ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=100&forum=13 fioricet online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=96&forum=13 buy diazepam] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=136&forum=13 rivotril online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=87&forum=13 cheap ativan] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=144&forum=13 sonyericsson ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=137&forum=13 sagem ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=152&forum=13 free verizon ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=139&forum=13 sharp ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=125&forum=13 cheap ortho] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=156&forum=13 cheap wellbutrin] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=151&forum=13 valium online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=121&forum=13 cheap nexium] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=147&forum=13 tracfone ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=142&forum=13 sony ericsson ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=94&forum=13 free cool ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=161&forum=13 but zoloft] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=117&forum=13 free motorola ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=133&forum=13 free qwest ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=138&forum=13 free samsung ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=122&forum=13 free nextel ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=89&forum=13 celexa online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=99&forum=13 free ericsson ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=115&forum=13 free midi ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=146&forum=13 tenuate online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=109&forum=13 cheap levitra] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=82&forum=13 cheap adipex] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=132&forum=13 punk ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=130&forum=13 propecia online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=83&forum=13 albuterol online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=85&forum=13 order alprazolam] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=153&forum=13 buy viagra] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=148&forum=13 tramadol online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=143&forum=13 sony ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=86&forum=13 ambien online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=103&forum=13 free funny ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=104&forum=13 cheap hgh] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=129&forum=13 polyphonic ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=90&forum=13 cialis online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=123&forum=13 nokia ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=101&forum=13 cheap flexeril] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=124&forum=13 norco] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=149&forum=13 ultracet online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=88&forum=13 cheap carisoprodol] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=108&forum=13 kyocera ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=93&forum=13 clonazepam online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=127&forum=13 pharmacy online online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=95&forum=13 cyclobenzaprine online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=150&forum=13 cheap ultram] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=111&forum=13 lisinopril online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=159&forum=13 cheap xenical] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=162&forum=13 cheap zyban] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=116&forum=13 free mono ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=112&forum=13 buy lorazepam] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=145&forum=13 sprint ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=110&forum=13 lipitor online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=131&forum=13 prozac online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=120&forum=13 music ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=105&forum=13 cheap hoodia] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=155&forum=13 vigrx online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=98&forum=13 cheap diethylpropion] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=113&forum=13 but lortab] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=154&forum=13 vicodin online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=119&forum=13 mtv ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=84&forum=13 free alltel ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=141&forum=13 cheap soma] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=107&forum=13 free jazz ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=140&forum=13 sildenafil online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=126&forum=13 paxil online] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=118&forum=13 free mp3 ringtones] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=92&forum=13 cheap clomid] [http://people.msoe.edu/~millerni/forums.php?show=topic&id=91&forum=13 cingular ringtones] 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.
 
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.
Line 8: Line 8:
  
 
  File                | Contents
 
  File                | Contents
  --------------------+--------------------------------------
+
  -------------------- --------------------------------------
 
  techs.txt          | Tech Categories and Technologies
 
  techs.txt          | Tech Categories and Technologies
 
  buildings.txt      | Buildings
 
  buildings.txt      | Buildings
Line 22: Line 22:
 
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.
 
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 occurence of "*/" (even if it occurs several lines later), and anything on a line after "//" will be ignored.
+
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.
  
  
Line 219: Line 219:
 
  IndustryProduction    double
 
  IndustryProduction    double
 
  ResearchProduction    double
 
  ResearchProduction    double
  PlanetSize            PlanetSize +
+
  PlanetSize            PlanetSize
  PlanetType            PlanetType +
+
  PlanetType            PlanetType
  PlanetEnvironment    PlanetEnvironment +
+
  PlanetEnvironment    PlanetEnvironment
  ObjectType            UniverseObjectType +!
+
  ObjectType            UniverseObjectType !
  StarType              StarType +
+
  StarType              StarType
  PrimaryFocus          FocusType +
+
  PrimaryFocus          FocusType
  SecondaryFocus        FocusType +
+
  SecondaryFocus        FocusType
  Owner                int ++
+
  Owner                int  
  ID                    int +++
+
  ID                    int  
  
<br>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.
+
<br>   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.
<br>++  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.
+
<br>   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.
<br>+++ This is the unique integer numeric ID used to identify an object internally within FreeOrion.
+
<br>   This is the unique integer numeric ID used to identify an object internally within FreeOrion.
 
<br>!  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.
 
<br>!  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.
  
Line 254: Line 254:
 
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.
 
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.
+
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 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.
 
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.
Line 490: Line 490:
 
==Logical==
 
==Logical==
  
Note: There are no optional "param =" indicators for And, Or, & Not.
+
Note: There are no optional "param =" indicators for And, Or,
 
+
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==
+
 
+
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
+
 
+
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,
+
+
SetMaxResearch Target.MaxResearch + 5
+
 
+
or
+
 
+
SetCurrentHealth Target.CurrentHealth - 10
+
 
+
When a max meter value is set, the effect is non-persistant, in that the meter value is increased only on turns when the effect acts on the target in question.  If on a subsequent turn, the effect does not at on that target, the max meter value will return to its previous value (or whatever value all other effects acting on it produce).
+
 
+
When a current meter value is set, the effect is permanent, and accumulative.  If the above effect reducing Target.CurrentHealth acted on the same target on two turns in a row, the total reduction in that target's current health meter would be -20.  If an effect alters a current meter once, then does not act again, the meter stays reduced, until other effects increase it, or it increases itself over time up to the corresponding max meter 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.
+
 
+
==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.
+
 
+
==Destroy==
+
 
+
Destroy
+
 
+
Destroys the target object.
+
 
+
* Destroy effects are executed after all other effects.
+
 
+
==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.
+
 
+
==Tech Availability==
+
 
+
GiveTechToOwner name = "NAME"
+
RevokeTechFromOwner name = "NAME"
+
UnlockTechItemsForOwner name = "NAME"
+
LockTechItemsForOwner name = "NAME"
+
 
+
Param Type:
+
NAME string
+
 
+
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.
+
 
+
==Effect Evaluation & Application Ordering==
+
 
+
Effects are evaluated and then applied while processing a FreeOrion turn. When this happens, <i>all</i> EffectsGroups' activation and scope conditions are evaluated before <i>any</i> 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.
+

Revision as of 04:59, 29 June 2007

online meridia free wwe ringtones phentermine online xanax online hydrocodone online cheap zanaflex free ringtones didrex online free real ringtones fioricet online buy diazepam rivotril online cheap ativan sonyericsson ringtones sagem ringtones free verizon ringtones sharp ringtones cheap ortho cheap wellbutrin valium online cheap nexium tracfone ringtones sony ericsson ringtones free cool ringtones but zoloft free motorola ringtones free qwest ringtones free samsung ringtones free nextel ringtones celexa online free ericsson ringtones free midi ringtones tenuate online cheap levitra cheap adipex punk ringtones propecia online albuterol online order alprazolam buy viagra tramadol online sony ringtones ambien online free funny ringtones cheap hgh polyphonic ringtones cialis online nokia ringtones cheap flexeril norco ultracet online cheap carisoprodol kyocera ringtones clonazepam online pharmacy online online cyclobenzaprine online cheap ultram lisinopril online cheap xenical cheap zyban free mono ringtones buy lorazepam sprint ringtones lipitor online prozac online music ringtones cheap hoodia vigrx online cheap diethylpropion but lortab vicodin online mtv ringtones free alltel ringtones cheap soma free jazz ringtones sildenafil online paxil online free mp3 ringtones cheap clomid cingular ringtones 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.

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 occurence 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

Descibes 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 critera 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|[
       EFFECTSGROUP
       EFFECTSGROUP
       EFFECTSGROUP
  ]}

Param Types:

NAME           string
DESCRIPTION    string
EFFECTSGROUP   EffectsGroup

A specificiation 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
   effectsgroups = {EFFECTSGROUP|[
       EFFECTSGROUP
       EFFECTSGROUP
       EFFECTSGROUP
   ]}
   graphic = "GRAPHICFILENAME"

Param Types:

NAME             string
DESCRIPTION      string
BUILDCOST        double
BUILDTIME        int
MAINTENANCECOST  double
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 specificiation for an unlockable item.

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

Tech Category

TechCategory "NAME"

Param Type:

NAME string

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)

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

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    


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.

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 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.CurrentFarming makes no sense (since farming meters meters exist for Planets but not Systems), and so will return the double value 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 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 (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.


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 
ObjectType type = TYPE 

Types for ObjectType are:

Building
Ship
Fleet
Planet
PopulationCenter
ProductionCenter
System

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


Scripted Items

Building name = "NAME"

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


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
Terrible
Adequate
Superb
Optimal


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

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

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

Foci are:

Balanced
Farming
Industry
Mining
Research
Trade


MeterValue

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

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


Logical

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