ConditionRef.h

Go to the documentation of this file.

/**
 * @file ConditionRef.h
 * @brief Defines OperandRef and ConditionRef — standalone operand-to-pin mapping structures.
 * @author Olympe Engine
 * @date 2026-03-18
 *
 * @details
 * ConditionRef is a self-contained representation of one condition expression
 * for a Branch or While node.  Unlike NodeConditionRef (which references a
 * ConditionPreset in the global registry), ConditionRef stores the full
 * operand data inline — enabling use cases where no registry round-trip is
 * required (e.g. migration, serialisation helpers, runtime evaluation).
 *
 * The `OperandRef::dynamicPinID` field provides the
 * ConditionRef -> DynamicDataPin mapping required by Phase 24 Milestone 1:
 * when an operand is in Pin mode the field holds the UUID of the
 * DynamicDataPin generated by DynamicDataPinManager so the runtime can look
 * up the live float value.
 *
 * C++14 compliant — no std::optional, structured bindings, std::filesystem.
 */
 
#pragma once
 
#include <string>
#include <vector>
 
#include "../TaskSystem/TaskGraphTypes.h"  // VariableType
#include "../third_party/nlohmann/json.hpp"
 
namespace Olympe {
 
/**
 * @struct OperandRef
 * @brief References one operand of a condition (left or right).
 *
 * @details
 * If mode is `Pin`, `dynamicPinID` stores the UUID of the DynamicDataPin
 * generated on the node by DynamicDataPinManager::RegeneratePinsFromConditions().
 * If mode is `Variable` or `Const`, no pin is generated and `dynamicPinID`
 * is left empty.
 */
struct OperandRef
{
    /** @brief Discriminates the data source of this operand. */
    enum class Mode
    {
        Variable, ///< References a blackboard variable by name
        Const,    ///< Literal constant value
        Pin       ///< External data-input pin on the owning node
    };
 
    Mode mode = Mode::Const; ///< Active mode
 
    // Variable / Const modes
    std::string variableName; ///< Blackboard key  (mode == Variable), e.g. "mHealth"
    std::string constValue;   ///< Literal string  (mode == Const),    e.g. "100.0"
 
    // Pin mode only
    /**
     * @brief UUID of the DynamicDataPin that supplies this operand's value.
     *
     * Populated by DynamicDataPinManager::RegeneratePinsFromConditions() when
     * the parent ConditionRef is registered with a Pin-mode operand.
     * Format: "pin_inst_<random>", e.g. "pin_inst_abc123def456".
     * Empty string means no pin has been assigned yet.
     */
    std::string dynamicPinID;
 
    // -----------------------------------------------------------------------
    // Serialization
    // -----------------------------------------------------------------------
 
    /// @brief Serializes this OperandRef to a JSON object.
    nlohmann::json ToJson() const;
 
    /// @brief Deserializes an OperandRef from a JSON object.
    static OperandRef FromJson(const nlohmann::json& data);
};
 
/**
 * @struct ConditionRef
 * @brief Stores the complete reference for one condition including
 *        operand-to-DynamicDataPin mapping.
 *
 * @details
 * Conditions whose operands are in Pin mode automatically have
 * DynamicDataPin objects generated for them by DynamicDataPinManager.
 * The panel renders this structure with editable fields for each component
 * (operand values, operator, logical combinator).
 *
 * Multiple ConditionRef objects on a single node are evaluated in order,
 * combined via their implicit logical operators (And/Or).
 */
struct ConditionRef
{
    int conditionIndex = -1; ///< Index in the Branch/While node's conditions[] array
 
    // Operands
    OperandRef  leftOperand;            ///< Left-hand side of the comparison
    std::string operatorStr = "==";     ///< Comparison operator: "==", "<=", ">=", "!=", "<", ">"
    OperandRef  rightOperand;           ///< Right-hand side of the comparison
 
    // Type hint used for type-checking and pin dataType selection
    VariableType compareType = VariableType::Float; ///< Expected value type of both operands
 
    // -----------------------------------------------------------------------
    // Serialization
    // -----------------------------------------------------------------------
 
    /// @brief Serializes this ConditionRef to a JSON object.
    nlohmann::json ToJson() const;
 
    /// @brief Deserializes a ConditionRef from a JSON object.
    static ConditionRef FromJson(const nlohmann::json& data);
};
 
} // namespace Olympe