World Importer

A Minecraft mod designed to upload and paste local world MCA region files to a server.

The client parses MCA files, extracts NBT data chunk by chunk, and uploads it to the server. The server replaces chunks (blocks, biomes, block entities) in real-time without requiring a restart. After the import is complete, it automatically recalculates lighting and synchronizes the chunks with all players.

Supports Fabric / Forge / NeoForge, compatible with Minecraft 1.19 ~ 1.20.6.

! WARNING: This mod will directly overwrite all chunks from the MCA file onto the server! Do not paste in areas with existing builds! It is highly recommended to make a backup before pasting!

Versions

Usage

1. Install the mod on both the client and the server.
2. Join the server, stand at the target location, and execute /wi setpos to set the paste origin.
3. Execute /wi select <path> to select the local world's region folder (or press K to open the configuration GUI and fill it in).
4. Execute /wi start to begin the upload (or click "Start Upload" in the configuration GUI).
5. Wait for the import to complete (the HUD will display a progress bar and TPS).
6. After the import finishes, lighting will automatically update and chunks will sync.

Commands

All commands require OP permissions (Level 2).

Configuration

Press the K key to open the configuration GUI (also accessible via Mod Menu on Fabric). You can adjust:

When Auto-throttle is enabled:

• TPS ≥ 18: Uses the configured upload interval.
• TPS ≤ 15: Automatically throttles down to the maximum interval (40 ticks).
• Linear interpolation is used for values in between.

The configuration file is saved at .minecraft/config/world_importer.json.

HUD

During the import process, the top of the screen displays:

• Importing — Green progress bar + Completed / Total.
• Lighting Update — Cyan progress bar.
• Syncing Chunks — Purple progress bar.
• The right side of the progress bar displays the server TPS (Green/Yellow/Red).

Building

# Build all versions and all loaders
./gradlew build

# Build only all Fabric versions
./gradlew build -Ploader=fabric

# Build only all Forge/NeoForge versions
./gradlew build -Ploader=forge

# Build only a specific MC version
./gradlew build -Pver=1201

# Combination: Build only 1.20.4 for Fabric
./gradlew build -Pver=4 -Ploader=fabric

# Run client (default is 1.20.1 Fabric)
./gradlew runClient

# Run client: Specify version and loader
./gradlew runClient -Pver=4 -Ploader=forge

# Run server
./gradlew runServer -Pver=1 -Ploader=fabric

# Collect all jars into release/
./gradlew collectJars

# Clean everything
./gradlew cleanAll

Supported -Ploader values: fabric, forge

Technical Details

• The client parses the MCA binary format (4096-byte header → sector offsets → extracts compressed NBT chunk by chunk).
• The server decompresses the NBT → parses the PalettedContainer (block states + biomes) in the sections → replaces the entire section → recalculates heightmaps → loads block entities.
• Light updates use the chunk NBT overwrite method → clears original lighting data and recalculates it.
• Traffic control: The server only notifies the client to send the next chunk after finishing the previous one, combined with TPS auto-throttling.
• Finally, it deletes the client's original chunk render cache and sends the updated chunks to the client.

Dependencies

• Architectury API
• Mod Menu (Optional for Fabric)

License

MIT License © rolling_cat

————————

简体中文