16. 移动、寻路与导航

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/navigation_recast/recast_generator.hpp（简化）
class RecastGenerator
{
    struct RecastConfig
    {
        BoundingBox chunkBB_;                 // 分块边界
        float maxWalkableSlopeInAngle_;       // 最大可走坡度
        float maxAgentClimb_;                 // 最大攀爬高度
        float agentHeight_;                   // 代理高度
        float agentRadius_;                   // 代理半径
        bool scaleNavigation_;                // 导航缩放
        float gridSize_;                      // 网格大小
    };

    bool generate(const CollisionSceneProviders& provider,
        const RecastConfig& config, int gridX, int gridZ, bool useMono);

    // Recast 流水线的中间产物
    AutoPtr<rcHeightfield> heightField_;
    AutoPtr<rcCompactHeightfield> compactHeightField_;
    AutoPtr<rcPolyMesh> polyMesh_;
};

// 文件：kbe/src/server/cellapp/loadnavmesh_threadtasks.h（简化）
class LoadNavmeshTask : public thread::TPTask
{
public:
    LoadNavmeshTask(const std::string& resPath, SPACE_ID spaceID,
        const std::map<int, std::string>& params);

    virtual bool process();              // 在线程池中加载 NavMesh
    virtual TPTaskState presentMainThread();  // 回到主线程通知

private:
    std::string resPath_;
    SPACE_ID spaceID_;
    std::map<int, std::string> params_;
};

// 文件：kbe/src/lib/navigation/navigation_handle.h（简化）
class NavigationHandle : public RefCountable
{
public:
    enum NAV_TYPE { NAV_UNKNOWN = 0, NAV_MESH = 1, NAV_TILE = 2 };
    enum NAV_OBJECT_STATE { NAV_OBJECT_STATE_MOVING = 1, NAV_OBJECT_STATE_MOVEOVER = 2 };

    virtual NAV_TYPE type() const { return NAV_UNKNOWN; }

    // 核心导航接口
    virtual int findStraightPath(int layer, const Position3D& start,
        const Position3D& end, std::vector<Position3D>& paths) = 0;

    virtual int findRandomPointAroundCircle(int layer, const Position3D& centerPos,
        std::vector<Position3D>& points, uint32 max_points, float maxRadius) = 0;

    virtual int raycast(int layer, const Position3D& start,
        const Position3D& end, std::vector<Position3D>& hitPointVec) = 0;

    std::string resPath;
};

// 文件：kbe/src/lib/navigation/navigation_mesh_handle.h（简化）
class NavMeshHandle : public NavigationHandle
{
public:
    static const int MAX_POLYS = 256;
    static const int INVALID_NAVMESH_POLYREF = 0;

    struct NavmeshLayer
    {
        dtNavMesh* pNavmesh;           // Detour 导航网格
        dtNavMeshQuery* pNavmeshQuery; // Detour 查询对象
    };

    virtual int findStraightPath(int layer, const Position3D& start,
        const Position3D& end, std::vector<Position3D>& paths);
    virtual int raycast(int layer, const Position3D& start,
        const Position3D& end, std::vector<Position3D>& hitPointVec);
    virtual NAV_TYPE type() const { return NAV_MESH; }

    std::map<int, NavmeshLayer> navmeshLayer;   // 支持多层导航网格
};

// 文件：kbe/src/lib/navigation/navigation_tile_handle.h（简化）
class NavTileHandle : public NavigationHandle
{
public:
    enum TILE_STATE
    {
        TILE_STATE_OPENED_COST0 = 0,   // 可通行，代价 0
        TILE_STATE_OPENED_COST1 = 1,   // 可通行，代价 1
        // ... 代价 2~5
        TILE_STATE_CLOSED = 9          // 不可通行
    };

    // A* 搜索节点
    class MapSearchNode
    {
    public:
        int x, y;
        float GoalDistanceEstimate(MapSearchNode& nodeGoal);
        bool IsGoal(MapSearchNode& nodeGoal);
        bool GetSuccessors(AStarSearch<MapSearchNode>* astarsearch,
            MapSearchNode* parent_node);
        float GetCost(MapSearchNode& successor);
        bool IsSameState(MapSearchNode& rhs);
    };

    virtual NAV_TYPE type() const { return NAV_TILE; }

    Tmx::Map* pTilemap;           // TMX 格式地图（Tiled Map Editor 导出）
    bool direction8_;             // 8 方向 vs 4 方向
};

// 文件：kbe/src/lib/navigation/navigation.h（简化）
class Navigation : public Singleton<Navigation>
{
public:
    NavigationHandlePtr loadNavigation(std::string resPath,
        const std::map<int, std::string>& params);
    bool hasNavigation(std::string resPath);
    bool removeNavigation(std::string resPath);
    NavigationHandlePtr findNavigation(std::string resPath);

private:
    KBEUnordered_map<std::string, NavigationHandlePtr> navhandles_;
    KBEngine::thread::ThreadMutex mutex_;
};

// 文件：kbe/src/server/cellapp/controller.h（简化）
class Controller
{
public:
    enum ControllerType
    {
        CONTROLLER_TYPE_NORMAL = 0,        // 常规类型
        CONTROLLER_TYPE_PROXIMITY = 1,     // 范围触发器类型
        CONTROLLER_TYPE_MOVE = 2,          // 移动控制器类型
        CONTROLLER_TYPE_ROTATE = 3,        // 旋转控制器类型
    };

    Controller(ControllerType type, Entity* pEntity, int32 userarg, uint32 id = 0);
    virtual ~Controller();

    virtual void destroy();
    virtual void addToStream(KBEngine::MemoryStream& s);
    virtual void createFromStream(KBEngine::MemoryStream& s);

protected:
    uint32 id_;
    Entity* pEntity_;
    int32 userarg_;
    Controllers* pControllers_;
    ControllerType type_;
};

// 文件：kbe/src/server/cellapp/move_controller.h（简化）
class MoveController : public Controller
{
public:
    MoveController(Entity* pEntity, MoveToPointHandler* pHandler = NULL,
        uint32 id = 0);

    float velocity() const { return pMoveToPointHandler_->velocity(); }
    void velocity(float v) { pMoveToPointHandler_->velocity(v); }

    virtual void destroy();

private:
    MoveToPointHandler* pMoveToPointHandler_;
};

// 文件：kbe/src/server/cellapp/navigate_handler.h（简化）
class NavigateHandler : public MoveToPointHandler
{
public:
    NavigateHandler(KBEShared_ptr<Controller>& pController,
        const Position3D& destPos, float velocity, float distance,
        bool faceMovement, float maxMoveDistance,
        VECTOR_POS3D_PTR paths_ptr, PyObject* userarg);

    virtual bool requestMoveOver(const Position3D& oldPos);
    virtual bool isOnGround() { return true; }
    virtual MoveType type() const { return MOVE_TYPE_NAV; }

protected:
    int destPosIdx_;                 // 当前路径点索引
    VECTOR_POS3D_PTR paths_;         // 完整路径点列表
    float maxMoveDistance_;           // 最大移动距离（安全限制）
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/controller.hpp（简化）
class Controller : public ReferenceCount
{
public:
    virtual ControllerType type() const = 0;
    virtual ControllerDomain domain() const = 0;
    virtual ControllerID exclusiveID() const = 0;

    // 生命周期
    virtual void startReal(bool isInitialStart);
    virtual void stopReal(bool isFinalStop);
    virtual void startGhost();
    virtual void stopGhost();

    // 序列化（跨 Cell 迁移时保存/恢复控制器状态）
    virtual void writeRealToStream(BinaryOStream& stream);
    virtual bool readRealFromStream(BinaryIStream& stream);
};

// 抽象移动基类
class MoveController : public Controller, public Updatable
{
    virtual void setEntityPosition(const Position3D& position,
        const Direction3D& direction);
    bool move(const Position3D& destination, float* pRemainingTicks = NULL);
};

// 移动到指定点
class MoveToPointController : public MoveController;

// 导航步骤（逐路径点移动）
class NavigateStepController : public MoveController;

// 追踪实体
class MoveToEntityController : public MoveController;

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/navigation_controller.hpp（简化）
class NavigationController : public Controller, public Updatable
{
    enum NavigationStatus
    {
        NAVIGATION_CANCELLED = -2,
        NAVIGATION_FAILED = -1,
        NAVIGATION_IN_PROGRESS = 0,
        NAVIGATION_COMPLETE = 1
    };

    NavigationStatus move();
    void generateTraversalPath(const NavLoc& srcLoc);

private:
    Vector3Path path_;          // 路径点数组
    int currentNode_;           // 当前路径节点索引
    Position3D destination_;    // 目标位置
    float girth_;               // 实体宽度（影响寻路避障）
    float closeEnough_;         // "足够接近"阈值
};

// 按固定角速度转向
class YawRotatorController : public Controller, public Updatable
{
    float radiansPerTick_;      // 每帧转向角度
    Angle targetYaw_;           // 目标偏航角
    bool turn();                // 执行转向
};

// 面向实体（持续跟踪）
class FaceEntityController : public Controller, public Updatable
{
    EntityPtr pTargetEntity_;   // 目标实体
    float radiansPerTick_;      // 转向速度
    int ticksToNextUpdate_;     // 更新间隔
    int period_;                // 更新周期
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/base_acceleration_controller.hpp（简化）
class BaseAccelerationController : public Controller, public Updatable
{
    enum Facing
    {
        FACING_NONE = 0,            // 不改变朝向
        FACING_VELOCITY = 1,        // 面向速度方向
        FACING_ACCELERATION = 2     // 面向加速度方向
    };

    static Vector3 calculateDesiredVelocity(
        const Position3D& currentPosition,
        const Position3D& desiredPosition,
        float acceleration, float maxSpeed, bool stopAtDestination);

    static Vector3 calculateAccelerationVector(
        const Vector3& currentVelocity,
        const Vector3& desiredVelocity);

    float acceleration_;    // 加速度
    float maxSpeed_;        // 最大速度
    Facing facing_;         // 朝向模式
};

// 具体实现
class AccelerateToPointController : public BaseAccelerationController;
class AccelerateAlongPathController : public BaseAccelerationController;
class AccelerateToEntityController : public BaseAccelerationController;

// 视觉控制器（视锥范围内的实体感知）
class VisionController : public Controller, public Updatable
{
    float visionAngle_;          // 视野角度
    float visionRange_;          // 视野距离
    float seeingHeight_;         // 观测高度
    int updatePeriod_;           // 更新周期（每 N tick 检查一次）
    VisionRangeTrigger* pVisionTrigger_;
};

// 临近控制器（球形范围内的实体感知）
class ProximityController : public Controller
{
    float range_;
    ProximityRangeTrigger* pProximityTrigger_;
    BW::vector<EntityID>* pOnloadedSet_;
};

class TimerController : public Controller
{
    class Handler : public TimerHandler
    {
        virtual void handleTimeout(TimerHandle handle, void* pUser);
        virtual void onRelease(TimerHandle handle, void* pUser);
    };

    Handler* pHandler_;
    GameTime start_;             // 开始时间
    GameTime interval_;          // 间隔时间
    TimerHandle timerHandle_;
};

// 文件：kbe/src/lib/navigation/navigation_handle.h（简化）
// NavMeshHandle::raycast
virtual int raycast(int layer, const Position3D& start,
    const Position3D& end, std::vector<Position3D>& hitPointVec);

// 文件：kbe/src/server/cellapp/cellapp.h（简化）
// Python 绑定
int raycast(SPACE_ID spaceID, int layer,
    const Position3D& start, const Position3D& end,
    std::vector<Position3D>& hitPos);
static PyObject* __py_raycast(PyObject* self, PyObject* args);

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/chunk/terrain_ray_collision_callback.hpp（简化）
class TerrainRayCollisionCallback : public Terrain::TerrainCollisionCallback
{
    virtual bool collide(const WorldTriangle& triangle, float dist);

    bool finishedColliding() const;

private:
    Matrix transform_;
    Vector3 start_;       // 射线起点
    Vector3 end_;         // 射线终点
    Vector3 dir_;         // 射线方向
    float dist_;          // 碰撞距离
};