🧭 坐标系

大约 3 分钟

背景

navmesh 升级后，为了同时满足以下目标，坐标系基准做了统一调整：

保持多客户端兼容。
保持未来插件升级兼容。
与官方支持的导航/渲染生态保持一致。

旧版本使用的是左手坐标系；升级后，底层导航相关坐标统一切换为官方支持的 -Z 右手坐标系，和 Recast Navigation、Three.js 保持一致。

需要注意的是，KBE 逻辑层仍然使用的是 +Z 右手坐标系。因此，客户端侧在做位置和朝向同步时，必须根据各自引擎的坐标定义做一次对应的手系翻转和轴映射。

基本约定

逻辑层基准：KBE 使用 +Z 右手坐标系。
导航/官方插件基准：使用 -Z 右手坐标系。
客户端接入原则：所有同步到客户端的位置、旋转，都必须经过引擎适配层转换后再使用。

旋转字段中：

x = roll
y = pitch
z = yaw

当前大部分客户端场景中，主要关注的是 yaw 的转换。

处理建议

不要在业务层到处手写坐标转换。
建议每个客户端引擎都封装统一的坐标转换函数，例如：
- 逻辑坐标转客户端坐标
- 客户端坐标转逻辑坐标
- 逻辑朝向转客户端朝向
- 客户端朝向转逻辑朝向
网络同步、寻路结果落地、场景对象摆放，全部走同一套转换逻辑，避免出现部分模块坐标系不一致的问题。

各客户端坐标转换

以下公式均以 KBE 逻辑层坐标为输入，转换到客户端引擎坐标。

Unity

Unity 侧需要对 x 轴做翻转。

位置：

x' = -x
y' = y
z' = z

朝向：

yaw' = -yaw

说明：

由于协议中的 z 表示 yaw，也可以写成：yaw = -z。

Cocos Creator

Cocos Creator 需要同时处理手系翻转和 y/z 轴对调。

位置：

x' = -x
y' = z
z' = y

朝向：

yaw' = yaw + 180

Godot

Godot 的处理方式与 Cocos Creator 一致。

位置：

x' = -x
y' = z
z' = y

朝向：

yaw' = yaw + 180

Unreal Engine

UE 除了轴映射外，还需要注意长度单位差异。KBE 常用米制逻辑单位，而 UE 默认使用厘米，因此位置需要乘以 100。

位置：

x' = x * 100
y' = z * 100
z' = y * 100

朝向：

yaw' = yaw + 90

对照汇总

客户端	位置转换	朝向转换
Unity	`(-x, y, z)`	`yaw = -yaw`
Cocos Creator	`(-x, z, y)`	`yaw = yaw + 180`
Godot	`(-x, z, y)`	`yaw = yaw + 180`
Unreal Engine	`(x * 100, z * 100, y * 100)`	`yaw = yaw + 90`

注意事项

如果客户端还存在“客户端坐标回传服务端”的逻辑，必须实现反向转换，不能只做单向适配。
yaw + 180、yaw + 90 后，建议统一做角度归一化，例如限制到 [-180, 180) 或 [0, 360)。
如果项目中还保留了旧版左手坐标的历史代码，需要优先排查并清理，避免升级后出现镜像、朝向相反、寻路点错位等问题。