nbt2yaml 0.2.0

Installation

First, be sure to read the disclaimer down below.

Install via pip is easiest:

pip install nbt2yaml

or alternatively easy_install:

easy_install nbt2yaml

Once installed, the nbtedit, nbt2yaml, and yaml2nbt commands should be available, from the same place other Python utilities are installed.

Commands

Note that an nbt file is typically in gzip format. nbt2yaml commands will assume gzip format for all nbt files written and read, unless the --no-gzip flag is specified.

For the nbt2yaml and yaml2nbt commands, the filename can be specified as -, which indicates the data should be read from standard input.

usage: nbtedit [-h] [-n] filename

Edit an nbt file in-place in Yaml format.

positional arguments:
  filename       filename

optional arguments:
  -h, --help     show this help message and exit
  -n, --no-gzip  Don't use gzip

usage: nbt2yaml [-h] [-n] filename

Dump an nbt file or stream to yaml.

positional arguments:
  filename       Filename. Specify as '-' to read from stdin.

optional arguments:
  -h, --help     show this help message and exit
  -n, --no-gzip  Don't use gzip

usage: yaml2nbt [-h] [-n] filename

Dump a yaml file or stream to nbt.

positional arguments:
  filename       Filename. Specify as '-' to read from stdin.

optional arguments:
  -h, --help     show this help message and exit
  -n, --no-gzip  Don't use gzip

Example Use

Suppose we want to switch the “GameMode” from “0” (survival) to “1” (creative).

First, ensure that Minecraft itself is not running. Then, navigate to where your Minecraft save files are. Here’s how it looks on a mac:

$ cd ~/Library/Application\ Support/minecraft/saves/

Once there, edit the level.dat file for any selected world:

nbtedit myworld/level.dat

Assuming you have your EDITOR variable set, an editor like vim, nano, emacs, or something else should pop up. Window based editors can be used if they present a command line command that doesn’t exit until the file is saved (such as, I can use mate -w here to use TextMate).

Then navigate down to the “GameType” value:

  - foodSaturationLevel: 0.0
  - FallDistance: 0.0
  - XpTotal: 0
  - Rotation:
    - -476.3782043457031
    - 28.349964141845703
  - Xp: 0
- RandomSeed: !long "1201953322384967445L"
- GameType: 0
- MapFeatures: !byte "0"
- version: 19132
- Time: !long "5601373"
- raining: !byte "0"
- thunderTime: 19527

Change it from “0” (survival) to “1” (creative):

- RandomSeed: !long "1201953322384967445L"
- GameType: 1
- MapFeatures: !byte "0"

Save the file. nbtedit reports that it saved a copy of the old file and wrote the changes to the existing file. Now you can build some castles !

Format

The specifics of how NBT is mapped to YAML is of course a decision this program has to make, as there are any number of ways to do it. The goal here is to have a YAML format that is as minimal and readable as possible, while still maintaining the ability to write the identical nbt file as the one parsed; for this reason, many datatypes have explicit directives (i.e. short, long, double, byte) which will result in the appropriate nbt tag (i.e. TAG_Short, TAG_Long, TAG_Double, TAG_Byte). The default for int, str and float Python types are TAG_Int, TAG_String, and TAG_Float, respectively.

When editing a YAML file, it’s important to keep the formatting exactly the same! nbt2yaml can only handle structures that are in the form in which it generates; see the example below to see all of these forms.

While nbt2yaml can handle any kind of data provided the format is correct, it’s expected that the normal use of this tool is just to change individual values without changing the document structure.

A current dump of the Minecraft reference file bigtest.nbt in YAML format is below. Suggestions on improving this format are welcome !

Level:
- longTest: !long "9223372036854775807L"
- shortTest: !short "32767"
- stringTest: !!python/str "HELLO WORLD THIS IS A TEST STRING \xC5\xC4\xD6!"
- floatTest: 0.4982314705848694
- intTest: 2147483647
- nested compound test:
  - ham:
    - name: Hampus
    - value: 0.75
  - egg:
    - name: Eggbert
    - value: 0.5
- listTest (long):
  - !long "11"
  - !long "12"
  - !long "13"
  - !long "14"
  - !long "15"
- listTest (compound):
  - - name: 'Compound tag #0'
    - created-on: !long "1264099775885L"
  - - name: 'Compound tag #1'
    - created-on: !long "1264099775885L"
- byteTest: !byte "127"
- byteArrayTest (the first 1000 values of (n*n*255+n*7)%100, starting with n=0 (0, 62, 34, 16, 8, ...)): !byte_array "\0\
    >\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1C\
    P*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16\
    ^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10\
    :\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\
    \x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\
    \x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1A\
    D\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\
    \x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E\
    `XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04\
    $N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\n\
    H,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\
    \x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\
    \x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1A\
    D\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\
    \x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E\
    `XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04\
    $N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\n\
    H,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\
    \x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\x10\b\n\x16,L\x12F \x04VNP\\\
    \x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E`XZ\x02\x188b2\fTB:<H^\x1A\
    D\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04$N\x1E\\@.&(4J\x060\0>\"\
    \x10\b\n\x16,L\x12F \x04VNP\\\x0E.X(\x02J802>T\x10:\nH,\x1A\x12\x14 6V\x1CP*\x0E\
    `XZ\x02\x188b2\fTB:<H^\x1AD\x14R6$\x1C\x1E*@`&Z4\x18\x06b\0\f\"B\b<\x16^LDFR\x04\
    $N\x1E\\@.&(4J\x060"
- doubleTest: !double "0.4931287132182315"

Disclaimer

nbtedit is brand new. If it’s September, 2011, you are one of the first people reading this README. If there is a bug in nbtedit, you’re about to be the person who finds it! It’s also very possible that an incorrectly edited YAML file could save an NBT file that Minecraft no longer knows how to read.

Back EVERYTHING up before tinkering with your files !! nbtedit saves a backup of each file it edits, but don’t rely solely on that! Please note you are using this editor at your own risk. The code is unit tested, works great, but I’d hate to be the reason you screwed up your world so make copies of all files being edited first. Thanks!