FOCS Scripting Details

From FreeOrionWiki
Revision as of 17:02, 21 July 2004 by Drek (Talk | contribs) (=System Effects=)

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”.
  • Diplomatic Affiliation There is no diplomacy in v.3. For now, diplomatic affiliation can be set to “self” and/or “enemy”. 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".
  • 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.
  • 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.
  • 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 target empire. 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.
  • War War, Peace, or None. This condition tests the target empire. 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.

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.

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.

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.

Every System Effect can have following 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.

Every Planet Effect can have following 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.
  • TODO

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.

TODO