附录 F 坐标系约定：BigWorld 与 KBEngine

// kbe/src/lib/math/math.h:144
// 从2个3d向量忽略y计算出2d长度
inline float KBEVec3CalcVec2Length(const Vector3& v1, const Vector3& v2)
{
    float x = v1.x - v2.x;
    float z = v1.z - v2.z;
    return sqrt(x*x + z*z);
}

// BigWorld RangeListNode 穿越回调
virtual void crossedX(RangeListNode* node, bool positiveCrossing,
    float oldOthX, float oldOthZ) {}
virtual void crossedZ(RangeListNode* node, bool positiveCrossing,
    float oldOthX, float oldOthZ) {}

// range_trigger_node.cpp:78
bool RangeTriggerNode::wasInYRange(CoordinateNode * pNode)
{
    if (!CoordinateSystem::hasY)
        return true;  // Y 关闭时，Y 范围判定永远返回 true
    ...
}

// kbe/src/lib/math/math.h:174-197
struct Direction3D
{
    Direction3D():dir(0.f, 0.f, 0.f) {};
    Direction3D(const Vector3 & v):dir(v){}
    Direction3D(float r, float p, float y):dir(r, p, y){}

    float roll()  const{ return dir.x; }
    float pitch() const{ return dir.y; }
    float yaw()   const{ return dir.z; }

    void roll(float v) { dir.x = v; }
    void pitch(float v){ dir.y = v; }
    void yaw(float v)  { dir.z = v; }

    Vector3 dir;  // 存储 (roll, pitch, yaw)
};

// kbe/src/lib/math/math.h:156-169
inline KBEngine::int8 angle2int8(float v, bool half = false)
{
    KBEngine::int8 angle = 0;
    if(!half)
    {
        // 普通模式：角度 → int8，覆盖 -π ~ π
        angle = (KBEngine::int8)floorf((v * 128.f) / float(KBE_PI) + 0.5f);
    }
    else
    {
        // 半范围模式：角度 → int8，覆盖 -π/2 ~ π/2
        angle = (KBEngine::int8)KBEClamp(floorf((v * 254.f) / float(KBE_PI) + 0.5f), -128.f, 127.f);
    }
    return angle;
}

inline float int82angle(KBEngine::int8 angle, bool half = false)
{
    return float(angle) * float((KBE_PI / (half ? 254.f : 128.f)));
}

// kbe/src/lib/common/memorystream.h:648-700
void appendPackXZ(float x, float z)
{
    // 利用 IEEE 754 浮点数结构：
    // 0-7位存放尾数, 8-10位存放指数, 11位存放标志
    // 舍弃第一位使范围达到 (-512~-2), (2~512)
    ...
}

// kbe/src/lib/common/memorystream.h:703-713
void appendPackY(float y)
{
    PackFloatXType yPackData;
    yPackData.fv = y;
    yPackData.fv += yPackData.iv < 0 ? -2.f : 2.f;
    uint16 data = 0;
    data = (yPackData.uv >> 12) & 0x7fff;
    data |= ((yPackData.uv >> 16) & 0x8000);
    (*this) << data;
}

// kbe/src/lib/common/memorystream.h:633-646
void appendPackXYZ(float x, float y, float z, float minf = -256.f)
{
    x -= minf;
    y -= minf / 2.f;
    z -= minf;
    // X: 11 bit, Z: 11 bit, Y: 10 bit, 总共 32 bit
    uint32 packed = 0;
    packed |= ((int)(x / 0.25f) & 0x7FF);        // X: 11 bit
    packed |= ((int)(z / 0.25f) & 0x7FF) << 11;   // Z: 11 bit
    packed |= ((int)(y / 0.25f) & 0x3FF) << 22;   // Y: 10 bit
    *this << packed;
}

// kbe/src/server/cellapp/witness.cpp:20-30
#define UPDATE_FLAG_NULL              0x00000000
#define UPDATE_FLAG_XZ                0x00000001  // 仅 XZ 位移
#define UPDATE_FLAG_XYZ               0x00000002  // 三轴位移
#define UPDATE_FLAG_YAW               0x00000004  // 仅 yaw
#define UPDATE_FLAG_ROLL              0x00000008  // 仅 roll
#define UPDATE_FLAG_PITCH             0x00000010  // 仅 pitch
#define UPDATE_FLAG_YAW_PITCH_ROLL    0x00000020  // 三轴旋转
#define UPDATE_FLAG_YAW_PITCH         0x00000040  // yaw + pitch
#define UPDATE_FLAG_YAW_ROLL          0x00000080  // yaw + roll
#define UPDATE_FLAG_PITCH_ROLL        0x00000100  // pitch + roll
#define UPDATE_FLAG_ONGOUND           0x00000200  // 在地面上

// witness.cpp:1074 — UPDATE_FLAG_XZ | UPDATE_FLAG_YAW
case (UPDATE_FLAG_XZ | UPDATE_FLAG_YAW):
{
    Position3D relativePos = otherEntity->position() - this->pEntity()->position();
    // 发送：实体ID(可变长) + PackXZ(3B) + angle2int8(1B) = ~5-6 字节
    pForwardBundle->appendPackXZ(relativePos.x, relativePos.z);
    (*pForwardBundle) << angle2int8(dir.yaw());
}

// api/cellapp/Entity.md:1140
// 还有一个特殊的bool属性optimized，它的作用是控制服务器同步时是否进行优化，
// 目前主要的优化是Y轴。
// 如果为true，在一些行为(如：navigate)导致服务器能确定实体在地面时，
// 服务器不同步实体的Y轴坐标，当同步大量实体时能节省大量带宽，默认为true。

// entity.h:648-652
float topSpeed_;   // entity x,z轴最高移动速度（米/秒）
float topSpeedY_;  // entity y轴最高移动速度（米/秒）

// entity.cpp — checkMoveForTopSpeed
// 如果移动距离超出速度限制，强制拉回上一个坐标位置

// kbe/src/lib/math/math.h
#if KBE_PLATFORM == PLATFORM_WIN32 && defined(USE_D3DX)
    // DirectX 数学库（D3DX）
    typedef D3DXVECTOR3 Vector3;
    typedef D3DXQUATERNION Quaternion;
    #define KBEMatrixRotationYawPitchRoll D3DXMatrixRotationYawPitchRoll
#else
    // G3D 数学库（跨平台）
    typedef G3D::Vector3 Vector3;
    typedef G3D::Quat Quaternion;
#endif