Converter Restructuring

cfg/converter/games/game_editions.toml

@@ -38,9 +38,9 @@ expansions      = []
   ]
 
   [AOC.targetmods.aoe2_base]
-  version         = "0.5.1"
+  version         = "0.6.0"
   versionstr      = "1.0c"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"
 
 
 [AOCDEMO]
@@ -63,9 +63,9 @@ expansions      = []
   blend     = ["data/blendomatic.dat"]
 
   [AOCDEMO.targetmods.trial_base]
-  version         = "0.5.1"
+  version         = "0.6.0"
   versionstr      = "Trial"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"
 
 
 [AOK]
@@ -145,9 +145,9 @@ expansions      = []
   ]
 
   [AOE1DE.targetmods.de1_base]
-  version         = "0.5.1"
+  version         = "0.6.0"
   versionstr      = "1.0a"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"
 
 
 [ROR]
@@ -185,9 +185,9 @@ expansions      = []
   ]
 
   [ROR.targetmods.aoe1_base]
-  version         = "0.5.1"
+  version         = "0.6.0"
   versionstr      = "1.0a"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"
 
 
 [HDEDITION]
@@ -229,9 +229,9 @@ expansions      = []
   ]
 
   [HDEDITION.targetmods.hd_base]
-  version         = "0.5.1"
+  version         = "0.6.0"
   versionstr      = "5.8"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"
 
 
 [AOE2DE]
@@ -278,9 +278,9 @@ expansions      = []
   ]
 
   [AOE2DE.targetmods.de2_base]
-  version         = "0.6.0"
+  version         = "0.7.0"
   versionstr      = "Update 118476+"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"
 
 
 [SWGB]
@@ -320,6 +320,6 @@ expansions      = ["SWGB_CC"]
   ]
 
   [SWGB.targetmods.swgb_base]
-  version         = "0.5.1"
+  version         = "0.6.0"
   versionstr      = "1.1-gog4"
-  min_api_version = "0.5.0"
+  min_api_version = "0.6.0"

doc/code/curves.md

@@ -18,6 +18,7 @@ Curves are an integral part of openage's event-based game simulation.
       1. [Queue](#queue)
       2. [Unordered Map](#unordered-map)
       3. [Array](#array)
+4. [Compression](#compression)
 
 
 ## Motivation
@@ -133,6 +134,9 @@ Modify operations insert values for a specific point in time.
 | `set_insert(t, value)`  | Insert a new keyframe value at time `t`                                           |
 | `set_last(t, value)`    | Insert a new keyframe value at time `t`; delete all keyframes after time `t`      |
 | `set_replace(t, value)` | Insert a new keyframe value at time `t`; remove all other keyframes with time `t` |
+| `compress(t)`           | Remove redundant keyframes at and after time `t`; see [Compression] for more info |
+
+[Compression]: #compression
 
 **Copy**
 
@@ -292,3 +296,28 @@ Modify operations insert values for a specific point in time.
 | Method           | Description                                                                                      |
 | ---------------- | ------------------------------------------------------------------------------------------------ |
 | `sync(Curve, t)` | Replace all keyframes from self after time `t` with keyframes from source `Curve` after time `t` |
+
+
+## Compression
+
+Curves support basic lossless compression by removing redundant keyframes from the curve.
+Keyframes are considered redundant if they do not change any interpolation results, i.e.
+the result of `get(t)` does not change.
+
+The most straight-forward way to use compression with primitive curves is the `compress(t)`
+method. `compress(t)` iterates over the curve and removes all redundant keyframes after
+or at time `t`. The runtime has linear complexity `O(n)` based on the number of elements
+in the keyframe container.
+
+Furthermore, primitive curves support incremental compression during insertion for the
+`set_insert(t, value)`  and `set_last(t, value)` methods via their `compress` argument.
+If compression is active, `(t, value)` is only inserted when it is not a redundant
+keyframe. `sync(Curve, t)` also supports compression with a flag `compress` passed as
+an argument.
+
+Compression may be used in cases where the size should be kept small, e.g. when the curve
+is transferred via network or recorded in a replay file. Another application of compression
+is in the [renderer](/doc/code/renderer/README.md) for the discrete curves storing an object's
+animations. Since compression removes redundant animation entries, the renderer can determine
+when the current animation has started much easier as this is then returned by the keyframe
+time in `frame(t)`.

doc/code/game_simulation/activity.md

@@ -5,7 +5,10 @@ configurable.
 
 1. [Motivation](#motivation)
 2. [Architecture](#architecture)
-3. [Node Types](#node-types)
+3. [Workflow](#workflow)
+   1. [Initialization](#initialization)
+   2. [Advancing in the graph](#advancing-in-the-graph)
+4. [Node Types](#node-types)
 
 
 ## Motivation
@@ -32,7 +35,20 @@ and event triggers that indicate which path to take next. By traversing the node
 its paths, the game entities actions are determined. The currently visited node in the graph
 corresponds to the current action of a unit.
 
-Activities are reusable, i.e. they are intended to be shared by many game entities Usually,
+Advancement to the next node can be initiated in several ways, depending on the
+[node type](#node-types) of the current node.
+It can happen automatically or be triggered by an event. In the latter case,
+the event is handled by the `GameEntityManager` which calls an activity *system*
+that processes the event to choose the next node.
+
+Advancing in the graph, i.e. visiting nodes and performing actions costs no ingame time. Time
+delays of actions, e.g. for using an game mechanic like movement, are instead handled by
+scheduling and waiting for events at certain nodes in the graph (e.g. `XOR_EVENT_GATE` nodes).
+This means that when running the activity system, the directed edges of the nodes are followed
+until a node that waits for an event is reached. This allows the activity graph to support
+complex action chains that can be executed in sequence.
+
+Activities are reusable, i.e. they are intended to be shared by many game entities. Usually,
 all game entities of the same type should share the same behaviour, so they get assigned
 the same activity node graph.
 
@@ -45,14 +61,47 @@ representation. You don't need to know BPMN to understand the activity control f
 we explain everything important about the graphs in our documentation. However,
 you can use available [BPMN tools](https://bpmn.io/) to draw activity node graphs.
 
-## Node Types
+Like all game data, activities and node types for game entities are defined via the
+[nyan API](doc/nyan/openage-lib.md).
+
+
+## Workflow
+
+![Activity Workflow](images/activity_workflow.png)
+
+### Initialization
 
+When a game entity is spawned, the engine first checks whether entity's `GameEntity` API object
+has an ability `Activity` assigned. If that is the case, the activity graph is loaded from
+the corresponding API objects defining the graph. Most of this step involves creates the
+nodes and connections for the graph as well as mapping the API objects to node actions.
+
+The loaded activity graph is stored in a `Activity` component that is assigned to the game
+entity. At this point, the activity state of the entity is still uninitialized which allows
+the entity or the component to be cached for faster assignment to entities using the same graph.
+To let the entity become active, the `init(..)` method of the Activity component should be
+called after the entity is completely initialized. This sets the activity state to the start
+node of the actvity graph.
+
+### Advancing in the graph
+
+After the game entity is spawned, the `GameEntityManager` is called once to trigger the initial
+behavior of the game entity. This advances the activity state until the first event branch where
+an event is required for further advancement. The `GameEntityManager` now waits for events
+for the entity to further advance in the graph.
+
+A game entity's current activity state is stored in its `Activity` component in form of
+a reference to the current node. Additionally, the components stores the list of events
+the entity currently waits for to advance.
+
+## Node Types
 
-| Type             | Inputs | Outputs | Description               |
-| ---------------- | ------ | ------- | ------------------------- |
-| `START`          | 0      | 1       | Start of activity         |
-| `END`            | 1      | 0       | End of activity           |
-| `TASK_SYSTEM`    | 1      | 1       | Run built-in system       |
-| `TASK_CUSTOM`    | 1      | 1       | Run custom function       |
-| `XOR_EVENT_GATE` | 1      | 1+      | Wait for event and branch |
-| `XOR_GATE`       | 1      | 1+      | Branch on condition       |
+| Type              | Description               | Inputs | Outputs |
+| ----------------- | ------------------------- | ------ | ------- |
+| `START`           | Start of activity         | 0      | 1       |
+| `END`             | End of activity           | 1      | 0       |
+| `TASK_SYSTEM`     | Run built-in system       | 1      | 1       |
+| `TASK_CUSTOM`     | Run custom function       | 1      | 1       |
+| `XOR_EVENT_GATE`  | Wait for event and branch | 1      | 1+      |
+| `XOR_GATE`        | Branch on condition       | 1      | 1+      |
+| `XOR_SWITCH_GATE` | Branch on value           | 1      | 1+      |