FOCS Scripting Details

From FreeOrionWiki
Revision as of 06:18, 28 May 2004 by (Talk)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 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 empire itself, or selects every planet/ship in the empire.
  • Expanded: This effect acts on the meters of 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
  • System-wide: These effects act on the meters of every object in a target star-system.
  • Local These effects only act on a single target planet

Galaxy, Expanded, 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 object 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. 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 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.

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...they are 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.