第 10 章：VBUF 区段

Directory Tag： VBUF · 作用范围： Chunk 级 · 必须性： 可选 · Directory Codec： RAW8

VBUF（Vertex Buffer）是可直接上传 GPU 的派生缓存。它针对特定的标准化顶点格式保存顶点和索引，不保存权威体素语义。

10.1 Payload Layout

Header 固定 64 字节：

Offset	Size	Type	Field	Description
0	2	uint16	bufferVersion	必须为 1
2	2	uint16	headerSize	必须为 64
4	4	int32	chunkId	所属 Chunk
8	4	uint32	vertexCount	顶点数量
12	4	uint32	indexCount	索引数量，必须为 3 的倍数
16	4	uint32	vertexStride	必须为 20
20	4	uint32	indexStride	必须为 4
24	4	uint32	vertexOffset	相对 Payload 起始偏移，必须为 64
28	4	uint32	indexOffset	相对 Payload 起始偏移
32	32	uint8[32]	sourceHash	生成时的权威 Source Hash

顶点数组紧随 Header。每条顶点固定 20 字节：

Offset	Size	Type	Field
0	4	float32	positionX
4	4	float32	positionY
8	4	float32	positionZ
12	4	uint32	normalPacked（10:10:10:2 signed normalized）
16	4	uint32	colorRgba（非预乘 RGBA8）

索引数组为 uint32[indexCount]，每三个索引组成一个三角形。indexOffset 必须等于 64 + vertexCount × 20，且所有索引小于 vertexCount。

10.2 生成规则

VBUF 应由有效 MSH0 或直接由 VOX0 生成。每个矩形面生成四个顶点与六个索引；实现可做跨面顶点复用，但必须保持一致法线和颜色。Position 使用 Chunk 局部坐标，应用根变换或 Chunk 全局原点属于运行时职责。

normalPacked 的三个 10 位分量表示法线，W 两位必须为 0。对六个轴向法线，写入器必须使用精确的轴向单位向量。colorRgba 必须来自 PAL0 对应条目的 RGBA；材质标志由渲染器通过 PAL0 或附加渲染数据处理。

10.3 使用与验证

读取器使用 VBUF 前必须验证 Source Hash、Chunk ID、布局版本、Offset 范围、数组长度、有限 Position 和索引范围。VBUF 不匹配当前权威数据、顶点格式不支持或校验失败时，读取器应丢弃它，回退到 MSH0 或 VOX0。

VBUF 固定顶点格式是 VFP 1.3 的跨运行时基础缓存，不要求所有平台直接使用；平台私有 Buffer 不得伪装为标准 VBUF。

---

本章总结

VBUF 让标准体素表面可被快速上传和绘制。它是性能优化，不是资产源，也不应被用于反推体素。