reference_ability.md

engine.ability

Reference documentation of the engine.ability module of the openage modding API.

ability.Ability

Ability(Object):
    properties : dict(abstract(AbilityProperty), AbilityProperty) = {}

Generalization object for all abilities. Abilities define what game entities can do and what they are, respectively. They can be considered passive and active traits.

properties Further specializes the ability beyond the standard behaviour.

The engine expects objects from the namespace engine.ability.property.type as keys. Values must always be an instance of the object used as key.

Standard behavior without properties:

• Abilities in the abilities set of GameEntity are considered enabled as soon as the game entity is created, unless a StateChager object disables them.
• No ability is explicitly required to be animated or to play a sound. For this purpose, ability properties are used.
• A game entity's abilities are available to all players, not just the owner. This can be limited to players with specific diplomatic stances towards the owner by assigning the Diplomatic property.
• An ability's execution does not block any other ability, unless explicitely defined by the API.

Properties:

• Animated: Assigns an animation that is played while the ability is active.
• AnimationOverride: Overrides the animations of specified animated abilities temporarily.
• CommandSound: Assigns a sound that is played once when the player orders the game entity to use the ability.
• Diplomatic: Makes the ability only accessible for players when the owner of the game entity has the specified diplomatic stances towards them.
• ExecutionSound: Assigns a sound that is played while the ability is active.
• Lock: Assigns the ability to a lock pool.

ability.property.AbilityProperty

AbilityProperty(Object):
    pass

Generalization object for all properties of abilities.

ability.property.type.Animated

Animated(AbilityProperty):
    animations : set(Animation)

Play an animation while the ability is used. The animation itself is configured in the .sprite file linked in the Animation object.

animations The animation(s) played while the ability is used. If more than one animation is defined, the engine randomly picks one of them.

ability.property.type.AnimationOverride

AnimationOverride(AbilityProperty):
    overrides : set(AnimationOverride)

Specifies a set of animation overrides that are applied when the ability is used.

Usage example: Consider a unit with two attacks. One of them is animated by having the unit wield a sword, while the other one is an animation in which the unit uses a bow. What we want is that the animation of the Move and Idle abilities correspond to the attack that was used last, e.g. after a sword attack, the movement animation show the unit moving around with a sword in its hand, and after a bow attack, the movement animation show the unit moving around with a bow. To accomplish this, we would add the AnimationOverride(AbilityProperty) to both attack abilities and specify AnimationOverride objects for them which target Move and Idle.

overrides Overrides initiated when using the ability.

ability.property.type.CommandSound

CommandSound(AbilityProperty):
    sounds : set(Sound)

Abilities with this property will play a sound once when the player orders the game entity to use them.

sounds Sound(s) played when the order to use the ability is given. If more than one sound is defined, the engine randomly picks one of them.

ability.property.type.Diplomatic

Diplomatic(AbilityProperty):
    stances : set(children(DiplomaticStance))

Restricts the players who can access the ability. Access is given to a player when the owner of the game entity has one of the specified stances towards this player. Note that when using this property, the access must also be explicitly allowed for the owner of the game entity by adding the Self stance to the set.

Usage example: Consider a trade post like the marketplace from AoE games. Players can send trade carts between trade posts to generate resources. Trade post behavior is activated by assigning the TradePost ability to a game entity. Without the Diplomatic property, all player can trade with this trade post, including its owner. However, if we want to limit the trade post to only be accessible for allies, we assign Diplomaticas a property and add the Allied stance to the stances set.

stances Whitelist of stances of the game entity owner towards other players. Only players that match these stances from the owner's perspective can use the ability.

ability.property.type.ExecutionSound

ExecutionSound(AbilityProperty):
    sounds : set(Sound)

Abilities with this property will play a sound while they are active.

sounds The sound(s) played while the ability is used. If more than one sound is defined, the engine randomly picks one of them.

ability.property.type.Lock

Lock(AbilityProperty):
    lock_pool : LockPool

Abilities with this property require a free slot in the specified lock pool to become active. While they are active, they occupy one slot in the lock pool. This property can be used to prevent abilities from specific abilities being executed simultaneously.

Usage example: Consider a game entity that has the abilities Create for producing game entities and Research for researching techs. At runtime, only one of them should be active at the same time, i.e. the game entity should either produce a game entity or research a tech, not both. We can realize this by assigning both abilities the Lock property which references the same LockPool object (which has 1 slot). As a consequence, Create cannot be used together with Research as they both require 1 free slot to be used.

lock_pool The lock pool used by the ability. This lock pool should be assigned to a Lock ability that is assigned to the game entity.

If the lock pool

• is not assigned to a Lock ability of the game entity or
• the corresponding Lock ability is disabled or
• all slots are occupied by other abilities at runtime

the ability with this property cannot become active.

ability.property.type.Ranged

Ranged(AbilityProperty):
    min_range : float
    max_range : float

Abilities with this property can only be used within a specified range around the game entity. The property mostly affects abilities that are targeted, i.e. that are used on other game entities or locations in the game world.

If the target of the ability is another game entity and said game entity has a Collision ability, the range check factors in the Hitbox boundaries of the targeted game entity when calculating the distance.

Without this property, abilities behave as if min_range and max_range are 0.0.

min_range Minimum distance to the target of the ability.

max_range Maximum distance to the target of the ability.

ability.type.ActiveTransformTo

ActiveTransformTo(Ability):
    target_state       : StateChanger
    transform_time     : float
    transform_progress : set(Progress)

Activates a state change for a game entity. Triggered by player input.

target_state Target state change that activates when the time defined in transform_time has passed.

transform_time The time for the transformation to complete.

transform_progress A set of Progress objects that can activate state changes and animation overrides while the transformation progresses. The objects in the set must have progress type Restock.

ability.type.Activity

Activity(Ability):
    graph: Activity

Defines the behaviour of a game entity. The behaviour is modelled as a directed node graph. Nodes in the graph correspond to actions that execute for the game entity or conditional queries and event triggers that indicate which path to take next. By traversing the node graph along its paths, the game entities actions are determined. See the activity control flow documentation for more information.

graph Node graph that defines the behaviour of the game entity.

ability.type.ApplyContinuousEffect

ApplyContinuousEffect(Ability):
    effects              : set(ContinuousEffect)
    application_delay    : float
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Applies a continuous effects on another game entity.

effects The applied continuous effect definitions.

application_delay Time between the initiation of the ability and the application of the effects in seconds.

allowed_types Whitelist of game entity types that can be targeted with the ability.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.ApplyDiscreteEffect

ApplyDiscreteEffect(Ability):
    batches              : set(EffectBatch)
    reload_time          : float
    application_delay    : float
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Applies batches of discrete effects on a game entity.

effects The batches of discrete effect which are applied when the ability is used.

reload_time Minimum time between two applications of the effect batches in seconds.

application_delay Time between the initiation of the ability and first application of the effects in seconds.

allowed_types Whitelist of game entity types that can be targeted with the ability.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.AttributeChangeTracker

AttributeChangeTracker(Ability):
    attribute       : Attribute
    change_progress : set(children(AttributeChangeProgress))

Allows the alteration of the state of the game entity when its attribute values increase or decrease.

attribute The attribute which is monitored.

change_progress Set of AttributeChangeProgress objects that activate when the current attribute value enters their defined intervals.

ability.type.Cloak

Cloak(Ability):
    interrupted_by     : set(Ability)
    interrupt_cooldown : float

Makes the unit untargetable for other game entities.

interrupted_by Abilities of the game entity that interrupt the cloak when used.

interrupt_cooldown Time needed to reactivate the cloak after an ability from interrupted_by has been used.

ability.type.CollectStorage

CollectStorage(Ability):
    container        : EntityContainer
    storage_elements : set(GameEntity)

Allows a game entity to insert specified game entities into one of its containers.

container Container the target game entity will be inserted into. A Storage ability with this container must be enabled.

storage_elements Game entities that can be inserted into the container. The container must allow the GameEntity objects.

ability.type.Collision

Collision(Ability):
    hitbox : Hitbox

Adds collision behaviour to a game entity.

hitbox Defines the size (x, y, z) of the collision hitbox.

ability.type.Constructable

Constructable(Ability):
    starting_progress     : int
    construction_progress : set(Progress)

Makes the game entity constructable via Effect types.

starting_progress The construction progress when the game entity is created.

construction_progress Set of Progress objects that activate when the current contruction progress value enters their defined intervals. The objects in the set must have progress type Construct.

ability.type.Create

Create(Ability):
    creatables : set(CreatableGameEntity)

Allows a game entity to spawn new instances of game entities.

creatables Stores the reference to the creatable game entities as well as configuration options for the creation.

ability.type.Despawn

Despawn(Ability):
    activation_condition : set(LogicElement)
    despawn_condition    : set(LogicElement)
    despawn_time         : float
    state_change         : optional(StateChanger) = None

Permanently removes the game entity from the game. By default, Despawn is inactive until triggered by activation_condition. Once activated, at least one of the elements in despawn_condition must be true to trigger the despawning.

activation_condition Activates (i.e. primes) the ability when one of the listed conditions are true. After activation, the ability will wait for an element in despawn_condition to be true.

despawn_condition Triggers the despawning process when of the conditions are true. activation_condition must have been fulfilled once before the despawn condition can be triggered.

despawn_time Time until the game entity is removed from the game after the despawn condition has been fulfilled. The removal is permanent.

state_change Alters the abilities and modifiers of a game entity after the despawn condition is fulfilled. The state change stays active until the game entity is removed from the game.

ability.type.DetectCloak

DetectCloak(Ability):
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Enables the game entity to decloak other game entities which use the Cloak ability.

allowed_types Whitelist of game entity types that can be decloaked.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.DropResources

DropResources(Ability):
    containers           : set(ResourceContainer)
    search_range         : float
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Allows a game entity to drop off resources at other game entities that have the DropSite ability. The resources are transferred to the player's global resource storage. Game entities with the ResourceStorage ability will automatically use this ability when their resource container capacity is reached.

containers Resource containers whose resources are transferred.

search_range Range in which the unit will search for a resource drop site if the ability is not used manually.

allowed_types Whitelist of game entity types that can be used as drop sites. They must have a DropSite ability accepting the corresponding resource container.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.DropSite

DropSite(Ability):
    accepts_from : set(ResourceContainer)

Allows a game entity to act as a resource drop off point for game entities with the DropResources ability. The resources are transfered to the player's global resource storage.

accepts_from Resource containers that can be emptied at the game entity.

ability.type.EnterContainer

EnterContainer(Ability):
    allowed_containers   : set(EntityContainer)
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Allows a game entity to enter specified containers of another game entity's Storage ability.

allowed_containers Containers that can be entered.

allowed_types Whitelist of game entity types that can be targeted with the ability.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.ExchangeResources

ExchangeResources(Ability):
    resource_a     : Resource
    resource_b     : Resource
    exchange_rate  : ExchangeRate
    exchange_modes : set(ExchangeMode)

Exchanges a resource for another resource. The type of exchange depends on the exchange mode. Players can exchange resources with themselves or other players.

resource_a First resource used for the exchange.

resource_b Second resource used for the exchange.

exchange_rate Exchange rate per unit of exchanged resources.

exchange_modes Defines how the resources can be exchanged.

ability.type.ExitContainer

ExitContainer(Ability):
    allowed_containers : set(EntityContainer)

Allows a game entity to exit specified containers of another game entity's Storage ability when they are in the container.

allowed_containers Containers that can be exited.

ability.type.Fly

Fly(Ability):
    height : float

Allows a game entity fly at a fixed height.

height The height at which the game entity flies. This value is always relative to the ground below.

ability.type.Formation

Formation(Ability):
    formations : set(GameEntityFormation)

Allows a game entity to be part of specified formations.

formations Formation types that the game entity can be part of.

ability.type.Foundation

Foundation(Ability):
    foundation_terrain : Terrain

Changes the terrain under a game entity on its creation.

foundation_terrain Replacement terrain that is placed under the space the game entity occupies.

ability.type.GameEntityStance

GameEntityStance(Ability):
    stances: set(GameEntityStance)

Defines activity stances for a game entity. These stances define which abilities will be used without player interaction when the game entity is idle.

stances Stance definitions for the game entity.

ability.type.Gather

Gather(Ability):
    auto_resume         : bool
    resume_search_range : float
    targets             : set(ResourceSpot)
    gather_rate         : ResourceRate
    container           : ResourceContainer

Allows a game entity to gather from resource spots defined in the Harvestable abilities of other game entities.

auto_resume Determines whether the game entity will automatically resume gathering after the resource spot is depleted. When enabled, the game entity will check if it can refill the depleted resource spot with one of its Restock abilities. Otherwise, the game entity will search for a new resource spot it can access with this ability.

resume_search_range Range in which the game entity searches for a new resource spot if auto_resume is enabled.

targets Resource spots that can be accessed and gathered from.

gather_rate Rate at which the game entity collects resources from the targeted resource spot.

container Resource container of the game entity where the gathered resources are stored. The resource container must be referenced by the game entity in a ResourceStorage ability.

ability.type.Harvestable

Harvestable(Ability):
    resources              : ResourceSpot
    harvest_progress       : set(HarvestProgress)
    restock_progress       : set(RestockProgress)
    gatherer_limit         : int
    harvestable_by_default : bool

Assigns a game entity a resource spot that can be harvested by other game entities with the Gather ability.

resource_spot The resource spot as a ResourceSpot object. It defines the contained resource type and resource capacity.

harvest_progress Can alter the game entity when the percentage of harvested resources reaches defined progress intervals. The objects in the set must have progress type Harvest.

restock_progress Can alter the game entity when the percentage of restocked resources reaches defined progress intervals. The objects in the set must have progress type Restock.

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 ability belongs to.

ability.type.Herd

Herd(Ability):
    strength             : int
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Allows a game entity to change the ownership of other game entities with the Herdable ability.

strength Comparison value for situations when the game entity competes with other game entities for a herdable. The game entity with the highest strength value will always be prefered, even if other game entities fulfill the condition set by mode in Herdable better.

allowed_types Whitelist of game entity types that can be herded.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.Herdable

Herdable(Ability):
    adjacent_discover_range : float
    mode                    : HerdableMode

Makes the game entity switch ownership when it is in range of another game entity with a Herd ability. Its new owner is owner of the herding game entity. If the herdable game entity is in range of two or more herding game entities, the ownership changes based on the mode set in the Herdable ability.

adjacent_discover_range When other herdables are in this range around the herded game entity, they will also be herded and switch ownership.

mode Determines who gets ownership of the herdable game entity when multiple game entities using Herd are in range.

ability.type.Idle

Idle(Ability):
    pass

Used for assigning animations and sounds to game entities in an idle state.

ability.type.LineOfSight

LineOfSight(Ability):
    range : float

Reveals the area around the game entity on the ingame map.

range Radius of the area around the game entity that is revealed.

ability.type.Live

Live(Ability):
    attributes : set(AttributeSetting)

Assigns attributes to a game entity.

attributes Configures the attribute values of the game entity.

ability.type.Lock

Lock(Ability):
    lock_pools : set(LockPool)

Defines lock pools which abilities with the Lock property can use.

lock_pools Lock pools definitions.

ability.type.Move

Move(Ability):
    speed      : float
    modes      : set(MoveMode)
    path_type  : children(PathType)

Allows a game entity to move around the map.

speed Speed of movement.

modes Modes of movements that can be used.

path_type Path type determining which pathfinding grid is searched to find a path from the start to the goal location.

ability.type.Named

Named(Ability):
    name             : TranslatedString
    description      : TranslatedMarkupFile
    long_description : TranslatedMarkupFile

Assigns the game entity a translatable name and descriptions.

name Name of the game entity as a translatable string.

description Description of the game entity as a translatable markup file.

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

ability.type.OverlayTerrain

OverlayTerrain(Ability):
    terrain_overlay : Terrain

Temporarily replace the map terrain the game entity is positioned on with a specified terrain.

terrain_overlay Terrain that is temporily replaces the existing map terrain.

ability.type.PassiveTransformTo

PassiveTransformTo(Ability):
    condition          : set(LogicElement)
    transform_time     : float
    target_state       : StateChanger
    transform_progress : set(Progress)

Activates a state change for a game entity when a condition is fulfilled.

condition Triggers the transformation when one condition becomes true.

transform_time Time to wait (in seconds) after the the transformation is triggered until the target state is activated.

target_state State change activated after transform_time has passed.

transform_progress Can alter the game entity while the transformation is in progress. The objects in the set must have progress type Transform.

ability.type.Pathable

Pathable(Ability):
    hitbox     : Hitbox
    path_costs : dict(children(PathType), int)

Lets a game entity influence the pathing costs on the (static) pathfinding grid.

This ability should only be used for game entitie that never (or rarely) change positions as pathfinding grid recalculations are expensive. For dynamic pathfinding effects, using the Collision ability should be preferred.

hitbox Hitbox around the game entity that affects the underlying pathfinding grids. All grid cells that are covered by this hitbox ae influenced by the cost definitions in the path_costs attribute.

path_costs Costs of traversing the area defined by the hitbox attribute on the pathfinding grid.

Keys are PathType objects that are associated with a pathfinding grid in the pathfinder.

Values represent the pathing cost for the terrain on the pathfinding grid. Each value must be an integer between 1 and 255. 1 defines the minimum possible cost and 254 represents the maximum possible cost. 255 signifies that the terrain is impassable for the specified path type.

ability.type.ProductionQueue

ProductionQueue(Ability):
    size             : int
    production_modes : set(ProductionMode)

Allows a game entity to queue production of CreatableGameEntity and ResearchableTech.

size Maximum number of production items in the queue.

production_modes Defines the production items which can be added to the queue.

ability.type.Projectile

Projectile(Ability):
    arc               : int
    accuracy          : set(Accuracy)
    target_mode       : TargetMode
    ignored_types     : set(children(GameEntityType))
    unignore_entities : set(GameEntity)

Gives a game entity projectile behaviour. A projectile is always spawned with another GameEntity object as a target. The engine calculates a parabolic path to the target, using the arc, accuracy and target_mode members. While moving along this path, the game entity can use other abilities.

arc The starting arc of the projectile as a value between 0 and 360.

accuracy Accuracy of the projectile. Depending on the type of target entity, a different accuracy might be used.

target_mode Determines the end point of the projectile path.

ignore_types The projectile will not use abilities on game entities with these types and ignore their hitbox, while moving along the path. However, the projectile will always use abilities on its target, even if it has one of they types in this set.

unignore_entities Whitelist of game entities who have a type that is listed in ignore_types, but should not ne ignored.

ability.type.ProvideContingent

ProvideContingent(Ability):
    amount : set(ResourceAmount)

Provides a temporary resource amount to a ResourceContingent. The amount is provided until the ability is disabled.

amount Temporary resource amount that is provided by the game entity.

ability.type.RallyPoint

RallyPoint(Ability):
    pass

Allows a game entity to set a rally point on the map. Game entities spawned by the Create ability or ejected from a container will move to the rally point location. The rally point can be placed on another game entity. In that case, the game entities moving there will try to use an appropriate ability on it.

ability.type.RegenerateAttribute

RegenerateAttribute(Ability):
    rate : AttributeRate

Regenerate attribute points at a defined rate. The game entity must have the attribute in its Live ability.

rate Regeneration rate as an AttributeRate object.

ability.type.RegenerateResourceSpot

RegenerateResourceSpot(Ability):
    rate          : ResourceRate
    resource_spot : ResourceSpot

Regenerate the available resources of a game entity's resource spot at a defined rate.

rate Resource regeneration rate.

resource_spot Resource spot that is refilled. The game entity must have a Harvestable ability that contains this resource spot.

ability.type.RemoveStorage

RemoveStorage(Ability):
    container        : EntityContainer
    storage_elements : set(GameEntity)

Allows a game entity to remove specified game entities from one of its containers.

container Container the target game entity will be removed from. A Storage ability with this container must be enabled.

storage_elements Game entities that can be removed from the container.

ability.type.Research

Research(Ability):
    researchables : set(ResearchableTech)

Allows a game entity to research a Tech object. Initiating a research will lock the technology for other game entities that can research it. The lock is removed if the research process of the Tech is cancelled.

researchables Stores the reference to the researchable techs as well as configuration options for researching.

ability.type.Resistance

Resistance(Ability):
    resistances : set(Resistance)

Assigns a game entity resistances to effects applied by other game entities.

resistances Resistances of the game entity against effects.

ability.type.ResourceStorage

ResourceStorage(Ability):
    containers : set(ResourceContainer)

Assigns a game entity containers for storing resources until they are dropped at a drop site.

containers Containers which specify how resources can be stored.

ability.type.Restock

Restock(Ability):
    auto_restock : bool
    target       : ResourceSpot
    restock_time : float
    manual_cost  : Cost
    auto_cost    : Cost
    amount       : int

Refills a resource spot with a defined amount of resources.

auto_restock Determines whether the game entity will automatically restock a resource spot that it harvested and is depleted.

target Resource spot that can be restocked with this ability.

restock_time Time until the restocking finishes in seconds.

manual_cost Cost of restocking when the ability is used manually by a player.

auto_cost Cost of restocking when the ability is automatically used by the game entity.

amount Resource amount that is added to the resource spot after restocking.

ability.type.Selectable

Selectable(Ability):
    selection_box : SelectionBox

Makes the game entity selectable by players.

selection_box Defines the clickable area around the game entity which results in a selection.

ability.type.SendBackToTask

SendBackToTask(Ability):
    allowed_types        : set(children(GameEntityType))
    blacklisted_entities : set(GameEntity)

Empties the containers of the Storage abilities of a game entity and makes the ejected game entities resume their previous tasks.

allowed_types Whitelist of game entity types that will be affected.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.ShootProjectile

ShootProjectile(Ability):
    projectiles              : orderedset(GameEntity)
    min_projectiles          : int
    max_projectiles          : int
    reload_time              : float
    spawn_delay              : float
    projectile_delay         : float
    require_turning          : bool
    manual_aiming_allowed    : bool
    spawning_area_offset_x   : float
    spawning_area_offset_y   : float
    spawning_area_offset_z   : float
    spawning_area_width      : float
    spawning_area_height     : float
    spawning_area_randomness : float
    allowed_types            : set(children(GameEntityType))
    blacklisted_entities     : set(GameEntity)

Spawns projectiles that have a game entity as a target. Projectiles are essentially fire-and-forget objects and only loosely depend on the game entity they originate from.

projectiles Game entities that can be spawned by the ability. Projectiles are spawned using the order in the set. The last Projectile is reused when the number of projectiles supposed to be fired is greater than the size of the set.

min_projectiles Minimum amount of projectiles spawned.

max_projectiles Maximum amount of projectiles spawned.

reload_time Time until the ability can be used again in seconds. The timer starts after the last projectile has been fired.

spawn_delay Time to wait between the initiation of the ability and spawning the first projectile in seconds.

projectile_delay Time to wait until the next projectile is spawned when min_projectiles > 1 in seconds.

require_turning Determines whether the game entity must face the target before it can use the ability.

manual_aiming_allowed Determines whether the ability can be aimed at a coordinate instead of a GameEntity object.

spawning_area_offset_x Part of the spawn location coordinates. The spawn location is an offset from the anchor point of the game entity.

spawning_area_offset_y Part of the spawn location coordinates. The spawn location is an offset from the anchor point of the game entity.

spawning_area_offset_z Part of the spawn location coordinates. The spawn location is an offset from the anchor point of the game entity.

spawning_area_width Determines the spawn area in which the projectile can be spawned randomly.

spawning_area_height Determines the spawn area in which the projectile can be spawned randomly.

spawning_area_randomness Value between 0.0 and 1.0 that determines how far the spawn location can be from the spawn area center. The engine chooses random (x,y) coordinates in the spawn area and multiplies them by this value in order to determine the spawn location.

allowed_types Whitelist of game entity types that can be targeted with the ability.

blacklisted_entities Blacklist for specific game entities that would be covered by allowed_types, but should be explicitly excluded.

ability.type.Stop

Stop(Ability):
    pass

Stops all current tasks and returns the game entity to an idle state.

ability.type.Storage

Storage(Ability):
    container       : EntityContainer
    empty_threshold : set(LogicElement)

Allows a game entity to store other game entities. Stored game entities can influence the state of the storing game entity.

container Configres the storage container.

empty_threshold Ejects all game entities from the container if one of the conditions is true.

ability.type.TerrainRequirement

TerrainRequirement(Ability):
    allowed_types        : set(children(TerrainType))
    blacklisted_terrains : set(Terrain)

Makes a game entity require specific terrains to be placed or moved on.

allowed_types Whitelist of terrain types that the game entity can be placed or moved on.

blacklisted_terrains Blacklist for specific terrains that would be covered by allowed_types, but should be explicitly excluded.

ability.type.Trade

Trade(Ability):
    trade_routes : set(TradeRoute)
    container    : ResourceContainer

Allows a game entity to trade with other game entities that have the TradePost ability.

trade_routes Trade routes that can be established with trade posts. The TradeRoute object defines rules and traded resources for the trade.

container Resource container of the game entity where the traded resources are stored. The resource container must be referenced by the game entity in a ResourceStorage ability.

ability.type.TradePost

TradePost(Ability):
    trade_routes : set(TradeRoute)

Makes a game entity a trade post that other game entities can trade with using their Trade ability.

trade_routes Trade routes that can be established with this trade post. The TradeRoute object defines rules and traded resources for the trade.

ability.type.TransferStorage

TransferStorage(Ability):
    storage_element  : GameEntity
    source_container : EntityContainer
    target_container : EntityContainer

Transfers a game entity from one container to another.

storage_element Game entity that is transferred.

source_container Container the transferable game entity is stored in.

target_container Container the game entity is inserted into. The target container can belong to the same game entity.

ability.type.Turn

Fly(Ability):
    turn_speed : float

Allows a game entity to turn on the spot.

turn_speed Speed at which the game entity turns. inf can be assigned to make the game entity turn immediately.

ability.type.UseContingent

UseContingent(Ability):
    amount : set(ResourceAmount)

Reserves a temporary resource amount of a ResourceContingent. The amount is freed when the ability is disabled.

amount Temporary resource amount that is reserved by the game entity.

ability.type.Visibility

Visibility(Ability):
    visible_in_fog : bool

Configures a game entity's visibility in the fog of war.

visible_in_fog Determines whether the game entity is visible in the fog of war.