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.)
(replacing my document with geoff's. Good work geoff, looks really good to me.)
Line 1: Line 1:
 
=Unofficial=
 
=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
+
Contents of this document have not passed public review.  Comments are welcome on the talk page.
  
=Effects=
+
=Introduction=
  
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.
+
"Effects" are changes/modifications to game objects.   
  
Most effects have:
+
"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.
  
*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.
+
=Game Objects & Effects=
*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.)
+
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.
  
All Effects can impose the following conditions:
+
Game Object Descriptions include:
* '''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==
+
*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).
These effects can be applied regardless of target type.
+
  
===Destroy Actor===
+
*Representation - very dependent on typeIn some cases, a particular visual icon (image file) may be indicated. Other options to be determined by programmers / graphics designers.
Used to remove events, specials, buildings, etc. from the target.
+
*'''List of Actors''' A list of events and/or specialsIf 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===
+
*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).
Note: in v.3, only applies to planets, as other objects do not have meters.
+
  
Adds or subtracts from the object's meters.
+
*Effects - a fairly detailed list of effects and information about their functionalityFor each effect in an effects lists, the object description indicates:
*'''Meters''' A list of meters.
+
**Effect Class - indication of basic functionality of the effectSee below.
*'''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.
+
**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 classSee below.
*'''Modification Type'''  A flag set to “Additive”, “Multiplicative”, "Scaled by Meters", or "Scaled by Count". 
+
**Parameters - details about how an effect should functionNeeded for details of the how the effect class functions and most of the scope limiting conditions.
**If '''Additive''', the Modification Value is added to the stockpile. 
+
**If '''Multiplicative''', the value is multiplied with the stockpile’s multiplierAfter 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 metersFor 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 metersA 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===
+
=Effects for v0.3:=
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 Planet Max Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's max meters this turn.  Does not affect current meter values.
  
==Galaxy Effects==
+
*Modify Planet Current Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's current meter values.  Does not affect max meter values.
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.  
+
*Modify Empire Stockpile (Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
  
 +
*Modify Planet Size/Environment (Specified Environment) - Sets the size and environment of a planet
  
==Empire 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.  This is obviously a rather complicated and multi-functional effect, with numerous possible variations in behaviour depending on the types and number of game objects being createdAs such, it may be more convenient to separate this effect into numerous separate effects in order to create objects of any given category (buildings, ships, specials, etc.) which appropriate parameters for each.  The specifics of this are left for programmer judgement to decide.
Empire effects can be used to spawn/de-spawn Actors, modify the Empire’s stockpiles, and unlock techs/buildingsIn 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”.
+
*Destroy Object - Destroys a game object.
  
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”):
+
*Set Empire Research (Specified Technology, Specified Yes/No) - Sets a tech a researched or not reserached for empire.
* '''Self'''  The target empire  
+
* '''Galactic'''  All empires in the game, excluding “Self”.
+
* '''Neighbors''' All empires sharing a border with the target
+
  
===Empire: Learn Technology===
+
*Set Empire Building Availability (Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not for empire.
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===
+
*Set Ship Type Availability (Specified Ship Class, Specified Buildable / Not Buildable) - Sets a ship class as buildable or not buildable for empire.
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===
+
*Set Star Colour (Specified Star Colour) - Sets the colour of a star.
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.
+
=Effect Scope and Scope-Limiting Conditions=
* '''Galactic''' All regions in the game, excluding the target region
+
* '''Tangent''' All regions that "touch" the target system
+
  
==System Effects==
+
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 scope-limiting conditions for each effect.  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.
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.
+
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.
  
System effects can be set to the following scopes.  A single effect can have multiple scopes:
+
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.
* '''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:
+
The hierarchy of attachment for scope condition purposes in v0.3:
*'''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===
+
*Buildings are attached to the planet on which they are located.
Used to change the color of all stars in scope that have met conditions.
+
*Planets are attached to the system in which they are located.
*'''Star Color''' The color to set.  Default is yellow.
+
*Ships are attached to the system in which they are located (if applicable), or nothing (if not in a system).
 +
*Specials are attached to the game object they are associated with (as / if applicable)
  
===System: Modify Planet Slot===
+
Note that the hierarchy described above is only used when checking for a property not specified for a given game objectThis 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).
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 colonyDefault 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.
+
Note also that targetting of empires, as opposed to other game objects owned by empires, may be "loose".  This this, it is meant that an effect that is described above as setting some property of a particular empire may be targetted to that empire directly, or may affect all empires that own an object that falls into the effect's scope.  The specifics of how this works can be decided by programmers, but it should be possible to target an empire directly, or target all empire's that own other objects objects in an effect's 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.
 
  
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”.
+
=Scope-Limiting Conditions for v0.3=
  
Planet effects can be set to the following scopes.  A single effect can have multiple scopes:
+
*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 exactlyIf 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 effectIn this case, if the source object has no environment, all objects are excluded from the effect scope.
* '''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 reachesSetting 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 conditionSetting distance to “0” will include all planets in the target system.
+
  
Planet Effects can have following conditions in addition to the generic conditions:
+
*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.
*'''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 colorsIf 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===
+
*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 effectIn this case, if the source object has no star colour, all objects are excluded from the effect scope.
Used to change the environment and size of all planets within scope.
+
*'''Environment''' The environment to set.  If set to “None” the planet is destroyedIf 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 destroyedIf set to “NoEffect” the planet’s current size is maintained.  Default is NoEffect.
+
  
===Planet: Unlock Item===
+
*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 may be set relative to the source object for the effectIf programmers elect to do so, "empire" might be an valid object type, allowing an effect to target empires directly, as opposed to targetting other game objects owned by an empire to get at the empire itself.
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==
+
*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.
In the future, it will be possible to spawn and destroy ships and modify the properties of ships via modify metersShip effects will be detailed in v.4.
+
 
 +
*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.
 +
 
 +
*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.
 +
 
 +
*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 probabilityIf the roll is less than the parameter, then the object is excluded form the scope.
 +
 
 +
*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.
 +
 
 +
*Current Meter Value (Specified Meter, Specified Value) -
 +
 
 +
*Scope Object Visible To Source Object (Specified True / False) -
 +
 
 +
*Source Object Visible To Scope Object (Specified True / False) -
 +
 
 +
*Current Stockpile Value (Specified Resource, Specified Value) -
 +
 
 +
*Co-located with Object of Class (Specified Class of Game Object) - Excludes objects from the scope if they are not at the same physical location on the galaxy map as an object of the specified class.  This could be used to exclude ships from the scope if they are not located in a system with a particular special on one of its planets, for example.
 +
 
 +
*Attached to Object of Class (Specified Class of Game Object) - Excludes objects from the scope if they are not attached to an object of the specified class. This could be used to exclude planets from the scope if they do not have a particular type of building located on them.
 +
 
 +
=TO DO: Order of effect firing=

Revision as of 22:06, 11 September 2004

Unofficial

Contents of this document have not passed public review. Comments are welcome on the talk page.

Introduction

"Effects" are changes/modifications to game objects.

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

Game Objects & Effects

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.

Game Object Descriptions include:

  • 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).
  • 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.
  • 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).
  • Effects - a fairly detailed list of effects and information about their functionality. For each effect in an effects lists, the object description indicates:
    • Effect Class - indication of basic functionality of the effect. See below.
    • 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:

  • 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.
  • Modify Planet Current Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's current meter values. Does not affect max meter values.
  • Modify Empire Stockpile (Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
  • Modify Planet Size/Environment (Specified Environment) - Sets the size and environment of a planet
  • 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. This is obviously a rather complicated and multi-functional effect, with numerous possible variations in behaviour depending on the types and number of game objects being created. As such, it may be more convenient to separate this effect into numerous separate effects in order to create objects of any given category (buildings, ships, specials, etc.) which appropriate parameters for each. The specifics of this are left for programmer judgement to decide.
  • Destroy Object - Destroys a game object.
  • Set Empire Research (Specified Technology, Specified Yes/No) - Sets a tech a researched or not reserached for empire.
  • Set Empire Building Availability (Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not for empire.
  • Set Ship Type Availability (Specified Ship Class, Specified Buildable / Not Buildable) - Sets a ship class as buildable or not buildable for empire.
  • Set Star Colour (Specified Star Colour) - Sets the colour of a star.


Effect Scope and Scope-Limiting Conditions

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 scope-limiting conditions for each effect. 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.

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.

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.

The hierarchy of attachment for scope condition purposes in v0.3:

  • Buildings are attached to the planet on which they are located.
  • Planets are attached to the system in which they are located.
  • Ships are attached to the system in which they are located (if applicable), or nothing (if not in a system).
  • Specials are attached to the game object they are associated with (as / if applicable)

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

Note also that targetting of empires, as opposed to other game objects owned by empires, may be "loose". This this, it is meant that an effect that is described above as setting some property of a particular empire may be targetted to that empire directly, or may affect all empires that own an object that falls into the effect's scope. The specifics of how this works can be decided by programmers, but it should be possible to target an empire directly, or target all empire's that own other objects objects in an effect's scope.


Scope-Limiting Conditions for v0.3

  • 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.
  • 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.
  • 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.
  • 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 may be set relative to the source object for the effect. If programmers elect to do so, "empire" might be an valid object type, allowing an effect to target empires directly, as opposed to targetting other game objects owned by an empire to get at the empire itself.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • Current Meter Value (Specified Meter, Specified Value) -
  • Scope Object Visible To Source Object (Specified True / False) -
  • Source Object Visible To Scope Object (Specified True / False) -
  • Current Stockpile Value (Specified Resource, Specified Value) -
  • Co-located with Object of Class (Specified Class of Game Object) - Excludes objects from the scope if they are not at the same physical location on the galaxy map as an object of the specified class. This could be used to exclude ships from the scope if they are not located in a system with a particular special on one of its planets, for example.
  • Attached to Object of Class (Specified Class of Game Object) - Excludes objects from the scope if they are not attached to an object of the specified class. This could be used to exclude planets from the scope if they do not have a particular type of building located on them.

TO DO: Order of effect firing