11. RPC、EntityCall 与通信模式

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/mailbox.hpp（简化）
class ServerEntityMailBox : public PyEntityMailBox
{
    Py_Header(ServerEntityMailBox, PyEntityMailBox)
public:
    ServerEntityMailBox(EntityTypePtr pBaseType,
            const Mercury::Address& addr, EntityID id,
            PyTypeObject* pType = &s_type_);

    // 获取到远端的输出流（开始写消息）
    virtual BinaryOStream* getStream(const MethodDescription& methodDesc,
            std::auto_ptr<Mercury::ReplyMessageHandler> pHandler);

    virtual ScriptObject pyGetAttribute(const ScriptString& attrObj);
    void sendStream();

    virtual const Mercury::Address& address() const { return addr_; }
    virtual Mercury::UDPChannel* pChannel() const;
    Mercury::Bundle& bundle() const { return this->pChannel()->bundle(); }

protected:
    Mercury::Address addr_;
    EntityID id_;
    EntityTypePtr pLocalType_;
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/baseapp/mailbox.cpp:1054（简化）
BinaryOStream* BaseEntityMailBox::getStreamEx(
        const MethodDescription& methodDesc,
        std::auto_ptr<Mercury::ReplyMessageHandler> pHandler)
{
    Mercury::Bundle& bundle = this->bundle();

    BaseAppIntInterface::setClientArgs::start(bundle).id = id_;

    if (pHandler.get())
    {
        // TwoWay：有回复处理器 → 使用 startRequest
        bundle.startRequest(BaseAppIntInterface::callBaseMethod,
                pHandler.release());
    }
    else
    {
        // 单向：无回复处理器 → 使用 startMessage
        bundle.startMessage(BaseAppIntInterface::callBaseMethod);
    }

    bundle << methodDesc.internalIndex();

    return &bundle;
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/entitydef/return_values_handler.cpp（简化）
void ReturnValuesHandler::handleMessage(
        const Mercury::Address& srcAddr,
        Mercury::UnpackedMessageHeader& header,
        BinaryIStream& data, void* arg)
{
    ScriptObject pValues;

    // 尝试从流中创建返回值，如果失败则创建错误
    uint8 isError = methodDescription_.createReturnValuesOrFailureFromStream(
            data, pValues);

    bool isOkay = isError ?
        deferred_.errback(pValues) :    // 错误回调
        deferred_.callback(pValues);    // 成功回调

    delete this;   // 一次性处理器，用完即销毁
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/mailbox.cpp:797（简化）
BinaryOStream* CellEntityMailBox::getStream(
        const MethodDescription& methodDesc,
        std::auto_ptr<Mercury::ReplyMessageHandler> pHandler)
{
    Mercury::Channel* pChannel = this->pChannel();
    if (!pChannel) return NULL;

    // CellApp 不支持 TwoWay 调用
    if (pHandler.get())
    {
        PyErr_Format(PyExc_TypeError,
                "Cannot call two-way method '%s' from CellApp",
                methodDesc.name().c_str());
        return NULL;
    }

    // 只能单向
    Mercury::Bundle& bundle = pChannel->bundle();
    bundle.startMessage(CellAppIntInterface::callEntityMethod);
    // ...
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/network/request_manager.hpp（简化）
class RequestManager
{
public:
    void addReplyOrder(const ReplyOrder& replyOrder, Channel* pChannel);
    void cancelRequestsFor(Channel* pChannel);
    void cancelRequestsFor(ReplyMessageHandler* pHandler, Reason reason);

    typedef BW::map<int, Request*> RequestMap;
    RequestMap requestMap_;     // replyID → Request
};

// 文件：kbe/src/lib/entitydef/entitycallabstract.h（简化）
class EntityCallAbstract : public script::ScriptObject
{
public:
    EntityCallAbstract(PyTypeObject* scriptType,
            const Network::Address* pAddr,
            COMPONENT_ID componentID,
            ENTITY_ID eid,
            uint16 utype,
            ENTITYCALL_TYPE type);

    // 核心方法
    virtual Network::Channel* getChannel(void);
    virtual bool sendCall(Network::Bundle* pBundle);
    virtual void newCall(Network::Bundle& bundle);
    virtual void newCall_(Network::Bundle& bundle);

    // 类型判断
    bool isClient() const;
    bool isCell() const;
    bool isBase() const;
    bool isCellReal() const;
    bool isBaseReal() const;

protected:
    Network::Address addr_;             // 远端地址
    COMPONENT_ID componentID_;          // 远端组件 ID
    ENTITYCALL_TYPE type_;              // 调用类型
    ENTITY_ID id_;                      // 远端实体 ID
    ENTITY_SCRIPT_UID utype_;           // 实体脚本类型 UID
};

// 文件：kbe/src/lib/common/common.h
enum ENTITYCALL_TYPE
{
    ENTITYCALL_TYPE_CELL            = 0,  // 直接调用 CellApp
    ENTITYCALL_TYPE_BASE            = 1,  // 直接调用 BaseApp
    ENTITYCALL_TYPE_CLIENT          = 2,  // 直接调用客户端
    ENTITYCALL_TYPE_CELL_VIA_BASE   = 3,  // 通过 BaseApp 转发到 CellApp
    ENTITYCALL_TYPE_BASE_VIA_CELL   = 4,  // 通过 CellApp 转发到 BaseApp
    ENTITYCALL_TYPE_CLIENT_VIA_CELL = 5,  // 通过 CellApp 转发到客户端
    ENTITYCALL_TYPE_CLIENT_VIA_BASE = 6   // 通过 BaseApp 转发到客户端
};

// 文件：kbe/src/lib/entitydef/entity_call.h（简化）
class EntityCall : public EntityCallAbstract
{
    INSTANCE_SCRIPT_HREADER(EntityCall, EntityCallAbstract)
public:
    EntityCall(ScriptDefModule* pScriptModule,
            const Network::Address* pAddr,
            COMPONENT_ID componentID,
            ENTITY_ID eid,
            ENTITYCALL_TYPE type);

    // Python 脚本获取属性/方法
    PyObject* onScriptGetAttribute(PyObject* attr);

    // 创建远程方法代理
    virtual RemoteEntityMethod* createRemoteMethod(
            MethodDescription* pMethodDescription);

    virtual void newCall(Network::Bundle& bundle);

    static ENTITYCALLS entityCalls;    // 全局 EntityCall 表

protected:
    ScriptDefModule* pScriptModule_;   // 实体定义模块
};

// 文件：kbe/src/lib/entitydef/entitycallabstract.cpp:65（简化）
void EntityCallAbstract::newCall_(Network::Bundle& bundle)
{
    // 服务器端
    if (g_componentType != CLIENT_TYPE && g_componentType != BOTS_TYPE)
    {
        if (componentID_ == 0)
        {
            // componentID==0 → 客户端
            bundle.newMessage(ClientInterface::onRemoteMethodCall);
        }
        else
        {
            // 找到目标组件
            Components::ComponentInfos* cinfos =
                Components::getSingleton().findComponent(componentID_);

            if (cinfos != NULL)
            {
                if (cinfos->componentType == BASEAPP_TYPE)
                    bundle.newMessage(BaseappInterface::onEntityCall);
                else
                    bundle.newMessage(CellappInterface::onEntityCall);
            }
        }

        bundle << id_;                // 实体 ID
        if (componentID_ > 0)
            bundle << type_;          // ENTITYCALL_TYPE
    }
    else
    {
        // 客户端发往服务端
        switch (type_)
        {
        case ENTITYCALL_TYPE_BASE:
            bundle.newMessage(BaseappInterface::onRemoteMethodCall);
            break;
        case ENTITYCALL_TYPE_CELL:
            bundle.newMessage(BaseappInterface::onRemoteCallCellMethodFromClient);
            break;
        default:
            break;
        }
        bundle << id_;
    }
}

// 文件：kbe/src/lib/entitydef/remote_entity_method.cpp:45（简化）
PyObject* RemoteEntityMethod::tp_call(PyObject* self, PyObject* args,
    PyObject* kwds)
{
    RemoteEntityMethod* rmethod = static_cast<RemoteEntityMethod*>(self);
    MethodDescription* methodDescription = rmethod->getDescription();
    EntityCallAbstract* entityCall = rmethod->getEntityCall();

    // 1. 参数类型检查
    if (methodDescription->checkArgs(args))
    {
        // 2. 序列化参数到 MemoryStream
        MemoryStream* mstream = MemoryStream::createPoolObject(OBJECTPOOL_POINT);
        try
        {
            methodDescription->addToStream(mstream, args);
        }
        catch (MemoryStreamWriteOverflow& err)
        {
            MemoryStream::reclaimPoolObject(mstream);
            S_Return;
        }

        // 3. 创建 Bundle
        Network::Channel* pChannel = entityCall->getChannel();
        Network::Bundle* pSendBundle;
        if (!pChannel)
            pSendBundle = Network::Bundle::createPoolObject(OBJECTPOOL_POINT);
        else
            pSendBundle = pChannel->createSendBundle();

        // 4. 写入调用头（实体ID + ENTITYCALL_TYPE + 组件属性占位）
        entityCall->newCall((*pSendBundle));

        // 5. 追加方法参数
        if (mstream->wpos() > 0)
            (*pSendBundle).append(mstream->data(), mstream->wpos());

        // 6. 发送
        MemoryStream::reclaimPoolObject(mstream);
        entityCall->sendCall(pSendBundle);
    }

    S_Return;   // 返回 None（纯单向，无返回值）
}

// EntityCall::onScriptGetAttribute 的核心逻辑（简化）
PyObject* EntityCall::onScriptGetAttribute(PyObject* attr)
{
    // 在 ScriptDefModule 中查找方法描述
    MethodDescription* pMethodDescription =
        pScriptModule_->findCellMethod(attr);

    if (pMethodDescription)
    {
        // 创建远程方法代理对象
        return createRemoteMethod(pMethodDescription);
    }

    // 查找 base 方法、client 方法...
    // 都没找到则返回 NULL（属性错误）
}

// 文件：kbe/src/server/cellapp/entity.h（简化）
class Entity : public script::ScriptObject
{
    // 接收远程方法调用
    void onRemoteMethodCall(Network::Channel* pChannel, MemoryStream& s);

    // 接收来自客户端的方法调用
    void onRemoteCallMethodFromClient(Network::Channel* pChannel,
            ENTITY_ID srcEntityID, MemoryStream& s);

    // Ghost 接收对 real 的调用
    void onRemoteRealMethodCall(KBEngine::MemoryStream& s);
};

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/real_entity.hpp（简化）
class RealEntity
{
    class Haunt
    {
    public:
        Haunt(CellAppChannel* pChannel, GameTime creationTime) :
            pChannel_(pChannel),
            creationTime_(creationTime)
        {}

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

    private:
        CellAppChannel* pChannel_;
        GameTime creationTime_;
    };

    void addHaunt(CellAppChannel& channel);      // 添加 ghost 位置
    Haunts::iterator delHaunt(Haunts::iterator);  // 删除 ghost 位置
    void deleteGhosts();

    typedef BW::list<Haunt> Haunts;
    Haunts haunts_;    // 所有 ghost 的位置列表
};

// 文件：kbe/src/lib/entitydef/method.h（简化）
class MethodDescription
{
    enum EXPOSED_TYPE
    {
        NO_EXPOSED,                  // 内部调用，客户端不可调用
        EXPOSED,                     // 客户端可调用，不加调用者参数
        EXPOSED_AND_CALLER_CHECK     // 客户端可调用 + 传入调用者 EntityID
    };
    EXPOSED_TYPE exposedType_;
};

// 文件：kbe/src/lib/server/callbackmgr.h（简化）
// 简单的回调注册表
// 发起请求时：callbackMgr_.save(callbackID, pyCallback)
// 结果回来时：callbackMgr_.take(callbackID) → 执行 pyCallback