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.
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:
./repair.py --output=repaired.world /path/to/world.failIf that works, then you can overwrite the new world file that Starbound
created (after your world failed) with repaired.world.
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:
./repair.py -o repaired.world -w /path/to/other.world /path/to/world.failThe command line interface will let you inspect various Starbound files.
Use the --get-value option to retrieve a metadata value. Example:
$ ./cli.py --get-value planet.config.gravity /Starbound/player/11475cedd80ead373c19a91de2e2c4d3.shipworld
open File(identifier="World2", path="/Starbound/player/11475cedd80ead373c19a91de2e2c4d3.shipworld")
planet.config.gravity = 80.0Another example for getting the name of a player:
/cli.py --get-value identity.name /Starbound/player/11475cedd80ead373c19a91de2e2c4d3.player
open File(identifier="PlayerEntity", path="/Starbound/player/11475cedd80ead373c19a91de2e2c4d3.player")
identity.name = FleurStarbound packages are essentially sets of packed (but uncompressed) files. Here's how to get the contents of a file in a .pak package:
$ ./cli.py --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:
$ ./cli.py --get-file-list /Starbound/assets/packed.pak
open File(identifier="Assets1", path="/Starbound/assets/packed.pak")
/animations/1hswordhitspark/1hswordhitspark.animation
/animations/1hswordhitspark/1hswordhitspark.frames
/animations/1hswordhitspark/1hswordhitspark.png
/animations/2hswordhitspark/2hswordhitspark.animation
/animations/2hswordhitspark/2hswordhitspark.frames
/animations/2hswordhitspark/2hswordhitspark.png
/animations/axehitspark/axehitspark.animation
/animations/axehitspark/axehitspark.frames
# ...and so on.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!' % player.name)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/beta_73998977_11092106_-913658_12_10.world')
world.open()
# 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)
stream.seek(8) # Ignore prefix
name, version, data = starbound.sbon.read_document(stream)
print(data['worldTemplate']['size'])You can use the export.py script to extract all the files in a .pak
(or .modpak) file.
Example:
./export.py -d assets /Starbound/assets/packed.pakIf you want information about a region in a world (planet or ship), you
can use the region.py script. For example, here's how to pretty print
the tiles in a region:
$ ./region.py /Starbound/giraffe_storage/universe/-809143555_95313027_54893405_6_3.world
World size: 93 by 62 regions
Spawn point region: 74, 28
Outputting region: 74, 27
Outputting value: foreground_materialOutputs 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):
$ ./region.py --value-index=12 /Starbound/giraffe_storage/universe/-809143555_95313027_54893405_6_3.world 69 27
World size: 93 by 62 regions
Spawn point region: 74, 28
Outputting region: 69, 27
Outputting value: liquid_pressureOutputs something like this:
And here's how to print the entities in a region:
$ ./region.py --entities /Starbound/universe/beta_73998977_11092106_-913658_12_8.world 249 52
World size: 250 by 156 regions
Spawn point region: 0, 51
Outputting region: 249, 52
[
[
"ObjectEntity",
{
"crafting": false,
"craftingProgress": 0.0,
"currentState": 0,
"direction": "right",
"initialized": true,
"items": [
{
"count": 100,
"data": {},
"name": "fabric"
},
null,
...