# Minecraft NBT Editor (Python)
A Python-based Minecraft NBT editor supporting Bedrock editions. This project is a complete rewrite of the original VSCode plugin, designed to work on Linux and other platforms.
## Features
- **Full NBT Support**: All NBT tag types (Byte, Short, Int, Long, Float, Double, String, ByteArray, IntArray, LongArray, List, Compound)
- **Multi-Format Support**: .dat, .nbt, .mca, .mcstructure files
- **Complete Editing Operations**: Create, Read, Update, Delete, Move, Composite edits
- **Bedrock Minecraft Support**: Little-endian format with optional 8-byte headers
- **Command Line Interface**: Easy to use in automation scripts
- **Comprehensive Error Handling**: Robust data validation and error reporting
- **Cross-Platform**: Works on Linux, Windows, and macOS
## Installation
### From PyPI (Recommended)
```bash
pip install minecraft-nbt-editor
```
### From Source
```bash
git clone https://github.com/geniusshiun/minecraft-nbt-editor.git
cd minecraft-nbt-editor
pip install -e .
```
## Quick Start
After installation, you can use the `minecraft-nbt` or `nbt-editor` command:
```bash
# View NBT file content
minecraft-nbt view level.dat
# Get a specific value
minecraft-nbt get level.dat --path "Data.Player.GameType"
# Set a value
minecraft-nbt set level.dat --path "Data.Player.GameType" --value "1"
# Add a new tag
minecraft-nbt add level.dat --path "Data.CustomTag" --value "Hello World" --type string
# Remove a tag
minecraft-nbt remove level.dat --path "Data.CustomTag"
```
## Usage Examples
### Basic Commands
```bash
# View file info (shows format, compression, endianness)
minecraft-nbt info level.dat
# View NBT file structure with limited depth
minecraft-nbt view level.dat --max-depth 3
# View as JSON format
minecraft-nbt view level.dat --format json
# View as table format
minecraft-nbt view level.dat --format table
# Get specific value
minecraft-nbt get level.dat --path "GameType"
# Set specific value
minecraft-nbt set level.dat --path "GameType" --value 1
# Enable features (Bedrock specific)
minecraft-nbt enable level.dat --exp --backup
```
### Common Minecraft Operations
#### Game Settings
```bash
# Get current game type (0=Survival, 1=Creative, 2=Adventure, 3=Spectator)
minecraft-nbt get level.dat --path GameType
# Change to Creative mode
minecraft-nbt set level.dat --path GameType --value 1
# Get current difficulty (0=Peaceful, 1=Easy, 2=Normal, 3=Hard)
minecraft-nbt get level.dat --path Difficulty
# Set difficulty to Hard
minecraft-nbt set level.dat --path Difficulty --value 3
# Get world name
minecraft-nbt get level.dat --path LevelName
# Change world name
minecraft-nbt set level.dat --path LevelName --value "My Awesome World"
```
#### Player Spawn Location
```bash
# Get spawn coordinates
minecraft-nbt get level.dat --path SpawnX
minecraft-nbt get level.dat --path SpawnY
minecraft-nbt get level.dat --path SpawnZ
# Set new spawn location
minecraft-nbt set level.dat --path SpawnX --value 100
minecraft-nbt set level.dat --path SpawnY --value 64
minecraft-nbt set level.dat --path SpawnZ --value 200
```
#### Game Rules and Features
```bash
# Check if cheats are enabled
minecraft-nbt get level.dat --path cheatsEnabled
# Enable cheats
minecraft-nbt set level.dat --path cheatsEnabled --value 1
# Get keep inventory setting
minecraft-nbt get level.dat --path keepinventory
# Enable keep inventory
minecraft-nbt set level.dat --path keepinventory --value 1
# Check daylight cycle
minecraft-nbt get level.dat --path daylightCycle
# Stop daylight cycle
minecraft-nbt set level.dat --path daylightCycle --value 0
```
#### Bedrock Edition Specific
```bash
# Get experimental features
minecraft-nbt get level.dat --path experiments
# Enable all experimental features at once (with backup)
minecraft-nbt enable level.dat --exp --backup
# Enable all experimental features without backup
minecraft-nbt enable level.dat --exp
# Get player abilities
minecraft-nbt get level.dat --path abilities.flying
minecraft-nbt get level.dat --path abilities.mayfly
# Enable flight for player
minecraft-nbt set level.dat --path abilities.mayfly --value 1
minecraft-nbt set level.dat --path abilities.flying --value 1
# Get world version info
minecraft-nbt get level.dat --path MinimumCompatibleClientVersion
minecraft-nbt get level.dat --path lastOpenedWithVersion
```
### Enable Command (Bedrock Edition)
The `enable` command provides quick access to commonly needed Minecraft Bedrock features:
```bash
# Enable all experimental features at once
minecraft-nbt enable level.dat --exp --backup
# Available experimental features that will be enabled:
# - data_driven_biomes: Data-driven biomes
# - experimental_creator_cameras: Experimental creator cameras
# - experiments_ever_used: Experiments usage tracking
# - gametest: GameTest framework
# - jigsaw_structures: Jigsaw structure support
# - saved_with_toggled_experiments: Experiment toggle tracking
# - upcoming_creator_features: Upcoming creator features
# - villager_trades_rebalance: Villager trade rebalancing
# - y_2025_drop_3: 2025 Q3 features
```
### Advanced Search Operations
```bash
# Search for specific values
minecraft-nbt search level.dat --value "survival"
# Search by tag type
minecraft-nbt search level.dat --type string
# Search by tag name pattern
minecraft-nbt search level.dat --name "GameType"
# Search in specific path
minecraft-nbt search level.dat --path abilities --type byte
```
### Batch Operations
```bash
# Convert NBT to JSON for external processing
minecraft-nbt convert level.dat --output level.json --format json
# Create backup before editing
cp level.dat level.dat.backup
# Batch modify multiple settings
minecraft-nbt set level.dat --path GameType --value 1
minecraft-nbt set level.dat --path cheatsEnabled --value 1
minecraft-nbt set level.dat --path keepinventory --value 1
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/geniusshiun/minecraft-nbt-editor.git
cd minecraft-nbt-editor
pip install -r requirements-dev.txt
pip install -e .
```
### Run Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=src
# Run specific test file
pytest test_basic.py
```
### Code Quality
```bash
# Format code
black src/
# Lint code
flake8 src/
# Type checking
mypy src/
```
## Project Structure
```
src/
├── core/
│ ├── __init__.py
│ ├── nbt_types.py # NBT tag type definitions
│ ├── nbt_path.py # NBT path operations
│ ├── nbt_file.py # NBT file I/O
│ └── operations.py # Editing operations
├── cli/
│ ├── __init__.py
│ └── main.py # Command line interface
└── utils/
├── __init__.py
└── binary.py # Binary operations
```
## Supported File Types
- **Java Edition**: Big-endian NBT files (typically gzipped)
- **Bedrock Edition**: Little-endian NBT files with optional 8-byte headers
- **Compression**: Gzip, Zlib, or uncompressed
- **Formats**: .dat, .nbt, .mca, .mcstructure
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Original VSCode plugin reference project
- Minecraft community for NBT format documentation
- Python community for excellent libraries and tools
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.
Raw data
{
"_id": null,
"home_page": null,
"name": "minecraft-nbt-editor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bedrock, editor, java, minecraft, nbt",
"author": null,
"author_email": "geniusshiun <geniusshiun@example.com>",
"download_url": "https://files.pythonhosted.org/packages/df/fe/c0045d861595a6bbc81e3a09f7f1d782461f7cfc9cc613dcbb8968237c44/minecraft_nbt_editor-0.2.1.tar.gz",
"platform": null,
"description": "# Minecraft NBT Editor (Python)\n\nA Python-based Minecraft NBT editor supporting Bedrock editions. This project is a complete rewrite of the original VSCode plugin, designed to work on Linux and other platforms.\n\n## Features\n\n- **Full NBT Support**: All NBT tag types (Byte, Short, Int, Long, Float, Double, String, ByteArray, IntArray, LongArray, List, Compound)\n- **Multi-Format Support**: .dat, .nbt, .mca, .mcstructure files\n- **Complete Editing Operations**: Create, Read, Update, Delete, Move, Composite edits\n- **Bedrock Minecraft Support**: Little-endian format with optional 8-byte headers\n- **Command Line Interface**: Easy to use in automation scripts\n- **Comprehensive Error Handling**: Robust data validation and error reporting\n- **Cross-Platform**: Works on Linux, Windows, and macOS\n\n## Installation\n\n### From PyPI (Recommended)\n```bash\npip install minecraft-nbt-editor\n```\n\n### From Source\n```bash\ngit clone https://github.com/geniusshiun/minecraft-nbt-editor.git\ncd minecraft-nbt-editor\npip install -e .\n```\n\n## Quick Start\n\nAfter installation, you can use the `minecraft-nbt` or `nbt-editor` command:\n\n```bash\n# View NBT file content\nminecraft-nbt view level.dat\n\n# Get a specific value\nminecraft-nbt get level.dat --path \"Data.Player.GameType\"\n\n# Set a value\nminecraft-nbt set level.dat --path \"Data.Player.GameType\" --value \"1\"\n\n# Add a new tag\nminecraft-nbt add level.dat --path \"Data.CustomTag\" --value \"Hello World\" --type string\n\n# Remove a tag\nminecraft-nbt remove level.dat --path \"Data.CustomTag\"\n```\n\n## Usage Examples\n\n### Basic Commands\n\n```bash\n# View file info (shows format, compression, endianness)\nminecraft-nbt info level.dat\n\n# View NBT file structure with limited depth\nminecraft-nbt view level.dat --max-depth 3\n\n# View as JSON format\nminecraft-nbt view level.dat --format json\n\n# View as table format\nminecraft-nbt view level.dat --format table\n\n# Get specific value\nminecraft-nbt get level.dat --path \"GameType\"\n\n# Set specific value\nminecraft-nbt set level.dat --path \"GameType\" --value 1\n\n# Enable features (Bedrock specific)\nminecraft-nbt enable level.dat --exp --backup\n```\n\n### Common Minecraft Operations\n\n#### Game Settings\n```bash\n# Get current game type (0=Survival, 1=Creative, 2=Adventure, 3=Spectator)\nminecraft-nbt get level.dat --path GameType\n\n# Change to Creative mode\nminecraft-nbt set level.dat --path GameType --value 1\n\n# Get current difficulty (0=Peaceful, 1=Easy, 2=Normal, 3=Hard)\nminecraft-nbt get level.dat --path Difficulty\n\n# Set difficulty to Hard\nminecraft-nbt set level.dat --path Difficulty --value 3\n\n# Get world name\nminecraft-nbt get level.dat --path LevelName\n\n# Change world name\nminecraft-nbt set level.dat --path LevelName --value \"My Awesome World\"\n```\n\n#### Player Spawn Location\n```bash\n# Get spawn coordinates\nminecraft-nbt get level.dat --path SpawnX\nminecraft-nbt get level.dat --path SpawnY\nminecraft-nbt get level.dat --path SpawnZ\n\n# Set new spawn location\nminecraft-nbt set level.dat --path SpawnX --value 100\nminecraft-nbt set level.dat --path SpawnY --value 64\nminecraft-nbt set level.dat --path SpawnZ --value 200\n```\n\n#### Game Rules and Features\n```bash\n# Check if cheats are enabled\nminecraft-nbt get level.dat --path cheatsEnabled\n\n# Enable cheats\nminecraft-nbt set level.dat --path cheatsEnabled --value 1\n\n# Get keep inventory setting\nminecraft-nbt get level.dat --path keepinventory\n\n# Enable keep inventory\nminecraft-nbt set level.dat --path keepinventory --value 1\n\n# Check daylight cycle\nminecraft-nbt get level.dat --path daylightCycle\n\n# Stop daylight cycle\nminecraft-nbt set level.dat --path daylightCycle --value 0\n```\n\n#### Bedrock Edition Specific\n```bash\n# Get experimental features\nminecraft-nbt get level.dat --path experiments\n\n# Enable all experimental features at once (with backup)\nminecraft-nbt enable level.dat --exp --backup\n\n# Enable all experimental features without backup\nminecraft-nbt enable level.dat --exp\n\n# Get player abilities\nminecraft-nbt get level.dat --path abilities.flying\nminecraft-nbt get level.dat --path abilities.mayfly\n\n# Enable flight for player\nminecraft-nbt set level.dat --path abilities.mayfly --value 1\nminecraft-nbt set level.dat --path abilities.flying --value 1\n\n# Get world version info\nminecraft-nbt get level.dat --path MinimumCompatibleClientVersion\nminecraft-nbt get level.dat --path lastOpenedWithVersion\n```\n\n### Enable Command (Bedrock Edition)\n\nThe `enable` command provides quick access to commonly needed Minecraft Bedrock features:\n\n```bash\n# Enable all experimental features at once\nminecraft-nbt enable level.dat --exp --backup\n\n# Available experimental features that will be enabled:\n# - data_driven_biomes: Data-driven biomes\n# - experimental_creator_cameras: Experimental creator cameras \n# - experiments_ever_used: Experiments usage tracking\n# - gametest: GameTest framework\n# - jigsaw_structures: Jigsaw structure support\n# - saved_with_toggled_experiments: Experiment toggle tracking\n# - upcoming_creator_features: Upcoming creator features\n# - villager_trades_rebalance: Villager trade rebalancing\n# - y_2025_drop_3: 2025 Q3 features\n```\n\n### Advanced Search Operations\n\n```bash\n# Search for specific values\nminecraft-nbt search level.dat --value \"survival\"\n\n# Search by tag type\nminecraft-nbt search level.dat --type string\n\n# Search by tag name pattern\nminecraft-nbt search level.dat --name \"GameType\"\n\n# Search in specific path\nminecraft-nbt search level.dat --path abilities --type byte\n```\n\n### Batch Operations\n\n```bash\n# Convert NBT to JSON for external processing\nminecraft-nbt convert level.dat --output level.json --format json\n\n# Create backup before editing\ncp level.dat level.dat.backup\n\n# Batch modify multiple settings\nminecraft-nbt set level.dat --path GameType --value 1\nminecraft-nbt set level.dat --path cheatsEnabled --value 1\nminecraft-nbt set level.dat --path keepinventory --value 1\n```\n\n## Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/geniusshiun/minecraft-nbt-editor.git\ncd minecraft-nbt-editor\npip install -r requirements-dev.txt\npip install -e .\n```\n\n### Run Tests\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src\n\n# Run specific test file\npytest test_basic.py\n```\n\n### Code Quality\n```bash\n# Format code\nblack src/\n\n# Lint code\nflake8 src/\n\n# Type checking\nmypy src/\n```\n\n## Project Structure\n\n```\nsrc/\n\u251c\u2500\u2500 core/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 nbt_types.py # NBT tag type definitions\n\u2502 \u251c\u2500\u2500 nbt_path.py # NBT path operations\n\u2502 \u251c\u2500\u2500 nbt_file.py # NBT file I/O\n\u2502 \u2514\u2500\u2500 operations.py # Editing operations\n\u251c\u2500\u2500 cli/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 main.py # Command line interface\n\u2514\u2500\u2500 utils/\n \u251c\u2500\u2500 __init__.py\n \u2514\u2500\u2500 binary.py # Binary operations\n```\n\n## Supported File Types\n\n- **Java Edition**: Big-endian NBT files (typically gzipped)\n- **Bedrock Edition**: Little-endian NBT files with optional 8-byte headers\n- **Compression**: Gzip, Zlib, or uncompressed\n- **Formats**: .dat, .nbt, .mca, .mcstructure\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Original VSCode plugin reference project\n- Minecraft community for NBT format documentation\n- Python community for excellent libraries and tools\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python-based Minecraft NBT editor supporting Bedrock editions",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/geniusshiun/minecraft-nbt-editor",
"Issues": "https://github.com/geniusshiun/minecraft-nbt-editor/issues",
"Repository": "https://github.com/geniusshiun/minecraft-nbt-editor"
},
"split_keywords": [
"bedrock",
" editor",
" java",
" minecraft",
" nbt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "721a5be79828a9b420ccf5f1647fb6f1a67dd83bf0646948cb21ed42ab95da75",
"md5": "18668ff19eb36e97db05fb0b9bbbe7be",
"sha256": "5cda15a80b9400f251b5fcaeee4bda976ec2480571babda1fd0a08bb4a9aae74"
},
"downloads": -1,
"filename": "minecraft_nbt_editor-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18668ff19eb36e97db05fb0b9bbbe7be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27952,
"upload_time": "2025-08-19T17:34:17",
"upload_time_iso_8601": "2025-08-19T17:34:17.693339Z",
"url": "https://files.pythonhosted.org/packages/72/1a/5be79828a9b420ccf5f1647fb6f1a67dd83bf0646948cb21ed42ab95da75/minecraft_nbt_editor-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dffec0045d861595a6bbc81e3a09f7f1d782461f7cfc9cc613dcbb8968237c44",
"md5": "56771ee6c13ea8fdb15bb6d8d8b8804e",
"sha256": "fdc6b18ef87be2694292c6e71ce2215ed619f4257d32a6d5c34cb6a271b6d01c"
},
"downloads": -1,
"filename": "minecraft_nbt_editor-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "56771ee6c13ea8fdb15bb6d8d8b8804e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 38501,
"upload_time": "2025-08-19T17:34:19",
"upload_time_iso_8601": "2025-08-19T17:34:19.552849Z",
"url": "https://files.pythonhosted.org/packages/df/fe/c0045d861595a6bbc81e3a09f7f1d782461f7cfc9cc613dcbb8968237c44/minecraft_nbt_editor-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 17:34:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geniusshiun",
"github_project": "minecraft-nbt-editor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9.0"
]
]
}
],
"lcname": "minecraft-nbt-editor"
}
JSON
