KBEngine Nex 引擎介绍
KBEngine Nex 是一款面向网络游戏和实时交互业务的开源分布式服务端引擎。它将连接管理、远程调用、状态同步、空间与 AOI、数据库持久化、负载分配、进程管理等通用能力放在 C++ 运行时中，并使用 Python 3.12 编写可热更新的业务逻辑。
客户端通过引擎生成或提供的 SDK 接入服务端。开发者主要描述 Entity 的属性、远程方法和同步范围，再分别实现服务端 Base、Cell 以及客户端行为，不需要从头设计私有协议、对象路由和分布式进程通信。
Nex 3.x 的技术定位
Nex 3.x 以 KBEngine 1.x 作为唯一协议基线，在保持 1.x Entity、EntityDef 和客户端通信语义的基础上继续演进。项目不再沿用早期 Nex 基于 KBEngine 2.x 的协议分支，从基线上避免消息编号、数据布局和 SDK 解释不一致造成的协议问题。
这意味着 Nex 3.x 不是对原版代码的简单升级，而是由两部分共同组成：
- 稳定的 1.x 协议模型：保留 Entity、Base/Cell/Client、EntityCall、Space、Witness 和 EntityDef 等核心概念。
- 现代化工程能力：升级 Python、CMake、vcpkg、编译器、数据库驱动、跨平台网络模型、测试体系和配套工具。
服务端内部实现可以持续优化，但客户端兼容性由客户端可见协议单独约束。只修改 Base/Cell 的服务端 RPC 或内部属性，不会无故改变客户端 EntityDef MD5；只有客户端可见的属性、方法、类型或编号发生变化时，才需要更新客户端 SDK。
引擎解决什么问题
一个可长期运行的游戏服务端不仅要处理业务规则，还必须解决许多跨业务复用的基础问题：
| 问题 | KBEngine Nex 提供的能力 |
|---|---|
| 客户端连接与登录 | LoginApp 接入、会话验证、BaseApp 分配、断线与重连流程 |
| 跨进程对象调用 | EntityCall、远程方法描述、参数序列化和组件路由 |
| 世界状态同步 | Witness、View、AOI、属性同步级别和客户端事件 |
| 场景与位置逻辑 | Space、Cell、移动控制器、触发器、导航与空间数据 |
| 数据持久化 | Entity 属性映射、异步写库、MySQL、MongoDB、PostgreSQL |
| 横向扩展 | 多 BaseApp、多 CellApp、负载采样和创建位置分配 |
| 运行与诊断 | Logger、Watcher、性能指标、Bots 压测和管理工具 |
| 客户端接入 | C#、TypeScript、C++ 等 SDK 生成与协议校验 |
引擎负责这些能力的生命周期和数据流，业务代码则负责角色、战斗、房间、任务、社交和经济系统等领域逻辑。
以 Entity 为中心的编程模型
Entity 是引擎中的核心业务对象。玩家、怪物、NPC、房间、场景、道具或公会都可以根据生命周期、交互方式和持久化需求建模为 Entity。
一个 Entity 可以由三个逻辑部分组成：
- Base 部分运行在 BaseApp，适合账户、背包、社交、匹配、排行榜、持久化和客户端会话等与空间位置无关的逻辑。
- Cell 部分运行在 CellApp，适合场景、移动、战斗、AI、AOI、触发器和导航等实时空间逻辑。
- Client 部分运行在客户端，接收服务端同步的数据和调用，并驱动显示、输入及客户端表现。
三部分不要求同时存在。例如，纯后台数据实体可以只有 Base；场景中的公共对象可以拥有 Cell 和 Client；连接玩家的 Proxy 则承担客户端与服务端之间的会话入口。
Entity 的网络契约由 entities.xml、entity_defs/*.def 和 entity_defs/types.xml 描述，包括：
- Entity 由哪些部分组成；
- 属性的数据类型、同步范围和持久化策略；
- Base、Cell、Client 方法及其参数；
- Interface、EntityComponent 和自定义数据类型；
- 显式或自动分配的协议 UType。
引擎读取定义后建立统一协议表，服务端运行时和客户端 SDK 使用同一份模型进行序列化与反序列化。详见 Entity、EntityCall 和 EntityComponent。
分布式运行架构
KBEngine Nex 由多个职责明确的进程协同运行。业务无需把所有玩家和场景塞进单个进程，也不需要手工维护每次跨进程调用的连接。
| 组件 | 主要职责 |
|---|---|
| Machine | 发现和管理本机组件，提供进程状态及机器资源信息 |
| LoginApp | 处理客户端登录入口、鉴权和 BaseApp 地址分配 |
| BaseAppMgr | 管理 BaseApp 集群并参与客户端及实体的负载分配 |
| BaseApp | 承载客户端会话、Base Entity、持久化和非空间业务 |
| CellAppMgr | 管理 CellApp 集群并参与 Space 创建位置分配 |
| CellApp | 承载 Space、Cell Entity、AOI、移动、AI 和实时交互 |
| DBMgr | 统一处理 Entity 数据模型、数据库任务和异步结果路由 |
| Interfaces | 对接第三方账户、计费、运营或其他外部系统 |
| Logger | 汇聚组件日志，供开发和运行诊断使用 |
典型连接过程如下：
- 客户端 SDK 连接 LoginApp 并完成登录验证。
- LoginApp 请求 BaseAppMgr 选择合适的 BaseApp。
- 客户端连接目标 BaseApp，服务端创建与该客户端关联的 Proxy Entity。
- 业务需要进入场景时，Base Entity 请求在 CellApp 中创建 Cell 部分或新的 Space。
- CellApp 维护空间状态、AOI 和实时逻辑，通过 Witness 将可见数据同步给客户端。
- EntityCall 负责 Base、Cell、Client 以及不同服务端进程之间的远程调用。
- 需要持久化时，BaseApp 或 CellApp 将 Entity 数据交给 DBMgr 异步写入数据库。
更完整的组件关系和流程见 引擎概览。
Space、AOI 与实时世界
Space 是 CellApp 中的逻辑空间，可以表示一张世界地图、一个副本、一个战斗房间或一局牌桌。Space 将互不相关的实时对象隔离开，使移动、触发器和可见性计算只在必要范围内发生。
客户端控制的 Cell Entity 可以拥有 Witness。Witness 根据 View 范围维护该客户端当前可见的 Entity，并只同步进入视野、离开视野或状态发生变化的数据。高密度场景中，AOI 的 Entity 数量、属性变化频率和客户端可见范围会直接影响 Cell Tick、CPU 与网络包量，因此业务仍需合理设计同步粒度。
对于大型或复杂场景，引擎还提供移动控制器、导航网格、Detour 寻路、触发器、DetailLevel 和易变属性同步策略。相关内容见 Space、View 与 Witness 和 导航网格。
Python 3.12 业务运行时
Nex 将原版 Python 3.7 升级到 Python 3.12。Python 用于业务逻辑而不是替代 C++ 网络核心：连接收发、消息解析、调度、Entity 管理和空间系统由底层负责，业务回调在对应组件的主线程中执行。
当前运行时具有以下约定：
- Windows、Linux 和 macOS 均使用动态 Python 运行时；
- 引擎 Debug/Release 配置统一链接 Release Python；
- Windows 支持加载
.pyd，Linux/macOS 支持对应的原生动态扩展； - 支持 VENV 和第三方 Python 包；
- asyncio 由底层 Dispatcher 定时推进，不额外创建独立 Python 调度线程；
- Python 运行库与服务端一起部署，服务器目录整体移动后仍可按相对路径运行。
Python 提高了业务迭代速度，但不会消除 Tick 预算。耗时循环、同步 IO、大对象序列化和一次性处理过多 Entity 仍会阻塞所在 BaseApp 或 CellApp。异步接口适合等待 IO，不适合掩盖 CPU 密集型逻辑。详见 Python 介绍、VENV 和 asyncio。
客户端协议与 SDK
客户端不直接解释服务端 Python 对象，而是依据生成的 EntityDef 和消息协议进行通信。SDK 生成器会输出客户端可见的 Entity、属性、Client 方法、暴露给客户端的 Base/Cell 方法及其数据类型，并嵌入协议摘要。
连接时，客户端与服务器会校验消息协议和客户端 EntityDef MD5。这样可以尽早拒绝使用错误 SDK 的客户端，避免数据已经按错误布局读取后才表现为随机逻辑错误。
下列修改通常需要重新生成 SDK：
- 新增、删除或修改客户端可见属性；
- 修改 Client 方法或暴露给客户端的 Base/Cell 方法；
- 修改上述成员使用的数据类型或协议 UType；
- 新增会进入客户端协议的 Entity 或组件。
纯服务端 Base/Cell 方法和内部实现的修改不应影响客户端摘要。SDK 生成与升级流程见 SDK 自动生成。
数据持久化
EntityDef 可以声明需要持久化的属性。引擎将 Entity 数据转换为数据库任务，并由 DBMgr 负责执行和返回结果，业务脚本不需要为每个 Entity 重复实现基本的对象映射和异步回调路由。
Nex 支持 MySQL、MongoDB 和 PostgreSQL。数据库选择不能替代数据建模：高频实时状态不应每 Tick 写库，大型集合需要考虑序列化成本，跨 Entity 的强事务需求也应在业务层明确设计。
引擎同时保留原生数据库命令接口，供复杂查询、运营分析或既有数据系统使用。此类接口应进行参数化、权限和耗时控制，避免把数据库慢查询传导为 BaseApp、CellApp 或 DBMgr 的长尾。
性能与扩展方式
KBEngine Nex 采用多进程架构，可以增加 BaseApp 和 CellApp 分担连接、实体和 Space 压力。管理进程根据组件负载参与分配，但“能够横向扩展”不等于业务可以无限增长。
实际容量主要受以下因素影响：
- 单个 Entity 每 Tick 执行的 Python 逻辑；
- 单个 Space 的活跃 Entity 数量和 AOI 密度；
- 属性同步频率、RPC 数量和单包大小；
- 导航、AI、触发器和移动计算量；
- 数据库 IO、外部接口延迟和日志量；
- 跨 BaseApp/CellApp 调用和 Entity 迁移频率；
- 单进程内存、网络带宽及操作系统调度能力。
正式项目应使用接近真实业务的数据量、移动模式和消息频率进行 Bots 压测，并观察 P50、P95、P99、P99.9 延迟、Cell Tick、消息队列、Witness/AOI、CPU、内存和网络指标，而不是只以“在线连接数”判断承载能力。参见 使用 Bots 进行压力测试。
适用场景
KBEngine Nex 更适合具有长期在线状态、服务端权威逻辑和多实体交互的项目，例如：
- MMORPG、ARPG、MOBA 和多人开放世界；
- 房间制战斗、棋牌、休闲竞技和多人副本；
- 带账户、角色、社交、匹配和持久化的在线游戏；
- 需要 Space、AOI、移动同步或服务端 AI 的实时交互应用；
- 希望以 Python 快速开发业务，同时保留 C++ 底层性能和分布式能力的团队。
对于只有少量无状态 HTTP 接口、完全依赖数据库事务的传统后台，或所有逻辑都由第三方托管服务完成的项目，使用常规 Web 框架可能更加直接。选择引擎前，应判断项目是否真正需要 Entity 生命周期、长连接、实时状态同步和分布式场景计算。
开发与部署平台
Nex 使用 CMake Preset、Ninja 和 vcpkg 统一 Windows、Linux 与 macOS 的构建流程，并支持 x64、ARM64 和 Apple Silicon。Windows 适合开发调试，Linux 通常用于正式服务器部署，macOS 可用于本地开发和原生工具链验证。
第三方依赖和 Python 版本由 vcpkg manifest 与固定 baseline 管理，使 CI 与开发机能够恢复一致的依赖集合。发布目录包含服务端程序、Python 运行库和必要动态库，可以整体复制或移动，不依赖构建机上的绝对路径。
具体环境要求和编译入口见 安装和启动。
从哪里开始
建议按以下顺序继续阅读：
- 引擎特性：快速了解引擎能力范围。
- 引擎概览：认识各服务端组件和完整连接流程。
- 创建项目：建立第一个可运行的 Assets 工程。
- Entity 的配置：定义属性和远程方法。
- Entity 的 Python 实现：编写 Base/Cell 业务逻辑。
- SDK 自动生成：让客户端使用与服务器一致的协议定义。