Crowd.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/Module.h"
#include "crowd/CrowdField.h"
 
#include <cstdint>
#include <memory>
#include <string>
#include <vector>
 
namespace eve::crowd {
 
struct AgentState {
    float x = 0.f;       
    float y = 0.f;       
    float heading = 0.f; 
    float speed = 0.f;   
    float vx = 0.f;      
    float vy = 0.f;      
    int action = -1;     
    int data = 0;        
    int avoidancePriority = 0; 
};
 
struct FlowVec {
    float x = 0.f; 
    float y = 0.f; 
};
 
struct StepReport {
    std::int64_t avoidanceChecks      = 0;    
    int          avoidanceTruncations = 0;    
    int          substeps             = 0;    
    int          unresolvedContacts   = 0;    
    int          unresolvedWalls      = 0;    
    float        maxPenetration       = 0.f;  
};
 
struct AvoidanceSettings {
    bool  enabled      = false;  
    float horizon      = 2.f;    
    float margin       = 0.05f;  
    int   maxNeighbors = 32;     
};
 
struct AgentInteraction {
    float pushability  = 1.f;         
    bool  holdPosition = false;       
    int   layer        = 1;           
    int   mask         = 0x7fffffff;  
};
 
enum class SpawnPolicy { RejectOverlap, NearestFree, PushNeighbors };
 
struct SpawnRequest {
    std::string      stableId;
    float            x = 0.f, y = 0.f, heading = 0.f, radius = 1.f;
    AgentInteraction interaction;
};
 
struct SpawnBatch {
    std::vector<SpawnRequest> agents;
    SpawnPolicy               policy        = SpawnPolicy::PushNeighbors;
    float                     maxDistance   = 64.f;  
    float                     searchSpacing = 1.f;   
    int                       maxPasses     = 64;    
    int                       maxChecks = 1000000;   
};
 
struct SpawnPlacement {
    std::string stableId;
    float       x = 0.f, y = 0.f;
};
 
struct SpawnReceipt {
    std::vector<SpawnPlacement> created;
    int                         displacedAgents = 0;
    int                         checks          = 0;
};
 
class EVENGINE_API_FOUNDATION Crowd : public Module {
public:
    Module_REG(Crowd);
    Crowd();
    ~Crowd() override;
 
    // --- 流场（内部持有一个 CrowdField） ---
    void resizeField(int width, int height, float cellSize, float originX, float originY);
    void setBlocked(int cx, int cy, bool blocked);
    void setCellCost(int cx, int cy, float cost);
    float getCellCost(int cx, int cy) const;
    void buildFlowField(int gx, int gy);
    void addFlowGoal(int gx, int gy);
    void clearFlowGoals();
    void build();
    bool isFieldBuilt() const;
    bool isReachable(int cx, int cy) const;
    int getFieldWidth() const;
    int getFieldHeight() const;
    float getCellSize() const;
    float getFieldOriginX() const;
    float getFieldOriginY() const;
 
    FlowVec flowAtWorld(float wx, float wy) const;
    float costAtWorld(float wx, float wy) const;
    FlowVec flowAtCell(int cx, int cy) const;
 
    // --- 单位 ---
    int addAgent(float x, float y, float heading, float radius);
    int addNamedAgent(const std::string &stableId, float x, float y, float heading, float radius);
    bool hasNamedAgent(const std::string &stableId) const;
    int getNamedAgentIndex(const std::string &stableId) const;
    std::string getAgentStableId(int index) const;
    bool removeNamedAgent(const std::string &stableId);
    bool removeAgent(int id);
    void clearAgents();
    int getAgentCount() const;
    void setMaxAgents(int maxAgents);
    int getMaxAgents() const;
 
    bool setAgentAction(int id, const std::string &action);
    std::string getAgentAction(int id) const;
    bool setAgentTarget(int id, float tx, float ty);
    bool clearAgentTarget(int id);
    bool setAgentSpeed(int id, float speed);
    bool setAgentAccel(int id, float accel);
    bool setAgentTurnRate(int id, float radPerSec);
    bool setAgentRadius(int id, float radius);
    bool setAgentData(int id, int data);
    int getAgentData(int id) const;
    [[nodiscard]] Result<void> setAgentAvoidancePriority(int id, int priority);
    int getAgentAvoidancePriority(int id) const;
    [[nodiscard]] Result<void> setAgentInteraction(int id, AgentInteraction policy);
    [[nodiscard]] Result<AgentInteraction> getAgentInteraction(int id) const;
    [[nodiscard]] Result<SpawnReceipt> applySpawnBatch(const SpawnBatch &batch);
    bool setAgentPosition(int id, float x, float y);
    AgentState getAgentState(int id) const;
 
    // --- 群体参数 ---
    void setDefaultSpeed(float speed);
    void setDefaultRadius(float radius);
    void setDefaultTurnRate(float radPerSec);
    void setArriveRadius(float radius);
    void setSeparationRadius(float radius);
    void setPerceptionRadius(float radius);
    void setSeparationWeight(float weight);
    void setAlignmentWeight(float weight);
    void setCohesionWeight(float weight);
    void setWanderWeight(float weight);
    void setGoalWeight(float weight);
    void setResolveOverlaps(bool enable);
    void setClampToField(bool enable);
    [[nodiscard]] Result<void> configureAvoidance(AvoidanceSettings settings);
    AvoidanceSettings getAvoidanceSettings() const;
 
    [[nodiscard]] Result<StepReport> advance(float dt);
 
    void step(float dt);
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
}  // namespace eve::crowd