介质与工具接口
根命名空间工具
| 接口 | 作用 | 注意 |
|---|---|---|
vve:_init | 初始化 VVE 模块、scoreboard 与默认常量 | 先初始化 Math3/LALib |
vve:_version | 把 VVE 版本写入约定分数 | 用于 load 前置检查 |
vve:_consts | 恢复默认运行常量 | 自定义模拟器每轮先调用 |
vve:_void | 空回调 | 用于需要函数 id 但不做事的字段 |
vve:_tp_here | 把执行实体传送到执行位置 | 要求可传送实体 |
vve:_tp_here_macro | 从 storage vve:io {x,y,z} 传送执行实体 | 宏输入必须完整 |
打印接口
调用前先把目标实例 _get 到共享临时对象。
| 接口 | 输出 |
|---|---|
vve:_print_coord | 中心坐标 |
vve:_print_coord_as | 以指定执行者/上下文打印坐标 |
vve:_print_velocity | 线速度 |
vve:_print_angular | 角速度 |
vve:_print_response | 当前介质响应信号 |
介质探测
所有入口都要求 cpoint 临时字段和正确执行位置，并会重置/覆盖响应区。
mcfunction
function demo:body/_get_cpoint
execute as 0-0-0-0-0 at @s run function vve:_detect_material
# 立刻接收结果
function vve:object/_receive_shift
function vve:object/_receive_impulse
function vve:object/_receive_friction详细差异见碰撞点、介质与响应。
ID 系统
vve:id 维护可复用整数编号。典型生命周期是初始化、拉取、绑定到实例、销毁时归还。编号是资源，不应：
- 拉取后因中途 return 而不归还；
- 同一实例归还两次；
- 把临时
result当长期唯一选择器； - 在两个独立模块里共享编号池却不共享生命周期规则。
为创建函数设计失败清理路径，比等 ID 耗尽后排查更便宜。
方块读取阵列
vve:block_reader 把大区域分成任务与 16×1×16 层/区块单元，避免一条函数一次扫描全部方块。
| 接口 | 用途 |
|---|---|
block_reader/_init | 手动建立工作区 |
_append_task | 从 storage vve:io input 加入任务 |
_append_task_over | 加入带结束回调的任务 |
_append_corner | 以两个角点创建立方区域任务 |
_iter_layer/_iter_layers | 遍历层级 |
_uninstall | 清理读取器工作区 |
回调 storage 的 res/loop 字段被框架占用；业务数据放在独立子结构，避免覆盖调度状态。
预设模拟器
| 接口 | 用途 |
|---|---|
vve:simulator/_class | 生成默认 simulator plate |
_get/_store | plate ↔ 临时 simulator 状态 |
_append_tick_func | 去重追加子步回调 |
_append_sync_func | 去重追加每游戏刻同步回调 |
_start/_stop | 计划或清除 vve:simulator/tick |
main/main_loop/tick | 完整调度路径 |
着色器接口
VVE 资源包集成修改过的 ShaderSelectorV4 roll 通道：
| 接口 | 行为 |
|---|---|
vve:shader/roll_instant | 立即写入 roll 状态 |
vve:shader/roll_linear | 线性过渡 roll |
.../_from_angle 变体 | 从角度输入构造 roll |
这是资源包/客户端视觉通道，不参与刚体四元数物理。Sandbox clean-room 渲染不会承诺复现所有客户端 shader 后处理。
声音程序
vve:sound/main 读取 bounce/grab/material/friction/impulse 等响应与实例声音状态，选择碰撞或滑动声。它应在响应仍有效时调用，但频率需做节流；持续接触每 tick 播音会产生噪声和额外命令成本。