NbtMapper - Automatic Map Art Builder

Disclaimer: This mod is intended for map art building and creative projects. Use on multiplayer servers only if permitted by the server rules.

A Fabric client-side mod that helps you build map art from NBT structure files. Load your structure, set the coordinates, and the mod assists with movement, inventory management, block placement, and resupply.

Requirements

• Minecraft 1.21.11
• Fabric Loader 0.18.2+
• Fabric API
• Java 21+
• A server with teleport commands (e.g., /home, /warp) for auto-resupply

Installation

1. Install Fabric Loader for Minecraft 1.21.11
2. Download and place the mod .jar into your mods/ folder
3. Make sure Fabric API is also in the mods/ folder
4. Launch the game

Quick Start

1. Place your .nbt structure files into <game_dir>/nbtmapper/
2. In-game, press Z to open the GUI
3. Go to the Tasks tab, click an NBT file to load it
4. On the Main tab, click New Site to set the build origin (auto-snaps to 128-block map grid)
5. Configure your storage chests in the Storage tab (chest coordinates for each block type)
6. Set your teleport commands in the Settings tab
7. Click Start — the mod handles the rest

Features

Fully Automated Building

• Loads NBT structures and places blocks in an optimized snake pattern
• Automatically places cobblestone bases before carpet/surface blocks
• Prefills nearby same-type blocks while in range for extra speed
• Skips already-correct blocks instantly

Auto Resupply

• Detects when inventory is low on a block type
• Uses server teleport commands (e.g., /home, /warp) to travel to your configured storage area
• Batch supply: fetches multiple block types in a single trip
• Consolidates split stacks in inventory after fetching

Auto-Next Map

• When a map completes, automatically loads the next NBT file (alphabetical order)
• Offsets the build origin along X axis by the previous map's width
• Perfect for building multi-map art pieces side by side
• Toggle on/off via the Auto button on the Main tab

Session Persistence

• Progress is auto-saved every 10 seconds
• Remembers last loaded file, origin, settings, and running state
• Resumes automatically after game restart if building was active

Safety Features

• Loop detection: auto-pauses if stuck in a loop, resumes after 20 seconds
• Block verification: checks previously placed blocks to ensure correctness
• Stuck detection: repositions the player if they get stuck during building
• Max retry limits on movement and placement attempts
• Automatic error recovery during movement

GUI Overview

Press Z to open. The GUI has 4 tabs:

Main Tab

• Build origin coordinates (read-only, set via New Site)
• Large Start/Pause button
• Progress display with manual set/reset
• Auto toggle (auto-load next map on completion)
• Debug toggle (shows real-time HUD overlay)

Tasks Tab

• Lists all .nbt files in the nbtmapper/ folder
• Click to load, X to delete
• Shows progress count and [done] marker for completed maps
• Open NBT Folder button for quick access

Storage Tab

• Maps each block type to a chest location (X/Y/Z)
• Edit coordinates directly in the GUI
• Auto-saves on change

Settings Tab

• TP to Store: command to teleport to your storage area
• TP to Worksite: command to return to the build site
• Update Home: command to update your home position before supply runs
• Move Mode: Walk / Sprint / Creative Fly / Always Fly / Elytra

Configuration Files

All config files are stored in <game_dir>/nbtmapper/:

File	Purpose
storage.json	Block-to-chest coordinate mappings and teleport commands
settings.json	Origin, move mode, auto-next, last loaded file, running state
<name>_progress.json	Per-map build progress

Movement Modes

Mode	Description
Walk	Standard ground movement
Sprint	Sprinting ground movement
Creative Fly	Creative mode flight, disables on arrival
Always Fly	Creative mode flight, stays enabled
Elytra	Elytra-based flight

How It Works

The mod runs a state machine on each client tick:

NEXT → EQUIPPING → MOVING → PLACING → NEXT → ...
                                ↘ SUPPLYING (when low on blocks)

• NEXT: Finds the next block to place, skips air/completed blocks in bulk
• EQUIPPING: Switches hotbar to the correct block
• MOVING: Navigates to within 4 blocks of the target
• PLACING: Places the block and prefills nearby same-type blocks
• SUPPLYING: Teleports to storage, fetches blocks, returns

Multiple states can chain in a single tick for efficient building.

NBT File Format

The mod reads standard Minecraft structure NBT files (.nbt). These can be created with:

• Structure blocks in-game
• External tools like NBT Studio or Amulet Editor
• Map art generators that export to NBT format
• Recommended: Online map art generators such as MapartCraft can convert images to NBT files

The mod reads the palette (block types) and blocks (positions), keeping only the topmost block per X/Z column.

Important Notes

• Client-side only: This mod runs entirely on the client. No server-side installation needed.
• Server rules: Always ensure your server permits building assistance tools before use.
• Teleport commands: The resupply system relies on server-provided teleport commands (e.g., Essentials /home, /warp). Configure these in the Settings tab.
• Creative fly: The default move mode requires creative flight ability. Switch to Walk/Sprint if playing in survival without fly permissions.
• Backup: The mod places blocks in the world. Always have backups of important builds.
• First run: On first launch, storage.json is created with default chest coordinates that won't match your server. You must configure your own chest locations in the Storage tab.

Keybindings

Key	Action
Z	Open/close GUI (auto-pauses when opening)