gamestate: Add activity node type for branching on value.

Author: heinezen

doc/code/game_simulation/activity.md

@@ -48,11 +48,12 @@ you can use available [BPMN tools](https://bpmn.io/) to draw activity node graph
 ## 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              | 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       |
+| `XOR_SWITCH_GATE` | 1      | 1+      | Branch on value           |

libopenage/gamestate/activity/CMakeLists.txt

@@ -9,6 +9,7 @@ add_sources(libopenage
     types.cpp
     xor_event_gate.cpp
     xor_gate.cpp
+    xor_switch_gate.cpp
 )
 
 add_subdirectory("event")

libopenage/gamestate/activity/types.h

@@ -13,6 +13,7 @@ enum class node_t {
 	END,
 	XOR_EVENT_GATE,
 	XOR_GATE,
+	XOR_SWITCH_GATE,
 	TASK_CUSTOM,
 	TASK_SYSTEM,
 };

libopenage/gamestate/activity/xor_event_gate.h

@@ -61,7 +61,7 @@ class XorEventGate : public Node {
 	 * @param label Human-readable label (optional).
 	 */
 	XorEventGate(node_id_t id,
-	             node_label_t label = "EventGateWay");
+	             node_label_t label = "ExclusiveEventGateway");
 
 	/**
 	 * Create a new exclusive event gateway.

libopenage/gamestate/activity/xor_gate.h

@@ -24,7 +24,7 @@ namespace activity {
 /**
  * Function that determines if an output node is chosen.
  *
- * @param time Current game time.
+ * @param time Current simulation time.
  * @param entity Entity that is executing the activity.
  *
  * @return true if the output node is chosen, false otherwise.

libopenage/gamestate/activity/xor_switch_gate.cpp

@@ -0,0 +1,53 @@
+// Copyright 2024-2024 the openage authors. See copying.md for legal info.
+
+#include "xor_switch_gate.h"
+
+
+namespace openage::gamestate::activity {
+
+XorSwitchGate::XorSwitchGate(node_id_t id,
+                             node_label_t label) :
+	Node{id, label} {}
+
+XorSwitchGate::XorSwitchGate(node_id_t id,
+                             node_label_t label,
+                             const lookup_function_t &lookup_func,
+                             const lookup_dict_t &lookup_dict,
+                             const std::shared_ptr<Node> &default_node) :
+	Node{id, label},
+	lookup_func{lookup_func},
+	lookup_dict{lookup_dict},
+	default_node{default_node} {}
+
+void XorSwitchGate::set_output(const std::shared_ptr<Node> &output,
+                               const lookup_key_t &key) {
+	this->outputs.emplace(output->get_id(), output);
+	this->lookup_dict.emplace(key, output);
+}
+
+const XorSwitchGate::lookup_function_t &XorSwitchGate::get_lookup_func() const {
+	return this->lookup_func;
+}
+
+void XorSwitchGate::set_lookup_func(const lookup_function_t &lookup_func) {
+	this->lookup_func = lookup_func;
+}
+
+const XorSwitchGate::lookup_dict_t &XorSwitchGate::get_lookup_dict() const {
+	return this->lookup_dict;
+}
+
+const std::shared_ptr<Node> &XorSwitchGate::get_default() const {
+	return this->default_node;
+}
+
+void XorSwitchGate::set_default(const std::shared_ptr<Node> &node) {
+	if (this->default_node != nullptr) {
+		throw Error{MSG(err) << this->str() << " already has a default node"};
+	}
+
+	this->outputs.emplace(node->get_id(), node);
+	this->default_node = node;
+}
+
+} // namespace openage::gamestate::activity

libopenage/gamestate/activity/xor_switch_gate.h

@@ -0,0 +1,152 @@
+// Copyright 2024-2024 the openage authors. See copying.md for legal info.
+
+#pragma once
+
+#include <concepts>
+#include <functional>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "gamestate/activity/node.h"
+#include "gamestate/activity/types.h"
+#include "time/time.h"
+
+
+namespace openage::gamestate {
+class GameEntity;
+
+namespace activity {
+
+/**
+ * Chooses one of its output nodes based on enum values.
+ *
+ * In comparison to the XOR gate, this node type does not tie individual
+ * conditions to each node. Instead, it operates on a single function that
+ * returns a key for a lookup dict. The lookup dict maps these keys to output
+ * node ID.
+ *
+ * This type of gate is easier to use for simpler branch switches based on
+ * similar conditions, e.g. a branching based on the value of an enum.
+ */
+class XorSwitchGate : public Node {
+public:
+	/**
+	 * Type used as lookup key for the lookup dict.
+	 */
+	using lookup_key_t = int;
+
+	/**
+	 * Function that retrieves a lookup key for the lookup dict from
+	 * the current state of an entity.
+	 *
+	 * @param time Current simulation time.
+	 * @param entity Entity that is executing the activity.
+	 *
+	 * @return Lookup key.
+	 */
+	using lookup_function_t = std::function<lookup_key_t(const time::time_t &,
+	                                                     const std::shared_ptr<gamestate::GameEntity> &)>;
+
+	/**
+	 * Lookup dict that maps lookup keys to output node IDs.
+	 */
+	using lookup_dict_t = std::unordered_map<lookup_key_t, std::shared_ptr<Node>>;
+
+	/**
+	 * Creates a new XOR switch gate node.
+	 *
+	 * @param id Unique identifier of the node.
+	 * @param label Human-readable label of the node (optional).
+	 */
+	XorSwitchGate(node_id_t id,
+	              node_label_t label = "ExclusiveSwitchGateway");
+
+	/**
+	 * Creates a new XOR switch gate node.
+	 *
+	 * @param id Unique identifier of the node.
+	 * @param label Human-readable label of the node.
+	 * @param lookup_func Function that looks up the key to the lookup dict.
+	 * @param lookup_dict Initial lookup dict that maps lookup keys to output node IDs.
+	 * @param default_node Default output node. Chosen if no lookup entry is defined.
+	 */
+	XorSwitchGate(node_id_t id,
+	              node_label_t label,
+	              const lookup_function_t &lookup_func,
+	              const lookup_dict_t &lookup_dict,
+	              const std::shared_ptr<Node> &default_node);
+
+	virtual ~XorSwitchGate() = default;
+
+	inline node_t get_type() const override {
+		return node_t::XOR_SWITCH_GATE;
+	}
+
+	/**
+	 * Set the output node for a given lookup key.
+	 *
+	 * @param output Output node.
+	 * @param key Enumeration value.
+	 */
+	void set_output(const std::shared_ptr<Node> &output,
+	                const lookup_key_t &key);
+
+	/**
+	 * Get the lookup function for determining the output nodes.
+	 *
+	 * @return Lookup function.
+	 */
+	const lookup_function_t &get_lookup_func() const;
+
+	/**
+	 * Set the lookup function for determining the output nodes.
+	 *
+	 * @param lookup_func Lookup function.
+	 */
+	void set_lookup_func(const lookup_function_t &lookup_func);
+
+	/**
+	 * Get the lookup dict for the output nodes.
+	 *
+	 * @return Lookup dict.
+	 */
+	const lookup_dict_t &get_lookup_dict() const;
+
+	/**
+	 * Get the default output node.
+	 *
+	 * @return Default output node.
+	 */
+	const std::shared_ptr<Node> &get_default() const;
+
+	/**
+	 * Set the the default output node.
+	 *
+	 * This node is chosen if the lookup dict does not contain an entry for the
+	 * lookup key returned by the lookup function.
+	 *
+	 * @param node Default output node.
+	 */
+	void set_default(const std::shared_ptr<Node> &node);
+
+private:
+	/**
+	 * Determines the lookup key for the lookup dict from the current state.
+	 */
+	lookup_function_t lookup_func;
+
+	/**
+	 * Maps lookup keys to output node IDs.
+	 */
+	lookup_dict_t lookup_dict;
+
+	/**
+	 * Default output node. Chosen if no lookup entry is defined.
+	 */
+	std::shared_ptr<Node> default_node;
+};
+
+} // namespace activity
+} // namespace openage::gamestate