17. Ghost 系统

// 文件：kbe/src/server/cellapp/entity.cpp
// 如果期间有base的消息发送过来， entity的ghost机制能够转到real上去...

// 文件：kbe/src/server/cellapp/ghost_manager.h
// ...需要向ghost_route_临时设置一个路由地址， 路由在最后一次收包超过一定时间擦除。

// 文件：kbe/src/server/cellapp/entity.inl（简化）
// 判断是否为 real 实体
INLINE bool Entity::isReal(void) const
{
    return realCell_ == 0;    // realCell_ 为 0 表示自己是 real
}

// 判断是否有 ghost
INLINE bool Entity::hasGhost(void) const
{
    return ghostCell_ > 0;    // ghostCell_ > 0 表示存在 ghost
}

// 文件：kbe/src/server/cellapp/entity.h（简化）
class Entity : public script::ScriptObject
{
protected:
    COMPONENT_ID realCell_;    // real 实体所在的 CellApp（0 = 本机）
    COMPONENT_ID ghostCell_;   // ghost 实体所在的 CellApp（0 = 无 ghost）
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/entity.hpp（简化）
class Entity : public PyObjectPlus
{
private:
    CellAppChannel* pRealChannel_;   // Real 实体通信通道（Ghost 使用）
    RealEntity* pReal_;              // Real 实体指针（非 NULL = 自己是 real）

public:
    bool isReal() const { return pReal_ != NULL; }
    bool isRealToScript() const { return pReal_ != NULL; }
    RealEntity* pReal() const { return pReal_; }
};

// KBEngine 中的典型用法
void Entity::onDefDataChanged(...)
{
    // 只有 real entity 才处理属性变更的广播
    if (!isReal() || initing())
        return;
    // ...
}

// BigWorld 中的典型用法
void Entity::onOwnedPropertyChanged(...)
{
    // 只有 real 才能发起属性变更
    if (!this->isReal())
        return;
    // ...
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/real_entity.hpp（简化）
class RealEntity
{
public:
    // Haunt：一个 Ghost 的位置记录
    class Haunt
    {
    public:
        Haunt(CellAppChannel* pChannel, GameTime creationTime);

        CellAppChannel& channel() { return *pChannel_; }
        Mercury::Bundle& bundle() { return pChannel_->bundle(); }
        const Mercury::Address& addr() const { return pChannel_->addr(); }

    private:
        CellAppChannel* pChannel_;     // 到 Ghost 所在 CellApp 的通道
        GameTime creationTime_;        // Ghost 创建时间
    };

    typedef BW::vector<Haunt> Haunts;

    // Ghost（Haunt）管理
    void addHaunt(CellAppChannel& channel);
    Haunts::iterator delHaunt(Haunts::iterator iter);
    void deleteGhosts();

    // 控制权管理
    const EntityMailBoxRef& controlledByRef() const { return controlledBy_; }
    bool controlledBySelf() const { return entity_.id() == controlledBy_.id; }
    bool controlledByOther() const;
    void delControlledBy(EntityID deadID);

    // 观察者
    Witness* pWitness() const { return pWitness_; }

private:
    Entity& entity_;
    Witness* pWitness_;
    Haunts haunts_;                       // 所有 Ghost 位置列表
    EntityMailBoxRef controlledBy_;       // 控制者引用
    Mercury::UDPChannel* pChannel_;       // 通信通道
};

// 文件：kbe/src/server/cellapp/ghost_manager.h（简化）
class GhostManager : public TimerHandler
{
public:
    // 创建发送 Bundle（复用已有 Bundle）
    Network::Bundle* createSendBundle(COMPONENT_ID componentID);

    // 投递消息
    void pushMessage(COMPONENT_ID componentID, Network::Bundle* pBundle);

    // 定时同步消息与路由
    void handleTimeout(TimerHandle, void* arg);

private:
    // real 实体列表
    std::map<ENTITY_ID, Entity*> realEntities_;

    // ghost 路由信息
    std::map<ENTITY_ID, ROUTE_INFO> ghost_route_;

    // 按 CellApp 分组的消息缓冲
    std::map<COMPONENT_ID, std::vector<Network::Bundle*>> messages_;
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/buffered_ghost_messages.hpp（简化）
class BufferedGhostMessages
{
public:
    // 按顺序播放缓冲消息
    void playSubsequenceFor(EntityID id, const Mercury::Address& srcAddr);
    void playNewLifespanFor(EntityID id);

    // 添加消息到缓冲
    void add(EntityID entityID, const Mercury::Address& srcAddr,
        BufferedGhostMessage* pMessage);

    // 消息序列边界
    static bool isSubsequenceStart(Mercury::MessageID id)
    { return id == CellAppInterface::ghostSetReal.id(); }

    static bool isSubsequenceEnd(Mercury::MessageID id)
    { return id == CellAppInterface::delGhost.id() ||
               id == CellAppInterface::ghostSetNextReal.id(); }
};

// 文件：kbe/src/server/cellapp/real_entity_method.h（简化）
class RealEntityMethod : public script::ScriptObject
{
public:
    RealEntityMethod(MethodDescription* pMethodDescription,
        ENTITY_ID ghostEntityID, COMPONENT_ID realCell);

    // tp_call：将方法调用转发到 real entity
    PyObject* callmethod(PyObject* args, PyObject* kwds);

private:
    MethodDescription* pMethodDescription_;
    ENTITY_ID ghostEntityID_;     // ghost 实体 ID
    COMPONENT_ID realCell_;       // real 所在的 CellApp
};

// 文件：kbe/src/server/cellapp/entity.h（简化）
class Entity : public script::ScriptObject
{
protected:
    // 当前实体的坐标朝向受谁控制
    EntityCall* controlledBy_;

public:
    EntityCall* controlledBy() const { return controlledBy_; }
    void controlledBy(EntityCall* baseEntityCall);

    bool isControlledNotSelfClient() const
    {
        return controlledBy_ == NULL || controlledBy_->id() != id();
    }
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/real_entity.hpp（简化）
class RealEntity
{
public:
    const EntityMailBoxRef& controlledByRef() const { return controlledBy_; }

    bool controlledBySelf() const
    {
        return entity_.id() == controlledBy_.id;
    }

    bool controlledByOther() const
    {
        return !this->controlledBySelf() && (controlledBy_.id != 0);
    }

    void delControlledBy(EntityID deadID);

private:
    EntityMailBoxRef controlledBy_;   // 控制者的 MailBox 引用
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/entity_ghost_maintainer.hpp（简化）
class EntityGhostMaintainer : public CellInfoVisitor
{
public:
    EntityGhostMaintainer(OffloadChecker& offloadChecker, EntityPtr pEntity);
    void check();

    virtual void visit(CellInfo& cellInfo);

private:
    void checkEntityForOffload();
    bool markHaunts();                  // 标记现有的 Haunt
    void createOrUnmarkRequiredHaunts(); // 创建新的或取消标记
    void deleteMarkedHaunts();           // 删除不再需要的 Haunt

    OffloadChecker& offloadChecker_;
    EntityPtr pEntity_;
};

// 文件：kbe/src/server/cellapp/entity.cpp（简化）
void Entity::onUpdateGhostPropertys(KBEngine::MemoryStream& s)
{
    ENTITY_PROPERTY_UID utype;
    s >> utype;

    // 查找属性描述
    PropertyDescription* pPropertyDescription =
        pScriptModule()->findCellPropertyDescription(utype);

    if (pPropertyDescription == NULL)
    {
        ERROR_MSG("onUpdateGhostPropertys: not found propertyID");
        return;
    }

    // 从流中读取属性值并设置
    PyObject* pyVal = pPropertyDescription->createFromStream(&s);
    PyObject_SetAttrString(static_cast<PyObject*>(this),
        pPropertyDescription->getName(), pyVal);
    Py_DECREF(pyVal);
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/entitydef/data_description.hpp（简化）
enum EntityDataFlags
{
    DATA_GHOSTED = 0x01,        // 同步到 Ghost 实体
    DATA_OTHER_CLIENT = 0x02,   // 发送到其他客户端
    DATA_OWN_CLIENT = 0x04,     // 发送到自身客户端
    DATA_BASE = 0x08,           // 发送到 Base
    DATA_PERSISTENT = 0x20,     // 持久化到数据库
};

// 文件：kbe/src/server/cellapp/cellapp_interface.h（简化）
// real → ghost：属性更新
CELLAPP_MESSAGE_DECLARE_STREAM(onUpdateGhostPropertys, NETWORK_VARIABLE_MESSAGE)

// ghost → real：方法调用转接
CELLAPP_MESSAGE_DECLARE_STREAM(onRemoteRealMethodCall, NETWORK_VARIABLE_MESSAGE)

// real → ghost：Volatile 数据更新（位置、朝向）
CELLAPP_MESSAGE_DECLARE_STREAM(onUpdateGhostVolatileData, NETWORK_VARIABLE_MESSAGE)

// 文件：kbe/src/server/cellapp/entity.cpp（简化）

// Real 变为 Ghost（实体迁移到另一个 CellApp）
void Entity::changeToGhost(COMPONENT_ID realCell, KBEngine::MemoryStream& s)
{
    KBE_ASSERT(isReal() == true);

    realCell_ = realCell;    // 记录 real 所在的 CellApp
    ghostCell_ = 0;

    // 添加路由到 GhostManager
    GhostManager* gm = Cellapp::getSingleton().pGhostManager();
    gm->addRoute(id(), realCell_);

    // 序列化完整状态到流
    addToStream(s);

    // 清理 Real 特有的资源
    if (pControllers_)
    {
        pControllers_->clear();
        SAFE_RELEASE(pControllers_);
    }
    if (pWitness())
    {
        pWitness()->clear(this);
        Witness::reclaimPoolObject(pWitness_);
        pWitness_ = NULL;
    }
}

// Ghost 变为 Real（实体迁移到本 CellApp）
void Entity::changeToReal(COMPONENT_ID ghostCell, KBEngine::MemoryStream& s)
{
    KBE_ASSERT(isReal() == false);

    ghostCell_ = ghostCell;
    realCell_ = 0;    // 设为 0 表示自己是 real

    // 从流中恢复完整状态
    createFromStream(s);
}