Difference between revisions of "FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
Line 1: Line 1:
(Unofficial)
+
=Effects=
  
==Defining Effects==
+
==Unofficial==
Many objects in the game universe act on other object though Effects.  Effects are objects themselves (in the O-O sense of the word).
+
Contents of this document have not undergone public review.
  
The following is a list of game objects that can have Effects attached to them:
+
==Introduction==
* Technologies
+
Each tech, building, and planet special will probably be encoded as XML, including mark-up tags describing the effects of the object.  
* 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 FocusThe Foci are Effects.
+
In v.3, if these are the only two classes of effects:  Modify Meter and Unlock ItemAn objects can have multiple effects, but no conditions beyond what is offered by the Effect Classes.
  
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.
+
==Modify Meter==
  
 +
===Effect Name===
 +
The name of the effect, mostly for internal usage.  Effects can share the same name, meaning they will not stack if the stacking flag is set.  Effects that share names should have identical bonuses.)
  
==Basic Effect Traits==
+
(programming note: "sharing a name" means that they share the same StackingID.)
  
All effects have:
+
===Scope===
* A short name
+
• Galaxy  The effect operates on the meters of every planet in the galaxy
* A Unique ID number (this number is defined for classes of effects, rather than instances…important for stacking checks)
+
• Empire  The effect operates on the meters belonging to every planet in the empire. 
* A brief description short enough to fit into a tooltip
+
• Sector    The effect operates on the meters belonging to the planets contained by the Target system and any planets in systems connected to the target system by a starlane or wormhole. 
 +
• System  The effect operates on the meters belonging to the planets contained by the Target system. 
 +
• Planet  The effect operates on a single planet.
  
''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.''
+
===Effect Affiliation===
 +
•  All: The effect influences the meters of every planet, regardless of empire affiliation.
 +
•  Exclusive: The effect only acts on planets owned by the target Empire. 
 +
•  Friends: The effect only acts the meters of on objects owned by the target Empire and allied Empires.  (not required in v.3)
 +
• Enemies: The effect only acts the meters of objects owned by empires unfriendly with the target Empire. (every empire is considered unfriendly in v.3)
  
==Scope of Effects==
+
===Meter===
 +
•  Farming 
 +
•  Industry
 +
•  Mining
 +
•  Science
 +
•  Economic
 +
•  Health  (growth of Population)
 +
•  Construction (growth of Infra)
 +
•  Enviroment (The results of Enviromental Preference)
 +
•  Security (not in v.3)
 +
•  Happiness (not in v.3)
  
Every effect has a scope:
+
===Type of Modification===
 +
* Additive  The default. 
 +
* Multiplicative  Should be used rarely.  The Modification value is multiplied with the Multiplier of the meter.  (The Meter’s multiplier is then multiplied with the meter itself after all effects have executed.)
  
* 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.
+
===Value of Modification===
* Empire wide : This effect acts on the meters of the target empire itself, or selects every planet/ship in the empire.
+
The value that is added to or multipled with the meter.  
* 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
+
  
 +
===Stacking===
 +
Does the effect stack?
  
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.
+
===Focus Condition===
* Exclusive to Empire: The effect only acts on objects owned by the empire generating the effect
+
* None  Effect occurs regardless of planet focus
* Exclusive to Friends: The effect only acts on objects owned by the generating empire and allied empires.
+
* Primary  Effect only occurs if the Meter being modified is set as the Primary
* Exclusive to Enemies: The effect only acts on objects owned by unfriendly empires.
+
* Secondary  Effect only occurs if the Meter being modified is set as Primary or Secondary
  
For all effects aside from Unlocking, the type of objects acted on is specified:
+
===Infra Condition===
* N/A (used for Unlocking effects, see below)
+
If total infrastructure is less than this value, the effect is canceled.
* 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:
+
===Enviromental Condition==
* Stacks normally. 
+
Either None, or the Enviroment in which this effect operates:
* 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.''
+
* Terran
 +
* Ocean
 +
* Swamp
 +
* Toxic
 +
* Inferno
 +
* Radiated
 +
* Barren
 +
* Turdra
 +
* Desert
 +
* Gaian
  
''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.''
+
===Description===
 +
Appended to the tooltip of the affected meter.  
  
''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.''
+
==Unlock Item==
  
==Order of Operations==
+
Techs, buildings, and ship parts can be unlocked.  An unlocked Tech can be researched, an unlocked building or ship part can be constructed.
1: Set up
+
--Every meter set to 0
+
  
2: Galaxy
+
===Type===
--Every object "attached" to the galaxy runs through it's effects, adding and subtracting to galaxy meters
+
The nature of the item being unlocked:
(mostly objects "attached" to the galaxy would be galaxy-wide events)
+
* Tech  A single technology
 +
* Tech Branch  An entire branch of the tech tree.
 +
* Building
 +
* Ship Part  (in version v.3, ship "parts" are scout, colony, mark I-V)
  
3: Empire
+
===ItemID===
--Empire meters=empire meters+galaxy meters
+
The unique name of the item being unlocked.
--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
+
===Duration===
--Base Enviroment meter is determined through enviromental preference
+
* Permanent  The item remains unlocked for the entire game.
--planet meters=planet meters+empire meters
+
* Life of Effect  When the effect is destoyed, the item returns to being
--Every attached object runs through through effects
+
(events, planet specials, buildings, Focus effects would be typical)
+
  
5: Execute Last Stage
+
locked. For example, if a buiding that opens up a special part of the  
--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
+
tech tree is destoryed, that branch of the tree would be closed for
(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
+
research.
--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==
 
  
===Unlocking===
+
==Examples==
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.)
+
===Universal University===
 +
(building)
 +
The Universal University offers a quality education to budding young science geeks.
  
===Influence Meter===
+
The U.U. has two effects:
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===
+
Advanced Education
Effects can directly act on planets within scope
+
Scope: Empire
* Raising/reducing population
+
Affliation: Exclusive
* Raising/reducing infrastructure
+
Meter: Science
* Razing/building structures in build slots
+
Type of Modification: Additive
* Adding/deleting planet specials
+
Value of Modification: +1
* Changing the environment
+
Stacking:  Does not stack
* Destroying any colony in scope
+
Focus Condition: None
* Destroying the entire planet  
+
Infra Condition: 5
 +
Enviro Condition: None
 +
Description: +1 Science to Developed worlds from Universal University
  
''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.''
+
Science Inspiration
 +
Scope: Sector
 +
Affliation: Friends
 +
Meter: Science
 +
Type of Modification: Additive
 +
Value of Modification: +1
 +
Stacking: Does not stack
 +
Focus Conditions: Primary
 +
Infra Conitions: 5
 +
Enviro Condidtion: None
 +
Description: +1 Research to Developed Science worlds, due to a nearby Universal University
  
 +
===Ocean Survival===
 +
(Tech)
 +
Your empire has developed methods of surviving and exploiting Ocean worlds.
  
===Create/Destroy  Specials===
+
Two effects:
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.)
+
Floating Platforms
 +
Scope: Empire
 +
Affliation: Exclusive
 +
Meter: Enviroment
 +
Type of Modification: Additive
 +
Value of Modification: +2
 +
Stacking: Does not stack
 +
Focus Condition: None
 +
Infra Condition: None
 +
Enviro Condition: Ocean
 +
Description: +2 Enviroment from Ocean Survival
  
===Influence Ship===
+
Fish n' Chips
Effects can reduce or increase the properties of ships.  These effects are temporary, except for damage to Hit Points:
+
Scope: Empire
* Damage Hit Points
+
Affliation: Exclusive
* Damage Shields
+
Meter: Farming
* Slow/Speed Engines
+
Type of Modification: Additive
* Increase/Decrease Firepower
+
Value of Modification: +1
* Increase/Decrease Defense
+
Stacking: Does not stack
 +
Focus Condition: Secondary
 +
Infra Condition: 1
 +
Enviro Condition: Ocean
 +
Description: +1 Food to Ocean Farming Worlds from Ocean Survial
  
===Influence Leader===
+
===Hostile Microcobes===
Effects can act on the properties of Leaders.
+
(Planet Special)
 +
Nasty little one celled horrors have proven resistant to extermination.
  
''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.''
+
Two effects:
 +
Sickness
 +
Scope: Planet
 +
Affliation: Exclusive
 +
Meter: Health
 +
Type of Modification: Additive
 +
Value of Modification: -1
 +
Stacking: Stacks
 +
Focus Condition: None
 +
Infra Condition: 0
 +
Enviro Condition: None
 +
Description: -1 Health due to the Hostile Microcobes
  
==Misc. Topics==
+
Hostile Biology
===Conditions===
+
Scope: Planet
Effects can test various conditions within the game, including:
+
Affliation: Exclusive
 +
Meter: Enviroment
 +
Type of Modification: Additive
 +
Value of Modification: -2
 +
Stacking: Does not stack
 +
Focus Condition: None
 +
Infra Condition: 0
 +
Enviro Condition: None
 +
Description: -2 Enviroment, because this planet's life hates you
  
* 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.
 
  
 +
==Future Effects==
 +
There will be more Effect Classes in future versions, possibly
  
===Effects with states===
+
including:
  
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.   
+
===Modify ShipPart===
 +
A modification of ship parts, improving or penalizing various stats.   
  
Example:
+
This is meant for techs that refine parts, or buildings that give bonuses to certain unit types.
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.
+
===Modify Infrastructure===
 +
Directly effects the infrastructure (ie, Current Meter) of a planet, rather than the Max Meter.  Useful for events like bombings or earthquakes.
  
===A note on the reuse of Effects===
+
===Events style effects===
It may be advantageous to reuse defined Effects as much as possible, rather than
+
Like the multiple choice events in EU2.  If the game has 'em, it will probably require some kind of scripting.
 
+
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.
+

Revision as of 09:47, 3 July 2004

Effects

Unofficial

Contents of this document have not undergone public review.

Introduction

Each tech, building, and planet special will probably be encoded as XML, including mark-up tags describing the effects of the object.

In v.3, if these are the only two classes of effects: Modify Meter and Unlock Item. An objects can have multiple effects, but no conditions beyond what is offered by the Effect Classes.

Modify Meter

Effect Name

The name of the effect, mostly for internal usage. Effects can share the same name, meaning they will not stack if the stacking flag is set. Effects that share names should have identical bonuses.)

(programming note: "sharing a name" means that they share the same StackingID.)

Scope

• Galaxy The effect operates on the meters of every planet in the galaxy • Empire The effect operates on the meters belonging to every planet in the empire. • Sector The effect operates on the meters belonging to the planets contained by the Target system and any planets in systems connected to the target system by a starlane or wormhole. • System The effect operates on the meters belonging to the planets contained by the Target system. • Planet The effect operates on a single planet.

Effect Affiliation

• All: The effect influences the meters of every planet, regardless of empire affiliation. • Exclusive: The effect only acts on planets owned by the target Empire. • Friends: The effect only acts the meters of on objects owned by the target Empire and allied Empires. (not required in v.3) • Enemies: The effect only acts the meters of objects owned by empires unfriendly with the target Empire. (every empire is considered unfriendly in v.3)

Meter

• Farming • Industry • Mining • Science • Economic • Health (growth of Population) • Construction (growth of Infra) • Enviroment (The results of Enviromental Preference) • Security (not in v.3) • Happiness (not in v.3)

Type of Modification

  • Additive The default.
  • Multiplicative Should be used rarely. The Modification value is multiplied with the Multiplier of the meter. (The Meter’s multiplier is then multiplied with the meter itself after all effects have executed.)

Value of Modification

The value that is added to or multipled with the meter.

Stacking

Does the effect stack?


Focus Condition

  • None Effect occurs regardless of planet focus
  • Primary Effect only occurs if the Meter being modified is set as the Primary
  • Secondary Effect only occurs if the Meter being modified is set as Primary or Secondary

Infra Condition

If total infrastructure is less than this value, the effect is canceled.

=Enviromental Condition

Either None, or the Enviroment in which this effect operates:

  • Terran
  • Ocean
  • Swamp
  • Toxic
  • Inferno
  • Radiated
  • Barren
  • Turdra
  • Desert
  • Gaian

Description

Appended to the tooltip of the affected meter.

Unlock Item

Techs, buildings, and ship parts can be unlocked. An unlocked Tech can be researched, an unlocked building or ship part can be constructed.

Type

The nature of the item being unlocked:

  • Tech A single technology
  • Tech Branch An entire branch of the tech tree.
  • Building
  • Ship Part (in version v.3, ship "parts" are scout, colony, mark I-V)

ItemID

The unique name of the item being unlocked.

Duration

  • Permanent The item remains unlocked for the entire game.
  • Life of Effect When the effect is destoyed, the item returns to being

locked. For example, if a buiding that opens up a special part of the

tech tree is destoryed, that branch of the tree would be closed for

research.


Examples

Universal University

(building) The Universal University offers a quality education to budding young science geeks.

The U.U. has two effects:

Advanced Education Scope: Empire Affliation: Exclusive Meter: Science Type of Modification: Additive Value of Modification: +1 Stacking: Does not stack Focus Condition: None Infra Condition: 5 Enviro Condition: None Description: +1 Science to Developed worlds from Universal University

Science Inspiration Scope: Sector Affliation: Friends Meter: Science Type of Modification: Additive Value of Modification: +1 Stacking: Does not stack Focus Conditions: Primary Infra Conitions: 5 Enviro Condidtion: None Description: +1 Research to Developed Science worlds, due to a nearby Universal University

Ocean Survival

(Tech) Your empire has developed methods of surviving and exploiting Ocean worlds.

Two effects: Floating Platforms Scope: Empire Affliation: Exclusive Meter: Enviroment Type of Modification: Additive Value of Modification: +2 Stacking: Does not stack Focus Condition: None Infra Condition: None Enviro Condition: Ocean Description: +2 Enviroment from Ocean Survival

Fish n' Chips Scope: Empire Affliation: Exclusive Meter: Farming Type of Modification: Additive Value of Modification: +1 Stacking: Does not stack Focus Condition: Secondary Infra Condition: 1 Enviro Condition: Ocean Description: +1 Food to Ocean Farming Worlds from Ocean Survial

Hostile Microcobes

(Planet Special) Nasty little one celled horrors have proven resistant to extermination.

Two effects: Sickness Scope: Planet Affliation: Exclusive Meter: Health Type of Modification: Additive Value of Modification: -1 Stacking: Stacks Focus Condition: None Infra Condition: 0 Enviro Condition: None Description: -1 Health due to the Hostile Microcobes

Hostile Biology Scope: Planet Affliation: Exclusive Meter: Enviroment Type of Modification: Additive Value of Modification: -2 Stacking: Does not stack Focus Condition: None Infra Condition: 0 Enviro Condition: None Description: -2 Enviroment, because this planet's life hates you


Future Effects

There will be more Effect Classes in future versions, possibly

including:

Modify ShipPart

A modification of ship parts, improving or penalizing various stats.

This is meant for techs that refine parts, or buildings that give bonuses to certain unit types.

Modify Infrastructure

Directly effects the infrastructure (ie, Current Meter) of a planet, rather than the Max Meter. Useful for events like bombings or earthquakes.

Events style effects

Like the multiple choice events in EU2. If the game has 'em, it will probably require some kind of scripting.