Sensor.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Nexus/Pheme/Perception.hpp"
 
namespace MayaFlux::Nexus {
 
/**
 * @class Sensor
 * @brief Object that reacts to nearby entities when committed.
 *
 * Constructed with a query radius and, optionally, a perception function. Position
 * is optional: call @c set_position before registering with @c Fabric if
 * spatial queries are required. A Sensor without a position receives an
 * empty @c spatial_results span on each commit.
 *
 * The id is assigned by @c Fabric::wire and is stable for the object's
 * lifetime.
 */
class MAYAFLUX_API Sensor {
public:
    using PerceptionFn = std::function<void(const PerceptionContext&)>;
 
    /**
     * @brief Construct with only a query radius, for a Sensor whose behaviour comes
     *        from a typed perception.
     * @param query_radius Radius passed to the spatial index on each commit.
     *                     Ignored if no position has been set.
     */
    explicit Sensor(float query_radius = 1.0F)
        : m_query_radius(query_radius)
    {
    }
 
    /**
     * @brief Construct with a query radius and a perception function.
     * @param query_radius Radius passed to the spatial index on each commit.
     *                     Ignored if no position has been set.
     * @param fn           Called on every commit with the current context.
     */
    explicit Sensor(float query_radius, PerceptionFn fn)
        : m_query_radius(query_radius)
        , m_fn(std::move(fn))
    {
    }
 
    /**
     * @brief Construct with a query radius and a named perception function.
     * @param query_radius Radius passed to the spatial index on each commit.
     * @param fn_name      Identifier used for state encoding.
     * @param fn           Called on every commit with the current context.
     */
    Sensor(float query_radius, std::string fn_name, PerceptionFn fn)
        : m_query_radius(query_radius)
        , m_fn_name(std::move(fn_name))
        , m_fn(std::move(fn))
    {
    }
 
    /** @brief Identifier assigned to the perception function, empty if anonymous. */
    [[nodiscard]] const std::string& fn_name() const { return m_fn_name; }
 
    /** @brief Set or replace the perception function's identifier. */
    void set_fn_name(std::string name) { m_fn_name = std::move(name); }
 
    /** @brief The perception function itself. */
    [[nodiscard]] const PerceptionFn& fn() const { return m_fn; }
 
    /**
     * @brief Return the current position, if set.
     */
    [[nodiscard]] const std::optional<glm::vec3>& position() const { return m_position; }
 
    /**
     * @brief Set the position, enabling spatial queries for this object.
     * @param p World-space coordinates.
     */
    void set_position(const glm::vec3& p) { m_position = p; }
 
    /**
     * @brief Clear the position, disabling spatial queries for this object.
     */
    void clear_position() { m_position.reset(); }
 
    /**
     * @brief Return the query radius.
     */
    [[nodiscard]] float query_radius() const { return m_query_radius; }
 
    /**
     * @brief Set the query radius.
     * @param r New radius in world-space units.
     */
    void set_query_radius(float r) { m_query_radius = r; }
 
    /**
     * @brief Return the stable object id assigned by Fabric.
     */
    [[nodiscard]] uint32_t id() const { return m_id; }
 
    /**
     * @brief Set the one source of a perception of any type.
     * @tparam T Type the source returns; whatever the target takes.
     * @param source Reads the value, using the perception context.
     * @param target Takes the value and decides where it lands.
     *
     * A Sensor has a single source: setting another replaces it. Runs on every
     * invoke before the perception function. Not part of encoded state.
     */
    template <typename T>
    void set_perception(typename Perception<T>::Source source, typename Perception<T>::Target target)
    {
        auto perception = std::make_shared<Perception<T>>(std::move(source));
        perception->add_target(std::move(target));
        m_perception = [perception](const PerceptionContext& ctx) { perception->invoke(ctx); };
    }
 
    /** @brief Remove the source set with set_perception(). */
    void clear_perception() { m_perception = nullptr; }
 
    /**
     * @brief Invoke the perception function with the supplied context.
     * @param ctx Populated context for this commit.
     */
    void invoke(const PerceptionContext& ctx) const
    {
        if (m_perception) {
            m_perception(ctx);
        }
        if (m_fn) {
            m_fn(ctx);
        }
    }
 
private:
    std::optional<glm::vec3> m_position;
    float m_query_radius;
    std::string m_fn_name;
    PerceptionFn m_fn;
    PerceptionFn m_perception;
    uint32_t m_id { 0 };
 
    friend class Fabric;
};
 
} // namespace MayaFlux::Nexus