api_aux.md

Reference

(Fill meeeeeeeeeeeee)

aux.cost.Cost

Cost(Entity):
    payment_mode : PaymentMode

Generalization object for resource and attribute costs.

payment_mode Determines when the costs have to be payed as PaymentMode objects.

aux.cost.type.AttributeCost

AttributeCost(Cost):
    amount : set(AttributeAmount)

Defines the cost as an amount of attribute points that is removed from the game entity's current attribute value.

amount Amounts of attribute points as AttributeAmount objects.

aux.cost.type.ResourceCost

ResourceCost(Cost):
    amount : set(ResourceAmount)

Defines the cost as an amount of resources that is removed from the player's resource pool.

amount Amounts of resources as ResourceAmount objects.

aux.payment_mode.PaymentMode

PaymentMode(Entity):

Generalization object for the payment options of a Cost object.

aux.payment_mode.type.Adaptive

Adaptive(PaymentMode):

The cost is handled as running costs. Payment is progressive (relative to a value, e.g. time) while an action is executed. The action halts if the costs cannot be payed anymore.

aux.payment_mode.type.Advance

Advance(PaymentMode):

The cost is handled as payment in advance. Actions require payment first before they can be executed.

aux.payment_mode.type.Arrear

Arrear(PaymentMode):

The cost is handled as payment in arrear. Actions that require payment are executed first and payed afterwards.

AnimationOverride

AnimationOverride(Entity):
    ability    : Ability
    animations : set(Animation)
    priority   : int

Internally overrides the animations used for an ability. The ability must be an AnimatedAbility when the override occurs. The override stops when

• Another override of the same ability with a greater than or equal to (>=) is initiated
• The overriden ability is deactivated
• The override animation would be the same as the standard animation

ability The ability whos animations should be overriden. This member can reference a specific ability of the game entity or an API ability. If an API ability is referenced, all its instances in the ability set of the game entity will be overriden.

animations The replacement animations of the override.

priority Priority of the override. Overrides are only executed if their priority is greater than or equal to (>=) an already existing override. The default animation of an ability always has a priority of 0.

AvailabilityPrerequisite

AvailabilityPrerequisite(Entity):
    mode : bool

This object is part of a mechanic for unlocking game entities (see CreatableGameEntity) through specifying a set of requirements. (TODO: explain)

Generalization object for a condition that can be either true or false.

mode Determines whether the condition defined by the prerequisite should be negated.

• mode = true: The prerequisite must be true
• mode = false: The prerequisite must be false.

availability_prerequisites.TechResearched

TechResearched(AvailabilityPrerequisite):
    tech : Tech

Is true when the technology has been researched by the player.

tech The technology that has to be researched.

availability_prerequisites.GameEntityProgress

GameEntityProgress(AvailabilityPrerequisite):
    game_entity : GameEntity
    status   ´  : ProgressStatus

Is true when an instance of a game entity owned by the player has reached a certain progress.

game_entity The game entity that should have progressed this far.

status Current status of a game entity as a ProgressStatus object.

AvailabilityRequirement

AvailabilityRequirement(Entity):
    requirements : set(AvailabilityPrerequisite)

This object is part of a mechanic for unlocking game entities (see CreatableGameEntity) through specifying a set of requirements. (TODO: explain)

To evaluate to true, all of the Prerequisites in the AvailabilityRequirement must be true as well.

requirements A number of prerequisites that can be true or false. If all of the prerequisites are true, the availability requirement is fulfilled.

cheat.Cheat

Cheat(Entity):
    activation_message : text
    display_message    : text
    changes            : orderedset(Patch)

Cheats are a predefined gameplay change, often in favor and to the amusement of the player. They are deactivated by default in multiplayer. Advanced cheating behavior can be realized by attaching scripts to the Cheat object.

activation_message The activation message that has to be typed into the chat console.

display_message The displayed message after the cheat is activated as a TranslatedString.

changes Changes to API objects.

Civilization

Civilization(Entity):
    name               : TranslatedString
    description        : TranslatedMarkupFile
    long_description   : TranslatedMarkupFile
    leader_names       : set(TranslatedString)
    modifiers          : set(Modifier)
    starting_resources : set(ResourceAmount)
    civ_setup          : orderedset(Patch)

Civilization customize the base state of the game for a player. This includes availabilitty of units, buildings and techs as well as changing their abilities and modifiers plus their individual members.

name The name of the civilization as a translatable string.

description A description of the civilization as a translatable markup file.

long_description A longer description of the civilization as a translatable markup file. Used for the tech tree help of the civilization.

leader_names Names for the leader of the civilizations that are displayed with the score.

modifiers Modifiers for game entities of the civilization. By default, these modifiers apply to all game entities belonging to the player. For example, an AttributeModifier with multiplier = 1.2 for the attribute Health will increase the maximum HP of every unit owned by the player by 20%. If you want the modifier to only affect specific game entities, you have to use ScopedModifier or assign Modifier objects to individual game entities using civ_setup.

starting_resources The resources of the civilization at the start of a game.

civ_setup Customizes the base state of the game through patches. Any members and objects can be patched. Normal Patch objects will only be applied to the player. To apply patches to other player with specific diplomatic stances, use DiplomaticPatch.

diplomatic_stance.DiplomaticStance

DiplomaticStance(Entity):

Generalization object for diplomaic stances that can be used for diplomacy ingame. Diplomatic stances also define which player can use the abilities, modifiers and effects of a game entity.

diplomatic_stance.Self

Self(DiplomaticStance):

The diplomatic stance of a player towards themselves.

DropoffType

DropoffType(Entity):

Used for calculating the effectiveness over distance of AreaEffects and Accuracy of projectiles. The dropoff modifier is always relational to the maximum range.

dropoff_types.InverseLinear

InverseLinear(DropoffType):

The effectiveness starts at 0% (for zero distance) and linearly increases to 100% (for maximum distance).

dropoff_types.Linear

Linear(DropoffType):

The effectiveness starts at 100% (for zero distance) and linearly decreases to 0% (for maximum distance).

dropoff_types.NoDropoff

NoDropoff(DropoffType):

The effectiveness is constant and independent from the range to the target.

formation.Formation

Formation(Entity):
    subformations : set(Subformation)

Organizational structure for multiple game entities.

subformations Subdivisions of the formation. Game entities are sorted into one of the subformations.

formation.Subformation

Subformation(Entity):

Subdivision of a formation. It defines the structure and placement of game entities when the formation is formed.

formation.PreceedingSubformation

PreceedingSubformation(Entity):
    preceeds : Subformation

Links the individual subformations of a formation together. By using this object, the subformations form a linked list that represents their order in the parent formation.

preceeds Subformation that should be in front of this subformation.

graphics.Animation

Animation(Entity):
    sprite : file

Points to a openage sprite definition file in the .sprite format. The specified aniimation can be used by AnimatedAbility objects.

graphics.Terrain

Terrain(Entity):
    sprite : file

Points to a openage terrain definition file in the .terrain format. This object is used by the terrain.Terrain object that defines properties of ingame terrain.

Language

Language(Entity):
    ietf_string : text

A language definition. Languages are used for translated strings, markup files and sounds.

ietf_string The IETF identification tag of the language. See here for more information on how the tags are established.

language.LanguageMarkupPair

LanguageMarkupPair(Entity):
    language    : Language
    markup_file : file

Defines the translation of a longer text from a markup file in a certain language.

language The language used in the markup file.

markup_file File descriptor of the markup file. Has to be relative to the .nyan file where the LanguageMarkupPair is defined.

language.LanguageSoundPair

LanguageSoundPair(Entity):
    language : Language
    sound    : Sound

Defines the translation of a sound in a certain language.

language The language used for the sound.

sound References the Sound object for the translation.

language.LanguageTextPair

LanguageTextPair(Entity):
    language : Language
    string   : text

Defines the translation of a string in a certain language.

language The language used for the string.

string The translated string.

Mod

Mod(Entity):
    patches : orderedset(Patch)

A set of patches that will be automatically applied when the modpack is loaded. It is recommended to only use one Mod object per modpack since the correct order of patches cannot be guaranteed otherwise.

patches Changes the game state through patches. Any members and objects can be patched. Every Patch will be applied to all players. DiplomaticPatch objects will also be applied to all players.

Patch

Patch(Entity):

Generalization object for all nyan patchesv. Let nyan patches inherit from this object to make them usable for the openage API.

patch.DiplomaticPatch

DiplomaticPatch(Patch):
    stances : set(DiplomaticStance)

A patch that is applied to all players that have the specified diplomatic stances from the viewpoint of the patch's initiator.

stances The diplomatic stances of the players the patch should apply to.

Progress

Progress(Entity):
    progress : int

Generalization object for progression types. Certain properties of a game entity can progress from 0% to 100%. These are for example construction or harvesting progress. Progress objects can define what happens at after a property has reached a specific point of progress.

A Progress object is always tied to an ability.

Specializations:

• AnimatedProgress: Overrides the animation of an ability.
• TerrainProgress: Changes the underlying terrain of the game entity.
• TerrainOverlayProgress: Changes terrain overlays of a game entity.
• StateChangeProgress: Alters the base abilities and modifiers of the game entity through StateChanger objects.

progress An integer between 0 and 100 that represents the percentage of progress after which the progress object is used.

progress.specialization.AnimatedProgress

AnimatedProgress(Progress):
    progress_sprite : AnimationOverride

Overrides the animation of an ability when the specified progress has been reached.

progress_sprite The new animation as an AnimationOverride object.

progress.specialization.StateChangeProgress

StateChangeProgress(Progress):
    state_change : StateChanger

Alters the base abilities and modifiers of a game entity when the specified progress has been reached.

state_change The state modifications as a StateChanger object.

progress.specialization.TerrainOverlayProgress

TerrainOverlayProgress(Progress):
    terrain_overlay : Terrain

Changes overlayed terrain of a game entity when the specified progress has been reached. The game entity needs an enabled OverlayTerrain ability for this to work.

terrain Overrides the overlayed terrain of the currently enabled OverlayTerrain ability of the game entity. The override stops when another terrain overlay override is initiated, the overriden OverlayTerrain ability is deactivated or the override terrain is the same as the default overlayed terrain of the ability.

progress.specialization.TerrainProgress

TerrainProgress(Progress):
    terrain : Terrain

Changes the underlying terrain of a game entity when the specified progress has been reached.

terrain The new terrain that will be permanently placed under the game entity.

progress.types.CarryProgress

CarryProgress(Progress):

Monitors the occupied storage space of a Storage or Gather ability. An empty storage has a progress of 0% and a full storage a progress of 100%.

progress.types.ConstructionProgress

ConstructionProgress(Progress):

Monitors the construction progress of a game entity with Contructable ability. An unconstructed game entity has a progress of 0% and a fully constructed game entity a progress of 100%.

progress.types.DamageProgress

DamageProgress(Progress):

Compares the current attribute value in relation to the max_value of an attribute of a game entity. The Progress objects are stored in a Damageable ability which specifies the type of attribute that is monitored. When the attribute value is equal to max_value of the attribute defined by the game entity, the progress is 0%. Once the attribute value reaches the min_value, the progress is 100%.

progress.types.HarvestProgress

HarvestProgress(Progress):

Monitors the harvesting progress of a resource spot stored by a Harvestable ability. A resource spot with full capacity has a progress of 0% and a fully harvested resource spot a progress of 100%.

progress.types.RestockProgress

RestockProgress(Progress):

Monitors the restock progress of a restockable resource spot stored by a Harvestable ability. The restocking progress is intiated by the Restock ability of another game entity. At the start of the restocking process, the progress is 0%. After the restocking has finished, the progress is 100%.

Restocking progress is only tracked between the start and end of restock process. Therefore, state changes initiated by RestockProgress objects of type StateChangerProgress will be deactivated after the progress reaches 100%.

progress.types.TransformProgress

TransformProgress(Progress):

Monitors the progress of a trasformation initiated by a TransformTo ability. At the start of the transformation, the progress is 0%. After the transformation has finished, the progress is 100%.

Transformation progress is only tracked between the start and end of transformation. Therefore, state changes initiated by TransformProgress objects of type StateChangerProgress will be deactivated after the progress reaches 100%.

ProgressStatus

ProgressStatus(Entity):
    progress_type : ProgressType
    progress      : float

Generalization object for progress status objects required by GameEntityProgress.

progress_type The type of progress.

progress Minimum amount of progress that has to be reached.

Resource

Resource(Entity):
    name        : TranslatedString
    max_storage : int

Defines a resource that can be used in the game. Adding a resources will give an amount of 0 of that resource to all players. The current amount of resources can be influenced by the abilities and modifiers of game entities.

name The name of the resource as a translatable string.

max_storage Maximum amount of resources that can be stored at a time by the player.

resource.ResourceContingent

ResourceContingent(Resource):
    min_amount : int
    max_amount : int

A Resource that creates a contingent which is temporarily usable by game entities. The size of the contingent is determined by two values:

• Static amounts can be aquired like normal resources
• Temporary amounts that can be provided by game entities with ProvideContingent

By using the contingent (see UseContingent ability), the current amount of resources is not reduced. Instead, the game entity will reserve parts of the contingent until it loses the ability or dies. When the whole contingent is reserved, no more game entities using it can be created.

Contingents can be utilized to implement mechanics like Population Space (AoE2) or Supply (Starcraft).

Note that it is also allowed to spend the static amounts determining the contingent size like normal resources.

min_amount The minimum contingent size. Static and temporary amounts will be added to this value.

max_amount The maximum contingent size.

ResourceAmount

ResourceAmount(Entity):
    type   : Resource
    amount : int

A fixed amount of a certain resource.

type The resource.

amount Amount of the resource.

ResourceRate

ResourceRate(Entity):
    type : Resource
    rate : float

A per-second rate of a certain resource.

type The resource.

rate Rate of the resource.

ResourceSpot

ResourceSpot(Entity):
    resource               : Resource
    capacity               : int
    starting_amount        : int
    decay_rate             : float
    harvest_progress       : set(HarvestProgress)
    gatherer_limit         : int
    harvestable_by_default : bool

Amount of resources that is gatherable through the Harvestable ability of a game entity.

resource Type of resource that can be harvested.

capacity Maximum resource capacity of the resource spot.

starting_amount Gatherable amount when the resource spot is created.

decay_rate Determines how much resources are lost each second after the resource spot is activated (see harvestable_by_default for details).

harvest_progress Can alter the game entity the resource spot belongs to after certain percentages of the resource amount are harvested.

gatherer_limit Limits the amount of gatherers that can access the resource spot simultaneously.

harvestable_by_default Determines whether the resource spot is harvestable when it is created. If true, the resource spot will be accessible without any conditions as long as the corresponding Harvestable ability of the game entity is enabled. When set to false, the resource spot must be activated with a MakeHarvestable effect. The conditions under which the activation succeeds are decided by the MakeHarvestable resistance of the game entity the resource spot belongs to.

resource_spots.RestockableResourceSpot

RestockableResourceSpot(ResourceSpot):
    destruction_time_limit : float
    restock_progress       : set(RestockProgress)

Resource spot that can be restocked after the contained resource amount reaches 0.

destruction_time_limit Time until the resource spot is made permanently inaccessible. Afterwards, restocking is impossible.

restock_progress Can alter the game entity the resource spot belongs to after certain percentages of the resource amount are restocked.

sound.Sound

Sound(Entity):
    play_delay : float
    sounds     : orderedset(file)

A collection of sound files that can be played by abilities of a game entity.

play_delay Delay when the sound loops.

sounds A set of sound files that are played in the order they are stored in the set.

state_machine.StateChanger

StateChanger(Entity):
    enable_abilities  : set(Ability)
    disable_abilities : set(Ability)
    enable_modifiers  : set(Modifier)
    disable_modifiers : set(Modifier)
    priority          : int

State changes alter the base state of a game entity which is defined by the abilities and modifers stored in a GameEntity object. They are allowed to enable new and disable existing abilities as well as modifiers. Multiple state changes can be applied at once. Only abilities and modifiers with a priority lower than or equal to (<=) the one defined in the StateChanger object will be disabled.

enable_abilities A set of abilities that are enabled when the state change is active.

disable_abilities A set of abilities that are disabled when the state change is active and the abilities have a priority lower than or equal to (<=) the priority in the disabling StateChanger object.

enable_modifiers A set of modifiers that are enabled when the state change is active.

disable_modifiers A set of modifiers that are disabled when the state change is active and the modifiers have a priority lower than or equal to (<=) the priority in the disabling StateChanger object.

priority Priority of a state change. The value can be negative. Abilities and modifiers belonging to the base state have an implicit priority of 0.

taunt.Taunt

Taunt(Entity):
    activation_message : text
    display_message    : TranslatedString
    sound              : Sound

A predefined message players can send to each other.

activation_message The activation message that has to be typed into the chat console.

display_message The displayed message after the taunt is activated as a TranslatedString.

sound Sounds that are played after the taunt is activated.

Tech

Tech(Entity):
    name             : TranslatedString
    description      : TranslatedMarkupFile
    long_description : TranslatedMarkupFile
    updates          : orderedset(Patch)

An object that can apply changes through patching. It follows the standard implementation from most other strategy games. The Tech object only stores the patches that change the game state, while cost, research time, and requirements are decided by the Research ability of a game entity. By default, technologies can only be applied once and researched by one game entity at a time. Afterwards, the engine sets a flag that the Tech was applied and automatically forbids researching it again.

name The name of the technology as a translatable string.

description A description of the technology as a translatable markup file.

long_description A longer description of the technology as a translatable markup file.

updates Changes the game state through patches. Any members and objects can be patched. Normal Patch objects will only be applied to the player. To apply patches to other player with specific diplomatic stances, use DiplomaticPatch.

Terrain

Terrain(Entity):
    name                      : TranslatedString
    terrain_graphic           : Terrain
    sound                     : Sound
    allowed_types             : set(GameEntityType)
    blacklisted_game_entities : set(GameEntity)
    ambience                  : set(TerrainAmbient)

Terrains define the properties of the ground which the game entities are placed on.

name The name of the terrain as a translatable string.

terrain_graphic Texture of the terrain (see Terrain). openage uses 3D terrain on which the texture is painted on.

sound Ambient sound played when the camera of the player is looking onto the terrain.

allowed_types Game entities that have one of the specified types (see GameEntityType) are allowed to traverse or be placed on the terrain.

blacklisted_game_entities Used to blacklist game entities that have one of the types listed in allowed_types, but must not traverse or be placed on the terrain.

ambience Defines ambient objects placed on the terrain through a set of TerrainAmbient objects.

terrain.TerrainAmbient

TerrainAmbient(Entity):
    object      : Ambient
    max_density : int

An ambient game entity that is placed randomly on a chunk of terrain (10x10 tiles).

object The game entity placed on the terrain.

max_density Defines how many ambient objects are allowed to be placed on a chunk at maximum.

TranslatedObject

TranslatedObject(Entity):

Generalization object for any objects that are or should be different depending on the language. Currently we support translations for strings, markup files and sounds.

translated.TranslatedMarkupFile

TranslatedMarkupFile(TranslatedObject):
    translations : set(LanguageMarkupPair)

The translated versions of a longer text stored in markup files.

translations All translations of the makrup files as language-file pairs (see LanguageMarkupPair).

translated.TranslatedSound

TranslatedSound(TranslatedObject):
    translations : set(LanguageSoundPair)

The translated versions of a sound.

translations All translations of the sound as language-sound pairs (see LanguageSoundPair).

translated.TranslatedString

TranslatedString(TranslatedObject):
    translations : set(LanguageTextPair)

The translated versions of a string.

translations All translations of the string as language-text pairs (see LanguageTextPair).

Variant

Variant(Entity):
    changes  : orderedset(Patch)
    priority : int

Variants can change the game entity when it is created. When variants are chosen depends on their type.

changes The changes to the game entity as a set of patches. Only the created game entity is affected.

priority When many variants are chosen, this member influences the order in which the patches from their changes member are applied. Patches from variants with higher priority value are applied first.

variants.RandomVariant

RandomVariant(Variant):
    chance_share : float

From all variants of this type in the variants member of the game entity, one will be picked at random.

chance_share The relative chance of the variant to be picked. Note that this is not a percentage chance. The value defines how likely it is for the variant to be chosen relative to the other RandomVariant objects.

Example:

• Random variant 1 with chance_share = 1.0
• Random variant 2 with chance_share = 4.0

The second variant is four times as likely to be picked. The absolute chances are:

• Random variant 1: 20%
• Random variant 2: 80%

variants.PerspectiveVariant

PerspectiveVariant(Variant):
    angle : int

Variant depending on the placement angle of the game entity. Cuurently only works with the PlacementMode of type Place with the allow_ratation member set to true.

angle Angle of the game entity. An angle of 0 points to the south-west direction.

variants.AdjacencyVariant

AdjacentTilesVariant(Variant):
    north      : optional(GameEntity)
    north_east : optional(GameEntity)
    east       : optional(GameEntity)
    south_east : optional(GameEntity)
    south      : optional(GameEntity)
    south_west : optional(GameEntity)
    west       : optional(GameEntity)
    north_west : optional(GameEntity)

A variant that is chosen based on adjacent game entities. Both the created game entity and the adjacent game entities must have the TileRequirement ability. From all AdjacentVariant variants the one with the most matches in all directions is chosen.

north The desired game entity north of the created game entity. Does not have to be set.

north_east The desired game entity north-east of the created game entity. Does not have to be set.

east The desired game entity east of the created game entity. Does not have to be set.

south_east The desired game entity south-east of the created game entity. Does not have to be set.

south The desired game entity south of the created game entity. Does not have to be set.

south_west The desired game entity south-west of the created game entity. Does not have to be set.

west The desired game entity west of the created game entity. Does not have to be set.

north_west The desired game entity north-west of the created game entity. Does not have to be set.