API 分类与核对清单

这份清单用于把 docs-vuepress/api 下的页面按职责分层，并按分类逐批核对 API 文案、参数语义、返回值、同步边界与源码实现。

核对原则

  • 先核对接口真实语义，再核对参数、返回值与调用边界。
  • API 页只保留接口说明、注意点与跳转；复杂机制统一下沉到 architecture/source-analysis。
  • 对 Player 身份、控制权、可见性、ownerOnly、同步/广播、异步回调 这些容易混淆的概念，必须拆开说明。
  • CHM 原文、现有文案、源码行为三者冲突时，以源码实际行为为准，并在 API 页补充“源码解析”跳转。

分类总览

分类页面范围当前重点状态
核心概念层api/README、basetypes、keywords基础类型、关键词、EntityCall/属性描述术语统一未开始
客户端运行时层client/KBEngine、client/Entity、bots/KBEngine、bots/Entity、bots/PyClientAppplayer、isPlayer、isControlled、可见性回调、客户端移动与 ownerOnly 边界进行中
服务端实体层baseapp/Entity、baseapp/Proxy、cellapp/EntityBase/Cell 实体职责、controlledBy、控制器、AOI、持久化、客户端绑定进行中
服务端全局入口层baseapp/KBEngine、cellapp/KBEngine、loginapp/KBEngine、dbmgr/KBEngine、interfaces/KBEngine、logger/KBEngine全局函数、全局数据字典、进程级回调、组件边界进行中
交叉专题层跨多个 API 页的同名概念玩家身份/控制权、生命周期、计时器、全局数据、属性同步、空间与控制器进行中

推荐核对顺序

  1. 客户端运行时层
  2. 服务端实体层
  3. 服务端全局入口层
  4. 核心概念层

这样排的原因很直接：

  • 客户端 API 最容易出现“名字像控制权、实际是身份判断”的误读。
  • 服务端实体层决定了客户端 API 的真实语义，第二批跟进最合适。
  • 进程级 KBEngine 入口多，但大多是围绕实体、数据字典与回调展开，放在实体层之后核对更稳。
  • basetypes 和 keywords 更像统一术语表，适合作为最后的收口整理。

分类明细

1. 核心概念层

页面：

重点核对：

  • 基础类型定义是否和 .def、脚本桥接、序列化实现一致
  • ENTITYCALL、CELLDATADICT、PyClient 等术语是否只讲“表面名词”，没有交代运行时语义
  • 关键词之间是否存在重复解释或互相矛盾

建议关联源码解析：

2. 客户端运行时层

页面：

重点核对：

  • player()、isPlayer() 与 controlledBy / isControlled 的边界
  • onEnterWorld()、onLeaveWorld()、onEnterSpace()、onLeaveSpace() 的真实触发语义
  • baseCall()、cellCall() 的调用限制与“只能访问玩家实体”这类边界条件
  • isOnGround、移动接口、客户端可写属性的同步方向
  • ownerOnly 属性在客户端的可见性与回调行为

建议关联源码解析：

当前已完成：

下一批待核对：

  • cellapp/Entity.addTimer() / delTimer()
  • cellapp/Entity.moveToPoint() / navigate() / cancelController()

3. 服务端实体层

页面：

重点核对：

  • Base / Cell / Proxy 各自职责边界
  • controlledBy、giveClientTo、客户端迁移与控制权切换
  • 控制器接口、导航接口、AOI / Witness / View 回调
  • writeToDB()、cell 备份、灾难恢复与真实持久化链路

建议关联源码解析：

当前已完成：

优先核对：

  • baseapp/Entity.writeToDB()
  • baseapp/Entity.destroy()
  • cellapp/Entity.addProximity()
  • cellapp/Entity.writeToDB()

4. 服务端全局入口层

页面：

重点核对：

  • 每个进程级 KBEngine 模块到底提供哪些“只在本组件可用”的接口
  • globalData、baseAppData、cellAppData 的同步方向、回调时机与使用边界
  • 账号、数据库、外部接口、日志相关 API 的真实职责

建议关联源码解析：

当前已完成：

优先核对：

  • loginapp/KBEngine 入口回调与账号流程接口
  • dbmgr/KBEngine 数据库入口与回调接口
  • interfaces/KBEngine 外部接口桥接
  • logger/KBEngine 进程日志入口

5. 交叉专题层

这一层不按单页推进，而是按“同一个概念横跨多个组件”推进。

当前专题：

  • 玩家身份与控制权
  • 实体生命周期与视野可见性
  • 定时器与回调
  • 全局数据字典同步
  • 属性同步、广播与 ownerOnly
  • 移动、控制器与导航

已打通的专题入口：

当前执行策略

  • 先把“一个术语在多个页面写法不一致”的问题收敛掉
  • 再把每个分类里最容易误解的 API 按“API 页简述 + 源码解析页深讲 + API 页跳转”补齐
  • 最后再回到 basetypes、keywords 做统一术语清理