FOCS Scripting Details
Contents of this document have not passed public review. Comments are welcome on the talk page.
"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 to the following effects 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. The meters of the source object are referenced.
Example: A parameter might read: 1d4+Farming, meaning 1 to 4 added to the Farming meter of the source object (or the parent planet of a building).
If a meter is not present on a source object, the value is assumed to be 0.
- 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 include and then exclude game objects from the set. The scope of an effect is nothing by default, and is first increased and then reduced by the various scope conditions. The conditions are evaluated at the time the effect fires, so an object may be part of an effect's scope for one firing, but not another firing. Inclusive conditions are executed first, and then exclusive conditions.
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
Scope starts with no objects. Inclusive conditions are run first, filling scope with potential targets. Then exclusive conditions are checked, widdling down the targets in scope.
An effect can have multiple exclusive and inclusive conditions.
(note to Geoff: for performance reason I don't think we should start with every object in scope. Hopefully, you agree with this change: I think it would be murder for every effect to widdle down to it's targer from every object, esp. since many effects will probably just effect the source object and/or it's neighbors in the same system.) #TODO: remove this note
- Galaxy No parameters. All objects are included in scope.
- Empire No parameters. All objects within the source object's empire are added to scope. Useful as shorthand for technologies that effect every planet in an empire. (or unlock new techs, buildings, etc.)
- Self (true or false) - If set to true, the source object is included into scope, though it may later be excluded due to other conditions. If set to false, this condition counts as "exclusive": the source object is excluded from scope.
- Direct Distance (Specified Distance) - Includes 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 the source object and objects within the source object's star system are included.) Note: Distance can be expressed via the dice and meter notion discussed in the previous section.
- Starlane Jumps (Specified Number) - Includes 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 the source object and objects within the source object's star system are included.) Note: Distance can be expressed via the dice and meter notion discussed in the previous section.
- 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 (Focus, "Secondary" or "Primary") Excludes objects not set to the specified focus, at the specified level or better.
- 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.
- 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.