Difference between revisions of "FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
Line 36: Line 36:
  
 
Effects are listed in groups.  Each effects group contains one or more effects that work together on the same game objects simultaneously, subject to the same conditions.
 
Effects are listed in groups.  Each effects group contains one or more effects that work together on the same game objects simultaneously, subject to the same conditions.
 +
 +
It would probably be most convenient to restrict effects of a particular group to all be of the same of these categories:
 +
*Effects that modify max meter values
 +
*Effects that modify current meter values
 +
*Effects that do not modify meter values
 +
 +
These categories of effects are processed separately (see effects system discussion below), and being able to process whole groups of effects at once by phase of turn in which they fire would likely be convenient and effecicent.
  
 
==Effect Group Descriptions==
 
==Effect Group Descriptions==
Line 262: Line 269:
  
 
=Effects System=
 
=Effects System=
 
TODO: More explanation of how stuff is supposed to work...
 
  
 
==Effect Ordering==
 
==Effect Ordering==
Line 273: Line 278:
 
*Start of Turn Processing  
 
*Start of Turn Processing  
 
*All current meters set to 0
 
*All current meters set to 0
*All actors iterated through, any effect that modifies a max meter value is fired
+
*All actors iterated through, any effect that modifies a max meter value is fired.  (This is the max meter modification effects ordering stage)
*All actors iterated through, any effect that modifies a current meter value is fired
+
*All actors iterated through, any effect that modifies a current meter value is fired.  (This is the current meter modification effects ordering stage)
*All actors iterated through, any effect that does not modify a meter value is fired
+
*All actors iterated through, any effect that does not modify a meter value is fired.  (This is the non-meter modifying effects ordering stage)
 
*Balance of Turn - other game systems, movement, combat etc.
 
*Balance of Turn - other game systems, movement, combat etc.
 
*End of Turn Processing
 
*End of Turn Processing
 +
 +
==Effect Processing==
 +
 +
When processing effects during one of the effects ordering stages, the following occurs:
 +
*Game objects are being iterated through, and a particular game object is selected to have its effects processed during this ordering stage
 +
*If the selected game object has any groups of effects containing effects that can fire during this ordering stage, it is considered further
 +
*An effect group is selected that contains effects that fire during this ordering stage
 +
*The inclusive scope conditions for this effects group are applied, building up an initial scope of game objects
 +
*The exclusive scope conditions for this effects group are applied, excluding objects from the scope
 +
*All of the effects of the effects group are applied, in order listed, to all of the objects in the scope
 +
*The processing loops back to cover all effects groups and all game objects

Revision as of 09:22, 12 September 2004

Unofficial

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

Introduction

Terminology

"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 list of groups of effects. A particular game object's effects groups determine many of the ways it iteracts with the other game objects. For example, a building might have an effects group containing an effect which alters a meter of a planet. Alternatively, a special attached to a system might have an effect in a group which makes all ships in the system have nonfunctional shields. A player-visible game object may contain no effects groups, and a player-invisible game object may contain multiple effects and groups, allowing for flexible in-game collection of effects that work together.

General Conception

The basic goals of effects are:

  • To influence how the game calculates basic game functions such as production, population, ship movement (not in v0.3), etc., but not to actually calculate or impliment these results in most cases
  • To permit additional manipulations of the game state beyond those provided by basic game functions
  • To do both of the above in a very customizable and moddable way, using data files external to the program to define relevant game content

To achieve these goals, the effects system requirements in this document allow (and require) the creating, in XML files (or similar), of template classes of game objects in various categories, which provide all of the "content" of the game. The specifics of the non-effects details of the content system are not relevant to the effects portion of the design, so will be written elsewhere.

Game Objects

Game objects are of a particular class. The class description of a game object is contained within an XML file (suggested). For a given class, this description indicates all the groups of effects and the effects they contain, contains all information about how the effects function, a category or "type" (eg. building, special, ship...) into which the game object falls (to enable to the game to deal with the object internally other than through effects), indicates how the object is represented to the player (if it is visible) and indicates any other necessary information about the object. The other "necessary information" is quite substantial, and is intentended to provide the majority of the game content in XML format (see below).

The "type" of an object is a general category, whereas class is a detailed, specific case of a type. "Building" is a type, whereas a "Level 5 Farming Enhancer" would be a specific class of object, defined in an XML file, and buildable by players in the game, assuming they have the appropriate in-game prerequisites (which falls under "other necessary information").

Game Object Descriptions include the following information which are relevant to the effects system (as well other necessary information):

  • 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. 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).
  • Duration - how many turns the game object remains in the game before disappearing on its own. This may be nonzero positive, indicating a limited duration in turns, or may be zero, indicating an infinite duration game object, that never disappears unless destroyed by an effect (of its own, or another object).
  • Effects Groups - a detailed list of groups of effects and information about their functionality (see below).

Effects Groups

Effects are listed in groups. Each effects group contains one or more effects that work together on the same game objects simultaneously, subject to the same conditions.

It would probably be most convenient to restrict effects of a particular group to all be of the same of these categories:

  • Effects that modify max meter values
  • Effects that modify current meter values
  • Effects that do not modify meter values

These categories of effects are processed separately (see effects system discussion below), and being able to process whole groups of effects at once by phase of turn in which they fire would likely be convenient and effecicent.

Effect Group Descriptions

For each effects group for a game object, the following are indicated:

  • Effects - a list of effect classes for the group. Particular classes may be duplicated, optionally have different parameter values. See below.
  • Scope Conditions - a list of scope building and limiting conditions that determine what game objects the effect of the group fire upon, in addition to any restrictions implied by the individual effects classes. See below.
  • Parameters - for individual effects in a group, and for conditions that determine the scope of the whole group of effects
    • Effect Parameters - details about how each individual effect should work. Indicates individually for each effect in the group.
    • Condition Parameters - details about how each inclusive or exclusive condition used to determine the scope of the effects group should work.

Note: In the following, the "source object" or "source" or "effect source" of an effect is the object which contains the effect in question.

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.

Set Planet Size

(Specified Size) - Sets the size property of a planet to a specified value.

Optional: Modify Planet Size

(Specified Change) - Increases or decreases the size of a planet by a specified number of sizes. Planet sizes are ordered tiny, small, medium, large, huge.

Optionally, asteroid belts may be placed below tiny, and gas giants above huge.

Planet environment is normally unchanged during a size change. In the case of growing larger than huge, or smaller than tiny, environment should be set to the appropriate environment for those types of planets, though retaining the original environoment of the planet as a property of the planet while it is an asteroid belt or gas giant would be desirable. In the case of a planet that has always been an asteroid belt growing larger, the environment of the new planet should be barren. In the case of a planet that has always been a gas giant growing smaller, the environment should be toxic.

Set Planet Environment

(Specified Environment) - Sets the environment property of a planet to a specified value.

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.

Future: Set Target

For v0.3, this effect is not required. It is largely dependent on some sort of user-interface which is capable of interacting with game objects and their effects, which is not yet specified in the requirements, and will likely be delayed until v0.4 or later.

(No XML Settable Parameters, possibly some UI/AI parameters or controls) - Sets the "target" property of a game object. "Target" would be a run-time-only settable property of a game object, which could be used to specifically and persistantly alter its behaviour and/or limit the scope of its effect(s).

This would not be configurable from an XML file. Rather it would need to bet set at run time as either part of the Create Object effect, using the Set Target effect, or by some other means. For example, a building on a planet could fire Set Target on itself to target a particular ship with some effect every turn. Alternatively, a special space-monster controlling ship could use Set Target to cause space monsters to attack a specific enemy ship (assuming that a space monster game object's "Target" property was used to keep track of what ship it was current hunting).

The specifics of how this effect works with scope conditions is not yet fully conceived. A single scope is likely insufficient, as there needs to be some way to specificy both what object to fire the effect on, and what object to which to set the fired upon object's target. Limiting objects to only firing set target only onto themselves might work, using scope to determine the new target, however this is inconsistent with the standard use of scope to determine which object(s) to fire upon.

How to decide how and when to fire Set Target is also not clear, nor is the persistance of the effect between turns (must Set Target be used every turn to maintain its effect?).

In any case, in future design versions, it is likely that some degree of user or AI interface with the effects system will be necessary. The details of "Set Target" and similar effect classes can be fleshed out and refined at that time.

Effect Scope and Scope 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 also evaluated and the scope set before any effects actually fire. The firing of an effect on one object in its scope cannot change the scope by excluding or including other objects from/in the scope.

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.

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 attempt 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 means that the object does not have a particular property, but is distinct from some cases in which an object has a property, but that property is set to "none". (Example: A space monster or uninhabited system are owned by no empire, but both still have the empire ownership property) The hierarchy is thus used only when necessary to determine a property value for a game object.

Note also that targetting of empires, as opposed to other game objects owned by empires, may be "loose". By 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 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.

Some conditions are very nearly duplicated as inclusive and exclusive conditions, for convenience and anticipated game performance reasons.

Inclusive Conditions

All

(No parameters) - All game 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 - Includes objects owned by the specified empire (including objects shared by the source empire and another empire)
  • Empire Exclusive - Includes objects owned by the specified empire only (not including objects shared by the source empire and another empire)
  • Enemies Inclusive - Includes objects owned by empires other than the source empire (including objects shared by the source empire)
  • Enemies Exclusive - Includes objects 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 - Includes objects owned by no empire (eg. space monsters)
  • Empire Exclusive - Includes objects owned by no empire (eg. space monsters)
  • Enemies Inclusive - Includes objects owned by any empire(s)
  • Enemies Exclusive - Includes objects 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) - Adds objects to the scope if their game object type is the specified object type. The specified type may be 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.

Object Class

(Specified Class) - Adds objects to the scope if their object class is the specified object class. The specified class may be an actual type (referenced by unique identifier and defined in an XML file), or may be set relative to the source object for the effect.

Future: Targeted Object

See Future: Set Target effect.

Exclusive Conditions

Empire Affiliation

(Specified Empire, Specifed one of: Empire Inclusive, Empire Exclusive, Enemies Inclusive, Enemies Exclusive) - Excludes objects from the scope based on the empire they are affiliated with. 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 - Excludes objects owned by the specified empire (including objects shared by the source empire and another empire)
  • Empire Exclusive - Excludes objects owned by the specified empire only (not including objects shared by the source empire and another empire)
  • Enemies Inclusive - Excludes objects owned by empires other than the source empire (including objects shared by the source empire)
  • Enemies Exclusive - Excludes objects 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 - Excludes objects owned by no empire (eg. space monsters)
  • Empire Exclusive - Excludes objects owned by no empire (eg. space monsters)
  • Enemies Inclusive - Excludes objects owned by any empire(s)
  • Enemies Exclusive - Excludes objects 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.

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

Object Class

(Specified Class) - Excludes objects from the scope if their object class is the specified object class. The specified class may be an actual type (referenced by unique identifier and defined in an XML file), or may be set relative to the source object for the effect.

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.

Object Type

(Specified Type) - Excludes objects from the scope if their game object type is the specified object type. The specified type may be 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.

Self

(No Parameters) - Excludes the source object from the scope.

Future: Targeted Object

See Future: Set Target effect.

Parameter Values

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

Numeric parameters for most effect or scope conditions may also be based on meter values of the source object or the scope / target object of the effect. Either the current or (if applicable) max meter values of an object may be referenced in this manner. IMPORTANT: Effects that modify current or max meter values may not refer to any meter value to determine their parameter values. This is essential to ensure that order of effect firing does not affect the results of all effects. See Effects System below.

Note that the ability to use dice notation for scope building or limiting conditions is not required (or desired?).

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 meter value is assumed to be 0.

Effects System

Effect Ordering

The main point of effects ordering for v0.3 is that effects that modify current meter values occur separately from other effects.

For v0.3, turn processing should occur in this order:

  • Start of Turn Processing
  • All current meters set to 0
  • All actors iterated through, any effect that modifies a max meter value is fired. (This is the max meter modification effects ordering stage)
  • All actors iterated through, any effect that modifies a current meter value is fired. (This is the current meter modification effects ordering stage)
  • All actors iterated through, any effect that does not modify a meter value is fired. (This is the non-meter modifying effects ordering stage)
  • Balance of Turn - other game systems, movement, combat etc.
  • End of Turn Processing

Effect Processing

When processing effects during one of the effects ordering stages, the following occurs:

  • Game objects are being iterated through, and a particular game object is selected to have its effects processed during this ordering stage
  • If the selected game object has any groups of effects containing effects that can fire during this ordering stage, it is considered further
  • An effect group is selected that contains effects that fire during this ordering stage
  • The inclusive scope conditions for this effects group are applied, building up an initial scope of game objects
  • The exclusive scope conditions for this effects group are applied, excluding objects from the scope
  • All of the effects of the effects group are applied, in order listed, to all of the objects in the scope
  • The processing loops back to cover all effects groups and all game objects