damatrix / rocksmc

fast and compact storage format for minecraft based on rocksdb (currently only supports cubic chunks)

RocksMC

A fast, compact and powerful storage format for Minecraft, built using rocksdb.
Currently only supports Cubic Chunks.

TODO:

• global saves
• snapshots

Conversion

RocksMC features a built-in converter between existing world formats based on CubicChunksConverter. Access it by installing RocksMC, opening a single-player world, and running /rocksmc converter.

Concepts

NOTE: Currently, only local saves are implemented, global saves and snapshots are not.

World

A Minecraft world. Consists of one or more dimensions.
On the client, worlds are stored in individual subdirectories of .minecraft/saves/ ( e.g. .minecraft/saves/New World/). Servers only have a single world, which is stored in a single directory ( named world by default).

Dimension

A dimension in a Minecraft world. Generally identified by name (e.g. minecraft:overworld, minecraft:nether), or by ID (e.g. 0, 1, -1). Dimensions are each stored in separate folders. The default world (dimension 0, or minecraft:overworld) is stored in <world_directory>/, all other dimensions are stored in <world_directory>/DIM<dimension_id>/.
When using Cubic Chunks, each dimension can use a different storage format.

Save

A save consists of a directory with two children:

• db/: contains the RocksDB
• snapshots/: contains some number of subdirectories, each of which represents a RocksMC snapshot and contains a RocksDB database checkpoint

Local Save (Storage Format ID: rocksmc:local)

A local save belongs to a single dimension using the rocksmc:local storage format, and is stored in <dimension_directory>/rocksmc_local/.

Global Save (Storage Format ID: rocksmc:global)

A global save belongs to a world, and is stored in <world directory>/rocksmc_global/. Its RocksDB contains one storage for every dimension in the world that uses the rocksmc:global storage format. They are kept separate by storing them in individual column families.

Storage

A storage contains the terrain data for a single dimension - the exact same data as would have been stored in the region files in a vanilla world.
Conceptually, storages are implemented as a wrapper over some number of RocksDB column families.

Local vs Global

The primary advantage of global saves is that all dimensions can be stored in a single RocksDB, which provides three primary benefits:

• crash consistency across the entire world - in the event of a crash, all dimensions are guaranteed to be at the same revision
• global, atomic snapshots - snapshots will contain all dimensions at once at the same instance in time
• open files limit - if multiple dimensions are open as local storages, they will each track their open files limit individually. On systems where the maximum number of open files is restricted, this can become a serious obstacle for large worlds

However, for the vast majority of users, these benefits will be of little to no significance, especially compared to the simplicity of being able to manage dimensions by manually working with the files and directories on disk (e.g. resetting the terrain in a dimension by simply deleting the directory).

Identifying RocksMC objects

Virtually every RocksMC command requires a save, storage or snapshot as an argument. This section explains the format for identifying these objects.

If any part of an identifier contains whitespace or a ., that part must be placed in double quotes. For example, Hello World! should be written as "Hello World!".

Worlds

All RocksMC objects belong to a world, which are identified by their directory name. Some examples:

Side	Path to world directory	RocksMC world identifier	Comment
Client	.minecraft/saves/test/	test
Client	.minecraft/saves/New World/	"New World"	Double quotes used because the name contains a space
Server	world/	world
Client/Server	currently open world	@
Client/Server	/home/user/Downloads/cool_world	$/home/user/Downloads/cool_world	$ symbol indicates an absolute file path
Client/Server	C:\Users\user\Downloads\Cool World	$"C:\Users\user\Downloads\Cool World"	$ comes before quotes

Saves

Assuming you have a world, you can now access the individual saves inside it.

Save Type	Dimension	RocksMC save identifier	Comment
Local	-1	DIM-1
Local	default dimension	d	d stands for “default”. This is generally dimension 0 (the overworld)
Global		*	Global save doesn’t need a dimension
Local/Global	current dimension	@	Finds the save used by the dimension that the command sender is currently in. Cannot be used from the server console

Snapshots

Identifying individual snapshots inside a save is quite trivial: simply enter the name.

Snapshot name	RocksMC snapshot identifier	Comment
asdf	asdf
my new snapshot	"my new snapshot"	Whitespace still needs to be quoted
latest snapshot	^	Computed based on filesystem creation time for the snapshot directory

Putting it all together

These three parts are concatenated together (using a .) in order to build full object references. You can't access a snapshot without a save, or a save without a world. Thus, the full identifier syntax is:

<world_identifier>[.<save_identifier>[.<snapshot_identifier>]]