蓝图格式

基本信息

属性 值
抽象基类 com.github.lunatrius.schematica.world.schematic.SchematicFormat
已注册格式数 2（Alpha、Litematica）
默认格式 FORMAT_DEFAULT = Names.NBT.FORMAT_ALPHA = "Alpha"（world/schematic/SchematicFormat.java:107）
注册表 static final Map<String, SchematicFormat> FORMATS（world/schematic/SchematicFormat.java:20）
格式标识键 NBT 根节点下的 Materials 字段（reference/Names.java:245、:246-247）
压缩写出 CompressedStreamTools.writeCompressed(tag, FileOutputStream)（world/schematic/SchematicFormat.java:89）

注册表在静态块中填充（world/schematic/SchematicFormat.java:103-108）：

FORMATS.put(Names.NBT.FORMAT_ALPHA, new SchematicAlpha());
FORMATS.put("Litematica", new SchematicLitematica());
FORMAT_DEFAULT = Names.NBT.FORMAT_ALPHA;

⚠️ Names.NBT.FORMAT_CLASSIC = "Classic"（reference/Names.java:246）是死常量——全仓库只有这一处声明，FORMATS 中没有注册任何 Classic 格式实现。读入 Materials 为 Classic 的旧版蓝图会在 SchematicFormat.readFromFile 抛 UnsupportedFormatException（:59-61）。

功能

读取分派

SchematicFormat.readFromFile(File)（world/schematic/SchematicFormat.java:32-69）按文件后缀分派：

  1. 文件名小写后以 .litematic 结尾 → 走 LitematicaNBTReader.readFromFile 自定义解析器，交给 FORMATS.get("Litematica")（:35-52）。自定义解析器用于处理 TAG_Long_Array（1.7.10 NBT 无此类型，:34 注释），读完后调 clearLongArrayStore() 释放旁路存储（:45、:48）。
  2. 其余 → 走标准 SchematicUtil.readTagCompoundFromFile，读根节点 Materials 字符串查表（:54-57）。查不到则抛 UnsupportedFormatException（:59-61）。

writeToFile 在序列化前向 MinecraftForge.EVENT_BUS 投递 PostSchematicCaptureEvent（:77-78），写完用 FORMAT_DEFAULT 对应的实现（:82-83）。

Alpha 格式

com.github.lunatrius.schematica.world.schematic.SchematicAlpha（:32）是本仓库自有的扩展 ID 格式，读与写各有两套分支。

写出时写入的 NBT 字段（world/schematic/SchematicAlpha.java:195-197、:281-284 与 :300-302、:393-397）：

字段 类型 含义
Materials String 固定写 Names.NBT.FORMAT_ALPHA = "Alpha"（:281、:393）
Width / Length / Height short 三轴尺寸（:195-197、:300-302）
Blocks byte[] 方块 ID
Data byte[] 元数据
AddBlocks / Add byte[] 超出 byte 范围的扩展方块 ID（Names.NBT.BLOCKS / ADD_BLOCKS / ADD_BLOCKS_SCHEMATICA，reference/Names.java:250,252,253）
SchematicaMapping NBTTagCompound 旧 ID → 新 ID 映射（Names.NBT.MAPPING_SCHEMATICA，reference/Names.java:258；写出见 :273-278、:385-390）

其他 NBT 键定义在 Names.NBT（reference/Names.java:241-262）：Schematic（根）、Icon、TileEntities、Entities、ExtendedMetadata、Materials、Format 相关、以及 MAPPING = "..."（带 // TODO: use this once MCEdit adds support for it 注释，:257）。

读入时若 useSchematicplusFormat 为 true，走扩展 ID 分支，并从 SchematicaMapping 复合标签重建 oldToNew 映射（world/schematic/SchematicAlpha.java:38-57）。

写出前投递 PreSchematicSaveEvent（world/schematic/SchematicAlpha.java:273、:385），其携带 extendedMetadata 与 replaceMapping 方法（api/event/PreSchematicSaveEvent.java:27,53）供其他 mod 改写映射。

SchematicFormat.saveNBT（默认 true）与 saveEntities（默认 false）控制 TileEntity NBT 与实体的保存（world/schematic/SchematicFormat.java:24-26）。

Litematica 格式

com.github.lunatrius.schematica.world.schematic.SchematicLitematica（:31）只读不写：writeToNBT 直接打 warn 日志 "Writing .litematic format is not supported." 并返回 false（world/schematic/SchematicLitematica.java:44-47）。

这是本仓库自身实现的 1.7.10 端 .litematic 解析器，不是 Litematica mod 的 API 集成——它不依赖 Litematica mod 加载，直接按 .litematic 的 NBT 结构解析：Version、Metadata、Regions 三个根字段（world/schematic/SchematicLitematica.java:50-54），Regions 为空则报 "No regions found in .litematic file!" 并返回 null（:56-59）。

每个 region 读 Position 与 Size 复合标签（:72-77），并用 globalMinX/Y/Z、globalMaxX/Y/Z 六个变量做全图包围盒归一（:67-70）。

读取依赖 compat/ 包的翻译层：BlockStateTranslator / EntityTranslator / TileEntityTranslator / BlockMapping（world/schematic/SchematicLitematica.java:22-25），见 API 与兼容。

⚠️ 跨版本内容隔离说明：.litematic 是 Minecraft 1.13+ 时代的存档格式，Litematica 是 1.21 mod。本仓库不依赖 Litematica mod，仅自行实现其文件格式的读取器；本条目不涉及仓库外 Litematica mod 的任何行为。

数值

数值名 值 来源
已注册格式数 2 world/schematic/SchematicFormat.java:104-105
默认格式 Alpha world/schematic/SchematicFormat.java:107
.litematic 可写 否（writeToNBT 返回 false） world/schematic/SchematicLitematica.java:44-47
saveNBT 默认 true world/schematic/SchematicFormat.java:24
saveEntities 默认 false world/schematic/SchematicFormat.java:26
死格式常量 Classic reference/Names.java:246（无注册）

保存时的三轴尺寸在 CommonProxy.saveSchematic 中各取 short（proxy/CommonProxy.java:224-226）。

交互

保存失败时 writeToNBT 抛异常会被 writeToFile 捕获并打 error 日志返回 false（world/schematic/SchematicFormat.java:92-95）。

保存过程中若某个 TileEntity 的 NBT 转换失败，copyChunkToSchematic 会把该方块替换为 Blocks.bedrock（proxy/CommonProxy.java:173-176）而非跳过，且无聊天提示（仅 log error）。

实体转换失败则只记 error 并跳过该实体（proxy/CommonProxy.java:197-198）。

保存时优先从服务端世界取 TileEntity 以获得完整 NBT（库存等），拿不到才回退客户端世界（proxy/CommonProxy.java:120-133、:162-166）。

相关条目

  • 配置项 - useSchematicplusFormat 切换 Alpha 的扩展 ID 分支
  • 指令 - /schematicaSave 与 /schematicaDownload 的文件名后缀行为
  • 网络封包 - /schematicaDownload 推送的是内存中的 ISchematic，与磁盘格式无关