Difference between revisions of "FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
(reverted to drek's version. thought I had been editing the talk page. oops.)
Line 1: Line 1:
−
=Introduction=
+
=Unofficial=
 +
Contents of this document have not passed public review.  Comments are welcome on the talk page, but please do not modify this document.--drek
  
−
"Effects" are changes/modifications to game objects. 
+
=Effects=
  
−
"Game Objects" include the player-visible parts of the game simulation, such as empires, systems, planets, buildings, ships and specials.  Game objects may also be invisible to the player, and be used internally by the game to simulate / maintain the gamestate. Game objects also each contain a group / list of effects.  A particular game object's effects determine many of the ways it iteracts with the other game objects.  For example, a building might have an effect which alters a meter of a planet, or a special attached to a system might make all ships in the system have nonfunctional shields.  A player-visible game object may contain no effects, and a player-invisible game object may contain effects, allowing for flexible in-game grouping of effects that work together by creation of the appropriate game object.
+
Buildings, technologies, racial picks, planet specials, events, government picks, and leaders are all “Actors”.  Actors operate on the game world through Effects. A single Actor can have any number of Effects.
  
−
=Game Objects & Effects=
+
Most effects have:
  
−
Game objects are of a particular class.  The class description of a game object is contained within an XML file.  This description indicates all the effects the game object contains, all information about how the effects function, a category into which the game object falls (to enable to the game to deal with the object internally, other than through effects), how the object is represented to the player (if it is visible) and any other necessary information about the object.
+
*a Target: the epicenter of an Effect’s scope.  This includes information for each object containing the target: a planet Effect would also target the planet’s system and the empire that owns the planet.
 +
*a Scope, defining how far the Effect reaches
 +
*Conditions, which exclude objects within Scope
 +
*Values that determine the modifications produced by the Effect on objects within Scope that have met all Conditions
  
−
Game Object Descriptions include:
+
Effects can be attached to any Actor, regardless of the type of object the Effect operates on.  For example, a planet special could have Empire Effects (ie, Effects that modify values associated with empires.)
  
−
*Type - the type of a game object determines how the object is managed by the game code in general.  Specific types may be determined by programmers, but suggestions include buildings, specials, ships, technologies, planets, systems etc.  The "type" of an object is like a general grouping, whereas class is a detailed, specific case of a type.  In practice, "type" may be an object property, or treated as a particular programming code-class.  In either case, "type" needs to be an settable property for objects in XML files, and accessibe for effects in game (see below).
+
All Effects can impose the following conditions:
 +
* '''Chance'''  The percent chance that the effect occurs.  Each turn, a random roll of 1-100 is made.  If the results of this roll are lower than “Chance”, then the effect occurs.  Defaults to: 101, meaning no random roll takes place.  The effect always occurs if chance is set to “101”.
 +
*'''Stacking''' True or False.  Determines whether or not the modifications produced by he effect stacks.  If the stacking flag is set to False, then the Effect is canceled if another Effect with the same name has already operated on the target in the Current Turn.  Defaults to: False.
 +
*'''Visibility'''  True or False.  If set to True, then the Effect only operates on objects not in the “Fog of War”.  Defaults to: False.
 +
*'''Meter Values'''  (Note: in v.3, this only applied to planets, as other objects don’t have meters.)  A listing of values for any number of meters, a flag set to “Min” or “Max” for each meter listed, and a “Chance Scale” for each meter listed.  If the flag is set to “Min”, then each listed meter must be greater than or equal to the values listed or the effect cancels.    If the flag is set to “Max”, then each meter must be lesser than or equal to the values listed or the effect cancels.  The Chance Scale defaults to 0.  If Chance Scale is not 0, then instead of canceling the effect, meters influnce the Chance that the effect will occur.  If the flag is set to "Min", then ((Value listed)-(Meter))*Chance Scale is added to the Chance condition.  If the Min/Max flag is set to "Max" then ((Meter)-(Value listed))*Chance Scale is added to the Chance condition.
 +
*'''Stockpile Values'''  A listing of values for resource types, a flag set to “Min” or “Max” for each resource type listed, and a “Chance Scale” for each resource type listed.  This condition tests the resource stockpiles of the empire that owns an object in scope.  If the flag is set to “Min”, then each resource stockpile must be greater than or equal to the values listed or the effect cancels.    If the flag is set to “Max”, then each stockpile must be lesser than or equal to the values listed or the effect cancels.  The Chance Scale defaults to 0.  If Chance Scale is not 0, then instead of canceling the effect, resource stockpiles influnce the Chance that the effect will occur.  If the flag is set to "Min", then ((Value listed)-(Stockpile))*Chance Scale is added to the Chance condition.  If the Min/Max flag is set to "Max" then ((Stockpile)-(Value listed))*Chance Scale is added to the Chance condition.
 +
*'''Actors''' A listing of buildings, leaders, events, techs, etc. and a flag set to True or False for each Actor listed.  The list can include certain generic Actor types, such as "Buildings", "Trade Buildings", or "Trade Commodity Special".  At least one Actor with the True flag must be contained by the tested object, or the effect cancels.  If any Actors with the False flag are contained by the tested object, the effect cancels.  Defaults to an empty list, meaning this condition does not apply.  (note: this condition is used for, amoung other things, applying building upgrades.)
 +
*'''Diplomatic Affiliation'''  There is no diplomacy in v.3.  For now, diplomatic affiliation can be set to “self” and/or “enemy”.  This condition tests the relationship between an empire owning an object in scope and the target empire.  If set to "self", the effect will operate on objects owned by the target empire.  If set to enemy, the effect will operate on objects by other empires.  Defaults to: "self".
 +
*'''War'''  War, Peace, or None.  This condition tests the war state of an empire that own objects in scope.  If set to "War", the effect cancels if the empire not engaded in a war.  If set to "Peace", the effect cancels if the empire is at war.  In v3, "at war" means a combat has occured in the previous turn.
 +
*'''Specific Empire'''  A list of EmpireIDs.  The effect cancels for objects that are not owned by a listed empire.  (Useful for the homeworld special, for example, which should only work for the orginal empire.)  If the list is empty (the default) then no test occurs.
 +
*'''Execute Priority''' A number.  Effects with an Execute Priority of 0 are executed in any order.  After all Effects with priority of 0 have executed, the effects with Priority greater than 0 are run:  in order of lowest priority to highest.  Any effect that uses conditions to test the values of meters should have an Execute Priority of at least 1.
  
−
*Representation - very dependent on type.  In some cases, a particular visual icon (image file) may be indicated.  Other options to be determined by programmers / graphics designers.
+
==Generic Effects==
 +
These effects can be applied regardless of target type.
  
−
*Duration - how many turns the game object remains in the game before disappearing on its own. This may be set to 0, indicating a game object that exists only to group several effects that fire instantly when it is created, may be nonzero positive, indicating a limited duration in turns, or may be negative, indicating an infinite duration game object, that never disappears unless destroyed by an effect (of its own, or another object).
+
===Destroy Actor===
 +
Used to remove events, specials, buildings, etc. from the target.
 +
*'''List of Actors''' A list of events and/or specials.  If conditions are met, then all Actors in this list will be removed from every object in scope.   Instead of a list of other Actors, Destroy Actor can be set to “Self”, destroying the Actor the effect is attached to.  When this Effect is set to “Self”, scope is ignored.  Defaults to: Self.
  
−
*Effects - a fairly detailed list of effects and information about their functionality.  For each effect in an effects lists, the object description indicates:
+
===Modify Meters===
−
**Effect Class - indication of basic functionality of the effect. See below.
+
Note: in v.3, only applies to planets, as other objects do not have meters.
−
**Scope Conditions - a list of scope-limiting conditions that determine what game objects the effect fires upon, in addition to any restrictions implied by the effect class.  See below.
+
−
**Parameters - details about how an effect should function.  Needed for details of the how the effect class functions and most of the scope limiting conditions.
+
  
−
=Effects for v0.3:=
+
Adds or subtracts from the object's meters.
 +
*'''Meters''' A list of meters.
 +
*'''Infrastructure'''  True or False.  Most meters associated with planets have "Max" values and "Current" values. If True, the modification occurs to the Current meter (instead of the Max meter).  Defaults to False, meaning the effect modifies the Max value of meters.
 +
*'''Modification Type'''  A flag set to “Additive”, “Multiplicative”, "Scaled by Meters", or "Scaled by Count". 
 +
**If '''Additive''', the Modification Value is added to the stockpile. 
 +
**If '''Multiplicative''', the value is multiplied with the stockpile’s multiplier.  After all effects have executed, the multipliers are applied to their associated stockpiles. 
 +
**If '''Scaled by Meters''' then the list of meters used in the conditions are referenced to determine the amount of change to the effected meters.  For each listed meter, if the flag is set to "Min", then ((Value listed)-(Tested Meter))*Modification Value is added to the effected meters. If the Min/Max flag on the tested meter is set to "Max" then ((Tested Meter)-(Value listed))*Modification Value is added to the effected meters.
 +
**If '''Scaled by Count''' then the list of Actors used in the conditions is referenced to determine the amount of change to the effected meters.  A count is made of every Actor contained by the effected object--only Actors that appear on the condition list with a flag of True are counted.  The total count is multiplied with "Modification Value", then added to each effected meter.
 +
*'''Modification Value''' A number.
  
−
*Modify Planet Max Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's max meters this turn.  Does not affect current meter values.
+
===Spawn Actor===
 +
Used to spawn events and specials attached to the galaxy itself.
 +
*'''List of Actors'''  A list of events and/or specials.  If conditions are met, then one Actor will be randomly selected from this list and then appended to the galaxy.
 +
*'''Allow Duplicates''' True or False.  Determines whether or not additional Actors will be spawned.  If False, then the effect cancels if any Actor from the “List of Actors” is already attached to the target galaxy.  Defaults to: False.
 +
*'''Spawn All'''  True or False.  If True, then every Actor in the “List of Actors” is spawned, rather than one at random.  Defaults to: False.
  
−
*Modify Current Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's current meter values.  Does not affect max meter values.
 
  
−
*Modify Stockpile (Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
+
==Galaxy Effects==
 +
Galaxy Effects operate on the entire galaxy.  In the future, the galaxy itself might have meters to operate on and test--for now, the only galaxy effects are those used to spawn and destroy events.  
  
−
*Modify Planet Size/Environment (Specified Environment) - Sets the size and environment of a planet
+
There is only one galaxy, therefore target, scope, and most conditions are irrelevant for galaxy effects. 
  
−
*Create Object (Specified Object Class) - Creates a new game object.  If applicable, location and empire ownership are the same as the game object being fired on by the effect.
 
  
−
*Destroy Object - Destroys a game object.
+
==Empire Effects==
 +
Empire effects can be used to spawn/de-spawn Actors, modify the Empire’s stockpiles, and unlock techs/buildings.  In the future, there may be empire meters to modify as well.
  
−
*Set Research (Specified Technology) - Sets a tech a researched or not reserached.
+
The target of an Empire Effect is usually the empire containing the effect’s Actor.  If the Actor is attached to the galaxy or a some other object not contained by an empire, then the target is usually “none”.  If the target is “none” then the only scope possible is “Galactic”.
  
−
*Set Building Availability (Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not.
+
Empire effects can be set to the following scopes.  A single Empire Effect can have multiple scopes  (for example, an Effect could be set to both “Self” and “Neighbors”):
 +
* '''Self'''  The target empire
 +
* '''Galactic'''  All empires in the game, excluding “Self”.
 +
* '''Neighbors''' All empires sharing a border with the target
  
−
*Set Ship Type Availability (Specified Ship Class, Specified Buildable / Not Buildable) - Sets a ship class as buildable or not buildable.
+
===Empire: Learn Technology===
 +
Sets a list of technologies to “Researched”. 
 +
*'''List of Techs'''
 +
*'''Un-Learn'''  True or False.  If True, every tech in the “List of Techs” is set to “Un-researched”.  Defaults to: False.
  
 +
===Empire: Modify Stockpile===
 +
Adds or subtracts from the empire's stockpiles.
 +
*'''Stockpiles''' A list of stockpiles to operate on.
 +
*'''Modification Type'''  A flag set to “Additive” or “Multiplicative”.  If Additive, the Modification Value is added to the stockpile.  If “Multiplicative”, the value is multiplied with the stockpile’s multiplier.  After all effects have executed, the multipliers are applied to their associated stockpiles.
 +
*'''Modification Value''' A number.  If negative and Modification Type is set to "Multiplicative" then the absolute value is used.
  
−
=Effect Scope and Scope-Limiting Conditions=
+
===Empire:  Unlock Item===
 +
Unlocks a tech, tech tree branch, building, ship-part or government pick.  Unlocked items can then be researched (if a tech) or built (if a ship-part or building) empire-wide.  Note: in v3, the “ship-parts” are: Scout, MarkI-V, and Colony Ship.
 +
*'''List of Objects'''  A list of items to unlock.
 +
*'''Re-lock'''  True or False.  If True the effect re-locks all every object in the “List of Objects”.  Defaults to: False.
  
−
The set of game objects (planets, ships, stars, buildings, specials) that are fired upon by an effect are collectively known as the effect's scope.  The scope of an effect is defined by a set of conditions which may exclude game objects from the set.  The scope of an effect is all objects in the game by default, and is reduced by the various conditions.  The conditions are evaluated at the time the effect fires, so an object may be part of an effect's scope for one firing, but not another firing.  All conditions are exclusive: applying a condition to a scope set for an effect can only remove objects from the scope, or leave the scope unchanged, and can never add more objects back into the scope that were previously removed by other conditions.  Thus, the order in which conditions are applied does not affect the contents of the final scope set fired upon by the effect.
+
==Region Effects==
 +
A region is a span of star systems, such a political region or a nebula containing star systems.  There are no regions in v.3.  In the future, effects might spawn/destroy Actors attached to Regions.
  
−
Conditions are checks of various properties of game objects.  Some conditions are based on properties of objects themselves, and others depend on other objects associated with the object being checked by the condition.  For example, a building may be checked for exclusion from the scope according to a planet environment condition.  The building itself has no planet environment, however the building is attached to a planet, so the environment of the planet is check for the purposes of determining whether the building is excluded from the scope of the effect.  Attachments form a tree, so if the building was checked by a condition for a property that neither it nor the planet it is attached to have (such as star colour), the system in which the planet is located would be checked. If no objects in the tree of attached objects for a given potential scope object have a property being checked for, then the object is excluded by default.  For example, if a ship was checked for star colour while it was not in any star system, the ship would be excluded from the scope of the effect by default.
+
* '''Self''' The target system, if any.
 +
* '''Galactic''' All regions in the game, excluding the target region
 +
* '''Tangent''' All regions that "touch" the target system
  
−
If a condition description (below) states that it restriction objects by some property, or "their" some property, the hierarchy is used when necessary to determine what value of the property applies to the game object.
+
==System Effects==
 +
System effects can be used to spawn/de-spawn Actors attached to star systems, or modify the star itself.
  
−
The hierarchy of attachment for scope condition purposes in v0.3:
+
The “system target” of a System Effect is usually the system containing the effect’s Actor.  If the Actor is attached to the galaxy, empire, region or a some other object not contained by system, then the target is usually “none”.  System Effects also have a “target empire”; unless explicitly overridden this should be the empire that owns the effect’s Actor.  In the future, System Effects might have “target regions” as well.
  
−
*Buildings are attached to the planet on which they are located.
+
System effects can be set to the following scopes. A single effect can have multiple scopes:
−
*Planets are attached to the system in which they are located.
+
* '''Self'''  The target system
−
*Ships are attached to the system in which they are located (if applicable), or nothing (if not in a system).
+
* '''Galactic'''  All systems in the game, excluding the target system
−
*Specials are attached to the game object they are associated with (as / if applicable)
+
* '''Neighbors'''  All systems that are a certain distance away from the target system.  The distance condition determines how far the effect reaches.
 +
*'''Neighbors by Starlane Hop'''  All systems that are a certain number of starlane hops away from the target system.  The number of hops is determined by the distance condition.
  
−
Note that the hierarchy described above is only used when checking for a property not specified for a given game object.  This is used only when necessary, and not in cases of possible conflict with another condition, should such a situation arise (though none are yet anticipated).
+
System Effects can have following conditions in addition to the generic conditions:
 +
*'''Distance'''  A number, used by scope.  Defaults to 0.
 +
*'''Star Color'''  A listing of star colors.  Effect cancels if a system's star color isn't included in the list.  Defaults to: "All", meaning every star color is effected.
  
 +
===System: Modify Color===
 +
Used to change the color of all stars in scope that have met conditions. 
 +
*'''Star Color''' The color to set.  Default is yellow.
  
−
=Scope-Limiting Conditions for v0.3=
+
===System: Modify Planet Slot===
 +
Used to add/delete planets to systems. 
 +
*'''Planet Slot'''  The planet slot (1-10) to modify.  Default is 1.
 +
*'''Environment''' The environment of the planet.  Setting Environment to None deletes any existing planet.  Default is barren.
 +
*'''Size''' The size of the planet.  Setting size to None deletes any existing planet.
 +
*'''Colony''' The empire to give the world to.  Starts as a new colony.  Default is None.  If None, the planet has no new colony.  Default is average.
 +
*'''Overwrite''' True or False.  If False, the Effect will only modify empty Planet slots.  Default is False.
  
−
*Planet Environment (Specified Type, Range) - Excludes objects from the scope if they are more than a specified range of environments types away from the specified environment type.  If the specified environment is not on the EP wheel, then the specified range is ignored, and the scope objects' environments must the specified environment exactly.  If the specified environment is on the wheel, but a scope object's environment is not, then the scope object is excluded.  The specified type of environment may be either an actual environment type (eg. "ocean"), or may be set to use the environment of the source object for the effect.  In this case, if the source object has no environment, all objects are excluded from the effect scope.
+
TO-DO: Figure out if it’s feasible/desirable to muck with starlanes/wormholes.
  
−
*Planet Size (Specified Size, Range) - Excludes objects from the scope if they are more than a specified range of planet sizes away from the specified planet size.  The specified size may be either an actual size type (eg. tiny), or may be set relative to the source object for the effect.  In this case, if the source object has no planet size, all objects are excluded from the effect scope.
+
==Planet Effects==
 +
Planet effects can be used to spawn/de-spawn Actors attached to planets (including buildings), modify the meters of colonized worlds, unlock buildings/ship-parts and change the environment.
  
−
*Star Colour (Specified Colour) - Excludes objects from the scope if their star colour does not match the specified colour. The specified colour may be either an actual colour (eg. blue), or may be set relative to the source object for the effect.  In this case, if the source object has no star colour, all objects are excluded from the effect scope.
+
The “planet target” of a Planet Effect is usually the planet containing the effect’s Actor.   If the Actor is attached to the galaxy, empire, region or a some other object not contained by a planet, then the planet target is usually “none”.  Planet Effects also have a “target empire” and “target system”.
  
−
*Object Type (Specified Type) - Excludes objects from the scope if their game object type does not match the specified object type.  The specified type maybe a an actual type (eg. ship, building, special, planet), or maybe be set relative to the source object for the effect.
+
Planet effects can be set to the following scopes.  A single effect can have multiple scopes:
 +
* '''Self'''  The target planet
 +
* '''Galactic'''  All planets in the game, excluding the target planet
 +
* '''Neighbors'''  All planets in systems that are a certain distance away from the target system.  The distance condition determines how far the effect reaches. Setting distance to “0” will include all planets in the target system.
 +
*'''Neighbors by Starlane Hop'''  All planets in systems that are a certain number of starlane hops away from the target system.  The number of hops is determined by the distance condition.  Setting distance to “0” will include all planets in the target system.
  
−
*Direct Distance (Specified Distance) - Excludes objects from the scope if their physical location on the galaxy map is not within a specified distance from the source object's location. If the source object or any of the scope objects have no physical location on the galaxy map, then all or the relevant scope objects are excluded, respectively.
+
Planet Effects can have following conditions in addition to the generic conditions:
 +
*'''Distance'''  A number, used by scope.  Default is 0.
 +
*'''Enviroment''' A list of planet environments, sizes, and environmental preferences.   If a planet’s size, environment, or current environmental preference rating do not appear on the list, then the effect is canceled. 
 +
*'''Star Color''' A listing of star colors.  If a planet's star is not listed, the effect cancels.  Defaults to: "All" meaning planets are effected regardless of parent star color.
  
−
*Starlane Jumps (Specified Number) - Excludes objects from the scope if their physical location is not within a specified number of starlane jumps from the source object.  If the source object is located at a system, then all systems connected to the source object's system by one starlane jump are at a distance 1, by two starlane jumps are at a distance 2, and so on.  Objects on starlanes between systems count as being one jump away from either starlane at the end of the lane they are on.  Objects are always considered to be the shortest number of starlane jumps away from the source as possible, whether or not the starlanes involved are known to the empire(s) involved.
+
===Planet: Modify Environment===
 +
Used to change the environment and size of all planets within scope.
 +
*'''Environment''' The environment to set.  If set to “None” the planet is destroyed.  If set to “NoEffect” the planet’s current enviroment is maintained.  Default is NoEffect.
 +
*'''Size''' The size to set.  If set to “None” the planet is destroyed.  If set to “NoEffect” the planet’s current size is maintained.  Default is NoEffect.
  
−
*Empire Affiliation (Specifed Source Empire, Enemies Inclusive, or Enemies Exclusive) - Excludes objects from the scope based on the empire they are affiliated with.  The condition may be specified to apply to objects owned by the empire that owns the source object only, to empires other than the source empire in both an inclusive and exclusive sense.  (more options will be added after diplomacy).  The "owner" of an object is generally clear, as in a ship or planet, which is clearly owned by a particular empire.  Systems containing planets owned by two or more empires are owned by all empires that own planets in the system.  In this case, "Enemies Inclusive" would include any system that contains a planet owned by an empire other than the source object's empire, and "Enemies Exclusive" would exclude systems that contain planets owned by both the source object's empire an another empire.
+
===Planet: Unlock Item===
 +
Unlocks a tech, tech tree branch, building, ship-part or government pick.  Unlocked items can then be researched (if a tech) or built (if a ship-part or building) on the effected planets.  
 +
*'''List of Objects''' A list of items to unlock.
 +
*'''Re-lock''' True or False.  If True the effect re-locks all every object in the “List of Objects”.  Defaults to: False.
  
−
*Chance (Specified Probability) - Excludes objects from the scope randomly.  Each object is given its own "dice roll", the value of which is compared to the specified probability.  If the roll is less than the parameter, then the object is excluded form the scope.
+
==Ship Effects==
−
 
+
In the future, it will be possible to spawn and destroy ships and modify the properties of ships via modify meters.  Ship effects will be detailed in v.4.
−
*Stacking (Specified Integer) - If the specified integer, or "Stacking Number" is 0, the effect can be fired on a given game object any number of times in a given turn.  If the stacking number is nonzero, effects of a given effect class will have a game object removed from their scope if another effect of the same class and stacking number has already fired on the scope object in a given turn.
+
−
 
+
−
*Source Object Meter (Specified Meter, Specified Value) -
+
−
 
+
−
*Scope Object Meter (Specified Meter, Specified Value) -
+
−
 
+
−
*Scope Object Visible To Source Object (Specified True / False) -
+
−
 
+
−
*Source Object Visible To Scope Object (Specified True / False) -
+
−
 
+
−
*Scope Object Stockpile (Specified Resource, Specified Value) -
+
−
 
+
−
*Source Object Stockpile (Specified Resource, Specified Value) -
+
−
 
+
−
=TO DO: Order of effect firing=
+

Revision as of 11:45, 10 September 2004

Unofficial

Contents of this document have not passed public review. Comments are welcome on the talk page, but please do not modify this document.--drek

Effects

Buildings, technologies, racial picks, planet specials, events, government picks, and leaders are all “Actors”. Actors operate on the game world through Effects. A single Actor can have any number of Effects.

Most effects have:

  • a Target: the epicenter of an Effect’s scope. This includes information for each object containing the target: a planet Effect would also target the planet’s system and the empire that owns the planet.
  • a Scope, defining how far the Effect reaches
  • Conditions, which exclude objects within Scope
  • Values that determine the modifications produced by the Effect on objects within Scope that have met all Conditions

Effects can be attached to any Actor, regardless of the type of object the Effect operates on. For example, a planet special could have Empire Effects (ie, Effects that modify values associated with empires.)

All Effects can impose the following conditions:

  • Chance The percent chance that the effect occurs. Each turn, a random roll of 1-100 is made. If the results of this roll are lower than “Chance”, then the effect occurs. Defaults to: 101, meaning no random roll takes place. The effect always occurs if chance is set to “101”.
  • Stacking True or False. Determines whether or not the modifications produced by he effect stacks. If the stacking flag is set to False, then the Effect is canceled if another Effect with the same name has already operated on the target in the Current Turn. Defaults to: False.
  • Visibility True or False. If set to True, then the Effect only operates on objects not in the “Fog of War”. Defaults to: False.
  • Meter Values (Note: in v.3, this only applied to planets, as other objects don’t have meters.) A listing of values for any number of meters, a flag set to “Min” or “Max” for each meter listed, and a “Chance Scale” for each meter listed. If the flag is set to “Min”, then each listed meter must be greater than or equal to the values listed or the effect cancels. If the flag is set to “Max”, then each meter must be lesser than or equal to the values listed or the effect cancels. The Chance Scale defaults to 0. If Chance Scale is not 0, then instead of canceling the effect, meters influnce the Chance that the effect will occur. If the flag is set to "Min", then ((Value listed)-(Meter))*Chance Scale is added to the Chance condition. If the Min/Max flag is set to "Max" then ((Meter)-(Value listed))*Chance Scale is added to the Chance condition.
  • Stockpile Values A listing of values for resource types, a flag set to “Min” or “Max” for each resource type listed, and a “Chance Scale” for each resource type listed. This condition tests the resource stockpiles of the empire that owns an object in scope. If the flag is set to “Min”, then each resource stockpile must be greater than or equal to the values listed or the effect cancels. If the flag is set to “Max”, then each stockpile must be lesser than or equal to the values listed or the effect cancels. The Chance Scale defaults to 0. If Chance Scale is not 0, then instead of canceling the effect, resource stockpiles influnce the Chance that the effect will occur. If the flag is set to "Min", then ((Value listed)-(Stockpile))*Chance Scale is added to the Chance condition. If the Min/Max flag is set to "Max" then ((Stockpile)-(Value listed))*Chance Scale is added to the Chance condition.
  • Actors A listing of buildings, leaders, events, techs, etc. and a flag set to True or False for each Actor listed. The list can include certain generic Actor types, such as "Buildings", "Trade Buildings", or "Trade Commodity Special". At least one Actor with the True flag must be contained by the tested object, or the effect cancels. If any Actors with the False flag are contained by the tested object, the effect cancels. Defaults to an empty list, meaning this condition does not apply. (note: this condition is used for, amoung other things, applying building upgrades.)
  • Diplomatic Affiliation There is no diplomacy in v.3. For now, diplomatic affiliation can be set to “self” and/or “enemy”. This condition tests the relationship between an empire owning an object in scope and the target empire. If set to "self", the effect will operate on objects owned by the target empire. If set to enemy, the effect will operate on objects by other empires. Defaults to: "self".
  • War War, Peace, or None. This condition tests the war state of an empire that own objects in scope. If set to "War", the effect cancels if the empire not engaded in a war. If set to "Peace", the effect cancels if the empire is at war. In v3, "at war" means a combat has occured in the previous turn.
  • Specific Empire A list of EmpireIDs. The effect cancels for objects that are not owned by a listed empire. (Useful for the homeworld special, for example, which should only work for the orginal empire.) If the list is empty (the default) then no test occurs.
  • Execute Priority A number. Effects with an Execute Priority of 0 are executed in any order. After all Effects with priority of 0 have executed, the effects with Priority greater than 0 are run: in order of lowest priority to highest. Any effect that uses conditions to test the values of meters should have an Execute Priority of at least 1.

Generic Effects

These effects can be applied regardless of target type.

Destroy Actor

Used to remove events, specials, buildings, etc. from the target.

  • List of Actors A list of events and/or specials. If conditions are met, then all Actors in this list will be removed from every object in scope. Instead of a list of other Actors, Destroy Actor can be set to “Self”, destroying the Actor the effect is attached to. When this Effect is set to “Self”, scope is ignored. Defaults to: Self.

Modify Meters

Note: in v.3, only applies to planets, as other objects do not have meters.

Adds or subtracts from the object's meters.

  • Meters A list of meters.
  • Infrastructure True or False. Most meters associated with planets have "Max" values and "Current" values. If True, the modification occurs to the Current meter (instead of the Max meter). Defaults to False, meaning the effect modifies the Max value of meters.
  • Modification Type A flag set to “Additive”, “Multiplicative”, "Scaled by Meters", or "Scaled by Count".
    • If Additive, the Modification Value is added to the stockpile.
    • If Multiplicative, the value is multiplied with the stockpile’s multiplier. After all effects have executed, the multipliers are applied to their associated stockpiles.
    • If Scaled by Meters then the list of meters used in the conditions are referenced to determine the amount of change to the effected meters. For each listed meter, if the flag is set to "Min", then ((Value listed)-(Tested Meter))*Modification Value is added to the effected meters. If the Min/Max flag on the tested meter is set to "Max" then ((Tested Meter)-(Value listed))*Modification Value is added to the effected meters.
    • If Scaled by Count then the list of Actors used in the conditions is referenced to determine the amount of change to the effected meters. A count is made of every Actor contained by the effected object--only Actors that appear on the condition list with a flag of True are counted. The total count is multiplied with "Modification Value", then added to each effected meter.
  • Modification Value A number.

Spawn Actor

Used to spawn events and specials attached to the galaxy itself.

  • List of Actors A list of events and/or specials. If conditions are met, then one Actor will be randomly selected from this list and then appended to the galaxy.
  • Allow Duplicates True or False. Determines whether or not additional Actors will be spawned. If False, then the effect cancels if any Actor from the “List of Actors” is already attached to the target galaxy. Defaults to: False.
  • Spawn All True or False. If True, then every Actor in the “List of Actors” is spawned, rather than one at random. Defaults to: False.


Galaxy Effects

Galaxy Effects operate on the entire galaxy. In the future, the galaxy itself might have meters to operate on and test--for now, the only galaxy effects are those used to spawn and destroy events.

There is only one galaxy, therefore target, scope, and most conditions are irrelevant for galaxy effects.


Empire Effects

Empire effects can be used to spawn/de-spawn Actors, modify the Empire’s stockpiles, and unlock techs/buildings. In the future, there may be empire meters to modify as well.

The target of an Empire Effect is usually the empire containing the effect’s Actor. If the Actor is attached to the galaxy or a some other object not contained by an empire, then the target is usually “none”. If the target is “none” then the only scope possible is “Galactic”.

Empire effects can be set to the following scopes. A single Empire Effect can have multiple scopes (for example, an Effect could be set to both “Self” and “Neighbors”):

  • Self The target empire
  • Galactic All empires in the game, excluding “Self”.
  • Neighbors All empires sharing a border with the target

Empire: Learn Technology

Sets a list of technologies to “Researched”.

  • List of Techs
  • Un-Learn True or False. If True, every tech in the “List of Techs” is set to “Un-researched”. Defaults to: False.

Empire: Modify Stockpile

Adds or subtracts from the empire's stockpiles.

  • Stockpiles A list of stockpiles to operate on.
  • Modification Type A flag set to “Additive” or “Multiplicative”. If Additive, the Modification Value is added to the stockpile. If “Multiplicative”, the value is multiplied with the stockpile’s multiplier. After all effects have executed, the multipliers are applied to their associated stockpiles.
  • Modification Value A number. If negative and Modification Type is set to "Multiplicative" then the absolute value is used.

Empire: Unlock Item

Unlocks a tech, tech tree branch, building, ship-part or government pick. Unlocked items can then be researched (if a tech) or built (if a ship-part or building) empire-wide. Note: in v3, the “ship-parts” are: Scout, MarkI-V, and Colony Ship.

  • List of Objects A list of items to unlock.
  • Re-lock True or False. If True the effect re-locks all every object in the “List of Objects”. Defaults to: False.

Region Effects

A region is a span of star systems, such a political region or a nebula containing star systems. There are no regions in v.3. In the future, effects might spawn/destroy Actors attached to Regions.

  • Self The target system, if any.
  • Galactic All regions in the game, excluding the target region
  • Tangent All regions that "touch" the target system

System Effects

System effects can be used to spawn/de-spawn Actors attached to star systems, or modify the star itself.

The “system target” of a System Effect is usually the system containing the effect’s Actor. If the Actor is attached to the galaxy, empire, region or a some other object not contained by system, then the target is usually “none”. System Effects also have a “target empire”; unless explicitly overridden this should be the empire that owns the effect’s Actor. In the future, System Effects might have “target regions” as well.

System effects can be set to the following scopes. A single effect can have multiple scopes:

  • Self The target system
  • Galactic All systems in the game, excluding the target system
  • Neighbors All systems that are a certain distance away from the target system. The distance condition determines how far the effect reaches.
  • Neighbors by Starlane Hop All systems that are a certain number of starlane hops away from the target system. The number of hops is determined by the distance condition.

System Effects can have following conditions in addition to the generic conditions:

  • Distance A number, used by scope. Defaults to 0.
  • Star Color A listing of star colors. Effect cancels if a system's star color isn't included in the list. Defaults to: "All", meaning every star color is effected.

System: Modify Color

Used to change the color of all stars in scope that have met conditions.

  • Star Color The color to set. Default is yellow.

System: Modify Planet Slot

Used to add/delete planets to systems.

  • Planet Slot The planet slot (1-10) to modify. Default is 1.
  • Environment The environment of the planet. Setting Environment to None deletes any existing planet. Default is barren.
  • Size The size of the planet. Setting size to None deletes any existing planet.
  • Colony The empire to give the world to. Starts as a new colony. Default is None. If None, the planet has no new colony. Default is average.
  • Overwrite True or False. If False, the Effect will only modify empty Planet slots. Default is False.

TO-DO: Figure out if it’s feasible/desirable to muck with starlanes/wormholes.

Planet Effects

Planet effects can be used to spawn/de-spawn Actors attached to planets (including buildings), modify the meters of colonized worlds, unlock buildings/ship-parts and change the environment.

The “planet target” of a Planet Effect is usually the planet containing the effect’s Actor. If the Actor is attached to the galaxy, empire, region or a some other object not contained by a planet, then the planet target is usually “none”. Planet Effects also have a “target empire” and “target system”.

Planet effects can be set to the following scopes. A single effect can have multiple scopes:

  • Self The target planet
  • Galactic All planets in the game, excluding the target planet
  • Neighbors All planets in systems that are a certain distance away from the target system. The distance condition determines how far the effect reaches. Setting distance to “0” will include all planets in the target system.
  • Neighbors by Starlane Hop All planets in systems that are a certain number of starlane hops away from the target system. The number of hops is determined by the distance condition. Setting distance to “0” will include all planets in the target system.

Planet Effects can have following conditions in addition to the generic conditions:

  • Distance A number, used by scope. Default is 0.
  • Enviroment A list of planet environments, sizes, and environmental preferences. If a planet’s size, environment, or current environmental preference rating do not appear on the list, then the effect is canceled.
  • Star Color A listing of star colors. If a planet's star is not listed, the effect cancels. Defaults to: "All" meaning planets are effected regardless of parent star color.

Planet: Modify Environment

Used to change the environment and size of all planets within scope.

  • Environment The environment to set. If set to “None” the planet is destroyed. If set to “NoEffect” the planet’s current enviroment is maintained. Default is NoEffect.
  • Size The size to set. If set to “None” the planet is destroyed. If set to “NoEffect” the planet’s current size is maintained. Default is NoEffect.

Planet: Unlock Item

Unlocks a tech, tech tree branch, building, ship-part or government pick. Unlocked items can then be researched (if a tech) or built (if a ship-part or building) on the effected planets.

  • List of Objects A list of items to unlock.
  • Re-lock True or False. If True the effect re-locks all every object in the “List of Objects”. Defaults to: False.

Ship Effects

In the future, it will be possible to spawn and destroy ships and modify the properties of ships via modify meters. Ship effects will be detailed in v.4.

Retrieved from "https://freeorion.org/index.php?title=FOCS_Scripting_Details&oldid=638"