Package: py-starbound
Starbound utilities for PythonThis 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 formatsCheck outFORMATS.mdfor technical information on
Starbound's file and data formats.Installationpy-starbound can be installed (either to your system, user account, or
virtualenv) using the usualsetup.pyscript:$pythonsetup.pyinstallAfter installation, the commandline utilities (described below) should
be available in your$PATHcan 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-mstarbound.cliexport[args]$python-mstarbound.cliregion[args]Command line utilitiesExtracting.pakfilesYou can use thepystarbound-exportscript to extract all the files in a.pak(or.modpak) file.Example:$pystarbound-export-dassets/Starbound/assets/packed.pakOr from the git checkout directly:$python-mstarbound.cliexport-dassets/Starbound/assets/packed.pakGetting world infoIf you want information about a region in a world (planet or ship), you
can use theregion.pyscript. For example, here's how to pretty print
the tiles in a region:$pystarbound-region/Starbound/storage/universe/-382912739_-582615456_-73870035_3.world
Worldsize:3000×2000
Spawnpoint:(1224.0,676.0)Outputtingregion:(37,21)Outputtingvalue:foreground_materialOr from the git checkout directly:$python-mstarbound.cliregion/Starbound/storage/universe/-382912739_-582615456_-73870035_3.worldOutputs 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/-382912739_-582615456_-73870035_3.world6927Worldsize:3000×2000
Spawnpoint:(1224.0,676.0)Outputtingregion:(69,27)Outputtingvalue:liquid_pressureOutputs something like this:And here's how to print the entities in a region:$pystarbound-region--entities/Starbound/storage/universe/-382912739_-582615456_-73870035_3.world6927Worldsize:3000×2000
Spawnpoint:(1224.0,676.0)Outputtingregion:(69,27)[["ObjectEntity",8,{"direction":"left","inputWireNodes":[],"interactive":true,"name":"wiringstation","orientationIndex":0,"outputWireNodes":[],"parameters":{"owner":"916d5878483e3a40d10467dc419982c2"},"scriptStorage":{},
...Using the Python packageThe 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 themmappackage to improve performance for large files,
such aspacked.pakand world files.Example: Reading a player fileHere's how to print the name of a player:importstarboundwithopen('player/11475cedd80ead373c19a91de2e2c4d3.player','rb')asfh:player=starbound.read_sbvj01(fh)print('Hello,{}!'.format(player.data['identity']['name']))Example: World filesIn the following example themmappackage is used for faster access:importmmap,starboundwithopen('universe/43619853_198908799_-9440367_6_3.world','rb')asfh:mm=mmap.mmap(fh.fileno(),0,access=mmap.ACCESS_READ)world=starbound.World(mm)world.read_metadata()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//32print('An entity:{}'.format(world.get_entities(rx,ry)[0]))Example: Easy access to various world attributesA vast amount of information about loaded Worlds is available via themetadataattribute (as seen in the above section), but some
information is also abstracted out into aninfoattribute. For instance:world=starbound.World(fh)print('World Name:{}'.format(world.info.name))print('World Description:{}'.format(world.info.description))print('World Coordinates: ({},{})'.format(world.info.coords[0],world.info.coords[1]))The full list of attributes currently available are:AttributeDescriptionbiomesThe full set of biomes found on the world. This should be a complete list, regardless of how much of the world has been explored.coordsWorld 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.descriptionThe internal description of the world. Will often include text describing the tier of the world.dungeonsThe full set of dungeons found on the world. This should be a complete list, regardless of how much of the world has been explored.nameThe name of the world. Will often include Starbound coloration markup.sizeA tuple describing the width and height of the world.world_biomesA set of the main biome IDs of the world, of the sort reported in the ingame navigation screen.Example: Finding an entity by UUID/IDMany 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 theplayer.data['universeMap']dict, underneathteleportBookmarks. One object type which doesnotuse UUIDs is a level's mech beacon, which instead uses the magic
stringmechbeacon. 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')ifmechbeacon_coords:print('Mech beacon found at ({},{})'.format(*mechbeacon_coords))else:print('No mech beacon in level!')Example: Getting assets frompacked.pakStarbound keeps most of the assets (images, configuration files,
dungeons, etc.) in a file calledpacked.pak. This file uses a special
format which can be read by py-starbound, as you can see below.importstarboundwithopen('assets/packed.pak','rb')asfh:package=starbound.SBAsset6(fh)# Print the contents of a file in the asset package.print(package.get('/lighting.config'))Example: Modifying Starbound filesCurrently, 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!):importstarboundwithopen('player/420ed511f83b3760dead42a173339b3e.player','r+b')asfh:player=starbound.read_sbvj01(fh)old_name=player.data['identity']['name']new_name=old_name.encode('rot13')player.data['identity']['name']=new_nameprint('Updating name:{}->{}'.format(old_name,new_name))# Go back to the beginning of the file and write the updated data.fh.seek(0)starbound.write_sbvj01(fh,player)# If the file got shorter, truncate away the remaining content.fh.truncate()LicenseMIT License