Talk:FOCS Scripting Details

(This was stuff that was previously on the infrastructure scratchpad)

Actors & Effects

Definition

Effects are changes/modifications to game objects. Actors are lists of Effects that function as a group.

Theory & Practice

Actors are of particular "types" (or "classes"). When actors are created, their type determines the effects that they contain, and any variable details of how each effect functions. Effects are also of particular types, and the details needed to specify how they function depend on their type. The description of an actor type contains a list of effect types and anys needed to specify how the effects will work.

All existing actors are iterated through several times while processing a turn. On each iteration, a particular effect may or may not be fired, depending what time during the turn it is set to fire. Effects are also given a chance to fire that is applied individually to each object in the effect's scope/restrictions.

Buildings, specials, techs and game mechanisms like a random event generator could all be treated as actors, or associated with a particular actor.

Description Actors

(Programmer comment/tweaking encouraged.)

Types of actors probably described in an XML file. Description contains data such as name, duration, number and list of descriptions of effects.

For Duration, may want to use values in this manner:

• -1 -> infinite duration -> never goes away on its own (may be destroyed by an effect in future versions. Remains forever in v0.3)
• 0 -> instant -> effects of actor fire immediately at time actor is created, but actor does not continue to exist for rest of turn (ie. if made in pre-movement phase, does not still exist or fire effects in post-movement. if made in post-movement, does not exist in next turn's meter accumulation or pre-movement)
• 1 or more -> limited lifetime -> disappears after # turns (at end of turn, or start... whichever)

Actors with nonzero, noninfinite duration disappear after their duration (in turns) is up.

Description of Effects

(Programmer comment/tweaking encouraged.)

Effects descriptions are parts of Actor descriptions. Each contains data such as the effect type, what phase of the turn processing in which to fire effect, chance to fire on each object in scope, details of what game objects are in scope, a specific target game object, an "affiliation" restriction on scope that works with target, and various other effect-type-specific details.

Some details to include:

• Turn Phase: Which phase of turn in which to fire effect. See Effects System. Meter Modifying effects ignore this parameter
• Effect Chance: If an object meets all restrictions on the effect's scope, this is the chance that the effect will "fire" on that object
• Effect Target: Works with Affiliation to determine which objects effect will "fire" on.
• Effect Scope: Physical location restrictions on what objects will be "fired" on by effect
  • Galaxy -> All objects... no restriction
  • Empire -> All objects in a system with a planet owned by empire of target object
  • Distance -> All objects within Scope Range parameter distance of target object
  • StarLaneJumps -> All objects within Scope Range parameter starlane jumps of target object. Partial starlane jumps count as a full jump (eg. if target is a ship on a starlane, not at a plant)
  • System -> All objects in system of target object (later: or in fleet travelling with target ship)
  • Personal -> Target Object Only
• Effect Scope Range: How many "lightyears" or starlane jumps for respective scope restrictions
• Effect Affiliation: Restricts list of objects effect will fire on based on the empire that owns them.
  • TargetEmpireOnly -> objects owned by empire of target object only
  • TargetAllies -> objects owned by empire of target object, or owned by ally of empire that owns target object (meaningless in v0.3)
  • TargetEnemies -> objects owned by empires that are enemies of the empire that owns the target object
  • All -> object owned by any empire (no restriction)

Effects System

The processing of a game turn proceeds in this order:

• Start of Turn Processing - all meters set to 0
• Meter Accumulation Phase - All actors iterated through, any effect that modifies a meter is fired
• Upkeep Phase - Production/resource creation, pop growth/starvation, creation of new ships, etc.
• Pre-Movement Effect Phase - All Actors are iterated through. Any effect that is marked for this phase in its definition is fired. Any Actors summoned with duration 0 by an Actor effect fire their effects immediately. Any Actors summomed with duration other than 0 do not fire now (but can fire in post-movement phase)
• Action Phase - Ship movement, battles, etc.
• Post-Movement Effect Phase - All Actors are iterated through, any effect that is marked for this phase in its definition is fired. Actors created in the Pre-Movement Effect Phase are included in the iteration. 0 duration actors summoned fire effects immediately. non-0 duration Actors created in this phase do not function this turn, but will function starting in the Meter-Accumulation Phase or Pre-Movement Phase of next turn.
• End of Turn Processing

Effects for v0.3

For v0.3, effects only function on:

• Planets - meter modification, changing environment/size/population etc.
• Empires - locking/unlocking reserach, buildings, ship types, stockpile modification
• Actors - via the SpawnActor effect

Unless stated otherwise, an effect can be set to work in either the pre-movement or post-movement phase.

Specific Effects:

• Modify Max Meter - Adds or subtracts from a planet's max meters this turn. Only functions during the meter accumulation phase. Does not affect current meter values.

• Modify Current Meter - Adds or subtracts from a planet's current meter values. Can function at any time. Does not affect max meter values.

• Modify Stockpile - Adds or subtracts from one of empire's stockpiles.

• Modify Planet Build Slots - Adds or removes buildings to/from build slots of planets

• Modify Planet Size/Environment - Sets the size and environment of a planet

• Destroy Planet - Destoys Planet (may be lumped with modify planet size/environment by setting size to "none")

• Modify Planet Population - Adds or subtracts from planet's population.

• Set Research - Sets a tech a researched or not reserached.

• Set Building Availability - Sets a building type as buildable or not buildable.

• Set ShipeType Availability - Sets a ship class as buildable or not buildable.