Skip to main content

Python package for working with Starbound files.

Project description

Starbound utilities for Python

This is a library to parse Starbound's file formats 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.

File & data formats

Check out for technical information on Starbound's file and data formats.


py-starbound can be installed (either to your system, user account, or virtualenv) using the usual script:

$ python install

After installation, the commandline utilities (described below) should be available in your $PATH can can be run like any other app:

$ pystarbound-export [args]
$ pystarbound-region [args]

If you wish to run these utilities from the git checkout itself (without installing first), the syntax is slightly more verbose:

$ python -m starbound.cliexport [args]
$ python -m starbound.cliregion [args]

Command line utilities

Extracting .pak files

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


$ pystarbound-export -d assets /Starbound/assets/packed.pak

Or from the git checkout directly:

$ python -m starbound.cliexport -d assets /Starbound/assets/packed.pak

Getting world info

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:

$ pystarbound-region /Starbound/storage/universe/
World size:        3000×2000
Spawn point:       (1224.0, 676.0)
Outputting region: (37, 21)
Outputting value:  foreground_material

Or from the git checkout directly:

$ python -m starbound.cliregion /Starbound/storage/universe/

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):

$ pystarbound-region --value-index=12 /Starbound/storage/universe/ 69 27
World size:        3000×2000
Spawn point:       (1224.0, 676.0)
Outputting region: (69, 27)
Outputting value:  liquid_pressure

Outputs something like this:

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

$ pystarbound-region --entities /Starbound/storage/universe/ 69 27
World size:        3000×2000
Spawn point:       (1224.0, 676.0)
Outputting region: (69, 27)

      "direction": "left",
      "inputWireNodes": [],
      "interactive": true,
      "name": "wiringstation",
      "orientationIndex": 0,
      "outputWireNodes": [],
      "parameters": {
        "owner": "916d5878483e3a40d10467dc419982c2"
      "scriptStorage": {},

Using the Python package

The Python package lets you read data from Starbound's various file formats. The classes and functions expect file objects to read from.

You can use the mmap package to improve performance for large files, such as packed.pak and world files.

Example: Reading a player file

Here's how to print the name of a player:

import starbound

with open('player/11475cedd80ead373c19a91de2e2c4d3.player', 'rb') as fh:
  player = starbound.read_sbvj01(fh)
  print('Hello, {}!'.format(['identity']['name']))

Example: World files

In the following example the mmap package is used for faster access:

import mmap, starbound

with open('universe/', 'rb') as fh:
  mm = mmap.mmap(fh.fileno(), 0, access=mmap.ACCESS_READ)

  world = starbound.World(mm)

  print('World size: {}×{}'.format(world.width, world.height))
  x, y = world.metadata['playerStart']
  print('Player spawns at ({}, {})'.format(x, y))

  # Regions consist of 32×32 tiles.
  rx, ry = x // 32, y // 32
  print('An entity: {}'.format(world.get_entities(rx, ry)[0]))

Example: Easy access to various world attributes

A vast amount of information about loaded Worlds is available via the metadata attribute (as seen in the above section), but some information is also abstracted out into an info attribute. For instance:

world = starbound.World(fh)
print('World Name: {}'.format(
print('World Description: {}'.format(
print('World Coordinates: ({}, {})'.format([0],[1]))

The full list of attributes currently available are:

Attribute Description
biomes The full set of biomes found on the world. This should be a complete list, regardless of how much of the world has been explored.
coords World coordinates, as a tuple. The first two elements are the in-map coordinates of the system, the third is effectively random but describes the world itself.
description The internal description of the world. Will often include text describing the tier of the world.
dungeons The full set of dungeons found on the world. This should be a complete list, regardless of how much of the world has been explored.
name The name of the world. Will often include Starbound coloration markup.
size A tuple describing the width and height of the world.
world_biomes A set of the main biome IDs of the world, of the sort reported in the ingame navigation screen.

Example: Finding an entity by UUID/ID

Many entities in Starbound, such as bookmarked flags, mech beacons, quest markers, etc, have UUIDs or IDs which the game can use to find where they are in the map without having to have all regions loaded. Player bookmark UUIDs can be found in the['universeMap'] dict, underneath teleportBookmarks. One object type which does not use UUIDs is a level's mech beacon, which instead uses the magic string mechbeacon. To find the ingame coordinates for a level's beacon (if one is present), this can be used:

mechbeacon_coords = world.get_entity_uuid_coords('mechbeacon')
if mechbeacon_coords:
  print('Mech beacon found at ({}, {})'.format(*mechbeacon_coords))
  print('No mech beacon in level!')

Example: Getting assets from packed.pak

Starbound keeps most of the assets (images, configuration files, dungeons, etc.) in a file called packed.pak. This file uses a special format which can be read by py-starbound, as you can see below.

import starbound

with open('assets/packed.pak', 'rb') as fh:
  package = starbound.SBAsset6(fh)

  # Print the contents of a file in the asset package.

Example: Modifying Starbound files

Currently, only the SBVJ01 file format can be written by py-starbound. This means player files, client context files, and the statistics file.

Here's an example that renames a player (WARNING: Always back up files before writing to them!):

import starbound

with open('player/420ed511f83b3760dead42a173339b3e.player', 'r+b') as fh:
  player = starbound.read_sbvj01(fh)

  old_name =['identity']['name']
  new_name = old_name.encode('rot13')['identity']['name'] = new_name
  print('Updating name: {} -> {}'.format(old_name, new_name))

  # Go back to the beginning of the file and write the updated data.
  starbound.write_sbvj01(fh, player)
  # If the file got shorter, truncate away the remaining content.


MIT License

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for py-starbound, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size py-starbound-1.0.0.tar.gz (21.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page