KBEngine Nex

Appearance

KBEngine Nex 常见问题 ​

这里收集开发者问的较多的问题，方便大家查询。

引擎基础 ​

Q：KBEngine Nex 与 KBEngine 是什么关系？ ​

KBEngine Nex 是在 KBEngine 2.5.12 基础上社区继续维护的版本，保持核心架构不变，在 SDK 生态、Python 版本、数据库支持、平台覆盖、开发工具等方面做了大幅升级。详见 关于 KBEngine Nex。

Q：KBEngine 使用什么网络模型？ ​

Linux 下使用 io_uring（epoll 兼容），Windows 下使用 IOCP，macOS 下使用 kqueue，三大平台全部采用 completion 模型。

Q：KBEngine 的运行平台支持哪些？ ​

支持 Linux (x64 / ARM64)、macOS (Apple Silicon)、Windows（调试开发）。每个版本都经过 Ubuntu、Debian、CentOS、Deepin 等多平台编译验证。

Python 脚本开发 ​

Q：Python 版本是多少？需要自己安装吗？ ​

目前 KBEngine Nex 使用 Python 3.13，引擎自带运行环境，不需要另外安装。开发时建议使用 PyCharm + KBEX 插件获得完整的 IDE 体验。

Q：如何使用 VENV 虚拟环境？ ​

引擎已原生支持 Python VENV。在项目 assets 目录下创建 .venv 文件夹即可，引擎启动时会自动激活。详见 VENV虚拟环境。

Q：虚拟环境文件夹名必须叫 .venv 吗？ ​

是的，引擎只识别 .venv，不支持其他名称。Python 版本必须与引擎内置版本一致。

Q：脚本支持热更新吗？ ​

支持。通过 KBEngine.reloadScript() 或在 KBEX 插件中点击刷新按钮即可触发热更。热更默认只更新逻辑层，被修改过的文件才会重新加载。

Q：支持 asyncio 协程吗？ ​

支持。系统回调和自定义逻辑都可以使用 async/await。asyncio 调度已从独立 Python 线程迁移到 C++ 底层 dispatcher timer 驱动，不再受 game tick 频率限制。详见 asyncio支持。

Q：如何在 kbengine.xml 中添加自定义配置？ ​

在 <root> 节点下新增 <customCfg> 段，Python 层通过 KBEngine.getCustomCfg("key", default) 读取。支持 int / bool / float / string / dict / list 类型。详见 自定义配置。

Q：脚本中如何获取当前 cellapp 下所有 Space？ ​

python
spaces = KBEngine.spaces()  # 返回 {spaceID: spaceEntity}

Q：如何获取指定 Space 内的所有 Entity？ ​

python
entities = KBEngine.entitiesForSpace(spaceID)

Entity 与 逻辑层 ​

Q：如何在传送 (teleport) 时由脚本决定是否允许？ ​

在 Entity 上实现 onTeleport() 回调，返回 True/None 允许传送，返回 False 拒绝。entity 和所有 cell 组件都会被询问，任一返回 False 即中断传送。

Q：createCellEntity 传入 baseEntityCall 可以吗？ ​

可以。现支持 CELL_VIA_BASE 类型：

python
avatar.createCellEntity(spaceBaseCall.cell)

Q：如何监听玩家超速？ ​

在 Entity 上实现 onMoveOverTopSpeed(clientX, clientY, clientZ, xzDist, yDist) 回调。引擎会在单包超速、同帧累积超速、滑动窗口超速时分别触发。

Q：EntityComponent 的回调为什么没有被调用？ ​

EntityComponent 的方法回调需要 owner Entity 也实现了同名方法，回调才会被触发。这是 Nex 已修复的问题，确保版本 ≥ 2.7.2。

数据库 ​

Q：支持哪些数据库？ ​

MySQL（5.x ~ 9.x）、MongoDB、PostgreSQL。MariaDB 自动兼容 MySQL 模式。详见 kbengine_defaults.xml 中的 dbmgr 配置。

Q：如何使用 executeRawDatabaseCommand？ ​

直接在脚本中执行原生 SQL / MongoDB 命令。引擎内置了命令黑名单保护（drop、truncate、alter 等危险命令默认拦截），可在 kbengine.xml 中配置。

Q：MySQL 连接报 SSL 错误？ ​

MySQL 8.0+ 默认尝试 SSL 连接，如果服务端使用自签名证书会报错。可在 kbengine.xml 中显式禁用 SSL，Nex 已内置此处理。

部署与运维 ​

Q：如何在不同环境下使用不同配置？ ​

支持按需启动：创建 kbengine_dev.xml、kbengine_prod.xml 等，启动时加 --prop=dev 或 --prop=prod 切换。也支持 --location=/path/to/kbengine.xml 直接指定。详见 按需启动服务配置。

Q：Docker 部署支持吗？ ​

支持。提供完整 Dockerfile，可构建自定义镜像。k8s 下配合 --prop 参数和 ConfigMap 可实现按环境注入配置。

客户端 SDK ​

Q：支持哪些客户端引擎？ ​

Unity、Unreal Engine 5、Cocos Creator、Godot、LayaAir，并提供 C# / TypeScript / C++ 三种 SDK。

Q：事件系统的 In / Out 是什么？ ​

  • Out：SDK → 游戏层。服务端消息到达后通知 UI/逻辑，游戏层注册监听。Out 事件受 pause/resume 控制，暂停时进入队列等待。
  • In：游戏层 → SDK。用户操作（登录、移动等）触发后向服务端发请求，SDK 插件注册监听。

重要

In 事件不受暂停 (pause) 影响。即使调用了 pause() 暂停了 Out 事件的触发，In 事件的底层网络发包依然正常进行。这意味着在场景加载期间暂停事件系统时，login、createAccount 等操作仍可正常工作。

详见 事件系统。