The Magic Block and Phases#

ChunkBlock's magic block is the AOneBlock engine, carried over deliberately unchanged. Everything about phase files — the weighted block and mob pools, fixedBlocks, holograms, chests and rarities, custom blocks, version gating, start and end commands, requirements, the phase index — works exactly as it does in AOneBlock, and the file formats are identical.

That means:

• Community phase packs work verbatim. A phase file written for AOneBlock drops into ChunkBlock's phases folder and runs.
• You can copy your own AOneBlock phases across without editing them.
• Fixes and features from upstream arrive here too, because the engine is kept in step rather than forked.

This page covers what is specific to ChunkBlock.

What ships#

Twenty phases, 15,500 blocks of content on a Minecraft 26.2+ server:

Sulfur Caves needs Minecraft 26.2 or later. It declares requiredMinecraftVersion: '26.2' in the index, so on older servers it is skipped with a single info log line — the phase takes up no blocks at all and Jagged Peaks simply runs to the loop point instead. That server has 19 phases and 15,000 blocks.

After the last phase the block count jumps back to gotoAtEnd in phases_index.yml, which is 0 by default, so the progression loops.

Where the files live#

plugins/BentoBox/addons/ChunkBlock/
├── config.yml
├── phases_index.yml          ← order, length, enabled, version gate
├── panels/
│   └── phases_panel.yml      ← the /ch phases GUI template
└── phases/
    ├── 0_plains.yml          ← blocks, mobs, holograms, commands
    ├── 0_plains_chests.yml   ← the loot for that phase
    ├── 700_underground.yml
    └── …

Files in phases/ are never overwritten on upgrade, so your edits survive. New phases shipped in a later jar are restored into the index automatically by reconciliation.

The phase index#

phases_index.yml is the source of truth for which phases load, in what order, how long each one is, and which Minecraft version each one needs. It is read before any phase file is parsed, so a phase that needs a newer Minecraft version is skipped without its YAML — or any item inside it — ever being touched.

Each entry takes these fields:

Start blocks are computed: the running sum of the lengths of the enabled phases above, starting at 0. Phases can be reordered freely, and a skipped phase collapses out of the progression.

A top-level adminLengths: true is written automatically the first time you edit a length in the panel. From then on reconciliation never recomputes lengths, so your values survive later file additions, renames and upgrades.

Reconciliation#

The index is reconciled against the files actually on disk on every load and on every save from the admin panel, so what /chadmin phases shows is what your server really runs. Watch the startup log for lines beginning Phase index: — they say exactly what changed.

• An entry whose file was renamed across addon versions is re-pointed at your file by phase name.
• An entry whose file is missing but shipped in the jar is restored automatically. This is how new phases appear on upgraded servers, given that phases/ is never overwritten.
• Custom phase files dropped into the folder are added automatically. A numeric key slots in at its legacy start block; anything else is appended at the end for you to arrange in the panel.
• Entries whose files are gone for good are removed with a warning.

The phase order editor#

/chadmin phases (permission chunkblock.admin.phases, OP by default) shows every phase in order with its computed start block, length and state. It edits phases_index.yml, and drops and toggles save the index and reload the phases immediately.

• Left-click a phase to pick it up — the rest shrink left. Click where it should go to shove the others right and drop it, or use the drop-at-end slot. Click anywhere else, or close the panel, to put it back without saving.
• Right-click toggles a phase on or off.
• Shift-left-click sets a phase's length. The panel closes and a chat prompt shows the current length; type a whole number to apply it, or cancel to keep it. Invalid input re-prompts and the prompt times out after 60 seconds. The first length edit writes adminLengths: true into the index.

Disabled phases show as grey glass and version-locked ones as barriers — both can still be reordered. A phase with no configured icon uses its first block.

Players and phases#

• /ch count — the current block count and phase, in chat.
• /ch phases — the phases GUI. Requires chunkblock.phases, which is off by default.
• /ch setcount <number> — replay a phase already reached. Requires chunkblock.island.setcount (OP by default) and obeys the set-count-cooldown config value, 5 minutes by default.
• /ch check — respawn the magic block if it has gone missing, or show its particles so you can find it.
• /ch bossbar / /ch actionbar — toggle the progress displays, if bossbar / actionbar are enabled in config.yml.

Holograms above the magic block are on by default (world.holograms: true), use native Minecraft text entities, and disappear after hologram-duration seconds.

Admin phase tools#

• /chadmin setcount <player> <number> [lifetime] — set a player's block count, or their lifetime count.
• /chadmin setchest <phase> <rarity> — the easy way to build loot. Fill a chest in-game with what you want, look at it, and run the command with the phase name and a rarity of COMMON, UNCOMMON, RARE or EPIC. The chest is written into that phase's chest file, ready to use. Deleting chests still means editing the file and reloading.
• /chadmin sanity [<phase>] — reports the phase probabilities in the console, so you can see what your weights actually add up to.
• /chadmin phases — the order editor described above.

ChunkBlock-specific notes#