Metadata-Version: 1.0
Name: nbt2yaml
Version: 0.2.2
Summary: Read and write Minecraft NBT files using Yaml.
Home-page: http://bitbucket.org/zzzeek/nbt2yaml
Author: Mike Bayer
Author-email: mike_mp@zzzcomputing.com
License: BSD
Description: ========
        nbt2yaml
        ========
        
        nbt2yaml presents a command line interface for reading and editing Minecraft NBT files using a
        custom YAML format.   It also includes a Python API for parsing and writing NBT files to/from
        a simple Python data structure.
        
        The key tool is ``nbtedit``, a command line utility that will shell out the
        YAML version of the target NBT file to your editor of choice, allowing
        relatively easy editing of NBT data.   When the editing session is closed,
        the saved file is parsed back into NBT, and if changes have occurred, the original
        file is updated; a copy of the previous version is saved as well.
        
        NBT format:  http://wiki.vg/NBT
        
        YAML: http://www.yaml.org/
        
        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.
        
        nbtedit
        --------
        
        Edits an nbt file in-place, allowing YAML format within the editor.
        
        The script uses the standard ``EDITOR`` environment variable to determine which
        text editor should be invoked.
        
        The program detects if changes were made when the editing session is closed;
        if so, the existing nbt file is copied to a backup unconditionally, and the new
        data is written to the file in place.
        
        Synopsis::
        
            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
        
        nbt2yaml
        --------
        
        Dumps an nbt file as YAML to standard output::
        
            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
        
        yaml2nbt
        --------
        
        Dumps a YAML file generated by nbt2yaml as nbt to standard output::
        
            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:
        
        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!
        
        
        
Keywords: minecraft
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
