VT 建筑文件格式 .vt —— 托管、加密与解密
本文档说明
.vt(Vector Building)建筑文件的容器结构、密钥派生、加密/解密流程与负载编码格式, 以及怎么把普通建筑文件转成.vt和每一层的压缩算法。适用版本:VQ 1.5.1(容器版本
1/ 负载版本1–3)。 对应代码:Services/Vt/VtContainer.cs(容器与加解密)、Services/Vt/VtBuilding.cs(负载编解码VtBuildingCodec)。
1. 这是什么
.vt 是 VQ 托管的建筑文件格式。一个 .vt 文件里装的是一座建筑的方块列表(方块名 + 坐标 + 方块状态 + 命令块/告示牌信息), 外层是一个带版本号、压缩、加密、完整性校验的容器:
- 用记事本 / 文本文档打开
.vt,只会看到二进制乱码,看不到建筑内容; - 文件只能由 VQ(文件模式)解释;被改动过的文件会被 HMAC 校验拦下;
- 由 VQ 在导入
.txt指令文件等建筑格式时自动生成(默认输出到桌面)。
1.1 速查(TL;DR)
| 项 | 值 |
|---|---|
| 魔数 / 容器版本 | ASCII VTVB / 1,固定 44 字节头 |
| 负载版本 | VtBuildingCodec v3(v1 只有方块表,v2 追加命令块 / 告示牌字段,v3 给命令块加了「延迟」;解码器向下兼容 v1/v2) |
| 压缩 | 明文负载 → Deflate(raw,无 zlib / gzip 头),CompressionLevel.Optimal |
| 加密 | AES-256-CBC + PKCS7,每次保存随机 IV |
| 完整性 | HMAC-SHA256(IV ‖ LE32(len) ‖ 密文) 取前 16 字节 |
| 密钥 | PBKDF2-HMAC-SHA256(内置材料, 固定盐, 4096 轮, 32 B) → 加密密钥;SHA256(enc ‖ "mac") → MAC 密钥 |
| 实测体积 | 1,306,576 方块:负载 8,594,894 B → .vt 3,245,068 B(Deflate 省 62.2%) |
| 谁生成 | VQ 文件模式:导入 .txt / .schem / .schematic / .mcstructure / .bdx 时自动生成,默认输出桌面 |
| 读取端 | VQ(C#,VtContainer)与 VtImporter 插件(纯 Python,vtformat.py,用 zlib.decompress(data, -15) 解 raw Deflate) |
2. 文件布局
所有整数均为小端(.NET BinaryWriter 默认),字符串为 UTF-8。
| 偏移 | 长度 | 内容 |
|---|---|---|
| 0 | 4 | 魔数,ASCII VTVB |
| 4 | 2 | uint16 版本号,当前 1 |
| 6 | 2 | uint16 标志位:bit0 = 已加密(AES-256-CBC)、bit1 = 已压缩(Deflate),当前恒为 3 |
| 8 | 16 | 随机 IV(每次保存都重新生成) |
| 24 | 16 | HMAC-SHA256 截断校验码(取前 16 字节) |
| 40 | 4 | uint32 密文长度(字节) |
| 44 | … | 密文(= Deflate 负载经 AES-256-CBC/PKCS7 加密后的数据) |
固定头长度 44 字节。密文长度不匹配时按「文件被截断」处理。 容器版本号(第 2 节)与负载版本号(第 6 节)是两个独立的版本位,可以各自升级。
3. 密钥派生
密钥不写在文件里,由程序内置材料派生:
SecretMaterial = UTF8("VQ-Vector-Building-Format|v1|9f2a31c7d84b06e5|ntvector|lurete-cn")
Salt = UTF8("VQVT$1$2026$building$container")
EncKey = PBKDF2-HMAC-SHA256(SecretMaterial, Salt, iterations = 4096, dkLen = 32) // 32 字节 = AES-256
MacKey = SHA256(EncKey || UTF8("mac")) // 32 字节 = HMAC-SHA256SecretMaterial 里的 |v1| 是格式/密钥版本位:将来换材料时递增版本号,旧文件仍可按旧材料打开。 代码位置:VtContainer.cs → internal static class VtCrypto.DeriveKeys()。
4. 写入(加密)流程 —— VtContainer.Save(path, building)
VtBuildingCodec.Encode(building)→ 明文负载P(见第 6 节);Deflate(P)(CompressionLevel.Optimal)→C0;RandomNumberGenerator.GetBytes(16)→ 随机IV;- AES-256-CBC + PKCS7,
Key = EncKey,IV = IV,加密C0→ 密文C1; MAC = HMAC-SHA256(MacKey, IV || LE32(len(C1)) || C1),取前 16 字节;- 按第 2 节布局写出:
"VTVB" | 1 | 3 | IV | MAC | len(C1) | C1。
5. 读取(解密)流程 —— VtContainer.Load(path)
- 读 4 字节魔数,不是
VTVB→ 抛「不是有效的 .vt 建筑文件(魔数不匹配)」; - 读版本号,不等于 1 → 抛「不支持的 .vt 版本:N」;
- 读标志位、
IV、MAC、长度、密文;密文实际长度与声明不符 → 抛「.vt 文件被截断」; - 用同样的派生密钥重算 HMAC,
CryptographicOperations.FixedTimeEquals比较前 16 字节; 不一致 → 抛「.vt 校验失败:文件损坏或不是由本程序生成」; - AES-256-CBC + PKCS7 解密 →
C0; - 若标志位 bit1 置位,
Inflate(C0)→P; VtBuildingCodec.Decode(P)→VtBuilding(方块列表 + 包围盒尺寸 + 名称 + 命令块/告示牌信息)。
6. 负载(明文)二进制格式 —— VtBuildingCodec v3
当前 CodecVersion = 3。v1 只有方块表,v2 追加了命令块与告示牌的详细信息,v3 给命令块加了「延迟」(刻);解码器同时支持 1、2、3。
6.1 公共部分(v1 起)
int32 CodecVersion = 3
int32 nameLen + UTF8 建筑名
int32 fmtLen + UTF8 来源格式("txt" / "schem" / "schematic" / "vt")
int32 SizeX, SizeY, SizeZ // 归一化后的包围盒尺寸
int32 blockCount // 方块数量
int32 nameCount + nameCount × ( uint16 字节长 + UTF8 方块名 )
int32 stateCount + stateCount × ( uint16 字节长 + UTF8 状态串 ) // 索引 0 恒为空串
blockCount × 5 个 varint:nameIndex, zigzag(X), zigzag(Y), zigzag(Z), stateIndex6.2 v2 起:命令块 / 告示牌信息(v3 增补「延迟」)
int32 metaCount
metaCount × :
varint slot // 该方块在方块表里的下标(0 起,与渲染/点选共用同一张表)
byte flags // bit0 = 命令块,bit1 = 告示牌
flags 含 bit0(命令块)时依次写:
string Command // 命令文本
string CommandMode // impulse / chain / repeat
byte CommandConditional // 条件制约
byte CommandAuto // 自动执行(不需要红石)
byte CommandPowered // 需要红石
byte CommandTrackOutput // 记录输出
string CustomName // 自定义名字(JSON 文本)
varint CommandTickDelay // v3 起:命令块「延迟」(刻),写在 CustomName 之后
flags 含 bit1(告示牌)时依次写:
lines SignLines // 正面 4 行
lines SignLinesBack // 背面 4 行
string SignColor // 颜色(black / dark_blue / …)
byte SignGlowing // 文字发光
byte SignWaxed // 打过蜡(游戏里不能再改)string=int32 字节长 + UTF8;lines=int32 行数 + 每行一个 string;byte只有 0/1;- 这些信息与方块一起被加密进
.vt;打开.vt后点击命令块/告示牌即可查看与修改(见第 10 节)。
6.3 编码细节
- varint = LEB128(每字节低 7 位有效,最高位表示「还有后续字节」,低位在前,最多 5 字节);
- 坐标用 zigzag 编码:
zigzag(v) = (v << 1) ^ (v >> 31),解码(v >> 1) ^ -(v & 1); - 方块名与状态串都走字符串表,重复出现的(例如砂岩的
["sand_stone_type"="default"])只存一次; - 坐标在
VtBuilding.Normalize()里平移到最小角为(0,0,0)。
7. 安全性说明(请按「托管 + 混淆 + 完整性」理解,不要当成强加密)
- 内置材料写在程序里,知道算法和材料的人可以解出内容。它保证的是:
- 文本编辑器直接打开
.vt看不到内容(不是可读的纯文本格式); - 文件必须由 VQ 解释,其它程序不知道结构;
- 文件被人改过(哪怕 1 个字节)时会被 HMAC 拦下,VQ 提示「文件损坏或不是由本程序生成」。
- 文本编辑器直接打开
- 它不保证对逆向者的机密性。若将来需要真正的机密性,可选的升级路线:
- 每个文件独立随机密钥,密钥用用户口令或 VQ 账号派生(PBKDF2/Argon2 + 用户盐);
- 服务器签发密钥/许可证,
.vt只在授权账号下解开; - 保留
SecretMaterial的|v1|版本位与容器/负载版本号,便于新旧格式并存。
8. 能导入哪些建筑格式
| 格式 | 说明 |
|---|---|
.txt / .mcfunction | 指令文本:逐行 setblock x y z 方块 [状态] 与 fill x1 y1 z1 x2 y2 z2 方块 [状态],支持 ~ 相对坐标;tellraw / # / // 开头与空行跳过 |
.schem | Sponge v3(WorldEdit 7.x):Blocks.Palette(compound 列表) + Blocks.Data(varint 调色板索引) + Blocks.BlockEntities |
.schematic | MCEdit / WorldEdit 旧版:数字 ID Blocks + 4bit Data + 可选 AddBlocks + TileEntities |
.vt | VQ 自己的加密建筑文件(直接解密读回) |
.mcstructure | 基岩版结构:小端 NBT,size[x,y,z] + palette.default.block_palette + block_indices[0] + block_position_data(命令块 / 告示牌信息在 block_entity_data 里),见 8.2 |
.bdx | 基岩版 BDX 建筑(TriM 的 BDXConverter 格式):BD@ + Brotli 压缩的操作流,见 8.1 |
8.1 .bdx 是怎么读的
- 容器:文件 =
BD@(3 字节) +brotli.compress(内层);内层 =BDX+0x00+ 作者名(UTF-8,\0结尾) + 操作序列 +(未签名时)XE; - 操作流是「游标 + 放置方块」的指令序列(见
Services/Vt/BdxBuildingImporter.cs):CreateConstantString往常量池塞方块名 / 状态串,AddX/Y/ZValue(±1)与AddInt8/16/32XValue移动游标,PlaceBlockWithBlockStates(名字索引, 状态索引)放下方块,PlaceBlockWithNBTData额外带一段小端 NBT (命令块 / 告示牌的id、Command、LPCommandMode、FrontText… 都在这里); - 端序坑:BDX 的操作载荷是大端,而它内嵌的 NBT 是小端,两边不能混;
- 状态串就是基岩命令语法(如
["stone_type"="spruce"]),直接交给贴图库的基岩别名 / 数据值换算; - runtime ID 类操作(
UseRuntimeIDPool/PlaceRuntimeBlock…)目前只计数并忽略:实测见到的 BDX 里 runtime 操作为 0。
8.2 .mcstructure 是怎么读的
文件本体是未压缩的小端 NBT(也可能被 gzip / zlib 包一层,
NbtReader会自动识别);结构既可能直接在根上,也可能在
structure子标签下(新旧两代写法都兼容);size = [x, y, z],方块索引数组block_indices[0]的换算是index = (x * sizeZ + z) * sizeY + y(y 变化最快);每个下标查
palette.default.block_palette[index]得到{name, states};block_position_data的键既可能是"x,y,z",也可能是一个扁平下标(例如"13"),两种都支持; 其中的block_entity_data用与 BDX 同一套基岩字段解析命令块 / 告示牌(BedrockMeta)。基岩版旧式数据值也认:
setblock ~ ~ ~ planks 1里的1会换算成spruce_planks等 Java 名,贴图才对得上;贴图全部来自本机 Minecraft 客户端 jar(自动找
%APPDATA%\.minecraft\versions等目录里版本最高的那个), 找不到的方块用按名字生成的彩色占位格,保证预览不出现空洞;贴图包固定放在程序目录(
VQ.exe旁边的img\):已经有了就直接用,不会重复下载;建筑文件自己旁边那个img\不再使用;保护上限:一次导入最多 6,000,000 个方块、NBT 里单个数组最多 200 MB(超限会给出明确提示,而不是让 VQ 卡死或爆内存);
超过上限也照样出
.vt:文件模式会提示「太大,不能预览」,然后自动改用「只转不预览」再导入一次(解除上限), 把建筑转成同名.vt存到桌面 —— 预览不了,但.vt一定给出来。
9. 相关文件(代码位置)
以下是 VQ 仓库里的相对路径(仓库根 = VQ.csproj 所在目录):
| 作用 | 路径 |
|---|---|
| 容器、密钥派生、AES/HMAC/Deflate | Services/Vt/VtContainer.cs |
方块模型 + 负载编解码 VtBuildingCodec | Services/Vt/VtBuilding.cs |
| NBT(gzip / zlib / 未压缩)读取 | Services/Vt/NbtReader.cs |
指令文本 / .vt 导入(setblock、fill) | Services/Vt/TxtBuildingImporter.cs |
结构文件(.schem v1/v2/v3、.schematic)解析 | Services/Vt/NbtStructureImporter.cs |
基岩 .mcstructure 解析 | Services/Vt/McStructureImporter.cs |
基岩 .bdx(BD@ + Brotli + 操作流)解析 | Services/Vt/BdxBuildingImporter.cs |
| 基岩命令块 / 告示牌字段共用解析 | Services/Vt/BedrockMeta.cs |
| 本机客户端 jar 贴图库(blockstates/models + 基岩别名与数据值) | Services/Vt/McTextureLibrary.cs |
| 贴图包下载 / 固定程序目录 | Services/Vt/TexturePack.cs |
| 等轴测建筑渲染 / 点选命中测试 | Services/Vt/IsoBuildingRenderer.cs |
| 三维预览场景(网格化、点选高亮) | Services/Vt/Vt3DScene.cs |
文件模式窗口(左上角「选择文件」→ 桌面生成 .vt、Ctrl 旋转、点方块改信息) | Views/VtFileWindow.xaml(.cs) |
| 无界面自测入口 | Services/Vt/VtHeadless.cs |
.vt 扩展名关联 / 图标 / 单实例转发 | Services/VtFile.cs、VtSingleInstance.cs |
10. 文件模式(预览窗口)怎么用
- 双击
.vt(或把文件拖到 VQ 上)→ 自动进入文件模式,中间是建筑预览,白底; - 左上角 「选择文件」:选
.txt/.schem/.schematic/.mcstructure/.bdx/.vt→ 自动导入并在桌面生成同名的.vt; - 鼠标:拖动 = 平移;滚轮 = 缩放;Ctrl + 拖动 = 整体旋转(任意角度,0–360°);
- 点击方块 = 右侧弹出信息面板:
- 命令块 → 显示/修改命令文本、模式(脉冲/连锁/循环)、条件制约、自动执行、需要红石、记录输出、自定义名字;
- 告示牌 → 显示/修改正面与背面 4 行文字、颜色、文字发光、打蜡;
- 改完点「应用修改」,标题栏出现
*表示有未保存改动,再点「保存.vt」写回文件;
- 底栏还能左右旋转 15°、放大缩小、适应窗口,以及「打开 VQ 主界面」。
11. 怎么验证
# 导入建筑文件 → 同时生成预览 PNG 与 .vt(无界面,方便自动化检查)
& '.\VQ.exe' --vt-render `
"$env:USERPROFILE\Desktop\a.schem" `
'.\out\check.png' --size 1100x820 --rot 35 --vt '.\out\check.vt'
# 日志(与 PNG 同目录,同名 + .log)里应能看到:
# 读回 .vt: … | 一致=True (写出的 .vt 再读回来与内存中的建筑完全相同)
# 元数据往返: 命令块/告示牌 N 条 → 读回 N 条 | 指纹一致=True
# 头部可读 ASCII: False (文本文档打开不是可读内容)
Get-Content '.\out\check.png.log'- 用记事本打开
check.vt:二进制乱码(第 1 行只有VTVB可辨认); - 把文件里任意 1 个字节改成别的值再用 VQ 打开 → 提示「.vt 校验失败:文件损坏或不是由本程序生成」;
- 文件模式窗口里「选择文件」导入
.txt后,桌面会出现同名的.vt,内容与预览一致; - 结构文件里的命令块/告示牌:导入后在文件模式里点击对应方块,能看到与结构文件里一致的指令与文字。
12. 怎么把普通文件转成 .vt
「普通文件」指 .txt / .schem / .schematic / .mcstructure / .bdx 这类建筑文件。转换由 VQ 文件模式完成(不需要游戏、不需要登录)。
12.1 图形界面(最常用)
- 打开 VQ → 进入文件模式:双击任意
.vt、把建筑文件拖到 VQ 窗口上,或在主界面点「文件模式」; - 点左上角 「选择文件」,选要转换的建筑文件(
.txt/.schem/.schematic/.mcstructure/.bdx/.vt); - 导入完成后 桌面上会出现同名的
.vt(默认输出位置),窗口里同时显示三维预览; - 需要在别处保存时点「保存
.vt」另存;改过命令块 / 告示牌后标题栏出现*,再点「保存.vt」写回。
- 文件太大(超过 600 万方块 / 单个 NBT 数组 200 MB)时先提示「太大,不能预览」,随后自动改用「只转不预览」再导入一次,
.vt照样生成,只是没有预览; - 转换失败不会写半个文件:损坏 / 被截断的源文件会直接报错(见第 8 节各格式的解析说明)。
12.2 命令行(无界面,可批量 / 可脚本化)
# 单个文件:导入 + 生成预览 PNG + 写出 .vt
& '.\VQ.exe' --vt-render '.\建筑\a.schem' '.\out\a.png' --size 800x600 --rot 35 --vt '.\out\a.vt'
# 批量:把一个目录里能认的建筑文件全部转成 .vt
$in = "$env:USERPROFILE\Desktop\建筑"
$out = "$env:USERPROFILE\Desktop\vt-out"
New-Item -ItemType Directory -Force -Path $out | Out-Null
Get-ChildItem $in -File | Where-Object { $_.Extension -in '.txt','.schem','.schematic','.mcstructure','.bdx' } | ForEach-Object {
& '.\VQ.exe' --vt-render $_.FullName (Join-Path $out ($_.BaseName + '.png')) `
--size 200x200 --vt (Join-Path $out ($_.BaseName + '.vt'))
}--vt-render一定同时产出 PNG(--vt只是额外再写.vt);不需要图时可以把 PNG 写到临时目录;- 真正的日志在 PNG 同名 +
.log里(VQ 不往 stdout 写日志),关键行是读回 .vt: … | 一致=True与元数据往返: … 指纹一致=True; - 参数全集见
Services/Vt/VtHeadless.cs:--size WxH、--rot <角度>、--zoom <倍数>、--pitch、--pan x,y、--vt3d、--select <下标>、--img <贴图目录>、--pack <贴图包.zip>、--ensure-pack、--export-textures <out.zip>、--bench。
12.3 跟「插件导入」的区别(别搞混)
| 场景 | 做什么 | 产出 |
|---|---|---|
| VQ 文件模式 / 命令行 | 把普通建筑文件转成 .vt | 桌面(或 --vt 指定位置)的 .vt 文件 |
| VtImporter 插件(游戏内) | .vt run <路径> 把 .vt 摆进游戏(/fill + 命令块 + 告示牌) | 游戏里的建筑;不产出文件 |
VtImporter 插件遇到 .txt | 逐行原样发送文件里的指令,不做解析、不转 .vt(这样最快,1999 条/秒) | 游戏里直接生效 |
13. 压缩算法(每一层都在压什么)
| 层 | 算法 | 参数 / 代码 |
|---|---|---|
.vt 负载(明文 → 压缩) | raw Deflate(无 zlib / gzip 头) | VtContainer.cs:172 new DeflateStream(ms, CompressionLevel.Optimal, leaveOpen: true) |
.vt 密文(压缩 → 加密) | AES-256-CBC + PKCS7,随机 16 B IV(每次保存都换) | VtContainer.cs:70-91 |
.vt 完整性 | HMAC-SHA256(IV ‖ LE32(len) ‖ 密文),取前 16 字节 | VtContainer.cs:83-91(读侧 :134-142) |
| 密钥派生 | PBKDF2-HMAC-SHA256(内置材料, 固定盐, 4096 轮, 32 B);MAC 密钥 = SHA256(encKey ‖ "mac") | VtContainer.cs:201-202 |
.schem(Sponge v3) | 通常 gzip 包着的 NBT(也可能是未压缩 NBT) | NbtStructureImporter.cs + NbtReader.cs:39 |
.schematic(MCEdit) | 同上:gzip + NBT | NbtStructureImporter.cs + NbtReader.cs:39 |
.mcstructure(基岩) | 未压缩 / gzip / zlib 三种都可能,读取端按魔数自动识别 | NbtReader.cs:39(gzip)、:44(zlib) |
.bdx(基岩 BDX) | 文件 = BD@ + Brotli(操作流),操作载荷大端、内嵌 NBT 小端 | BdxBuildingImporter.cs:30-35 |
插件侧读取 .vt | 纯 Python zlib raw deflate:zlib.decompress(plain, -15) | VtImporter/vtformat.py:153 |
发布整包 package.zip | Deflate(Compress-Archive) | installer/build_package.ps1 |
安装程序 VQsetup.exe | LZMA2 + SolidCompression | installer/VQsetup.iss |
贴图包 vq-textures.zip | zip(Deflate) | Services/Vt/TexturePack.cs |
实测 Deflate 效果(VtContainer 明文负载 → 压缩后;容器 = 44 B 头 + 密文):
| 建筑 | 方块数 | 明文负载 | .vt 文件 | 压缩率 |
|---|---|---|---|---|
大型结构(skull.vt) | 1,306,576 | 8,594,894 B | 3,245,068 B | 62.2%(2.65 : 1) |
| 中型结构(21,915 方块) | 21,915 | 127,596 B | 67,436 B | 47.1%(1.89 : 1) |
小型结构(抽奖.vt) | 899 | 23,287 B | 5,724 B | 75.4%(4.07 : 1) |
两个必须记住的坑:
.NET的DeflateStream输出的是 raw deflate,没有 zlib / gzip 头 —— Python 侧必须wbits = -15,用zlib.decompress(data)(默认+15有 zlib 头)会直接抛zlib.error: incorrect header check;- 密文长度 = 压缩数据向上取整到 16 字节(PKCS7 填充),所以
.vt文件大小 = 44 + 16 × ⌈压缩长度 / 16⌉,别拿它反推明文长度。
