FOCS Scripting Details
"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. 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 Current Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's current meter values. Does not affect max meter values.
- Modify Stockpile (Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
- 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.
- Destroy Object - Destroys a game object.
- Set Research (Specified Technology) - Sets a tech a researched or not reserached.
- Set Building Availability (Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not.
- Set Ship Type Availability (Specified Ship Class, Specified Buildable / Not Buildable) - Sets a ship class as buildable or not buildable.
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 conditions. The conditions are evaluated at the time the effect fires, so an object may be part of an effect's scope for one firing, but not another firing. All conditions are exclusive: applying a condition to a scope set for an effect can only remove objects from the scope, or leave the scope unchanged, and can never add more objects back into the scope that were previously removed by other conditions. Thus, the order in which conditions are applied does not affect the contents of the final scope set fired upon by the effect.
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).
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 maybe be set relative to the source object for the effect.
- 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.
- Source Object Meter (Specified Meter, Specified Value) -
- Scope Object Meter (Specified Meter, Specified Value) -
- Scope Object Visible To Source Object (Specified True / False) -
- Source Object Visible To Scope Object (Specified True / False) -
- Scope Object Stockpile (Specified Resource, Specified Value) -
- Source Object Stockpile (Specified Resource, Specified Value) -