Capsule

Press one key to capture blocks, entities, and NBT around the player into a .cap file, then restore anywhere — even on servers.

Version	v26.0 Alpha 1
Loader	Fabric
Minecraft	1.20.4
Java	17+
Author	NDBlockConnect@StarsailsClover
License	MIT
Repository	https://github.com/NDBlockConnect/Capsule

Overview

Capsule is a Minecraft Java Edition Fabric mod that performs violent region capture: press one key to grab every block, block entity NBT, entity, and (optionally) biome/lighting data inside a configurable radius around the player, serialize it into a compressed .cap file, and paste it back into any world — single-player, LAN, or dedicated server.

Features (P0)

• Configurable hotkey capture (default: Ctrl+Shift+C)
• Cube or sphere region shapes, radius up to 1024 blocks
• Per-block palette compression for compact storage
• ZSTD compression with automatic GZIP fallback
• Async, tick-budgeted capture and restore — no main-thread freeze
• Configurable restore modes: merge, overwrite, preview
• /capsule capture|restore|list|info command surface
• HUD progress bar and chat feedback
• Server-side operation — works without client install on dedicated servers

Quick Start

1. Drop the built JAR into .minecraft/mods/.
2. Launch the game. A config/capsule.json is generated on first run.
3. Press Ctrl+Shift+C (default) to capture a region around you.
4. Press Ctrl+Shift+V (default) to restore the most recent capture at your position.
5. Use /capsule list to see previous captures and /capsule restore <filename> to pick one.

For fast iteration, launch the game with MCDebugLauncher v26.0-alpha.5.1.

Configuration

{
  "capture": {
    "radius": 32,
    "shape": "cube",
    "include_entities": true,
    "include_block_entities": true,
    "force_load_chunks": false,
    "max_blocks_per_tick": 8192,
    "keybind_capture": "LEFT_CONTROL+LEFT_SHIFT+C",
    "keybind_restore": "LEFT_CONTROL+LEFT_SHIFT+V"
  },
  "restore": {
    "mode": "merge",
    "max_blocks_per_tick": 8192
  },
  "storage": {
    "compression": "zstd",
    "directory": "captures"
  }
}

The config is hot-reloadable. Run /capsule reload to apply changes without restart.

Commands

Command	Description
/capsule capture [radius]	Capture region around the player
/capsule restore <filename>	Restore a capture at the player position
/capsule restore	Restore the most recent capture
/capsule list [page]	List saved captures
/capsule info <filename>	Show metadata for a capture
/capsule reload	Reload config

Storage Format

A .cap file is a single compressed NBT container with the following structure:

root
├── meta            # version, time, source world, origin, radius, shape, mod fingerprint
├── blocks          # palette (registry name + properties) + packed positions + indices
├── block_entities  # relative positions + NBT
├── entities        # relative positions + NBT (P2)
└── biomes          # relative positions + biome id (P1+)

Block states are stored as minecraft:name + property map — never numeric IDs — so captures remain portable across minor Minecraft versions when block registries are stable.

Roadmap

Phase	Scope
P0	Block capture + NBT storage + basic restore (this release)
P1	Block entity NBT (chest contents, signs, furnaces, etc.)
P2	Entity capture and restore with UUID remap
P3	Preview mode + rotate/mirror transforms
P4	World clone (independent new save)
P5	In-game GUI browser + screenshot preview

Build

.\gradlew.bat build

Output JAR: build/libs/capsule-26.0-alpha.1.jar.

License

MIT — see LICENSE.