Skip to content

Instantly share code, notes, and snippets.

@heinezen

heinezen/api_doc_test.md

Last active June 26, 2019 15:04
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save heinezen/c24b594e6a41f7ae27e5384fb0af72fb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save heinezen/c24b594e6a41f7ae27e5384fb0af72fb to your computer and use it in GitHub Desktop.
Download ZIP
Raw
api_doc_test.md

Reference

(Fill meeeeeeeeeeeee)

aux.progress_type.ProgressType

ProgressType(Entity):

Used by Convert effects and resistances for matching.

aux.progress_type.type.Construct

Construct(ProgressType):

A progress type that covers construction progress.

effect.continuous.time_relative_attribute_change.TimeRelativeAttributeChange

TimeRelativeAttributeChange(ContinuousEffect):
    type              : AttributeChangeType
    total_change_time : float
    ignore_protection : set(ProtectingAttribute)

Generalization object for effects that change the resistor's current attribute values at a per-second rate relative to the max_value of their attribute settings. The change rate is scaled such that it would increase the attribute points of the resistor from 0 to max_value (or decrease them from max_value to 0, respectively) in a fixed amount of time. The current attribute points are not considered. Calculating the change rate can be done by using this formula:

applied_rate = resistor_max_value / total_change_time

Example: Consider a resistor with 50 maximum HP and an effector with a TimeRelativeAttributeDecrease time of 5 seconds. The per-second change rate is calculated by dividing the maximum HP value by the time requirement of the effect. Hence, the change rate is 10HP/s. This rate is fix as long as the maximum HP value does not change. If the resistor currently has 30 HP, it would arrive at 0 HP in 3 seconds.

type The effect will be matched with a Resistance.ContinuousResistance.TimeRelativeAttributeChange object that stores the same AttributeChangeType object in its type member. Otherwise, the effect will not be applied.

total_change_time The total time needed to change the resistors attribute points from max_value to 0 (for TimeRelativeAttributeDecrease) or from 0 to max_value (for TimeRelativeAttributeIncrease).

ignore_protection Ignores the ProtectingAttributes in the set when changing the attributes of the target.

effect.continuous.time_relative_attribute_change.type.TimeRelativeAttributeDecrease

TimeRelativeAttributeDecrease(TimeRelativeAttributeChange):

Specialization of the continuous TimeRelativeAttributeChange effect that decreases the resistor's current attribute value in a fixed amount of time relative to their attribute's max_value.

effect.continuous.time_relative_attribute_change.type.TimeRelativeAttributeIncrease

TimeRelativeAttributeIncrease(TimeRelativeAttributeChange):

Specialization of the continuous TimeRelativeAttributeChange effect that increases the resistor's current attribute value in a fixed amount of time relative to their attribute's max_value.

effect.continuous.time_relative_progress.TimeRelativeProgress

TimeRelativeProgress(ContinuousEffect):
    type              : ProgressType
    total_change_time : float

Generalization object for effects that changes a resistor's current progress amount at a per-second rate relative to 100%. The change rate is scaled such that it would increase the specified progress amount of the resistor from 0% to 100% (or decrease it from 100% to 0%, respectively) in a fixed amount of time. The current progress amount is not considered. Calculating the change rate can be done by using this formula:

applied_rate = 100 / total_change_time

Example: Consider a constructable resistor and an effector with a TimeRelativeProgressIncrease time of 10 seconds. The per-second change rate is calculated by dividing 100% by the time requirement of the effect. Hence, the change rate is 10%/s. This rate is fix. If the resistor currently has 30% construction progress, it would be constructed in 7 seconds.

type The effect will be matched with a Resistance.ContinuousResistance.TimeRelativeProgress object that stores the same ProgressType object in its type member. Otherwise, the effect will not be applied.

total_change_time The total time needed to change the resistors attribute points from 100% to 0 (for TimeRelativeProgressDecrease) or from 0 to 100% (for TimeRelativeProgressIncrease).

effect.continuous.time_relative_progress.type.TimeRelativeProgressDecrease

TimeRelativeProgressDecrease(TimeRelativeProgress):

Specialization of the continuous TimeRelativeProgress effect that decreases the resistor's progress amount in a fixed amount of time relative to 100%.

effect.continuous.time_relative_progress.type.TimeRelativeProgressIncrease

TimeRelativeProgressIncrease(TimeRelativeProgress):

Specialization of the continuous TimeRelativeProgress effect that increases the resistor's progress amount in a fixed amount of time relative to 100%.

resistance.continuous.time_relative_attribute_change.TimeRelativeAttributeChange

TimeRelativeAttributeChange(ContinuousResistance):
    type : AttributeChangeType

Generalization object for resistances to continuous TimeRelativeAttributeChange effects.

Note that you cannot use this resistance object directly and have to choose one of the specializations TimeRelativeAttributeDecrease or TimeRelativeAttributeIncrease.

type Effects of type Effect.ContinuousEffect.TimeRelativeAttributeChange are matched to this resistance if they store the same AttributeChangeType object in their type member. Otherwise, the effect will not be applied.

resistance.continuous.time_relative_attribute_change.type.TimeRelativeAttributeDecrease

TimeRelativeAttributeDecrease(TimeRelativeAttributeChange):

Specialization of the continuous TimeRelativeAttributeChange resistance that decreases the resistor's current attribute value in a fixed amount of time relative to their attribute's max_value.

resistance.continuous.time_relative_attribute_change.type.TimeRelativeAttributeIncrease

TimeRelativeAttributeIncrease(TimeRelativeAttributeChange):

Specialization of the continuous TimeRelativeAttributeChange resistance that increases the resistor's current attribute value in a fixed amount of time relative to their attribute's max_value.

resistance.continuous.time_relative_progress.TimeRelativeProgress

TimeRelativeProgress(ContinuousResistance):
    type : ProgressType

Generalization object for resistances to continuous TimeRelativeProgress effects.

Note that you cannot use this resistance object directly and have to choose one of the specializations TimeRelativeProgressDecrease or TimeRelativeProgressIncrease.

type Effects of type Effect.ContinuousEffect.TimeRelativeProgress are matched to this resistance if they store the same ProgressType object in their type member. Otherwise, the effect will not be applied.

resistance.continuous.time_relative_progress.type.TimeRelativeProgressDecrease

TimeRelativeProgressDecrease(TimeRelativeProgress):

Specialization of the continuous TimeRelativeProgress resistance that decreases the resistor's progress amount in a fixed amount of time relative to 100%.

resistance.continuous.time_relative_progress.type.TimeRelativeProgressIncrease

TimeRelativeProgressIncrease(TimeRelativeProgress):

Specialization of the continuous TimeRelativeProgress resistance that increases the resistor's progress amount in a fixed amount of time relative to 100%.

AttributeChangeType

AttributeChangeType(Entity):

Used by FlatAttributeChange effects and resistances for matching.

AttributeChangeType.Fallback

Fallback(AttributeChangeType):

A special type for FlatAttributeChange. Effects with this type are only evaluated if the accumalated applied value or applied rate of all other effects is outside of a specified interval. The interval is defined by the FlatAttributeChange object that has its type member set to Fallback. Upper and lower bounds are [min_change_rate,max_change_rate] (continuous effects) and [min_change_value,max_change_value] (discrete effects). The fallback effect is also evaluated if no other FlatAttributeChange effect is present or matched to any resistances. However, fallback effects still needs to be matched against a resistance object with type set to Fallback.

For example, effects that utilize fallback can be used to model minimum or maximum damage of a game entity.

ConvertType

ConvertType(Entity):

Used by Convert effects and resistances for matching.

Effect

Effect(Entity):

Generalization object for all effects.

Standard behavior without specializations:

  • Effects are only applied if the resistor has a matching Resistance object. Matching can be further defined depending on the concrete effect.
  • Applying them costs nothing.
  • Will be applied to targets with any diplomatic stance.
  • Only affect the target chosen with the ApplyContinuousEffect/ApplyDiscretEffect ability.

Specializations:

  • AreaEffect: Effects are applied to other game entities in a circular area around the target.
  • CostEffect: Makes effects cost attribute points or resources.
  • DiplomaticEffect: Effects only apply to specified diplomatic stances.

Effect.AreaEffect

AreaEffect(Effect):
    range   : float
    dropoff : DropoffType

Can be inherited to apply the effect to game entities in a circular area around the target.

range The radius of the area in which game entities are affected.

dropoff Changes the effectiveness of the effect based on the distance to the center of the circle (see DropoffType).

Effect.CostEffect

AttributeCostEffect(Effect):
    cost : Cost

Can be inherited to make the effect cost attribute points or resources.

cost The costs for the effect as a Cost object.

Effect.ContinuousEffect

ContinuousEffect(Effect):

Generalization object for effects that are applied at a per-second rate.

Effect.ContinuousEffect.FlatAttributeChange

FlatAttributeChange(ContinuousEffect):
    type              : AttributeChangeType
    min_change_rate   : optional(AttributeRate)
    max_change_rate   : optional(AttributeRate)
    change_rate       : AttributeRate
    ignore_protection : set(ProtectingAttribute)

Generalization object for effects that change the resistor's current attribute values at a flat per-second rate. The change value can optionally be limited to an interval with min_change_rate as the lower bound and max_change_rate as the upper bound.

Note that you cannot use this effect object directly and have to choose one of the specializations FlatAttributeChangeDecrease or FlatAttributeChangeIncrease.

type The effect will be matched with a Resistance.ContinuousResistance.FlatAttributeChange object that stores the same AttributeChangeType object in its type member. Otherwise, the effect will not be applied.

min_change_rate (optional) The applied change rate can never go lower than the specified rate. Does not have to be set.

max_change_rate (optional) The applied change rate can never go higher than the specified rate. Does not have to be set.

change_rate The gross per-second rate at which the attribute points of the resistor change. The net change rate (applied rate) is calculated by subtracting the effector's change_rate from the resistor's block_rate.

$$applied_rate = change_rate - block_rate$$

The applied rate is further bound by the interval defined by min_change_rate and max_change_rate, if these members are set.

ignore_protection Ignores the ProtectingAttributes in the set when changing the attributes of the target.

Effect.ContinuousEffect.FlatAttributeChange.FlatAttributeChangeDecrease

FlatAttributeChangeDecrease(FlatAttributeChange):

Specialization of the continuous FlatAttributeChange effect that decreases the resistor's current attribute value at a per-second rate.

Effect.ContinuousEffect.FlatAttributeChange.FlatAttributeChangeIncrease

FlatAttributeChangeIncrease(FlatAttributeChange):

Specialization of the continuous FlatAttributeChange effect that increases the resistor's current attribute value at a per-second rate.

Effect.ContinuousEffect.Lure

Lure(ContinuousEffect):
    type                        : LureType
    destination                 : set(GameEntity)
    min_distance_to_destination : float

Makes the target move to another game entity.

type The effect will be matched with a Resistance.ContinuousResistance.Lure object that stores the same LureType object in its type member. Otherwise, the effect will not be applied.

destination The possible destinations the target can move to. Whichever game entity is closest will be chosen.

min_range_to_destination The minimum distance to the destination the target has to have before it will stop.

Effect.DiplomaticEffect

DiplomaticEffect(Effect):
    stances : set(DiplomaticStance)

Can be inherited to make the effect only applicable to game entities of a player with a specified diplomatic stance.

stances If the target is owned by a player has any of the specified diplomatic stances, the effect is applied.

Effect.DiscreteEffect

DiscreteEffect(Effect):

Generalization object for effects that are applied immediately.

Effect.DiscreteEffect.Convert

Convert(DiscreteEffect):
    type               : ConvertType
    min_chance_success : optional(float)
    max_chance_success : optional(float)
    chance_success     : float
    cost_fail          : optional(Cost)

Change the owner of the target unit to the player who owns the effector game entity.

type The effect will be matched with a Resistance.DiscreteResistance.Convert object that stores the same ConvertType object in its type member. Otherwise, the effect will not be applied.

min_chance_success (optional) The applied chance can never go lower than the specified percentage. Does not have to be set.

max_chance_success (optional) The applied chance can never go higher than the specified percentage. Does not have to be set.

chance_success Gross chance for the conversion to succeed as a percentage chance. The percentage should be stored as a float value between 0.0 and 1.0. The net chance (applied chance) of success is calculated by subtracting the effector's chance_success from the resistor's chance_resist.

$$applied_chance = chance_success - chance_resist$$

Any value below 0.0 is an automatic fail, while any value above 1.0 is an automatic success. The applied chance is further bound by the interval defined by min_chance_success and max_chance_success, if these members are set.

cost_fail The amount of attribute points or resources removed from the effector if the conversion fails. Does not have to be set.

Effect.DiscreteEffect.Convert.AoE2Convert

AoE2Convert(Convert):
    skip_guaranteed_rounds : int
    skip_protected_rounds  : int

Specialized conversion effect that is implemented in AoE2. The convert chance at the start is guaranteed to be 0.0 for X rounds and guaranteed to be 1.0 after Y rounds (both defined by the Restistance.DiscreteResistance.Convert.AoE2Convert object).

When the effector stops applying the effect, the resistor's protected rounds are increased until they reach their maximum value again. Running out of the range of the effector does not count as stopping the effect application.

skip_guaranteed_rounds Lowers the number of rounds that the resistor is guaranteed to resist every time.

skip_protected_rounds Lowers the number of rounds that are needed for the success chance to always be 1.0.

Effect.DiscreteEffect.FlatAttributeChange

FlatAttributeChange(DiscreteEffect):
    type              : AttributeChangeType
    min_change_rate   : optional(AttributeAmount)
    max_change_rate   : optional(AttributeAmount)
    change_rate       : AttributeAmount
    ignore_protection : set(ProtectingAttribute)

Generalization object for effects that change the resistor's current attribute values by a flat amount. The change value can optionally be limited to an interval with min_change_value as the lower bound and max_change_value as the upper bound.

Note that you cannot use this effect object directly and have to choose one of the specializations FlatAttributeChangeDecrease or FlatAttributeChangeIncrease.

type The effect will be matched with a Resistance.DiscreteResistance.FlatAttributeChange object that stores the same AttributeChangeType object in its type member. Otherwise, the effect will not be applied.

min_change_value (optional) The applied change value can never go lower than the specified amount. Does not have to be set.

max_change_value (optional) The applied change value can never go higher than the specified amount. Does not have to be set.

change_value The gross amount by that the attribute points of the resistor change. The net change value (applied value) is calculated by subtracting the effector's change_value from the resistor's block_value.

$$applied_value = change_value - block_value$$

The applied rate is further bound by the interval defined by min_change_value and max_change_value, if these members are set.

ignore_protection Ignores the ProtectingAttributes in the set when changing the attributes of the target.

Effect.DiscreteEffect.FlatAttributeChange.FlatAttributeChangeDecrease

FlatAttributeChangeDecrease(FlatAttributeChange):

Specialization of the discrete FlatAttributeChange effect that decreases the resistor's current attribute value by a flat amount.

Effect.DiscreteEffect.FlatAttributeChange.FlatAttributeChangeIncrease

FlatAttributeChangeIncrease(FlatAttributeChange):

Specialization of the discrete FlatAttributeChange effect that increases the resistor's current attribute value by a flat amount.

Effect.DiscreteEffect.MakeHarvestable

MakeHarvestable(DiscreteEffect):
    resource_spot : ResourceSpot

Makes a resource spot harvestable, if it is not already harbestable by default.

resource_spot Resource spot that should be made harvestable. The effect will be matched with a Resistance.DiscreteResistance.MakeHarvestable object that stores the same ResourceSpot object in its resource_spot member. Additionally, the target needs to have a Harvestable ability that contains the resource spot.

Effect.DiscreteEffect.SendToContainer

SendToContainer(DiscreteEffect):
    type     : SendToStorageType
    storages : set(Container)

Makes the target move to and enter the nearest game entity where it can be stored. The resistor needs an EnterContainer ability for at least one of the containers for this to work.

type The effect will be matched with a Resistance.DiscreteResistance.SendToStorage object that stores the same SendToStorageType object in its type member. Otherwise, the effect will not be applied.

storages Set of containers the target should enter. The target will choose the nearest one for which it has an EnterContainer ability.

Entity

Entity():

Root object of the API. All other objects inherit from it, either explicitely or implicitely.

GameEntity

GameEntity(Entity):
    types     : set(GameEntityType)
    variants  : set(Variant)
    abilities : set(Ability)
    modifiers : set(Modifier)

For definition of all ingame objects, including units, buildings, items, projectiles and ambience. Their capabilities are handled through Ability and Modifier API objects stored in the members.

types Classification of the game entity via GameEntityType objects.

variants Variants can alter the game entity before they are created. The requirement and extent of the changes depends on the Variant object.

abilities Define what the game entity does and is through Ability objects.

modifiers Change the stats of abilities belonging to the game entity. Mostly used to give boni or mali in certain situations (see Modifier).

GameEntity.Ambient

Ambient(GameEntity):

Specialization of GameEntity for objects in the scenery (cliffs, rocks, trees).

GameEntity.Building

Building(GameEntity):

Specialization of GameEntity for buildable objects.

GameEntity.Building.BuildingPart

BuildingPart(Building):
    offset_x : int
    offset_y : int

A subpart of a MultiPartBuilding. Works essentially like any other Building game entity.

offset_x Offset on the x-axis relative to the MultiPartBuilding container.

offset_y Offset on the y-axis relative to the MultiPartBuilding container.

GameEntity.Building.MultiPartBuilding

MultiPartBuilding(Building):
    building_parts : set(BuildingPart)

A building that also is container for several other buildings with own abilities and modifiers.

building_parts The buildings managed by the container (see BuildingPart).

GameEntity.Item

Item(GameEntity):

Specialization of GameEntity for items.

GameEntity.Unit

Unit(GameEntity):

Specialization of GameEntity for military and civilian units.

LureType

LureType(Entity):

Used by Lure effects and resistances for matching.

Resistance

Resistance(Entity):

Generalization object for all resistances.

Standard behavior without specializations:

  • Effects are only applied if the resistor has a matching Resistance object. Matching can be further defined depending on the concrete effect.
  • Resisting costs no attribute points.

Resistance.CostResistance

AttributeCostResistance(Resistance):
    cost : Cost

Can be inherited to make the resistance cost attribute points or resources.

cost The amount of attribute points or resources removed from the resistor.

Resistance.ContinuousResistance

ContinuousResistance(Resistance):

Generalization object for resistances to continuous effects.

Resistance.ContinuousResistance.FlatAttributeChange

FlatAttributeChange(ContinuousResistance):
    type       : AttributeChangeType
    block_rate : set(AttributeRate)

Generalization object for resistances to continuous FlatAttributeChange effects.

Note that you cannot use this resistance object directly and have to choose one of the specializations FlatAttributeChangeDecrease or FlatAttributeChangeIncrease.

type Effects of type Effect.ContinuousEffect.FlatAttributeChange are matched to this resistance if they store the same AttributeChangeType object in their type member. Otherwise, the effect will not be applied.

block_rate The per-second attribute rate that is blocked by the resistor. The net change rate (applied rate) is calculated by subtracting the effector's change_rate from the resistor's block_rate.

$$applied_rate = change_rate - block_rate$$

The applied rate is further bound by the interval defined by min_change_rate and max_change_rate in the effect, if these members are set.

Resistance.ContinuousResistance.FlatAttributeChange.FlatAttributeChangeDecrease

FlatAttributeChangeDecrease(FlatAttributeChange):

Specialization of the continuous FlatAttributeChange resistance that blocks the effector's attribute decrease rate.

Resistance.ContinuousResistance.FlatAttributeChange.FlatAttributeChangeIncrease

FlatAttributeChangeIncrease(FlatAttributeChange):

Specialization of the continuous FlatAttributeChange resistance that blocks the effector's attribute increase rate.

Resistance.ContinuousResistance.Lure

Lure(ContinuousResistance):
    type : LureType

Resistance to the Lure effect.

type Effects of type Effect.ContinuousEffect.Lure are matched to this resistance if they store the same LureType object in their type member. Otherwise, the effect will not be applied.

Resistance.DiscreteResistance

DiscreteResistance(Resistance):

Generalization object for resistances to discrete effects.

Resistance.DiscreteResistance.Convert

Convert(DiscreteResistance):
    type          : ConvertType
    chance_resist : float

Resistance to the Convert effect.

type Effects of type Effect.ContinuousEffect.Convert are matched to this resistance if they store the same ConvertType object in their type member. Otherwise, the effect will not be applied.

chance_resist Percentage amount subtracted from the effector's success chance. The percentage should be stored as a float value between 0.0 and 1.0. The net chance (applied chance) of success is calculated by subtracting the effector's chance_success from the resistor's chance_resist.

$$applied_chance = chance_success - chance_resist$$

Any value below 0.0 is an automatic fail, while any value above 1.0 is an automatic success. The applied chance is further bound by the interval defined by min_chance_success and max_chance_success in the effect, if these members are set.

Resistance.DiscreteResistance.Convert.AoE2Convert

AoE2Convert(Convert):
    guaranteed_resist_rounds       : int
    protected_rounds               : int
    protection_round_recharge_time : float

Resistance to the AoE2Convert effect.

guaranteed_resist_rounds Number of rounds at the start where the success chance is guaranteed to be 0.0.

protected_rounds Number of rounds that are needed for the success chance to always be 1.0.

protection_round_recharge_time Time it takes until one protected round is added back to the number of protected rounds.

When the effector stops applying the effect, the number of protected rounds is increased until they reach their maximum value again. Running out of the range of the effector does not count as stopping the effect application.

Resistance.DiscreteResistance.FlatAttributeChange

FlatAttributeChange(DiscreteResistance):
    type        : AttributeChangeType
    block_value : set(AttributeAmount)

Generalization object for resistances to discrete FlatAttributeChange effects.

Note that you cannot use this resistance object directly and have to choose one of the specializations FlatAttributeChangeDecrease or FlatAttributeChangeIncrease.

type Effects of type Effect.DiscreteEffect.FlatAttributeChange are matched to this resistance if they store the same AttributeChangeType object in their type member. Otherwise, the effect will not be applied.

change_value The flat attribute amount that is blocked by the resistor. The net change value (applied value) is calculated by subtracting the effector's change_value from the resistor's block_value.

$$applied_value = change_value - block_value$$

The applied value is further bound by the interval defined by min_change_value and max_change_value in the effect, if these members are set.

Resistance.DiscreteResistance.FlatAttributeChange.FlatAttributeChangeDecrease

FlatAttributeChangeDecrease(FlatAttributeChange):

Specialization of the discrete FlatAttributeChange resistance that blocks the effector's attribute decrease value.

Resistance.DiscreteResistance.FlatAttributeChange.FlatAttributeChangeIncrease

FlatAttributeChangeIncrease(FlatAttributeChange):

Specialization of the discrete FlatAttributeChange resistance that blocks the effector's attribute increase value.

Resistance.DiscreteResistance.MakeHarvestable

MakeHarvestable(DiscreteResistance):
    resource_spot      : ResourceSpot
    harvest_conditions : set(HarvestableRequirement)

Resistance to the MakeHarvestable effect.

resource_spot Resource spot that should be made harvestable. Effects of type Effect.DiscreteEffect.MakeHarvestable are matched to this resistance if they store the same ResourceSpot object in their resource_spot member. Additionally, the target needs to have a Harvestable ability that contains the resource spot.

harvest_conditions The requirements under which the resource spots will be made harvestable.

Resistance.DiscreteEffect.SendToContainer

SendToContainer(DiscreteResistance):
    type              : SendToStorageType
    search_range      : float
    ignore_containers : set(Container)

Resistance to the SendToContainer effect.

type Effects of type Effect.DiscreteEffect.SendToContainer are matched to this resistance if they store the same SendToStorageType object in their type member. Otherwise, the effect will not be applied.

search_range The range in which the resistor will search for a container.

ignore_containers Excludes the containers from the set when searching for a target container.

SendToStorageType

SendToStorageType(Entity):

Used by SendToStorage effects and resistances for matching.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment