Save-Game File Format

Overview

The current format version is 23. Versions 22 and 23 load directly; migration and full saves always write version 23. Games can be saved through scripting or the console command /save.

The format uses binary files with RLE compression for chunk data and Deflate compression for custom data sections.

File Structure

The format supports two layouts, selected by the Save Mode setting:

• Multi-File Regions: a main file (header data and region file names), one region file per 256x256 area (chunk and voxel data) and an optional extra data file. Only affected region files update when world contents change; region files load on demand.
• Single File: header, region payload and extra data sections concatenated in one file.

Header Data Structure

• Format number (1 byte)
• Chunk size specification (1 byte)
• Character controller position (X, Y, Z as floats)
• Controller rotation angles (3 floats)
• Camera rotation angles (3 floats)
• Stage number (Int16)
• Region IDs (variable-length string)

Region Data Format

Region files contain:

• Voxel definition count and names
• Item definition count and names
• Chunk count
• Per-chunk data: position, generation status, timestamps, and voxel data
• Light sources with position and attachment info
• Items with positions, quantities and (version 23) per-item custom properties
• Custom voxel data
• Microvoxel occupancy masks
• GameObjects with VoxelPlaySaveThis component
• Custom prefab data including transform and rotation values

Extra Data File Format

Contains custom data sections with key-value pairs where data is compressed using Deflate algorithm.