19. 客户端协议与前后端交互

客户端发送（脚本调用 → 网络）：
  Python: entity.base.requestMatchmaking()
    │
    ├── EntityCall::tp_call()
    │     → newCall(bundle)
    │     → 序列化参数到 bundle
    │
    ├── Channel::send(bundle)
    │     → Bundle 拆分为 Packet
    │     → TCP/KCP 发送
    │
    └── 到达服务器

客户端接收（网络 → 脚本回调）：
  网络层收到 Packet
    │
    ├── PacketReader::processMessages()
    │     → 解析消息 ID
    │     → 查找 MessageHandler
    │
    ├── ClientInterface::onRemoteMethodCall handler
    │     → 反序列化 ENTITY_ID + 方法 utype + 参数
    │     → 找到目标 Entity
    │     → Entity::onRemoteMethodCall(stream)
    │
    └── Python 回调被触发
          entity.onMatchmakingResult(result)

                  服务器                           客户端
                    │                                │
  1. 登录成功        │── onLoginSuccessfully ──────→ │ 建立连接
                    │                                │
  2. 创建玩家实体    │── onCreatedProxies ──────────→ │ 创建 Entity
                    │    (uuid, eid, entityType)      │ 初始化属性
                    │                                │
  3. 进入世界        │── onEntityEnterWorld ────────→ │ entity.onEnterWorld()
                    │    (eid, scriptType, ...)       │ 绑定 cellEntityCall
                    │                                │
  4. 进入空间        │── onEntityEnterSpace ────────→ │ entity.onEnterSpace()
                    │    (eid, spaceID, ...)          │ 设置当前 spaceID
                    │                                │
  5. 其他实体进入AOI │── onEntityEnterWorld ────────→ │ 创建其他 Entity
                    │── onUpdatePropertys ──────────→ │ 设置初始属性
                    │                                │
  6. 属性更新        │── onUpdatePropertys ──────────→ │ entity.onUpdatePropertys()
                    │    (eid, prop1=val1, ...)       │ 更新显示
                    │                                │
  7. 远程方法调用    │── onRemoteMethodCall ─────────→ │ entity.onMethod(args)
                    │                                │
  8. 实体离开世界    │── onEntityLeaveWorld ────────→ │ entity.onLeaveWorld()
                    │    (eid)                       │ 非玩家实体通常随即销毁
                    │                                │
  9. 玩家离开空间    │── onEntityLeaveSpace ────────→ │ entity.onLeaveSpace()
                    │    (eid)                       │
 10. 预进入世界即销毁 │── onEntityDestroyed ──────────→ │ destroyEntity()
                    │    (eid)                       │ 典型是尚未 enterWorld 的实体
                    │                                │
 11. 玩家下线        │── 断开连接 ──────────────────→ │ 清理所有实体

服务器发送 enterAoI(id, idAlias)
  → 客户端创建 Entity shell（空壳）
  → 服务器发送 createEntity / createEntityDetailed（属性数据）
  → Entity 填充属性
  → onEnterWorld() 被调用

离开 AOI：
  → 服务器发送 leaveAoI(id)
  → onLeaveWorld() 被调用
  → 实体被销毁

服务器每 tick（100ms）发送一次位置：
  t=0.0s: pos = (0, 0, 0)
  t=0.1s: pos = (1, 0, 0)
  t=0.2s: pos = (2, 0, 0)

客户端渲染帧率 60fps（~16.7ms/帧）：

  无插值：
    frame 0: (0,0,0)  frame 1: (0,0,0)  ...  frame 6: (1,0,0)  ← 突然跳了一格
    frame 7: (1,0,0)  ...  frame 12: (2,0,0) ← 又跳了一格

  线性插值：
    frame 0: (0, 0, 0)
    frame 1: (0.17, 0, 0)
    frame 2: (0.33, 0, 0)
    ...
    frame 6: (1.0, 0, 0)     ← 平滑到达
    frame 7: (1.17, 0, 0)
    ...
    frame 12: (2.0, 0, 0)    ← 平滑到达

detailLevel=0（近处）：全部属性都同步
  → 客户端显示完整模型、装备、buff 图标、名称...

detailLevel=1（中距离）：部分属性
  → 客户端显示简化模型、名称...

detailLevel=2（远处）：只有位置和朝向
  → 客户端只显示一个点/简化图标

客户端不需要显式知道 detailLevel——
服务器已经按 detailLevel 过滤了属性，
客户端只需要渲染收到的属性。

客户端检测到断线
  │
  ├── 1. 使用上次 onLoginSuccessfully 保存的 baseappIP_ / baseappPort_
  │
  ├── 2. 重新连接 BaseApp
  │     → 发送 BaseappInterface::reloginBaseapp
  │     → 携带 name / password / rndUUID / entityID
  │
  ├── 3a. 重连成功
  │     BaseApp 回复 onReloginBaseappSuccessfully
  │       → createClientProxies(proxy, true)
  │       → Proxy::onGetWitness()
  │       → 重新推送 onCreatedProxies / 属性 / world / space 消息
  │       → 客户端重建实体和视野
  │
  └── 3b. 重连失败
        BaseApp 回复 onReloginBaseappFailed(failedcode)
          → rndUUID 不匹配 / 实体不存在 / 会话非法

重连成功后，服务器会重推完整状态：

1. onCreatedProxies(uuid, eid, entityType)
     → 重建玩家实体并拿回 baseEntityCall

2. onUpdatePropertys(stream)
     → 填充玩家实体的所有属性

3. onEntityEnterWorld(...)
     → 重建 world / cell 侧状态

4. onEntityEnterSpace(spaceID, eid, ...)
     → 玩家进入空间

5. [对视野内每个实体]
     onEntityEnterWorld → onUpdatePropertys → onEntityEnterSpace
     → 重建所有可见实体

重连成功
  │
  ├── 恢复网络连接
  ├── 服务器发送 controlEntity(id, true)
  │     → 客户端重新获得实体的控制权
  ├── 服务器推送完整世界状态
  └── 客户端恢复渲染

TCP 下的消息顺序保证：

BaseApp 发送：
  msg1: onUpdatePropertys(health=80)
  msg2: onRemoteMethodCall(onDamage, 50)
  msg3: onUpdatePropertys(health=30)

客户端收到顺序一定是 msg1 → msg2 → msg3
  → health 先变成 80，然后收到 onDamage 调用，最后 health 变成 30
  → 逻辑正确

1. KCP 是在 UDP 之上提供“可靠、有序”交付，不是按消息级别选择可靠性。
2. KBEngine 当前客户端协议语义不因为切到 KCP 就变成“不可靠属性同步”。

KCP 的价值主要在于：
  1. 更积极的重传与 RTT 估计
  2. 避开 TCP 某些额外等待
  3. 保持业务消息的顺序交付

KBEngine KCP 集成：
  kbe/src/lib/network/kcp_packet_sender.h
  kbe/src/lib/network/kcp_packet_receiver.h

Mercury 可靠性级别：
  RELIABLE_NO：不保证送达（位置更新，丢了也无所谓）
  RELIABLE_DRIVER：保证送达的驱动消息
  RELIABLE_PASSENGER：随驱动消息一起可靠传输
  RELIABLE_CRITICAL：关键消息，必须可靠

TCP vs KCP vs Mercury：
  TCP：所有消息可靠有序，延迟较高
  KCP：所有消息可靠有序，延迟较低
  Mercury：按消息选择可靠性，最低延迟但实现最复杂

Python（客户端）: entity.base.requestBuyItem(itemId=1001, count=5)
  │
  ├── EntityCall::tp_call()
  │     → newCall(bundle)
  │     → bundle << BaseappInterface::onRemoteMethodCall
  │     → bundle << entityID << ENTITYCALL_TYPE_BASE
  │     → bundle << methodUtype
  │     → 序列化参数 (itemId=1001, count=5)
  │
  ├── 通过 Channel 发送到 BaseApp
  │
  └── BaseApp 收到 onRemoteMethodCall
        → Entity::onRemoteMethodCall(channel, stream)
        → 检查方法是否标记为 Exposed
        → 如果不是 Exposed → 拒绝（安全边界）
        → 如果是 Exposed → 执行方法

信任边界示意图：

客户端                    服务器
  │                        │
  │  只有 Exposed 方法     │
  │  可以被调用 ────────→  │  验证：方法是否 Exposed？
  │                        │  验证：调用者身份（Channel 绑定）
  │                        │
  │  非 Exposed 方法       │  拒绝！
  │  无法调用 ────────→    │  → condemn channel
  │                        │
  │  Exposed + CallerCheck │  额外验证：调用者 EntityID
  │  ───────────────────→  │  → 脚本层可以检查 callerID 是否合法

攻击场景：
  恶意客户端发送 onRemoteMethodCall(entityID=其他玩家ID, method=heal, args=100)
    │
    └── 服务器检查：
          1. Channel 绑定的 EntityID ≠ 请求中的 entityID → 拒绝
          2. 或者 method 不是 Exposed → 拒绝
          3. 或者 entityID 根本不存在 → 忽略

客户端不能直接与 CellApp 通信！

entity.cell.onMove(x, y, z)
  │
  ├── 客户端发送到 BaseApp
  │     BaseappInterface::onRemoteCallCellMethodFromClient
  │     bundle << entityID << methodUtype << args
  │
  ├── BaseApp 收到后转发到 CellApp
  │     CellappInterface::onEntityCall
  │     bundle << entityID << ENTITYCALL_TYPE_CELL << methodUtype << args
  │
  └── CellApp 收到后执行方法
        Entity::onRemoteMethodCall(channel, stream)

间接调用的原因：
  1. 安全：BaseApp 作为中间层可以验证客户端身份
  2. 简化：客户端只需要与 BaseApp 建立一个连接
  3. 灵活：BaseApp 可以在转发前/后添加逻辑