API 阅读约定
VVE 的 API 不是类型系统强制的；调用契约由函数注释、执行上下文、共享 score/storage 和结果选择器共同组成。查一个接口时，至少确认五件事。
五项调用契约
| 项目 | 要问的问题 |
|---|---|
| 执行者 | 需要物理实例、玩家、世界 marker，还是 0-0-0-0-0 运算实体？ |
| 执行位置/朝向 | 函数是否读取 at @s、局部坐标 ^ ^ ^ 或当前 rotation？ |
| 输入 | 来自假玩家、storage <ns>:io input，还是实例自身？精度是多少？ |
| 输出 | 写到临时对象、io result、@e[tag=result]，还是直接修改实例？ |
| 破坏范围 | 会覆盖哪些共享字段、移动运算实体、消费 result tag 或计划函数？ |
命名约定
| 形式 | 语义 |
|---|---|
init | 初始化本模块的 scoreboard、常量和 plate |
_class | 构造预设数据模板 |
_consts | 恢复/设置模块常量 |
_zero | 清空该模型的临时字段 |
_proj | io input → 临时对象 |
_model | 临时对象 → io result |
_get | 执行实例 → 临时对象 |
_store | 临时对象 → 执行实例 |
_new | 从 io input 创建实例，输出 tag=result |
_del | 销毁执行实例及其关联实体 |
_sync_motion | 把计算结果同步到世界/显示实体 |
main* | 执行完整帧或明确阶段 |
tick* | 遍历实例或自计划调度 |
共享临时区不是可重入 API
大多数核心函数使用同一批 int 假玩家、storage vve:io 和 Math3 临时结构。除非源码明确保存/恢复，否则不要并发或嵌套模型运算。
模块前缀占位符
MOT 模板中：
| 占位符 | data/demo/function/vehicle/car/ 的值 |
|---|---|
$(module_prefix) | demo:vehicle/car/ |
$(project_name) | demo |
$(module_name) | car |
模板内的 function $(module_prefix)_class 最终变成 function demo:vehicle/car/_class。阅读 .mcfi 时先做这一步脑内替换。
API 稳定性分层
- 业务稳定入口：文档明确描述的
init/_class/_new/_get/_store/_proj/_model、探测函数、模型主程序。 - 模板扩展点：预设要求用户实现或覆盖的
_consts、显示、碰撞点/控制回调。 - 实现细节：无接口命名、只被同目录内部函数调用的 loop/calc/set 辅助文件。
- 测试/示例：
vve:test/*与vve_examples:*可学习，但不应当作所有项目的稳定公共 ABI。
API 页面以 VVE 3.0.1 当前源码为基线；升级时应 diff 模板生成结果和接口注释，而不是只看 README 版本号。