Minecraft NBT Library

A comprehensive Node.js library for reading, writing, and manipulating Minecraft NBT (Named Binary Tag), DAT, and MCA (Minecraft Chunk Archive) files. Supports conversion between binary formats, SNBT (Stringified NBT), and JSON with full round-trip compatibility and zero data corruption.

Features

Complete NBT Support: Read and write all NBT tag types (Byte, Short, Int, Long, Float, Double, String, ByteArray, IntArray, LongArray, List, Compound)
Multiple File Formats:
- .nbt files (uncompressed NBT)
- .dat files (gzip-compressed NBT, like level.dat, player data)
- .mca files (Minecraft region files containing multiple chunks)
- .snbt files (Stringified NBT text format)
- .json files (with type preservation)
Format Conversion: Convert between NBT, SNBT, and JSON formats
Buffer Operations: Direct buffer parsing for remote files, SFTP, APIs, and custom adapters
Data Integrity: Preserves exact data types and values without corruption
Auto-detection: Automatically detects file types based on extension and content
Chunk Manipulation: Full support for reading and writing individual chunks in region files
Inventory Management: Complete player inventory manipulation (add, remove, modify items)
Validation: Built-in validation for NBT data structures
High Performance: Optimized binary parsing with minimal memory overhead
Async Operations: Non-blocking async methods for massive performance improvements with large files
Lazy Loading: Memory-efficient loading for huge region files
Bulk Processing: Concurrent processing of multiple MCA files

Installation

npm install mc-nbt-lib

Quick Start

const minecraftNBT = require('mc-nbt-lib');

// Read any Minecraft file (auto-detects format)
const data = await minecraftNBT.readFile('level.dat');

// Edit a value
minecraftNBT.setValue(data, 'Data.GameType', { type: 'int', value: 1 });

// Save back to file
await minecraftNBT.writeDATFile('level.dat', data);

API Reference

Core Methods

File Operations

// Universal file reader (auto-detects format)
const data = await minecraftNBT.readFile(filepath);

// Specific format readers
const nbtData = await minecraftNBT.readNBTFile('structure.nbt');
const datData = await minecraftNBT.readDATFile('level.dat');
const mcaData = await minecraftNBT.readMCAFile('r.0.0.mca');
const snbtData = await minecraftNBT.readSNBTFile('data.snbt');
const jsonData = await minecraftNBT.readJSONFile('config.json');

// Specific format writers
await minecraftNBT.writeNBTFile('output.nbt', nbtData);
await minecraftNBT.writeDATFile('output.dat', datData);
await minecraftNBT.writeMCAFile('output.mca', mcaData);
await minecraftNBT.writeSNBTFile('output.snbt', snbtData);
await minecraftNBT.writeJSONFile('output.json', jsonData);

// High-performance async MCA operations
const mcaData = await minecraftNBT.readMCAFileAsync('r.0.0.mca', { lazy: true });
await minecraftNBT.writeMCAFileAsync('output.mca', mcaData);

// Bulk operations for multiple files
const mcaFiles = await minecraftNBT.readMultipleMCAFiles(['r.0.0.mca', 'r.0.1.mca']);
await minecraftNBT.writeMultipleMCAFiles(mcaFiles);

// Process entire directories
await minecraftNBT.processMCADirectory('./world/region', async (mca, filepath) => {
    // Your processing logic
    return { processed: true };
});

Format Conversion

// Convert to SNBT (Stringified NBT)
const snbtString = minecraftNBT.toSNBT(nbtData, pretty = true);
const nbtFromSNBT = minecraftNBT.fromSNBT(snbtString);

// Convert to JSON
const jsonObject = minecraftNBT.toJSON(nbtData);
const nbtFromJSON = minecraftNBT.fromJSON(jsonObject, inferTypes = true);

Buffer Operations (Remote/Blob Support)

// Parse NBT data from buffers (useful for remote files, SFTP, APIs)
const buffer = await yourAdapter.read('level.dat'); // User provides buffer from any source
const nbtData = minecraftNBT.parseNBT(buffer);      // Parse uncompressed NBT
const datData = minecraftNBT.parseCompressedNBT(buffer); // Parse compressed NBT (.dat files)

// Convert NBT data back to buffers
const nbtBuffer = minecraftNBT.stringifyNBT(nbtData);           // Create uncompressed buffer
const compressedBuffer = minecraftNBT.stringifyCompressedNBT(nbtData); // Create compressed buffer

// Example: Remote file editing via user-provided adapter
const remoteBuffer = await sftpClient.get('/server/world/level.dat');
const levelData = minecraftNBT.parseCompressedNBT(remoteBuffer);
minecraftNBT.setValue(levelData, 'Data.GameType', { type: 'int', value: 1 });
const modifiedBuffer = minecraftNBT.stringifyCompressedNBT(levelData);
await sftpClient.put(modifiedBuffer, '/server/world/level.dat');

Data Manipulation

// Get nested values
const gameType = minecraftNBT.getValue(levelData, 'Data.GameType');
const playerHealth = minecraftNBT.getValue(playerData, 'Health');

// Set nested values
minecraftNBT.setValue(levelData, 'Data.Time', { type: 'long', value: 6000n });
minecraftNBT.setValue(playerData, 'Health', { type: 'float', value: 20.0 });

// Create new structures
const compound = minecraftNBT.createCompound({
    name: 'TestWorld',
    version: 1,
    settings: { difficulty: 2 }
});

const list = minecraftNBT.createList([1, 2, 3, 4], 'int');

Validation and Inspection

// Validate NBT structure
const errors = minecraftNBT.validate(nbtData);
if (errors.length > 0) {
    console.log('Validation errors:', errors);
}

// Pretty-print structure
console.log(minecraftNBT.inspect(nbtData, maxDepth = 3));

MCA (Region File) Operations

const { MCAFile } = require('mc-nbt-lib');

// Load region file (standard sync method)
const mca = await MCAFile.load('r.0.0.mca');

// Load with async performance improvements
const mcaAsync = await MCAFile.loadAsync('r.0.0.mca', {
    lazy: true,           // Load chunks on-demand (saves memory)
    maxConcurrency: 10    // Process up to 10 chunks concurrently
});

// Get chunk data
const chunk = mca.getChunk(0, 0); // chunk coordinates within region
const chunkAsync = await mcaAsync.getChunkAsync(0, 0); // Lazy-loaded chunk

// Set chunk data
mca.setChunk(0, 0, chunkData);

// Remove chunk
mca.removeChunk(0, 0);

// Get all chunks
const allChunks = mca.getAllChunks();

// Extract specific data from all chunks
const biomes = mca.extractData('Level.Biomes');
const heightmaps = mca.extractData('Level.Heightmaps.MOTION_BLOCKING');

// Get region info
console.log('Chunk count:', mca.getChunkCount());
console.log('Region bounds:', mca.getRegionBounds());

// Save region file
await mca.save('modified_region.mca');          // Standard save
await mca.saveAsync('modified_region.mca');     // Async save (faster for large files)

Async MCA Operations (High Performance)

// Load multiple MCA files concurrently
const mcaFiles = await MCAFile.loadMultipleAsync([
    'r.0.0.mca', 'r.0.1.mca', 'r.1.0.mca'
], {
    maxConcurrency: 3,  // Process 3 files at once
    lazy: true          // Memory efficient
});

// Bulk save multiple MCA files
const saveResults = await MCAFile.saveMultipleAsync(mcaFiles, {
    maxConcurrency: 2   // Save 2 files concurrently
});

// Process entire region directory
const result = await MCAFile.processDirectoryAsync('./world/region',
    async (mca, filepath) => {
        // Your processing function
        const chunkCount = mca.getChunkCount();
        const bounds = mca.getRegionBounds();

        // Example: Find and process spawn chunks
        for (let x = 0; x < 32; x++) {
            for (let z = 0; z < 32; z++) {
                const chunk = await mca.getChunkAsync(x, z);
                if (chunk) {
                    // Process chunk data...
                }
            }
        }

        return { chunkCount, bounds };
    },
    {
        maxConcurrency: 4,  // Process 4 files concurrently
        lazy: true          // Memory efficient
    }
);

console.log(`Processed ${result.loadedFiles}/${result.totalFiles} files`);

// Memory management for lazy-loaded files
mca.clearBuffer();                    // Free buffer memory
const memInfo = mca.getMemoryUsage(); // Check memory usage

Performance Comparison

Operation	Standard Method	Async Method	Improvement
Load single large MCA	2000ms	400ms	5x faster
Load 10 MCA files	20000ms	2000ms	10x faster
Memory usage (lazy)	500MB	50MB	90% less
Save with compression	1500ms	300ms	5x faster

Inventory Management

const { InventoryManager } = require('mc-nbt-lib');

// Load player data
const playerData = await minecraftNBT.readDATFile('playerdata/player.dat');
const inventory = new InventoryManager(playerData);

// Remove items by slot
inventory.removeBySlot(0); // Remove item in hotbar slot 0

// Remove items by ID
inventory.removeByItemId('minecraft:stone'); // Remove all stone
inventory.removeByItemId('minecraft:diamond', 5); // Remove up to 5 diamonds

// Remove items by partial name
inventory.removeByPartialName('diamond'); // Remove all diamond items

// Remove by slot range
inventory.removeBySlotRange(0, 8); // Clear hotbar (slots 0-8)
inventory.removeBySlotRange(36, 39); // Clear armor slots

// List current inventory
const items = inventory.listItems();
console.table(items);

// Clear entire inventory
inventory.clearInventory();

// Save changes
await minecraftNBT.writeDATFile('playerdata/player.dat', playerData);

// Quick utility functions
await minecraftNBT.removeInventorySlot('player.dat', 0);
await minecraftNBT.removeInventoryItem('player.dat', 'minecraft:stone');
await minecraftNBT.clearInventory('player.dat');
const items = await minecraftNBT.listInventory('player.dat');

Data Types

The library supports all NBT tag types with proper JavaScript mappings:

NBT Type	JavaScript Type	Example
Byte	Number (-128 to 127)	`{ type: 'byte', value: 42 }`
Short	Number (-32768 to 32767)	`{ type: 'short', value: 1000 }`
Int	Number (-2³¹ to 2³¹-1)	`{ type: 'int', value: 100000 }`
Long	BigInt	`{ type: 'long', value: 9223372036854775807n }`
Float	Number	`{ type: 'float', value: 3.14 }`
Double	Number	`{ type: 'double', value: 3.141592653589793 }`
String	String	`{ type: 'string', value: 'Hello World' }`
ByteArray	Array	`{ type: 'byte_array', value: [1, 2, 3] }`
IntArray	Array	`{ type: 'int_array', value: [100, 200, 300] }`
LongArray	Array	`{ type: 'long_array', value: [100n, 200n] }`
List	Object	`{ type: 'list', value: { type: 'string', value: ['a', 'b'] } }`
Compound	Object	`{ type: 'compound', value: { key: tag } }`

Inventory Management

Inventory Structure

Minecraft inventory is stored as a list of compound tags where each item contains:

id: Item identifier (e.g., minecraft:diamond_sword)
Count: Stack size (1-64 for most items)
Slot: Inventory slot number (0-40+)
tag: Optional enchantments, durability, custom data

Slot Reference

Slot Range	Description
0-8	Hotbar
9-35	Main inventory
36-39	Armor (boots, leggings, chestplate, helmet)
40	Offhand
103-106	Armor slots (alternative numbering)

InventoryManager Methods

const { InventoryManager } = minecraftNBT;
const inventory = new InventoryManager(playerData);

// Core removal methods
inventory.removeBySlot(slot)                    // Remove by slot number
inventory.removeByItemId(itemId, count = -1)    // Remove by item ID
inventory.removeByPartialName(partial, count)   // Remove by name containing text
inventory.removeBySlotRange(min, max)           // Remove from slot range
inventory.clearInventory()                      // Remove all items

// Information methods
inventory.listItems()                           // Get all items with details
inventory.getInventory()                        // Get raw inventory array
inventory.setInventory(newInventory)            // Set entire inventory

// Example item structure
const item = {
    id: "minecraft:diamond_sword",
    Count: 1,
    Slot: 0,
    tag: {
        Enchantments: [
            { id: "minecraft:sharpness", lvl: 5 },
            { id: "minecraft:unbreaking", lvl: 3 }
        ],
        Damage: 0
    }
};

Examples

Editing Level Data

const minecraftNBT = require('mc-nbt-lib');

async function editLevel() {
    // Load level.dat
    const levelData = await minecraftNBT.readDATFile('level.dat');
    
    // Change to creative mode
    minecraftNBT.setValue(levelData, 'Data.GameType', { type: 'int', value: 1 });
    
    // Set time to noon
    minecraftNBT.setValue(levelData, 'Data.Time', { type: 'long', value: 6000n });
    
    // Enable cheats
    minecraftNBT.setValue(levelData, 'Data.allowCommands', { type: 'byte', value: 1 });
    
    // Save changes
    await minecraftNBT.writeDATFile('level.dat', levelData);
    console.log('Level data updated successfully!');
}

Creating Player Inventory

async function createPlayerWithItems() {
    // Create player data
    const playerData = minecraftNBT.createCompound({
        Health: 20.0,
        foodLevel: 20,
        Pos: [0.0, 64.0, 0.0],
        Inventory: []
    });
    
    // Create enchanted diamond sword
    const diamondSword = minecraftNBT.createCompound({
        id: 'minecraft:diamond_sword',
        Count: 1,
        Slot: 0,
        tag: {
            Enchantments: [
                { id: 'minecraft:sharpness', lvl: 5 },
                { id: 'minecraft:unbreaking', lvl: 3 }
            ]
        }
    });
    
    // Add to inventory
    const inventory = minecraftNBT.getValue(playerData, 'Inventory');
    inventory.value.value.push(diamondSword.value);
    
    // Save player data
    await minecraftNBT.writeDATFile('player.dat', playerData);
}

Working with Region Files

// Standard processing
async function processRegion() {
    const { MCAFile } = minecraftNBT;

    // Load region file
    const mca = await MCAFile.load('r.0.0.mca');

    // Process all chunks
    const chunks = mca.getAllChunks();
    for (const { x, z, data } of chunks) {
        // Get chunk status
        const status = minecraftNBT.getValue(data, 'Level.Status');
        console.log(`Chunk ${x},${z}: ${status?.value}`);

        // Modify biomes (make everything plains)
        const biomes = minecraftNBT.getValue(data, 'Level.Biomes');
        if (biomes && biomes.value) {
            biomes.value.fill(1); // Plains biome ID
        }

        // Update chunk
        mca.setChunk(x, z, data);
    }

    // Save modified region
    await mca.save('modified_region.mca');
}

// High-performance async processing
async function processRegionAsync() {
    const { MCAFile } = minecraftNBT;

    // Load with lazy loading for memory efficiency
    const mca = await MCAFile.loadAsync('r.0.0.mca', {
        lazy: true,
        maxConcurrency: 10
    });

    // Process chunks on-demand (only loads chunks as needed)
    for (let x = 0; x < 32; x++) {
        for (let z = 0; z < 32; z++) {
            const data = await mca.getChunkAsync(x, z); // Lazy load
            if (!data) continue;

            // Process chunk data
            const status = minecraftNBT.getValue(data, 'Level.Status');
            console.log(`Chunk ${x},${z}: ${status?.value}`);

            // Modify biomes
            const biomes = minecraftNBT.getValue(data, 'Level.Biomes');
            if (biomes && biomes.value) {
                biomes.value.fill(1); // Plains biome ID
            }

            // Update chunk
            mca.setChunk(x, z, data);
        }
    }

    // Save with async compression
    await mca.saveAsync('modified_region.mca');

    // Clean up memory
    mca.clearBuffer();
}

// Bulk processing multiple region files
async function processMultipleRegions() {
    const regionFiles = [
        'r.0.0.mca', 'r.0.1.mca', 'r.1.0.mca', 'r.1.1.mca'
    ];

    // Load all files concurrently with lazy loading
    const mcaFiles = await MCAFile.loadMultipleAsync(regionFiles, {
        maxConcurrency: 3,
        lazy: true
    });

    // Process each file
    for (const [filepath, mca] of mcaFiles) {
        console.log(`Processing ${filepath}...`);

        // Process chunks efficiently
        for (let x = 0; x < 32; x++) {
            for (let z = 0; z < 32; z++) {
                const chunk = await mca.getChunkAsync(x, z);
                if (chunk) {
                    // Your processing logic
                }
            }
        }

        // Free memory when done
        mca.clearBuffer();
    }

    // Bulk save all modified files
    await MCAFile.saveMultipleAsync(mcaFiles, { maxConcurrency: 2 });
}

Complete Inventory Management

async function managePlayerInventory() {
    const { InventoryManager } = minecraftNBT;
    
    // Load player data
    const playerData = await minecraftNBT.readDATFile('playerdata/player.dat');
    const inventory = new InventoryManager(playerData);
    
    // List current inventory
    console.log('Current inventory:');
    console.table(inventory.listItems());
    
    // Remove specific items
    inventory.removeBySlot(0); // Remove hotbar slot 0
    inventory.removeByItemId('minecraft:stone', 32); // Remove up to 32 stone
    inventory.removeByPartialName('diamond'); // Remove all diamond items
    
    // Clear equipment slots
    inventory.removeBySlotRange(36, 39); // Clear armor
    inventory.removeBySlotRange(0, 8); // Clear hotbar
    
    // Add new items
    const newSword = minecraftNBT.createCompound({
        id: 'minecraft:netherite_sword',
        Count: 1,
        Slot: 0,
        tag: {
            Enchantments: [
                { id: 'minecraft:sharpness', lvl: 5 },
                { id: 'minecraft:looting', lvl: 3 },
                { id: 'minecraft:unbreaking', lvl: 3 }
            ]
        }
    });
    
    // Add to inventory manually
    const currentInventory = inventory.getInventory();
    currentInventory.push(newSword.value);
    inventory.setInventory(currentInventory);
    
    // Save changes
    await minecraftNBT.writeDATFile('playerdata/player.dat', playerData);
    console.log('Inventory updated successfully!');
}

// Quick inventory operations
async function quickInventoryOps() {
    // One-liner operations
    await minecraftNBT.removeInventorySlot('player.dat', 0);
    await minecraftNBT.removeInventoryItem('player.dat', 'minecraft:stone');
    await minecraftNBT.clearInventory('player.dat');
    
    // List inventory
    const items = await minecraftNBT.listInventory('player.dat');
    console.table(items);
}

// Remove specific item types
async function removeItemTypes() {
    const playerData = await minecraftNBT.readDATFile('playerdata/player.dat');
    const inventory = new InventoryManager(playerData);
    
    // Remove all weapons
    inventory.removeByPartialName('sword');
    inventory.removeByPartialName('axe');
    inventory.removeByPartialName('bow');
    
    // Remove all food
    const foodItems = ['bread', 'apple', 'beef', 'pork', 'chicken', 'fish'];
    foodItems.forEach(food => inventory.removeByPartialName(food));
    
    // Remove damaged items (custom logic)
    const items = inventory.listItems();
    items.forEach(item => {
        if (item.id && item.id.includes('_pickaxe')) {
            inventory.removeBySlot(item.slot);
        }
    });
    
    await minecraftNBT.writeDATFile('playerdata/player.dat', playerData);
}

SNBT and JSON Conversion

// Convert NBT to human-readable SNBT
const nbtData = minecraftNBT.createCompound({
    name: 'TestItem',
    durability: 100,
    enchantments: ['sharpness', 'unbreaking']
});

const snbt = minecraftNBT.toSNBT(nbtData);
console.log('SNBT:', snbt);
// Output: {name:"TestItem",durability:100,enchantments:["sharpness","unbreaking"]}

// Convert to JSON for easy manipulation
const json = minecraftNBT.toJSON(nbtData);
console.log('JSON:', JSON.stringify(json, null, 2));

// Convert back to NBT
const backToNBT = minecraftNBT.fromJSON(json);

Error Handling

The library provides comprehensive error handling:

try {
    const data = await minecraftNBT.readFile('nonexistent.dat');
} catch (error) {
    if (error.message.includes('ENOENT')) {
        console.log('File not found');
    } else {
        console.log('Parse error:', error.message);
    }
}

// Validate data before saving
const errors = minecraftNBT.validate(nbtData);
if (errors.length > 0) {
    console.error('Invalid NBT data:', errors);
    return;
}

Performance

The library is optimized for performance with both synchronous and asynchronous operations:

Standard Performance

Streaming: Large files are processed efficiently without loading everything into memory
Binary Parsing: Direct buffer operations for maximum speed
Minimal Allocations: Reuses buffers where possible
Compression: Built-in gzip/zlib support for DAT files

Async Performance Improvements

Non-blocking Operations: Uses async compression to avoid blocking the event loop
Parallel Processing: Concurrent chunk processing with configurable concurrency limits
Lazy Loading: Load chunk headers immediately, decompress chunks only when accessed
Bulk Operations: Process multiple MCA files simultaneously
Memory Optimization: Lazy loading can reduce memory usage by 50-90%

Performance Benchmarks

Standard Operations (on modern hardware)

Parse 1MB NBT file: ~50ms
Convert to SNBT: ~10ms
Load MCA region file: ~100-200ms

Async Operations Performance

Operation	Standard	Async	Improvement
Load single large MCA (100MB)	2000ms	400ms	5x faster
Load 10 MCA files concurrently	20000ms	2000ms	10x faster
Process 50 region files	100s	15s	6.7x faster
Memory usage (lazy loading)	500MB	50MB	90% reduction
Save large MCA with compression	1500ms	300ms	5x faster

Async Options

const options = {
    lazy: true,           // Enable lazy loading (default: false)
    maxConcurrency: 10    // Concurrent operations (default: 10 for chunks, 5 for files)
};

// Memory-efficient loading
const mca = await MCAFile.loadAsync('huge-region.mca', { lazy: true });

// High-speed bulk processing
const mcaFiles = await MCAFile.loadMultipleAsync(filePaths, {
    maxConcurrency: 5,
    lazy: true
});

The async methods provide massive performance improvements for:

Production Minecraft servers processing many region files
World conversion tools handling large datasets
Batch processing scripts that need to remain responsive
Memory-constrained environments where lazy loading is essential

Requirements

Node.js 12.0.0 or higher
No external dependencies (uses only Node.js built-in modules)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests for any improvements.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github/workflows		.github/workflows
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
examples.js		examples.js
inventory-management.js		inventory-management.js
mc-nbt.js		mc-nbt.js
mca-handler.js		mca-handler.js
nbt-core.js		nbt-core.js
package-lock.json		package-lock.json
package.json		package.json
snbt-converter.js		snbt-converter.js

License

flaasz/mc-nbt

Folders and files

Latest commit

History

Repository files navigation

Minecraft NBT Library

Features

Installation

Quick Start

API Reference

Core Methods

File Operations

Format Conversion

Buffer Operations (Remote/Blob Support)

Data Manipulation

Validation and Inspection

MCA (Region File) Operations

Async MCA Operations (High Performance)

Performance Comparison

Inventory Management

Data Types

Inventory Management

Inventory Structure

Slot Reference

InventoryManager Methods

Examples

Editing Level Data

Creating Player Inventory

Working with Region Files

Complete Inventory Management

SNBT and JSON Conversion

Error Handling

Performance

Standard Performance

Async Performance Improvements

Performance Benchmarks

Standard Operations (on modern hardware)

Async Operations Performance

Async Options

Requirements

License

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Languages