Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Python package for working with Starbound files.
Branch: master

Starbound utilities for Python

This is a library to parse Starbound's file formats, SBBF02 and SBVJ01, which are used to store worlds, player characters, assets, etc.

Feel free to contribute either via submitting pull requests or writing up issues with suggestions and/or bugs.

Repairing broken worlds (.fail files)

Note: It's always better to back up your .world files at regular intervals. This tool is only meant to be a last resort if you lost your world completely. It might only be able to recover parts of a world, and if the metadata is corrupt, your world might not work properly in the future.

To repair a failed world, try to run this command to see if it works:

./ /path/to/

If that works, then you can overwrite the new world file that Starbound created (after your world failed) with

If it fails to load the metadata section, then you can have the repair script pull in the metadata from another world. It's highly recommended that you only use either another .fail file of the same world, or the newly created .world file that Starbound creates when a world fails.

Here's how:

./ -o -w /path/to/ /path/to/

Using the command line interface

The command line interface will let you inspect various Starbound files.

Getting metadata from world or player files

Use the --get-value option to retrieve a metadata value. Example:

$ ./ --get-value planet.config.gravity /Starbound/player/11475cedd80ead373c19a91de2e2c4d3.shipworld
open File(identifier="World2", path="/Starbound/player/11475cedd80ead373c19a91de2e2c4d3.shipworld")

planet.config.gravity = 80.0

Another example for getting the name of a player:

/ --get-value /Starbound/player/11475cedd80ead373c19a91de2e2c4d3.player
open File(identifier="PlayerEntity", path="/Starbound/player/11475cedd80ead373c19a91de2e2c4d3.player") = Fleur

Inspecting Starbound packages

Starbound packages are essentially sets of packed (but uncompressed) files. Here's how to get the contents of a file in a .pak package:

$ ./ --get-file /tiles/mods/sand.matmod /Starbound/assets/packed.pak
  "modId" : 4,
  "modName" : "sand",
  "frames" : "sand.png",
  "variants" : 5,
  "Description" : "Scattered sand.",
  "footstepSound" : "/sfx/blocks/footstep_sand.wav",
  "health" : 0

You can also get the list of the files in a .pak file:

$ ./ --get-file-list /Starbound/assets/packed.pak
open File(identifier="Assets1", path="/Starbound/assets/packed.pak")

# ...and so on.

Using the Python package

The easiest way to get started with the package is to use the helper function open_file:

import starbound
player = starbound.open_file('player/11475cedd80ead373c19a91de2e2c4d3.player')
print('Hello, %s!' %

The open_file function will look at the file extension and choose the appropriate file format as well as parse additional metadata about that file type. To be more specific, you can use the file type classes:

import io
import starbound

world = starbound.FileBTreeDB4('universe/')

# Get the raw data out of the database, then parse it.
raw_data = world.get(b'\x00\x00\x00\x00\x00')
stream = io.BytesIO(raw_data) # Ignore prefix
name, version, data = starbound.sbon.read_document(stream)


Extracting .pak files

You can use the script to extract all the files in a .pak (or .modpak) file.


./ -d assets /Starbound/assets/packed.pak

Getting world data

If you want information about a region in a world (planet or ship), you can use the script. For example, here's how to pretty print the tiles in a region:

$ ./ /Starbound/giraffe_storage/universe/
World size:          93 by 62 regions
Spawn point region:  74, 28
Outputting region:   74, 27
Outputting value:    foreground_material

Outputs something like this:

If you don't provide X and Y coordinates after the path, it will default to the region that the spawn point is in.

You can also output specific tile values (instead of the foreground) using --value-index (or -v):

$ ./ --value-index=12 /Starbound/giraffe_storage/universe/ 69 27
World size:          93 by 62 regions
Spawn point region:  74, 28
Outputting region:   69, 27
Outputting value:    liquid_pressure

Outputs something like this:

And here's how to print the entities in a region:

$ ./ --entities /Starbound/universe/ 249 52
World size:          250 by 156 regions
Spawn point region:  0, 51
Outputting region:   249, 52

      "crafting": false,
      "craftingProgress": 0.0,
      "currentState": 0,
      "direction": "right",
      "initialized": true,
      "items": [
          "count": 100,
          "data": {},
          "name": "fabric"
Something went wrong with that request. Please try again.