Save-game file format (Voxel Play 3)

Modified on Thu, 20 Feb at 5:00 PM

Current format version: 16.

Game can be saved either by scripting or using the console command /save.

The file format is binary. Chunk data is RLE compressed to reduce redundant data. Custom data sections are compressed using Deflate algorithm.

In version 16, Voxel Play stores world/game data in 3 files:

- main file containing header data as well as a list of the names of region files.

- one or more region files containing chunk & voxel data.

- an extra datafile containing gameobject data and custom sections data.

When the contents of the world are modified, only the affected region file is updated.

Header datafile structure

Byte Pos	Length	Type	Description
0	1	Byte	File format number
1	1	Byte	Chunk size (16 or 32)
1	4	Float	Position x of the character controller
5	4	Float	Position y of the character controller
9	4	Float	Position z of the character controller
13	4	Float	Character controller’s transform.eulerAngles.x
17	4	Float	Character controller’s transform.eulerAngles.y
21	4	Float	Character controller’s transform.eulerAngles.z
25	4	Float	Camera’s transform.eulerAngles.x
29	4	Float	Camera’s transform.eulerAngles.y
33	4	Float	Camera’s transform.eulerAngles.z
37	2	Int	Stage number
39	Variable	String	Ids of the regions included in the stage

Region datafile format

Byte Pos	Length	Type	Description
0	2	Int16	Number of voxel definitions
2	Variable	Strings	Names of each voxel definition (list)
??	2	Int16	Number of item definitions
	Variable	Strings	Names of each item definition (list) - this includes the item definitions for torches
	4	Int	Number of chunks
START OF CHUNK
	4	Float	Position x of the chunk
	4	Float	Position y of the chunk
	4	Float	Position z of the chunk
	1	Byte	If this chunk has some voxels above terrain surface (1) or not (0). Used for computing lightmap when neighbour chunks do not exist (yet). Above surface chunks assume Sun light from above. Chunks below surface won't receive Sun light from above if there's no chunk on top.
	1	Byte	1 if the chunk is completely generated. 0 if the chunk was modified after calling GetChunkUnpopulated() method but the terrain generator has not yet filled the chunk with contents.
	2	Int16	Number of words
FOR EACH VOXEL REPETITION ("WORD")...
	2	Int16	Index of the voxel definition list
	1	Byte	Voxel color (R) (0-255)
	1	Byte	Voxel color (G) (0-255)
	1	Byte	Voxel color (B) (0-255)
	2	Int16	Start index of the voxel repetition
	2	Int16	Repetitions
	1	Byte	If voxel is of transparent type or 6-textures opaque type, a flags byte with info with water level and/or voxel texture rotation info. "0" otherwise
...END VOXEL REPETITION
	2	Int16	Number of torches or light sources
FOR EACH LIGHT SOURCE...
	2	Int16	Index of the voxel within the chunk where the light source is
	4	Float	Normal.x (used to determine the face of the voxel where the light source is attached)
	4	Float	Normal.y
	4	Float	Normal.z
	2	Int16	Index of the item definition for the torch in the header list
...END OF LIGHT SOURCES SECTION
	2	Int16	Number of items in the chunk
FOR EACH ITEM
	2	Int16	Index of the item definition in the header list
	4	Float	Position x of the item
	4	Float	Position y of the item
	4	Float	Position z of the item
	4	Float	Quantity
...END OF ITEMS SECTION
	2	Int16	Number of voxels in this chunk with custom data
FOR EACH VOXEL WITH CUSTOM DATA...
	2	Int16	Index of voxel in the chunk
	2	Int16	Number of custom properties
	4	Int	Property Id
	4	Float	Float value
	??	String	String value
...END OF PER VOXEL CUSTOM DATA SECTION
END OF CHUNK
	2	Int16	Number of voxels with microvoxels in the chunk
FOR EACH VOXEL WITH MICROVOXELS...
	2	Int16	Index of the voxel in the chunk
8	UInt64	Entries of UInt64 containing the occupancy mask of the microvoxels (actual amount depends on the resolution of microvoxels defined in the Voxel Play Environment - this value should be set and not changed).

Extra datafile format:

Byte Pos	Length	Type	Description
	2	Int16	Number of gameobjects with "VoxelPlaySaveThis" component
FOR EACH GAMEOBJECT...
		String	Path for the prefab from a Resources folder (ie. "MyPrefabs/thisprefab" where MyPrefabs is a folder inside Resources folder)
		String	Name of the gameobject
	4	Float	Position x
	4	Float	Position y
	4	Float	Position z
	4	Float	Rotation angle x
	4	Float	Rotation angle y
	4	Float	Rotation angle z
	4	Float	Scale x
	4	Float	Scale y
	4	Float	Scale z
	2	Int16	Number of custom data values
PER EACH GAMEOBJECT DATA VALUE
		String	Key
		String	Value
END OF DATA VALUE
END OF GAMEOBJECT

	2	Int16	Number of custom data sections
PER EACH CUSTOM DATA SECTION
		String	Key
		Int16	Length of byte array
		Byte[]	Data contents
END OF CUSTOM DATA SECTION