CubicChunk 存储格式
基本信息
| 属性 | 值 |
|---|---|
| 格式 ID | cubicchunks:anvil3d |
| 主存储实现 | com.cardinalstar.cubicchunks.server.chunkio.RegionCubeStorage（implements ICubicStorage） |
| 区域文件 | com.cardinalstar.cubicchunks.world.storage.CubicRegionFile |
| 影子分页实现 | com.cardinalstar.cubicchunks.server.chunkio.region.ShadowPagingRegion<K> |
| 区块加载器 | CubicAnvilChunkLoader、CubeLoaderServer |
| 批量 NBT I/O | NBTBatch（readBatch / writeBatch） |
| 影子分页开关 | use_shadow_paging_io，默认 true |
功能
立方世界的数据不能塞进原版的 region 文件（它只按 XZ 索引区块），因此本移植实现了独立的立方体存储层。
RegionCubeStorage（server/chunkio/RegionCubeStorage.java:65，implements ICubicStorage）提供成对的读写方法：
| 操作 | 方法 | 行 |
|---|---|---|
| 列存在性 | columnExists(ChunkCoordIntPair) |
:133 |
| 立方体存在性 | cubeExists(CubePos) |
:139 |
| 读列 | readColumn(ChunkCoordIntPair) → NBTTagCompound |
:145 |
| 读立方体 | readCube(CubePos) → NBTTagCompound |
:158 |
| 批量读 | readBatch(PosBatch) → NBTBatch |
:169 |
| 写列 | writeColumn(ChunkCoordIntPair, NBTTagCompound) |
:220 |
| 写立方体 | writeCube(CubePos, NBTTagCompound) |
:234 |
| 批量写 | writeBatch(NBTBatch) |
:248 |
| 遍历列 | forEachColumn(Consumer<ChunkCoordIntPair>) |
:300 |
| 遍历立方体 | forEachCube(Consumer<CubePos>) |
:306 |
构造器只接受一个 Path（:127）——存档目录由格式工厂解析（见 存储格式 SPI）。
影子分页
ShadowPagingRegion（server/chunkio/region/ShadowPagingRegion.java:68，implements IRegion<K>）的类注释说明它是"简化版 Region，用自定义扇区跟踪器实现影子分页"（:65-66），内部含 Builder<K>（:541）与私有 SectorTracker<K>（:587）。
RegionCubeStorage 在构造时读取配置开关决定走哪条路径（server/chunkio/RegionCubeStorage.java:68）：
if (CubicChunksConfig.useShadowPagingIO) { ... }
该配置默认 true（CubicChunksConfig.java:139），注释解释其取舍：“可能略慢并占用更多存储，但能显著提高非正常关闭时的可靠性”（:136-137），且带 @Config.RequiresWorldRestart（:138）。
配套的 I/O 抽象在 server/chunkio/：ICubeIO、ICubeLoader、IONbtReader、IONbtWriter、CubeIO、CubeLoaderServer、CubeLoaderCallback、CubeInitLevel、CCNBTUtils、IPreloadFailureDelegate、LoadFailureException。
world/storage/ 另有 IStorageFormat、Storage2d、Storage3d、RegionHeader，用于列/立方体两级存储抽象。
数值
| 数值名 | 值 | 来源 |
|---|---|---|
| 格式 ID | cubicchunks:anvil3d |
StorageFormatFactory.java:37 |
use_shadow_paging_io 默认 |
true |
CubicChunksConfig.java:139 |
storage_format 默认 |
""（自动判定） |
CubicChunksConfig.java:102 |
readBatch 返回类型 |
NBTBatch（批量） |
RegionCubeStorage.java:169 |
| 影子分页需重启世界 | 是 | CubicChunksConfig.java:138 |
交互
| 触发 | 行为 |
|---|---|
| 首次进入新世界 | 按 storage_format 选定格式，默认为 cubicchunks:anvil3d |
| 立方体加载 / 卸载 | 走 readCube / writeCube |
| 大批量存档 | 走 readBatch / writeBatch 降低 NBT 调用开销 |
| 服务器被强杀 | 开启影子分页时以额外空间换取写入可靠性 |
| 已有世界 | 沿用创建时的格式，不受改配置影响 |