FOCS Scripting Details

From FreeOrionWiki
Revision as of 17:52, 21 July 2004 by Drek (Talk | contribs) (=Modify Meters=)

Jump to: navigation, search

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

Effects

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.

Most effects have:

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

All Effects can impose the following conditions:

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

Generic Effects

These effects can be applied regardless of target type.

Destroy Actor

Used to remove events, specials, buildings, etc. from the target.

  • List of Actors A list of events and/or specials. If 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

Note: in v.3, only applies to planets, as other objects do not have meters.

Adds or subtracts from the object's meters.

  • Meters A list of meters.
  • 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.
  • Modification Type A flag set to “Additive”, “Multiplicative”, "Scaled by Meters", or "Scaled by Count".
    • 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.
    • If Scaled by Meters then the list of meters used in the conditions are referenced to determine the amount of change to the effected meters. For 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 meters. A 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

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.


Galaxy Effects

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.


Empire Effects

Empire effects can be used to spawn/de-spawn Actors, modify the Empire’s stockpiles, and unlock techs/buildings. In 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”.

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

  • Self The target empire
  • Galactic All empires in the game, excluding “Self”.
  • Neighbors All empires sharing a border with the target

Empire: Learn Technology

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

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

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.
  • Galactic All regions in the game, excluding the target region
  • Tangent All regions that "touch" the target system

System Effects

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.

System effects can be set to the following scopes. A single effect can have multiple scopes:

  • 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:

  • 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

Used to change the color of all stars in scope that have met conditions.

  • Star Color The color to set. Default is yellow.

System: Modify Planet Slot

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 colony. Default 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.

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

Planet effects can be set to the following scopes. A single effect can have multiple scopes:

  • 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 reaches. Setting 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 condition. Setting distance to “0” will include all planets in the target system.

Planet Effects can have following conditions in addition to the generic conditions:

  • 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 colors. If 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

Used to change the environment and size of all planets within scope.

  • Environment The environment to set. If set to “None” the planet is destroyed. If 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 destroyed. If set to “NoEffect” the planet’s current size is maintained. Default is NoEffect.

Planet: Unlock Item

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

In the future, it will be possible to spawn and destroy ships and modify the properties of ships via modify meters. Ship effects will be detailed in v.4.