Modding:Save

Work In Progress!

This article or section is currently in the process of an expansion or major restructuring.
You are welcome to assist in its construction by editing it as well.

Last edited by Rl.starbound on 2024-03-14 02:50:11.

Saving in Starbound is a complex procedure. Every aspect of the game is saved separately in a certain location, making it possible to manipulate parts of a save independently, to an extent. Most often knowing the structure of the save is required for doing universe reset. Save location in Starbound (as of version 1.4) is at

[Starbound directory]/storage/

If you wish to experiment with mods it is highly recommended to backup this directory.

Universe save structure

Universe of Starbound is procedurally generated and saved at

[Starbound directory]/storage/universe

Save structure is as follows:

<--MAY BE OUTDATED!!!-->

universe.chunks

Contains known starsystem locations. Each star which you have seen in navigation console (farthest zoom level) is partially saved here. Only star name, seed, location and information on planets (type, slot, and certain metadata, such as how many and which major dungeons will spawn on the world) is saved in this file. Results of deleting this file vary depending on whether star generation code has been modded.

<hex string>.clientcontext

Contains current ship location, current player location, admin state. If this file is deleted the player's ship will be teleported to a new randomly chosen starting planet (Lush type of lowest difficulty).

universe.dat

Contains outpost state and universe unique identifier. If this file is lost or corrupted everyone in server loses their bookmarks/teleport locations (because the unique identifier is lost) and outpost state is reset.

If you only want to reset the outpost it is highly recommended to use the appropriate console command instead of deleting this file.

<XCoord>_<YCoord>_<uuid>.system

Contains description of a star system.

World files

<XCoord>_<YCoord>_<uuid>_<Planet number>_<Moon number>.world

Contains planet/moon data. (Starbound considers a planet orbiting another planet a moon; if the file refers to a planet orbiting the star itself, 'moon number' part is absent). Everything that is built or preexisting in that planet/moon. If this file is deleted, that specific planet/moon gets reset to its original state. The more the player modifies a certain planet, the bigger this file get.

There is a known bug in the Starbound engine in which world files will continuously grow in size, as long as at least one player is active in the world. World files will never decrease in size.

unique-spacestation_<spacestation type>-<hex string>-<1 digit number?>.world

Contains unique spacestation data. <spacestation type> is peacekeeper<1~5>, electronics, food, medical or weapons.

Temp world files

These world files operate similarly to the regular world files, but the game engine will remove them after all players leave them and a specified timeout occurs.

Corrupted(?) files

<XCoord>_<YCoord>_<uuid>_<Planet number>_<Moon number>.world.<number string>.fail

Player save structure

Player files are saved in

<Starbound directory>/storage/player

The same hex string corresponds to the same player.

<hex string>.player.bak<1/2/3>

3 <hex string>.player backup files.

<hex string>.shipworld.bak<1/2/3>

3 <hex string>.shipworld backup files.

<hex string>.player

Player save file.

<hex string>.shipworld

Operates similarly to a regular world file, including the same continuous growth bug. Given that ship world files are transferred between a client computer and a server when in multiplayer, the continuous growth bug will eventually result in a player's shipworld becoming corrupted if it grows large enough and is used in multiplayer.

metadata

This file has no extension. Its structure is humanreadable:

{"order":["<.player hexstring>"],"chatHistory":["<most recent>","<64(?) lines>","<of chat content>","<in double quotes>","<from newest to oldest>","<separated by commas.>"]}

Universe Reset

Universe reset, also known as 'Universe wipe', is an action of reverting the universe of Starbound to its initial state prior to being modified by a player. The easiest (and the most crude) way to do this is to delete the entire storage/universe directory.

Universe reset is necessary when universe generation is changed (most probably via modding the game). If a part of the save is corrupted and it is possible to track the corruption to a certain planet, wiping that planet instead of the whole universe is less damaging.