18. 钩子、回调、定时器与事件

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

// 实体创建完成
void Entity::onInitializeScript()
{
    // C++ → Python: 调用实体脚本的 __init__ 方法
}

// 实体获得 Witness（有客户端连上了）
void Entity::onGetWitness()
{
    CALL_ENTITY_AND_COMPONENTS_METHOD(this,
        SCRIPT_OBJECT_CALL_ARGS0(pyTempObj, "onGetWitness", GETERR));
}

// 实体即将写入数据库
void Entity::onWriteToDB()
{
    CALL_ENTITY_AND_COMPONENTS_METHOD(this,
        SCRIPT_OBJECT_CALL_ARGS0(pyTempObj, "onWriteToDB", GETERR));
}

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

// 所有 BaseApp 准备就绪
void Baseapp::onBaseAppReady()
{
    // 通知脚本层
    SCOPED_PROFILE(BAPP_READY_PROFILE);
    // 调用 KBEngine.onBaseAppReady()
}

// 服务器准备接受登录
void Baseapp::onReadyForLogin()
{
    // 轮询调用 KBEngine.onReadyForLogin()
    // 返回 Py_True 表示准备好
    // 返回 float 表示初始化进度，之后继续轮询
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/baseapp/base.cpp（简化）

// Base 实体登录成功
// Script::call(PyObject_GetAttrString(this, "onLoggedOn"), ...)

// Base 实体销毁
// Script::call(PyObject_GetAttrString(this, "onDestroy"), ...)

// 获得/失去 Cell
// if (haveCell) Script::call(pMethod, PyTuple_New(0), "onGetCell");
// else          Script::call(pMethod, PyTuple_New(0), "onLoseCell");

// 写入数据库
// Script::call(PyObject_GetAttrString(this, "onWriteToDB"), ...)

// 文件：kbe/src/lib/server/script_timers.h（简化）
class ScriptTimers
{
public:
    typedef int32 ScriptID;

    ScriptID addTimer(float initialOffset, float repeatOffset,
        int userArg, TimerHandler* pHandler);
    bool delTimer(ScriptID timerID);
    void releaseTimer(TimerHandle handle);
    void cancelAll();

    typedef std::map<ScriptID, TimerHandle> Map;
    Map& map() { return map_; }

    void directAddTimer(ScriptID tid, TimerHandle handle);

private:
    Map map_;                  // ScriptID → TimerHandle 映射
    ScriptID getNewID();
};

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

// 序列化定时器到流
void Entity::addTimersToStream(KBEngine::MemoryStream& s)
{
    ScriptTimers::Map& map = scriptTimers_.map();
    uint32 size = map.size();
    s << size;

    ScriptTimers::Map::const_iterator iter = map.begin();
    while (iter != map.end())
    {
        s << iter->first;    // ScriptID

        uint32 time, interval;
        void* pUser;
        Cellapp::getSingleton().timers().getTimerInfo(
            iter->second, time, interval, pUser);

        int32 userData = int32(uintptr(pUser));
        s << time << interval << userData;
        ++iter;
    }
}

// 从流中恢复定时器
void Entity::createTimersFromStream(KBEngine::MemoryStream& s)
{
    uint32 size;
    s >> size;

    for (uint32 i = 0; i < size; ++i)
    {
        ScriptID tid;
        uint32 time, interval;
        int32 userData;
        s >> tid >> time >> interval >> userData;

        EntityScriptTimerHandler* pHandler = new EntityScriptTimerHandler(this);
        TimerHandle timerHandle = Cellapp::getSingleton().timers().add(
            time, interval, pHandler, (void*)(intptr_t)userData);
        scriptTimers_.directAddTimer(tid, timerHandle);
    }
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/server/cellapp/timer_controller.hpp（简化）
class TimerController : public Controller
{
    DECLARE_CONTROLLER_TYPE(TimerController)

public:
    TimerController(GameTime start = 0, GameTime interval = 0);

    virtual void startReal(bool isInitialStart);
    virtual void stopReal(bool isFinalStop);

    void handleTimeout();
    void onHandlerRelease();

    // Controller 序列化（跨 Cell 迁移时自动调用）
    virtual void writeRealToStream(BinaryOStream& stream);
    virtual bool readRealFromStream(BinaryIStream& stream);

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

    Handler* pHandler_;
    GameTime start_;
    GameTime interval_;
    TimerHandle timerHandle_;
};

// 文件：kbe/src/lib/server/callbackmgr.h（简化）
template<typename T>
class CallbackMgr
{
public:
    typedef std::map<CALLBACK_ID, std::pair<T, uint64>> CALLBACKS;

    // 保存回调，返回 callbackID
    CALLBACK_ID save(T callback, uint64 timeout = 0)
    {
        CALLBACK_ID cbID = idAlloc_.alloc();
        cbMap_[cbID] = std::make_pair(callback, timeout);
        return cbID;
    }

    // 取出并执行回调
    T take(CALLBACK_ID cbID)
    {
        typename CALLBACKS::iterator iter = cbMap_.find(cbID);
        if (iter == cbMap_.end())
            return NULL;
        T callback = iter->second.first;
        cbMap_.erase(iter);
        return callback;
    }

    // 超时检查（tick 中调用）
    void tick()
    {
        // 检查超时的回调并清理
    }

    // 序列化（用于进程迁移）
    void addToStream(KBEngine::MemoryStream& s);
    void createFromStream(KBEngine::MemoryStream& s);

protected:
    CALLBACKS cbMap_;                        // callbackID → (callback, timeout)
    IDAllocate<CALLBACK_ID> idAlloc_;        // ID 分配器
    uint64 lastTimestamp_;
};

// Python 回调管理器
typedef CallbackMgr<PyObjectPtr> PY_CALLBACKMGR;

// Python 回调的序列化（pickle Python 对象）
template<>
inline void CallbackMgr<PyObjectPtr>::addToStream(KBEngine::MemoryStream& s)
{
    uint32 size = (uint32)cbMap_.size();
    s << idAlloc_.lastID() << size;

    CALLBACKS::iterator iter = cbMap_.begin();
    for (; iter != cbMap_.end(); ++iter)
    {
        s << iter->first;
        // 用 pickle 序列化 Python 回调对象
        s.appendBlob(script::Pickler::pickle(iter->second.first.get()));
        s << iter->second.second;
    }
}

template<>
inline void CallbackMgr<PyObjectPtr>::createFromStream(KBEngine::MemoryStream& s)
{
    CALLBACK_ID v;
    s >> v;
    idAlloc_.lastID(v);

    uint32 size;
    s >> size;

    for (uint32 i = 0; i < size; ++i)
    {
        CALLBACK_ID cbID;
        s >> cbID;

        std::string data;
        s.readBlob(data);
        PyObject* pyCallback = script::Pickler::unpickle(data);

        uint64 timeout;
        s >> timeout;

        if (pyCallback && cbID != 0)
        {
            cbMap_[cbID] = std::make_pair(PyObjectPtr(pyCallback), timeout);
            Py_DECREF(pyCallback);
        }
    }
}

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

// 注册事件
void Entity::registerEvent(const std::string& eventName, PyObject* pyCallback)
{
    ENTITY_EVENTS& eventsMap = events();
    eventsMap[eventName].push_back(PyObjectPtr(pyCallback));
}

// 取消注册
void Entity::deregisterEvent(const std::string& eventName, PyObject* pyCallback)
{
    ENTITY_EVENTS& eventsMap = events();
    // 从 eventsMap[eventName] 中移除 pyCallback
}

// 触发事件
void Entity::fireEvent(const std::string& eventName, PyObject* args)
{
    ENTITY_EVENTS& eventsMap = events();
    ENTITY_EVENTS::iterator iter = eventsMap.find(eventName);
    if (iter == eventsMap.end())
        return;

    std::vector<PyObjectPtr>& callbacks = iter->second;
    for (size_t i = 0; i < callbacks.size(); ++i)
    {
        PyObject_CallObject(callbacks[i].get(), args);
    }
}

// 序列化事件到流
void Entity::addEventsToStream(KBEngine::MemoryStream& s)
{
    ENTITY_EVENTS& eventsMap = events();
    int eventNameSize = eventsMap.size();
    s << eventNameSize;

    ENTITY_EVENTS::const_iterator mapiter = eventsMap.begin();
    for (; mapiter != eventsMap.end(); ++mapiter)
    {
        int eventSize = mapiter->second.size();
        s << mapiter->first << eventSize;

        // 保存回调的限定名（而非对象本身）
        std::vector<PyObjectPtr>::const_iterator vecIter = mapiter->second.begin();
        for (; vecIter != mapiter->second.end(); ++vecIter)
        {
            PyObject* pyObj = PyObject_GetAttrString(
                (*vecIter).get(), "__qualname__");
            const char* ccattr = PyUnicode_AsUTF8AndSize(pyObj, NULL);
            s << ccattr;
            S_RELEASE(pyObj);
        }
    }
}

// 从流中恢复事件
void Entity::createEventsFromStream(KBEngine::MemoryStream& s)
{
    ENTITY_EVENTS& eventsMap = events();
    eventsMap.clear();

    int eventNameSize;
    s >> eventNameSize;

    while (eventNameSize-- > 0)
    {
        std::string eventName;
        s >> eventName;

        int eventSize;
        s >> eventSize;

        while (eventSize-- > 0)
        {
            std::string callbackName;
            s >> callbackName;

            if (callbackName == "None") continue;

            // 通过限定名恢复回调函数引用
            // "Avatar.onLevelUp" → getattr(self, "onLevelUp")
            std::vector<std::string> callBackNameVec;
            KBEngine::strutil::kbe_split(callbackName, '.', callBackNameVec);

            PyObject* pyCallback = NULL;
            if (callBackNameVec.size() >= 2)
            {
                PyObject* pyObj = PyObject_GetAttrString(
                    this, callBackNameVec[0].c_str());
                pyCallback = PyObject_GetAttrString(
                    pyObj, callBackNameVec[1].c_str());
                Py_DECREF(pyObj);
            }
            else
            {
                pyCallback = PyObject_GetAttrString(
                    this, callBackNameVec[0].c_str());
            }

            registerEvent(eventName, pyCallback);
            Py_DECREF(pyCallback);
        }
    }
}

// 文件：BigWorld-Engine-14.4.1/programming/bigworld/lib/pyscript/script_events.cpp（简化）
class ScriptEvents
{
public:
    void createEventType(const char* eventName);
    bool triggerEvent(const char* eventName, PyObject* pArgs,
        ScriptList resultsList);
    bool addEventListener(const char* eventName, PyObject* pListener,
        int level = 0);
    bool removeEventListener(const char* eventName, PyObject* pListener);

    static ScriptEvents* instance();
};