doc: Document API changes for nyan data API v0.6.0.

doc: Document API changes for ApplyEffect.
doc: Document API changes for Task nodes.
doc: Document API changes for Ranged property.
doc: Document API changes for NextCommand condition.

Author: heinezen

doc/nyan/api_reference/reference_ability.md

@@ -127,6 +127,26 @@ If the lock pool
 
 the ability with this property cannot become active.
 
+## ability.property.type.Ranged
+
+```python
+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
 
 ```python
@@ -327,16 +347,12 @@ Alters the abilities and modifiers of a game entity after the despawn condition
 
 ```python
 DetectCloak(Ability):
-    range                : float
     allowed_types        : set(children(GameEntityType))
     blacklisted_entities : set(GameEntity)
 ```
 
 Enables the game entity to decloak other game entities which use the `Cloak` ability.
 
-**range**
-Range around the game entity in which other game entities will be decloaked.
-
 **allowed_types**
 Whitelist of game entity types that can be decloaked.
 
@@ -543,17 +559,13 @@ Determines whether the resource spot is harvestable when it is created. If `True
 
 ```python
 Herd(Ability):
-    range                : float
     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.
 
-**range**
-Minimum distance to a herdable game entity to make it change ownership.
-
 **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.
 
@@ -787,38 +799,6 @@ RallyPoint(Ability):
 
 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.RangedContinuousEffect
-
-```python
-RangedContinuousEffect(ApplyContinuousEffect):
-    min_range : int
-    max_range : int
-```
-
-Applies continuous effects on another game entity. This specialization of `ApplyContinuousEffect` allows ranged application.
-
-**min_range**
-Minimum distance to target.
-
-**max_range**
-Maximum distance to the target.
-
-## ability.type.RangedDiscreteEffect
-
-```python
-RangedDiscreteEffect(ApplyDiscreteEffect):
-    min_range : int
-    max_range : int
-```
-
-Applies batches of discrete effects on another game entity. This specialization of `ApplyDiscreteEffect` allows ranged application.
-
-**min_range**
-Minimum distance to target.
-
-**max_range**
-Maximum distance to the target.
-
 ## ability.type.RegenerateAttribute
 
 ```python
@@ -966,8 +946,6 @@ ShootProjectile(Ability):
     projectiles              : orderedset(GameEntity)
     min_projectiles          : int
     max_projectiles          : int
-    min_range                : int
-    max_range                : int
     reload_time              : float
     spawn_delay              : float
     projectile_delay         : float
@@ -994,12 +972,6 @@ Minimum amount of projectiles spawned.
 **max_projectiles**
 Maximum amount of projectiles spawned.
 
-**min_range**
-Minimum distance to the targeted game entity.
-
-**max_range**
-Maximum distance to the targeted game entity.
-
 **reload_time**
 Time until the ability can be used again in seconds. The timer starts after the *last* projectile has been fired.
 

doc/nyan/api_reference/reference_util.md

@@ -54,32 +54,54 @@ Generalization object for conditions that can be used in `XORGate` nodes.
 **node**
 Node that is visited when the condition is true.
 
+## util.activity.condition.type.AbilityUsable
+
+```python
+AbilityUsable(Condition):
+    ability : abstract(Ability)
+```
+
+Is true when an ability can be used by the game entity when the node is visited.
+
+**ability**
+Ability definition used for the usability check. This can reference a specific ability of the game entity or an abstract API object from the `engine.ability.type` namespace. If a specific ability is referenced, the ability must be assigned to the game entity **and** be enabled for the check to pass. If an API object is referenced, at least one ability of the same type must be enabled for the check to pass.
+
 ## util.activity.condition.type.CommandInQueue
 
 ```python
 CommandInQueue(Condition):
     pass
 ```
 
-Is true when the command queue is not empty when the node is visited.
+Is true when the game entity's command queue is not empty when the node is visited.
 
-## util.activity.condition.type.NextCommandIdle
+## util.activity.condition.type.NextCommand
 
 ```python
-NextCommandIdle(Condition):
-    pass
+NextCommand(Condition):
+    command : children(Command)
 ```
 
-Is true when the next command in the queue is of type `Idle`.
+Is true when the next command in the game entity's command queue is of a specific type.
 
-## util.activity.condition.type.NextCommandMove
+**command**
+Command type checked by the condition.
+
+## util.activity.condition.type.TargetInRange
 
 ```python
-NextCommandMove(Condition):
-    pass
+TargetInRange(Condition):
+    ability : abstract(Ability)
 ```
 
-Is true when the next command in the queue is of type `Move`.
+Is true when the target of the next command in the game entity's command queue is in range of an ability.
+
+**ability**
+Ability definition used for the range check.
+
+This can reference a specific ability of the game entity or an abstract API object from the `engine.ability.type` namespace. If a specific ability is referenced, the ability must be assigned to the game entity and must be enabled. Otherwise, the range check fails. If an API object is referenced, the first active ability with the same type as the API object is executed.
+
+If the ability has the property `Ranged`, the attributes of this property are utilized for the range check calculations. If the ability does not have a `Ranged` property, the condition is only true when the game entity is at the same position as the target.
 
 ## util.activity.event.Event
 
@@ -149,7 +171,7 @@ Next node in the activity graph.
 **ability**
 Ability that is executed.
 
-This can reference a specific ability of the game entity or an abstract API object from the `engine.ability.type` namespace. If a specific ability is referenced, the ability must be assigned to the game entity and must not be disabled. Otherwise, the ability is not executed. If an API object is referenced, the first active ability with the same type as the API object is executed.
+This can reference a specific ability of the game entity or an abstract API object from the `engine.ability.type` namespace. If a specific ability is referenced, the ability must be assigned to the game entity and must be enabled. Otherwise, the ability is not executed. If an API object is referenced, the first active ability with the same type as the API object is executed.
 
 ## util.activity.node.type.End
 
@@ -172,6 +194,22 @@ Start of an activity. Does nothing but pointing to the next node.
 **next**
 Next node in the activity graph.
 
+## util.activity.node.type.Task
+
+```python
+Task(Node):
+    next : Node
+    task : children(Task)
+```
+
+Executes a task on the game entity when the node is visited.
+
+**next**
+Next node in the activity graph.
+
+**task**
+Task that is executed.
+
 ## util.activity.node.type.XOREventGate
 
 ```python
@@ -195,11 +233,84 @@ XORGate(Node):
 Gateway that branches the activity graph depending on the result of conditional queries. Queries are executed immediately when the node is visited.
 
 **next**
-Mapping of conditional queries to the next node in the activity graph. The first query that evaluates to true is used to determine the next node. If no query evaluates to true, the `default` node is used.
+Mapping of conditional queries to the next node in the activity graph. The first query that evaluates to true is used to determine the next node. If no query evaluates to true, the `default` node is used as fallback.
 
 **default**
 Default node that is used if no query evaluates to true.
 
+## util.activity.node.type.XORSwitchGate
+
+```python
+XORSwitchGate(Node):
+    switch  : children(SwitchCondition)
+    default : Node
+```
+
+Gateway that branches the activity graph depending on the value of a runtime parameter. In comparison to `XORGate`, only one conditional query is done based on the value (similar to the behaviour of a [switch statement](https://en.wikipedia.org/wiki/Switch_statement)). The query is executed immediately when the node is visited.
+
+**switch**
+Defines which runtime parameter is checked as well as the mapping of parameter value to the next node in the activity graph. If a value is encountered at query execution time that is not associated with a node, the `default` node is used as fallback.
+
+**default**
+Default node that is used if a value does not have an associated node.
+
+## util.activity.switch_condition.SwitchCondition
+
+```python
+SwitchCondition(Object):
+    pass
+```
+
+Generalization object for conditions that can be used in `XORSwitchGate` nodes.
+
+## util.activity.switch_condition.type.NextCommand
+
+```python
+NextCommand(SwitchCondition):
+    next : dict(children(Command), Node)
+```
+
+Switches branches based on the type of command that is in the queue of the game entity.
+
+**next**
+Mapping of command types to the next node in the activity graph.
+
+## util.activity.task.Task
+
+```python
+Task(Object):
+    pass
+```
+
+Generalization object for tasks that can be used in `Task` nodes.
+
+## util.activity.task.type.ClearCommandQueue
+
+```python
+ClearCommandQueue(Task):
+    pass
+```
+
+Clear the command queue of the game entity executing the activity.
+
+## util.activity.task.type.MoveToTarget
+
+```python
+MoveToTarget(Task):
+    pass
+```
+
+Move to the current target of the game entity. The target may be a position or another game entity. If the game entity has no target at time of execution, the task is skipped.
+
+## util.activity.task.type.PopCommandQueue
+
+```python
+PopCommandQueue(Task):
+    pass
+```
+
+Pop the front command from the command queue of the game entity executing the activity.
+
 ## util.animation_override.AnimationOverride
 
 ```python
@@ -420,6 +531,42 @@ The activation message that has to be typed into the chat console.
 **changes**
 Changes to API objects.
 
+## util.command.Command
+
+```python
+Command(Object):
+    pass
+```
+
+Generalization object for commands of a game entity.
+
+## util.command.type.ApplyEffect
+
+```python
+ApplyEffect(Command):
+    pass
+```
+
+Game entity command for using the `ApplyEffect` ability.
+
+## util.command.type.Idle
+
+```python
+Idle(Command):
+    pass
+```
+
+Game entity command for using the `Idle` ability.
+
+## util.command.type.Move
+
+```python
+Move(Command):
+    pass
+```
+
+Game entity command for using the `Move` ability.
+
 ## util.container_type.SendToContainerType
 
 ```python