FOCS Scripting Details

From FreeOrionWiki
Revision as of 19:56, 2 July 2004 by Drek (Talk | contribs)

Jump to: navigation, search


Defining Effects

Many objects in the game universe act on other object though Effects. Effects are objects themselves (in the O-O sense of the word).

The following is a list of game objects that can have Effects attached to them:

  • Technologies
  • Structures
  • Government Picks
  • Specials (including Galaxy, Empire, System, and Planet) Note: Events are specials.
  • Racial attributes
  • Leader abilities

In addition to the list above, each planet has a Primary and Secondary Focus. The Foci are Effects.

At the beginning of each turn, the engine iterates through every object in the game, running each effect attached. Multiple effects can be attached to one object.

Basic Effect Traits

All effects have:

  • A short name
  • A Unique ID number (this number is defined for classes of effects, rather than instances…important for stacking checks)
  • A brief description short enough to fit into a tooltip

Implementation note: The tooltip should be generated run-time by a function in the effect class, so that variables can be added to the description.

Scope of Effects

Every effect has a scope:

  • Galaxy wide: This effect acts on every applicable object in the galaxy. Such effects are probably not going to be in v.3, and in any case would be very rare.
  • Empire wide : This effect acts on the meters of the target empire itself, or selects every planet/ship in the empire.
  • Expanded: This effect acts on every object in a target star-system, and every system connected by a starlane to the target.
  • Connecting Starlanes A special scope for selecting ships in starlanes connecting to the target system
  • System-wide: These effects act every object in a target star-system.
  • Local These effects only act on a single target planet

Galaxy, Expanded, Connecting Starlanes and System-wide effects have an additional flag that defines which objects are acted on based on empire affiliation:

  • Effects All: The effect influences every object, regardless of empire affiliation.
  • Exclusive to Empire: The effect only acts on objects owned by the empire generating the effect
  • Exclusive to Friends: The effect only acts on objects owned by the generating empire and allied empires.
  • Exclusive to Enemies: The effect only acts on objects owned by unfriendly empires.

For all effects aside from Unlocking, the type of objects acted on is specified:

  • N/A (used for Unlocking effects, see below)
  • Planets (Local scoped effects are always Planet effects)
  • Ships
  • Leaders
  • Empires (Only Empire-wide or Galaxy scoped events)

The stacking flag determines how each effect stacks with duplicates of the same effect:

  • Stacks normally.
  • Doesn’t stack. Once this particular effect has acted on an object, a duplicated effect of the same class cannot act.

Implementation note: Each effect calls a function to get a list of objects based on the scope of the effect. The effect then iterates through each object, adjusting meters or doing whatever. At the beginning of each turn, all meters are reset to default, and the process re-run for each currently operating effect.

Many effects will have “targets”, which is generally the location of the object generating the effect. The spawning “target” object ought to have it’s own handle, so it can be referenced by the effect.

To check for stacking and provide the player (and a debugging coder) with a ledger of effects acting on objects, the objects themselves should store the IDs of each effect that has acted upon the object. The IDs are for the class of effect, rather than the instanced effect.

Order of Operations

1: Set up --Every meter set to 0

2: Galaxy --Every object "attached" to the galaxy runs through it's effects, adding and subtracting to galaxy meters (mostly objects "attached" to the galaxy would be galaxy-wide events)

3: Empire --Empire meters=empire meters+galaxy meters --Every object attached to each empire (save planets and ships) runs though effects (events, technologies, racial picks, government picks would be typical of objects run at this stage)

4: Planets --Base Enviroment meter is determined through enviromental preference --planet meters=planet meters+empire meters --Every attached object runs through through effects (events, planet specials, buildings, Focus effects would be typical)

5: Execute Last Stage --Any effect encounted in the previous stages with the execute last flag is appened to a list to be executed in this stage. Each Execute Last effect is given a Priority--high Priority effects are executed before lower priority effects. (if an effect has to check the amount of a meter, it needs to be executed in this stage. Effects that are executed last should be relatively rare) --If an Execute Last effects touches the Empire or Galaxy meters, the must also apply the modifer to each applicable planet.

6: Meter Effects (some meters, such as Enviroment, effect other meters. Meters poking at other meters happens in this phase.) --For each planet, check meters and take action where required, in this order:

Enviroment (effects Health, Happiness, Farming)
Health (effects Happiness)
Happiness vs Secuirty (causes cities to rebel)

7:Economy --Nutrients, Minerals, Science, Money, Industry are tallied for each planet --Nutrients divided by Population provides a new modifier to the Health meter. This modifier is applied to the Empire meter, then each planet within the empire. --Population/infrastructure/city/whatever growth is checked for --Industry and mineral are applied to build projects on the queues --Science is applied to research projects on the queues --Unit upkeeps are taxed to Money

Types of Effects


Unlock allows the use of a technology, ship part, or building. These effects must be scoped to either Empire or Galaxy-wide.

(Unlocked technologies must still be researched before their effects come into play. An unlocked building must be built before its effects come into play. Unlocking merely opens the option.)

Influence Meter

Effects can add or subtract to the following meters:

  • Farming
  • Production
  • Mining
  • Science
  • Economy
  • Health
  • Infrastructure (growth of Infra)
  • Security (not in v.3)
  • Happiness (not in v.3)
  • Intelligence (not in v3) (as in spying, not book-learning)

Meters exist on the empire and planet level. Empire level meters are added to the planet level meters before economy calculations are made...a short cut to adding or subtracting to every planet in an empire.

Influence Planet

Effects can directly act on planets within scope

  • Raising/reducing population
  • Raising/reducing infrastructure
  • Razing/building structures in build slots
  • Adding/deleting planet specials
  • Changing the environment
  • Destroying any colony in scope
  • Destroying the entire planet

Implementation note: When a planet is destroyed, it is replaced by an asteroid field with the name “Ruins of planetname” with planetname being the original name. When an asteroid field is destroyed, the planet slot is emptied.

Create/Destroy Specials

Specials can be added and deleted from objects in scope, including the galaxy itself, empires, systems, and planets. (See “Effects with States” below for one reason why this is important.)

Influence Ship

Effects can reduce or increase the properties of ships. These effects are temporary, except for damage to Hit Points:

  • Damage Hit Points
  • Damage Shields
  • Slow/Speed Engines
  • Increase/Decrease Firepower
  • Increase/Decrease Defense

Influence Leader

Effects can act on the properties of Leaders.

Implementation note: Ship and Leader effects are only examples. Effects on ships probably should wait for v.4 to be implemented. Leaders are too ill-defined at this stage to consider effects.

Misc. Topics


Effects can test various conditions within the game, including:

  • the state of meters, both on the planet and empire level
  • the quantity and types of buildings within scope
  • the properties of planets, ships, leaders within scope

Querying the Player

Effects can query the player for input. An EU2-ish Event dialog appears to the player, containing flavor text, an optional picture, and multiple choices. Since effects are calculated during the pre-turn, these event dialogs occur during the pre-turn.

Effects with states

Effects are stateless. To approximate effects with different states, specials can be spawned on planets/systems/empires/or the galaxy itself. For example, an event that occurs in different stages over the course of several turns might spawn a distinct system special for each stage of the event.

Example: A random event is generated, spawning a system special. This special queries the player with a choice. Depending upon the selection made, the effect spawns one special or another then destroys itself. These new specials will act in the next turn, providing more choices that lead to the spawning of more system specials.

The end result is a choose-your-own-adventure style web of events.

A note on the reuse of Effects

It may be advantageous to reuse defined Effects as much as possible, rather than

Obviously, there’d be some generic effects that follow common patterns. It would be cool to use these generics as parents for functioning effect classes.