编辑器类型与保存 API
本页列出由 voxel-kit 根入口导出的编辑器枚举、状态和保存类型。所有坐标均为源体素网格坐标：x 最快、y 次之、z 最慢，范围为 0..gridSize-1。
VoxelEditMode
| 值 | 含义 |
|---|---|
VIEW | 点击仅查看一个体素。 |
ADD | 在命中面的外侧添加当前颜色。 |
DELETE | 删除命中体素。 |
REPLACE | 用当前颜色替换命中体素。 |
SELECT | 单击切换多选成员。 |
SELECT_BRUSH | 单指滑过可见表面，连续把命中的体素加入选区。 |
BOX_SELECT | 单指拖出屏幕矩形选择可见表面。 |
PICK | 吸取命中体素颜色。 |
VoxelEditorOptions
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- |
| maxHistory | number | 100 | 最大撤销批次数；超过后最早记录被丢弃。 |
| placementRebuildIdleMs | number | 180 | ADD/DELETE/REPLACE 的局部重建合并窗口。 |
| directRebuildIdleMs | number | 16 | 撤销、重做和批量命令的局部重建延迟。 |
| symmetryX | boolean | false | 初始 X 轴对称状态。 |
| selectBrushAppend | boolean | true | 滑动选择每一笔开始时是否保留已有选区；false 会先清空再选择。 |
| onSelectBrushHit | (x: number, y: number, z: number) => void | 空函数 | 每笔首次加入一个体素时的轻量回调；回调异常不会中断滑选。 |
| onStateChanged | (state: VoxelEditorState) => void | 空函数 | 编辑状态变化回调。回调内只做轻量 UI 状态更新。 |
VoxelEditorState
| 字段 | 类型 | 说明 |
|---|---|---|
active | boolean | 编辑已可操作。 |
preparing | boolean | 正在恢复体素或预热编辑资源。 |
updating | boolean | 正在提交局部网格更新。 |
mode | VoxelEditMode | 当前交互模式。 |
selectedSymbol | string | 当前放置/替换符号。 |
symmetryX | boolean | 当前 X 对称状态。 |
selection | VoxelSelection | undefined | 最后活动的选区成员，兼容单选 UI。 |
selectionCount | number | 所有选中体素数量。 |
selectionBounds | VoxelSelectionBounds | undefined | 所有选中体素的包含式边界。 |
palette | Array<VoxelEditorPaletteItem> | 当前可用调色板。 |
canUndo / canRedo | boolean | 历史按钮是否可用。 |
voxelCount | number | 当前非空体素数。 |
message | string | 面向用户的状态文本，不应作为逻辑枚举比较。 |
dirty | boolean | 自上次成功保存后是否有模型修改。 |
saving | boolean | 是否正在编译或写入保存文件。 |
exporting | boolean | 是否正在通过 TaskPool 生成离屏 GIF。此时不应重复触发保存、编辑或 GIF 导出。 |
VoxelEditorPaletteItem 包含 symbol 和 hex；VoxelSelection 包含 x/y/z、命中的 faceX/faceY/faceZ 以及当时 symbol。VoxelSelectionBounds 由 minX/minY/minZ/maxX/maxY/maxZ 构成，所有端点均包含在内。
坐标、轴和对齐
new VoxelCoordinate(x, y, z)
VoxelAxis 可取 X、Y、Z。VoxelSelectionAlign 可取：
| 轴 | 最小 | 中间 | 最大 |
|---|---|---|---|
| X | MIN_X | CENTER_X | MAX_X |
| Y | MIN_Y | CENTER_Y | MAX_Y |
| Z | MIN_Z | CENTER_Z | MAX_Z |
CENTER_* 使用选区最小与最大坐标的向下取整中点；对齐会把多个体素压到一个平面，可能减少最终非空体素数量。
保存类型
VoxelEditorSaveOptions
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
format | VoxelSaveFormat | SOURCE | SOURCE、JSON 或 VFP。 |
fileName | string | '' | saveAs() 的建议文件名；扩展名会按实际格式处理。 |
vfpChunkSize | number | 16 | VFP Native 编译 Chunk 规格。 |
vfp | VoxelVfpSaveOptions | 新建对象 | 可选派生区段覆盖。 |
VoxelVfpSaveOptions
五个字段均为 boolean | undefined：undefined 表示继承导入 VFP 的区段存在策略。
| 字段 | 派生内容 |
|---|---|
includeRuntimeCaches | VBUF/PMSH 快速预览缓存。 |
includeRenderCache | RND0 渲染器扩展缓存。 |
includeAnimationCache | ANM0 载入动画计划。 |
includePreviewGlb | PRVW GLB 预览。 |
includeThumbnail | THMB PNG 缩略图。 |
VoxelSaveFormat 的值为 SOURCE、JSON、VFP。VoxelEditorSaveResult 在成功后提供 uri、fileName、format、byteLength。保存规则和示例见 保存与性能。