KBEngine Nex 引擎特性

KBEngine Nex 是以 KBEngine 1.x 协议体系为基线持续维护的开源分布式游戏服务端引擎。底层使用 C++ 处理网络、调度、进程通信、Entity 生命周期、空间与数据库任务，业务层使用 Python 3.12 编写游戏逻辑。

引擎的目标不是替代所有业务代码，而是把长连接游戏服务中重复且容易出错的基础能力统一起来：客户端接入、远程调用、状态同步、场景管理、AOI、导航、持久化、负载分配、日志和运行诊断。开发者可以把主要精力放在角色、战斗、任务、房间、社交和经济系统上。

特性总览

领域	核心能力
业务模型	Entity、Base/Cell/Client 分层、EntityComponent、自定义数据类型
分布式运行	多 BaseApp、多 CellApp、管理组件协调、跨进程 EntityCall
客户端通信	SDK 生成、RPC、属性同步、协议摘要校验、TCP/KCP/WebSocket 接入
实时世界	Space、AOI、Witness、View、触发器、移动控制器、导航网格
数据持久化	Entity 属性映射、异步数据库任务、MySQL、MongoDB、PostgreSQL
Python	Python 3.12、热更新、VENV、asyncio、原生扩展模块
工程与平台	CMake、Ninja、vcpkg、Windows、Linux、macOS、x64/ARM64
运维与诊断	Logger、Watcher、Bots、性能指标、管理工具、配置覆盖
安全与稳定性	协议边界校验、管理 token、会话与回调生命周期校验、网络背压

Entity 驱动的业务开发

Entity 是引擎中最基本的业务对象。玩家、怪物、NPC、房间、场景、公会或其他长期存在的对象，都可以根据其生命周期和交互方式建模为 Entity。

一个 Entity 可以由以下部分组成：

• Base：运行在 BaseApp，适合账户、背包、社交、匹配、排行榜、持久化和客户端会话等非空间逻辑。
• Cell：运行在 CellApp，适合移动、战斗、AI、AOI、触发器、导航和其他空间实时逻辑。
• Client：运行在客户端，接收服务端属性同步与远程调用，并负责客户端表现和输入。

开发者通过 XML EntityDef 声明属性、方法、参数、同步范围和持久化策略，再用 Python 实现 Base/Cell 逻辑。底层根据相同定义完成参数序列化、对象路由、客户端同步和数据库映射，减少手写协议产生的不一致。

EntityComponent 可用于组合可复用的属性与行为。组件适合表达装备、技能、状态、任务等可独立建模的领域能力，避免所有逻辑集中在单个 Entity 类中。详见 Entity 和 EntityComponent。

分布式多进程架构

KBEngine Nex 将不同职责拆分到多个服务进程中：

• LoginApp 负责客户端登录入口；
• BaseApp 承载客户端连接、Base Entity 和非空间业务；
• CellApp 承载 Space、Cell Entity 和实时空间逻辑；
• DBMgr 负责数据库任务和 Entity 持久化；
• BaseAppMgr、CellAppMgr 负责对应集群的协调与负载信息；
• Machine 负责组件发现、本机进程管理和机器状态；
• Logger 汇聚运行日志；
• Interfaces 用于对接第三方账号、计费或运营系统。

项目早期可以把组件部署在一台开发机上；业务增长后，可以增加 BaseApp、CellApp 并分布到多台机器。EntityCall 封装跨进程对象引用，使脚本层以远程对象调用的方式传递消息，而不需要直接管理底层连接。

多进程架构能够隔离职责并提供横向扩展基础，但不会自动消除热点。单个超大 Space、高密度 AOI、集中到一个 BaseApp 的业务单例或大量跨进程调用，仍可能形成单核、网络和 Tick 瓶颈。详见 引擎概览。

客户端协议与 SDK

客户端协议由客户端可见的 Entity、属性、方法和数据类型共同构成。SDK 生成器根据 EntityDef 输出对应语言的协议代码，使客户端与服务器共享相同的数据布局和方法签名。

当前项目提供 C#、TypeScript、C++ 等客户端接入能力，可用于 Unity、Godot、Cocos Creator、LayaAir、Unreal Engine 和原生客户端。具体支持方式以各客户端 SDK 仓库及 客户端接入文档 为准。

Nex 3.x 将客户端可见协议摘要与完整服务端 EntityDef 摘要分离：

• 修改只在服务器内部使用的 Base/Cell 属性或方法，不应导致客户端摘要变化；
• 修改客户端可见属性、Client 方法、暴露给客户端的 Base/Cell 方法或相关数据类型时，需要重新生成 SDK；
• 插件提供的客户端可见 EntityDef 同样参与客户端协议摘要，避免插件协议未被纳入版本校验。

连接阶段的消息协议与 EntityDef 摘要校验可以尽早发现 SDK 不一致，避免客户端按错误类型读取数据。详见 SDK 自动生成。

Space、AOI 与导航

Space 是 CellApp 中的逻辑空间，可以表示世界地图、副本、战斗房间、牌桌或其他实时交互区域。不同 Space 的 Entity 默认彼此隔离，业务可以按场景边界组织移动、战斗和可见性。

客户端控制的 Cell Entity 可以拥有 Witness。Witness 根据 View 范围维护可见 Entity 集合，并同步进入视野、离开视野、属性变化和远程调用。DetailLevel 与易变属性策略可进一步控制不同距离下的同步精度和频率。

空间系统还提供：

• 范围触发器和坐标系统；
• 移动控制器及导航控制器；
• Recast/Detour 导航网格寻路；
• 多层导航和高度贴合；
• SpaceData 与几何映射；
• Cell Entity 创建、销毁和跨 Cell 生命周期管理。

AOI 的成本取决于可见关系数量，而不只是在线人数。扩大 View 半径、提高属性同步频率或在一个 Space 中堆积大量活跃 Entity，都会增加 Cell Tick、内存和网络包量。详见 Space、View 和 导航网格。

数据持久化

EntityDef 可以标记需要持久化的属性。业务调用写库接口后，数据通过 DBMgr 转换为异步数据库任务，并在完成后将结果路由回相应 Entity 或回调对象。

当前支持：

• MySQL；
• MongoDB；
• PostgreSQL。

引擎提供 Entity 数据模型同步和原生数据库命令接口，但数据库能力不等于可以忽略数据建模。高频实时坐标不应每 Tick 写库，大集合序列化、复杂查询、跨 Entity 事务和索引仍需要按业务负载设计。原生命令还应使用最小权限、参数校验和耗时控制。

Python 3.12 运行时

Nex 将原版 KBEngine 的 Python 3.7 升级到 Python 3.12，并统一了 Windows、Linux 和 macOS 的动态 Python 运行时部署方式。

主要能力包括：

• 引擎自带匹配版本的 Python 运行库，无需依赖系统 Python 才能启动；
• Debug 和 Release 引擎均链接 Release Python ABI；
• Windows 支持 .pyd，Linux/macOS 支持对应 ABI 的原生动态扩展；
• 自动发现项目下的 .venv 或 venv，也可以显式配置 KBE_VENV_PATH；
• 支持 reloadScript 热更新业务脚本；
• 支持 asyncio，并由组件 Dispatcher 定时推进事件循环。

Python 回调仍运行在所属组件的调度线程中。asyncio 可以避免在等待 IO 时阻塞，但 CPU 密集循环、同步文件或数据库操作、过量序列化仍会占用 Tick。需要将耗时工作拆分、异步化或转移到职责明确的外部服务。详见 Python、VENV、热更新 和 asyncio。

网络与高并发处理

引擎为不同平台使用对应的高性能事件机制，并在客户端链路提供 TCP、KCP 等接入方式。网络层负责连接生命周期、数据包解析、加密过滤、发送队列和异常输入处理。

Nex 对高并发链路补充了以下治理能力：

• KCP ACK、重传、窗口和更新队列调度；
• UDP/KCP 积压限制和网络背压；
• Windows IOCP completion 批量处理与调度预算；
• 客户端请求、包长、固定头和会话状态校验；
• 网络队列、延迟与丢包相关 Watcher 指标。

网络模型不能替代容量规划。消息数量、单包大小、广播范围、连接抖动和业务回包频率都会影响 CPU、内存和带宽，应使用接近真实玩法的 Bots 场景进行验证。

负载分配与性能观测

BaseAppMgr 和 CellAppMgr 根据组件状态与负载参与客户端、Entity 和 Space 的分配。Nex 还对 Space 待创建压力、Witness 压力、AOI 队列和实时负载等指标进行了补充，降低新任务短时间集中到单个进程的风险。

引擎提供 Watcher、日志和标准压测能力，可观察：

• 组件 CPU、内存和网络收发；
• BaseApp/CellApp Tick 及慢 Tick；
• 消息处理、Python 回调和队列延迟；
• AOI、Witness、触发器和 Cell 迁移；
• KCP、UDP 背压和 IOCP completion；
• P50、P95、P99、P99.9 等延迟分位数。

性能探针应按需开启，避免诊断本身制造额外日志和采样压力。容量结论必须基于具体业务模型、硬件和网络环境，不能只用“最大连接数”衡量。参见 性能优化 和 Bots 压测。

配置、管理与安全边界

服务端公共默认值位于引擎资源配置中，项目通过自身的 kbengine.xml 覆盖需要调整的部分。启动参数还支持选择环境配置，便于开发、测试和生产使用不同的数据库、端口和日志级别。

管理控制入口使用 management 共享 token 校验。生产环境应为不同部署设置足够强的 token，并限制管理端口和内部组件网络的访问范围。不要把内部组件、数据库或管理接口直接暴露到公网。

协议层会校验消息来源、会话、实体类型、长度、索引、回调状态和生命周期。此类校验用于阻断非法数据进入业务层，但业务仍需负责账号权限、资源归属、操作频率、经济系统一致性等领域安全规则。

工具与开发体验

项目围绕开发、调试和运维提供多种工具：

• KBEX PyCharm 插件：项目创建、代码补全、定义跳转、服务管理、热更新和 SDK 生成；
• Bots：模拟客户端登录、RPC、移动和压力场景；
• Logger 与日志查看工具：集中收集和筛选组件日志；
• Watcher：读取组件状态、队列和性能指标；
• WebConsole、GUIConsole、Space Viewer：按各自职责提供管理和空间观察能力；
• 安装与构建脚本：准备工具链、恢复 vcpkg 依赖并执行 CMake Preset。

工具提供观察和控制入口，但不替代生产监控、告警、备份、审计和发布系统。正式部署应将引擎指标接入团队已有的运维体系。

跨平台构建与可移动部署

Nex 使用 CMake、Ninja 和 vcpkg 管理 Windows、Linux、macOS 的构建与第三方依赖，并覆盖 x64、ARM64 和 Apple Silicon 等环境。

发布目录包含服务端可执行文件、Python 动态运行库和必要依赖。Linux 使用相对 $ORIGIN，macOS 使用 @loader_path 解析同目录动态库，Windows 按系统 DLL 搜索规则从可执行文件目录加载依赖。因此完整发布目录可以整体移动，不依赖构建机的绝对路径；移动时不能只复制可执行文件而遗漏运行库。

Windows 更适合本地开发与调试，Linux 通常作为正式服务器环境，macOS 可用于本地开发和原生工具链验证。具体支持范围应以当前版本 CI 和 安装与启动 为准。

开源协议

仓库提供 GPLv3 与 LGPLv3 协议文件。不同目录、库、链接方式和发行物可能适用不同条款，使用、修改或分发前应阅读仓库中的 GPL-LICENSE.txt、LGPL-LICENSE.txt 及相关文件声明。 本文仅描述项目中存在的协议文件，不构成法律意见。商业项目如对闭源发布、动态链接、修改分发或第三方依赖许可证存在疑问，应由具备资质的专业人员结合实际发行方式评估。