Sensing.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/BorrowedRef.h"
#include "common/Module.h"
#include "common/Result.h"
#include "common/SensingQuery.h"
#include "common/SquirrelOwnership.h"
#include "spatial/SpatialHash2D.h"
 
#include <cstdint>
#include <limits>
#include <map>
#include <memory>
#include <optional>
#include <set>
#include <span>
#include <string>
#include <string_view>
#include <unordered_map>
#include <variant>
#include <vector>
 
namespace eve::sensing {
 
struct Subject {
    std::string           id;
    float                 x = 0, y = 0;
    std::string           faction;
    std::set<std::string> tags;
    std::set<std::string> visibleTo;
    std::set<std::string> zones; 
};
 
struct Candidate {
    std::string id;
    float       x = 0, y = 0, distance = 0;
};
 
enum class CountPolicy : std::uint8_t {
    FailIfOutOfRange,
    TruncateToMax,
};
 
enum class SortKey : std::uint8_t {
    None,
    DistanceAscending,
};
 
struct QueryCircle {
    float x      = 0.f;
    float y      = 0.f;
    float radius = 0.f;
};
 
struct QueryBox {
    float minX = 0.f;
    float minY = 0.f;
    float maxX = 0.f;
    float maxY = 0.f;
};
 
struct QueryCone {
    float x         = 0.f;
    float y         = 0.f;
    float dirX      = 1.f;
    float dirY      = 0.f;
    float halfAngle = 0.f;
    float range     = 0.f;
};
 
using QueryShape = std::variant<std::monostate, QueryCircle, QueryBox, QueryCone>;
 
struct QuerySpec {
    QueryShape               shape{};
    float                    minRange = 0.f;
    float                    maxRange = std::numeric_limits<float>::infinity();
    std::vector<std::string> requiredTags;
    std::vector<std::string> excludedTags;
    std::vector<std::string> includeFactions;
    std::vector<std::string> excludeFactions;
    std::optional<std::string> visibleTo;
    std::uint32_t            minCount    = 0;
    std::uint32_t            maxCount    = std::numeric_limits<std::uint32_t>::max();
    CountPolicy              countPolicy = CountPolicy::TruncateToMax;
    SortKey                  sortKey     = SortKey::DistanceAscending;
 
    [[nodiscard]] eve::Result<void> validate() const;
};
 
struct QueryOrigin {
    float                x = 0.f;
    float                y = 0.f;
    std::optional<std::string> subjectId; 
};
 
struct RankedCandidate {
    std::string id;
    float       x            = 0.f;
    float       y            = 0.f;
    float       distance     = 0.f;
    float       score        = 0.f; 
    std::string scoreReason;        
};
 
class CandidateQueryResult {
public:
    CandidateQueryResult() = default;
    explicit CandidateQueryResult(std::vector<RankedCandidate> ranked) : ranked_(std::move(ranked)) {}
 
    [[nodiscard]] std::span<const RankedCandidate> ranked() const noexcept { return ranked_; }
    [[nodiscard]] std::size_t size() const noexcept { return ranked_.size(); }
 
private:
    std::vector<RankedCandidate> ranked_;
};
 
class EVENGINE_API_PLATFORM SensingWorld {
public:
    [[nodiscard]] eve::Result<void> upsert(std::string_view id, float x, float y, std::string_view faction,
                                           std::string_view tagsCsv, std::string_view visibleToCsv);
    [[nodiscard]] eve::Result<void> remove(std::string_view id);
    [[nodiscard]] eve::Result<void> setZones(std::string_view id, std::string_view zonesCsv);
 
    [[nodiscard]] eve::Result<void> setSpatialIndexEnabled(bool enabled, float cellSize = 64.f);
    [[nodiscard]] bool spatialIndexEnabled() const noexcept;
 
    [[nodiscard]] eve::Result<CandidateQueryResult> query(const QueryOrigin& origin, const QuerySpec& spec);
 
    [[nodiscard]] eve::Result<int> circle(float x, float y, float radius, std::string_view requireTagsCsv,
                                          std::string_view excludeTagsCsv, std::string_view includeFactionsCsv,
                                          std::string_view excludeFactionsCsv, std::string_view visibleTo, int limit);
    [[nodiscard]] eve::Result<int> box(float minX, float minY, float maxX, float maxY, std::string_view requireTagsCsv,
                                       std::string_view excludeTagsCsv, std::string_view includeFactionsCsv,
                                       std::string_view excludeFactionsCsv, std::string_view visibleTo, int limit);
    [[nodiscard]] eve::Result<int> executePreset(std::string_view presetId, float originX, float originY, float dirX,
                                                 float dirY);
    [[nodiscard]] eve::OptionalRef<const Candidate> resultAt(int index) const;
    [[nodiscard]] std::string debugLastQueryJson() const;
    std::string snapshotJson() const;
    [[nodiscard]] eve::Result<void> restoreJson(const std::string& json);
 
    [[nodiscard]] const std::map<std::string, Subject>& subjects() const noexcept { return subjects_; }
 
    SensingWorld() = default;
    ~SensingWorld() = default;
    SensingWorld(const SensingWorld&) = delete;
    SensingWorld& operator=(const SensingWorld&) = delete;
    SensingWorld(SensingWorld&&) noexcept = default;
    SensingWorld& operator=(SensingWorld&&) noexcept = default;
 
private:
    [[nodiscard]] bool accepts(const Subject& subject, const QuerySpec& spec) const;
    void               publishResults(std::vector<RankedCandidate> ranked);
    void               clearSpatialIndex();
    void               rebuildSpatialIndex();
    void               indexSubject(const Subject& subject);
    void               unindexSubject(const std::string& id);
    [[nodiscard]] bool trySpatialBroadphase(const QueryOrigin& origin, const QuerySpec& spec,
                                            std::vector<const Subject*>& out) const;
 
    std::map<std::string, Subject> subjects_;
    std::vector<Candidate>         results_;
 
    std::unique_ptr<eve::spatial::SpatialHash2D> spatialIndex_;
    std::unordered_map<std::string, int>         subjectSpatialIds_;
    std::unordered_map<int, std::string>         spatialIdSubjects_;
    int                                          nextSpatialId_ = 1;
 
    struct LastQueryDebug {
        bool                         usedSpatial = false;
        std::uint32_t                scanned     = 0;
        std::uint32_t                accepted    = 0;
        float                        originX     = 0.f;
        float                        originY     = 0.f;
        std::string                  shapeKind   = "none";
        std::vector<RankedCandidate> ranked;
    };
    LastQueryDebug lastQuery_;
};
 
struct SensingWorldHandleTag {};
using SensingWorldHandleRef = eve::script::RuntimeHandleRef<SensingWorldHandleTag>;
 
class EVENGINE_API_PLATFORM Sensing : public Module, public eve::ISensingQuery {
public:
    Module_REG(Sensing);
    Sensing();
    ~Sensing() override;
    [[nodiscard]] static eve::Result<SensingWorldHandleRef> newWorld();
    [[nodiscard]] static eve::script::Borrowed<SensingWorld> resolve(SensingWorldHandleRef reference) noexcept;
    [[nodiscard]] static eve::Result<void> release(SensingWorldHandleRef reference);
    [[nodiscard]] static bool isStale(SensingWorldHandleRef reference) noexcept;
 
    [[nodiscard]] int worldCount() const override;
    [[nodiscard]] std::vector<eve::SensingWorldQuery> lastQueries() const override;
 
private:
    eve::script::RuntimeObjectRegistry<SensingWorld, SensingWorldHandleTag> worlds_;
};
 
struct PerceptionFact {
    std::string subjectId;
    float       x            = 0.f;
    float       y            = 0.f;
    float       distance     = 0.f;
    float       score        = 0.f;
    std::string scoreReason;
};
 
[[nodiscard]] inline std::vector<PerceptionFact> perceptionFactsFrom(const CandidateQueryResult& result) {
    std::vector<PerceptionFact> facts;
    facts.reserve(result.size());
    for (const auto& candidate : result.ranked()) {
        PerceptionFact fact;
        fact.subjectId   = candidate.id;
        fact.x           = candidate.x;
        fact.y           = candidate.y;
        fact.distance    = candidate.distance;
        fact.score       = candidate.score;
        fact.scoreReason = candidate.scoreReason;
        facts.push_back(std::move(fact));
    }
    return facts;
}
 
}  // namespace eve::sensing