Skip to content

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。

偏移长度内容
04魔数,ASCII VTVB
42uint16 版本号,当前 1
62uint16 标志位:bit0 = 已加密(AES-256-CBC)、bit1 = 已压缩(Deflate),当前恒为 3
816随机 IV(每次保存都重新生成)
2416HMAC-SHA256 截断校验码(取前 16 字节)
404uint32 密文长度(字节)
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-SHA256

SecretMaterial 里的 |v1| 是格式/密钥版本位:将来换材料时递增版本号,旧文件仍可按旧材料打开。 代码位置:VtContainer.cs → internal static class VtCrypto.DeriveKeys()。

4. 写入(加密)流程 —— VtContainer.Save(path, building) ​

  1. VtBuildingCodec.Encode(building) → 明文负载 P(见第 6 节);
  2. Deflate(P)(CompressionLevel.Optimal)→ C0;
  3. RandomNumberGenerator.GetBytes(16) → 随机 IV;
  4. AES-256-CBC + PKCS7,Key = EncKey,IV = IV,加密 C0 → 密文 C1;
  5. MAC = HMAC-SHA256(MacKey, IV || LE32(len(C1)) || C1),取前 16 字节;
  6. 按第 2 节布局写出:"VTVB" | 1 | 3 | IV | MAC | len(C1) | C1。

5. 读取(解密)流程 —— VtContainer.Load(path) ​

  1. 读 4 字节魔数,不是 VTVB → 抛「不是有效的 .vt 建筑文件(魔数不匹配)」;
  2. 读版本号,不等于 1 → 抛「不支持的 .vt 版本:N」;
  3. 读标志位、IV、MAC、长度、密文;密文实际长度与声明不符 → 抛「.vt 文件被截断」;
  4. 用同样的派生密钥重算 HMAC,CryptographicOperations.FixedTimeEquals 比较前 16 字节; 不一致 → 抛「.vt 校验失败:文件损坏或不是由本程序生成」;
  5. AES-256-CBC + PKCS7 解密 → C0;
  6. 若标志位 bit1 置位,Inflate(C0) → P;
  7. 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), stateIndex

6.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 提示「文件损坏或不是由本程序生成」。
  • 它不保证对逆向者的机密性。若将来需要真正的机密性,可选的升级路线:
    1. 每个文件独立随机密钥,密钥用用户口令或 VQ 账号派生(PBKDF2/Argon2 + 用户盐);
    2. 服务器签发密钥/许可证,.vt 只在授权账号下解开;
    3. 保留 SecretMaterial 的 |v1| 版本位与容器/负载版本号,便于新旧格式并存。

8. 能导入哪些建筑格式 ​

格式说明
.txt / .mcfunction指令文本:逐行 setblock x y z 方块 [状态] 与 fill x1 y1 z1 x2 y2 z2 方块 [状态],支持 ~ 相对坐标;tellraw / # / // 开头与空行跳过
.schemSponge v3(WorldEdit 7.x):Blocks.Palette(compound 列表) + Blocks.Data(varint 调色板索引) + Blocks.BlockEntities
.schematicMCEdit / WorldEdit 旧版:数字 ID Blocks + 4bit Data + 可选 AddBlocks + TileEntities
.vtVQ 自己的加密建筑文件(直接解密读回)
.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/DeflateServices/Vt/VtContainer.cs
方块模型 + 负载编解码 VtBuildingCodecServices/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. 怎么验证 ​

powershell
# 导入建筑文件 → 同时生成预览 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 图形界面(最常用) ​

  1. 打开 VQ → 进入文件模式:双击任意 .vt、把建筑文件拖到 VQ 窗口上,或在主界面点「文件模式」;
  2. 点左上角 「选择文件」,选要转换的建筑文件(.txt / .schem / .schematic / .mcstructure / .bdx / .vt);
  3. 导入完成后 桌面上会出现同名的 .vt(默认输出位置),窗口里同时显示三维预览;
  4. 需要在别处保存时点「保存 .vt」另存;改过命令块 / 告示牌后标题栏出现 *,再点「保存 .vt」写回。
  • 文件太大(超过 600 万方块 / 单个 NBT 数组 200 MB)时先提示「太大,不能预览」,随后自动改用「只转不预览」再导入一次,.vt 照样生成,只是没有预览;
  • 转换失败不会写半个文件:损坏 / 被截断的源文件会直接报错(见第 8 节各格式的解析说明)。

12.2 命令行(无界面,可批量 / 可脚本化) ​

powershell
# 单个文件:导入 + 生成预览 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 + NBTNbtStructureImporter.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.zipDeflate(Compress-Archive)installer/build_package.ps1
安装程序 VQsetup.exeLZMA2 + SolidCompressioninstaller/VQsetup.iss
贴图包 vq-textures.zipzip(Deflate)Services/Vt/TexturePack.cs

实测 Deflate 效果(VtContainer 明文负载 → 压缩后;容器 = 44 B 头 + 密文):

建筑方块数明文负载.vt 文件压缩率
大型结构(skull.vt)1,306,5768,594,894 B3,245,068 B62.2%(2.65 : 1)
中型结构(21,915 方块)21,915127,596 B67,436 B47.1%(1.89 : 1)
小型结构(抽奖.vt)89923,287 B5,724 B75.4%(4.07 : 1)

两个必须记住的坑:

  1. .NET 的 DeflateStream 输出的是 raw deflate,没有 zlib / gzip 头 —— Python 侧必须 wbits = -15,用 zlib.decompress(data)(默认 +15 有 zlib 头)会直接抛 zlib.error: incorrect header check;
  2. 密文长度 = 压缩数据向上取整到 16 字节(PKCS7 填充),所以 .vt 文件大小 = 44 + 16 × ⌈压缩长度 / 16⌉,别拿它反推明文长度。

第三方库请参阅各自目录下的许可证文件