Metadata-Version: 2.1
Name: Python-NBT
Version: 1.2.0
Summary: A python library for reading and writing NBT files
Home-page: https://github.com/TowardtheStars/Python-NBT
Author: TowardtheStars
Author-email: hty16@mail.ustc.edu.cn
License: GPLv3
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown

# Python-NBT

A python library for reading and writing NBT files. Compatible with json.

Based on NBT Version: 19133 (Current version used by Minecraft)

## What is NBT

> NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data. An NBT file consists of a single GZIPped Named Tag of type TAG_Compound.

From official [Minecraft Wiki](https://minecraft.gamepedia.com/NBT_format).

## Installation

```bash
pip install Python-NBT
```

## Usage

### Read an NBT file

```Python
>>> import python_nbt.nbt as nbt
>>> file = nbt.read_from_nbt_file("file.nbt")
```

This function returns an instance of NBTTagCompound, or by the name on Minecraft Wiki, an instance of TAG_Compound. It only accept 1 argument, which can be either a file path string or an opened file stream.

The TAG_Compound acts like a `dict` in Python. More accurately, it is a subclass of `dict` in Python with some restrictions put on its keys and values. So you can get, and set its items as shown below:

```Python
>>> file['drop_loot_crates']
{'type_id': 1, 'value': 0}
>>> file['drop_loot_crates'] = nbt.TAG_Byte(1)
>>> file['drop_loot_crates']
{'type_id': 1, 'value': 1}
```

In the dict shown as above, the key `'type_id'` represents the type id of an NBT. In our example, its `'type_id'` is `1`, which indicates this NBT is a TAG_Byte. And `'value'` indicates its actual value.

### Write an NBT file

Once you've completed editing an NBT, you can store it into an NBT file with the function below:

```Python
write_to_nbt_file(file, tag)
```

The first argument `file` should be a path string or a file stream to the file you want to create/write. The second argument `tag` is the NBT you want to write.

### Compat with Json

If you want to export NBT in json, you can use `NBTTagBase.json_obj(full_json=True)` to get an json style `dict` that contains all the NBT information.
After that, you can use `json` module in Python to do whatever you want.
If you want a simpler version, which omits type id of an NBT and NBTs inside it, set `full_json` to `False`.
**Note**: Changing `full_json` to `False` will also turn json dict of nested tags into simple version.

If you want to import NBT from a json object, you can use `nbt.from_json(json_obj)` to do so.
This function will return an NBT object. And its argument must be as same format as what `NBTTagBase.json_obj(full_json=True)` exports.

## Future features

Ticked entries are finished.

- [x] More json compat
  - [x] Convert json into NBT
  - [x] Better and configurable json output (omitting NBT types)
- [ ] Convenient classes for reading and writing Minecraft saves files
  - [ ] World
  - [ ] Region
  - [ ] Chunk
  - [ ] ItemStack
  - [ ] TileEntity
  - [ ] Entity
  - [ ] Player
- [ ] Utilities for mods
  - [ ] [FTB Quests](https://github.com/FTBTeam/FTB-Quests) [(CurseForge Link)](https://www.curseforge.com/minecraft/mc-mods/ftb-quests)
  - [ ] [GameStages](https://github.com/Darkhax-Minecraft/Game-Stages) [(CurseForge Link)](https://minecraft.curseforge.com/projects/game-stages)
  - [ ] Recognize blocks and items form mods in World according to NEI exports
- [x] A detailed ~~doc/~~wiki
- [ ] More convenient interfaces for NBT (try to fully abandon `value` property, and makes everthing just it should be)
  - [ ] Operators for numeric tags
    - [ ] +, -, *, /
    - [ ] **, //
    - [ ] >, <
  - [x] List interfaces for array-like NBT
  - [x] Dict interfaces for dict-like NBT


