Difference between revisions of "FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
Line 44: Line 44:
  
 
==The Effects==
 
==The Effects==
*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 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 Empire Stockpile (Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
+
===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 Planet Size/Environment (Specified Environment) - Sets the size and environment of a planet
+
===Modify Empire Stockpile===
 +
(Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
  
*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.
+
===Modify Planet Size/Environment===
 +
(Specified Environment) - Sets the size and environment of a planet
  
*Destroy Object - Destroys a game object.
+
===Create Object===
 +
(Specified Object Class) - Creates new game object(s).  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.
  
*Set Empire Research (Specified Technology, Specified Yes/No) - Sets a tech a researched or not reserached for empire.
+
===Destroy Object===
 +
(No Parameters) - Destroys game object(s).
  
*Set Empire Building Availability (Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not for empire.
+
===Set Empire Research===
 +
(Specified Technology, Specified Yes/No) - Sets a tech a researched or not reserached 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 Empire Building Availability===
 +
(Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not for empire.
  
*Set Star Colour (Specified Star Colour) - Sets the colour of a star.
+
===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=
 
=Effect Scope and Scope-Limiting Conditions=

Revision as of 02:16, 12 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:

A single effect can fire off multiple entries from the following list. (This is so if an object produces multiple effects across the same scope, the scope only has to be computed once.)

A note on values

Any numeric parameter can be expressed in "dice notion". Dice notion (from pen and paper RPGs) is a number of dice to roll, followed by a "d", followed by the number of sides on the die, followed by any additional modifiers. For example, 3d8-2 indicates to "roll" three eight sided dice, tally the results, then subtract 2.

Numeric parameters can also reference meter values of the source or target object, either the Max or Current value of the meter.

Examples:

1d4+Source.Farming.Current, meaning 1 to 4 added to the Current Farming meter of the source object (or the parent planet of a building) to determine the value of the parameter.

3d8*Target.Population.Max, meaning three eight sided dice are multiplied with the target object's max population to determine the value of the parameter.

If a referenced meter is not present on a source object, the value is assumed to be 0.

The Effects

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 new game object(s). 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

(No Parameters) - Destroys game object(s).

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 determined using conditions in two steps. The scope is initially empty, and game objects are first put into the scope using 'inclusive' conditions. A given game object is either included, or not yet included in the scope, so being included by more than one condition causes no further change (no multiple inclusion). A particular inclusive condition may either add objects to the scope, or may have no effect. After all inclusive conditions have been applied, 'exclusive' conditions are used to exclude game objects from the scope. A given 'exclusive' condition may either exclude objects from the scope, or have no effect. All 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.

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 excludes objects from the scope by some property, or "their" some property, a 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

Scope starts with no objects. Inclusive conditions are applied first, adding game objects into the scope. Exclusive conditions are then applied, removing objects from the scope, leaving a final set of objects in the scope, on which the effect is fired.

An effect can have multiple exclusive and inclusive conditions.

Inclusive Conditions

All

(No parameters) - All objects are included in scope.

Empire Affiliation

(Specified Empire, Specifed one of: Empire Inclusive, Empire Exclusive, Enemies Inclusive, Enemies Exclusive) - Includes objects from the scope based on the empire they are affiliated with, if any. The specified empire may be the source object's empire, a specific empire in the game, or may be "none". For an specified empire other than none, the second parameter specifies how the condition adds objects to the scope based on their empire according to the following criteria:

  • Empire Inclusive - Owned by the specified empire only (including objects shared by the source empire and another empire)
  • Empire Exclusive - Owned by the specified empire only (not including objects shared by the source empire and another empire)
  • Enemies Inclusive - Owned by empires other than the source empire (including objects shared by the source empire)
  • Enemies Exclusive - Owned by empires other than the source empire (not including objects shared by the source empire)

If the specified empire is "none", the second parameter specifies how the condition adds objects to the scope according to the following criteria:

  • Empire Inclusive - Owned by no empire (eg. space monsters)
  • Empire Exclusive - Owned by no empire (eg. space monsters)
  • Enemies Inclusive - Owned by any empire(s)
  • Enemies Exclusive - Owned by any empire(s)

(An object cannot be shared between "no empire" and a particular empire, so the distinction between inclusive and exclusive does not apply if the specified empire is "none").

The "owner" of an object is generally clear, as in a ship or planet, which is clearly owned by a particular empire. In some cases however, objects are owned by more than one empire, such as systems containing planets owned by two or more empires are owned by all empires that own planets in the system. In other cases, objects are owned by no empire (eg. space monsters), no matter who owns the system in which they are located.

Self

(No parameters) - The source object is added to the scope.

Object Type

(Specified Type) - Add objects from the scope if their game object type is 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.

Exclusive Conditions

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.

Planet Focus

(Specified Focus, Specified Primary or Secondary) - If specified Primary, excludes objects whose primary focus is not set to the specified focus. If specified Secondary, excludes objects whose primary and secondary focii are both not set to the specified focus.

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.

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. Note: The probability can be expressed via the dice and meter notion explained in a prior section.

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) - Note: The specified value can be expressed via the dice and meter notion explained in a prior section.

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

Direct Distance

(Specified Distance) - Excludes objects from the scope if their physical location on the galaxy map is 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. Distance can be 0, meaning only objects co-located with the source object are included (meaning in the same star system, or located at the same position on a starlane).

Starlane Jumps

(Specified Number) - Excludes objects from the scope if their physical location is 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. Distance can be 0, meaning only objects co-located with the source object are included (meaning in the same star system, or located at the same position on a starlane).

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