Customizing AOneBlock Phases#

Everything a player mines out of the magic block comes from a phase file. This page explains how those files work, what every number in them means, and how to build your own phases.

Where the files live#

After the addon has run once, the files are in:

plugins/BentoBox/addons/AOneBlock/
├── config.yml
├── phases_index.yml          ← which phases load, in what order, and how long each is
└── phases/
    ├── 0_plains.yml          ← the blocks, mobs, holograms and settings of a phase
    ├── 0_plains_chests.yml   ← the loot tables of that phase
    ├── 700_underground.yml
    ├── 700_underground_chests.yml
    └── ...

Every phase is a pair of files: <name>.yml and <name>_chests.yml. The chest file is paired by file name, so if you rename one you must rename the other.

After editing any of these files, reload the addon (/bbox reload) or restart the server.

The three kinds of number#

This is the part that trips people up. A phase file contains three completely different kinds of number, and which is which depends entirely on the section it is in.

Weights — the blocks: and mobs: sections#

How the roll works#

Every time a player breaks the magic block, AOneBlock:

1. Adds up every weight in the current phase — all of blocks:, all of mobs:, and all of custom-blocks:.
2. Picks a random number in that range and returns whichever entry it lands on.

So:

chance of an entry = its weight ÷ total of all weights in the phase

A weight is not a quantity. STONE: 1000 does not mean a thousand stone will be generated during the phase — it means stone gets 1000 tickets in the raffle, and it is rolled fresh on every single block break.

Worked example#

'2500':
  name: Winter
  firstBlock: SNOW_BLOCK
  biome: SNOWY_TAIGA
  blocks:
    COBBLESTONE: 900
    SAND: 100
    DIRT: 200
    STONE: 1000
    SPRUCE_LEAVES: 500

The weights total 900 + 100 + 200 + 1000 + 500 = 2700, so:

Over a 1000-block phase you would expect about 370 stone, but every break is an independent roll, so the real count wobbles around that figure.

Only the ratio matters#

blocks:
  STONE: 1000
  DIRT: 200

behaves identically to

blocks:
  STONE: 10
  DIRT: 2

The shipped files use large numbers on purpose: with a total in the thousands you can add a rare entry at weight 5 without having to rescale everything else to keep the percentages sensible.

Blocks and mobs share one pool#

The shipped Plains phase makes this concrete. Its blocks: weights total 11450 and its mobs: weights total 665, for a phase total of 12115:

Tuning recipes#

Rules and gotchas#

• A weight must be a whole number of 1 or more. 0, a negative value or a decimal is rejected and logged as Bad item weight for <phase>: <material>.
• The material must be a real Bukkit Material that is a block. Items like DIAMOND will be logged as Bad block material.
• Mobs must be a live, spawnable EntityType. Invalid names log the full list of valid ones on startup.
• If a phase has no valid weights at all, it logs has zero probability of generating blocks and falls back to a single block type — check the section name spelling.

CHEST is a special case#

When CHEST is rolled from the pool, AOneBlock fills it from that phase's _chests.yml file. So the CHEST weight is the chance of getting a chest; which chest you get is a second, separate roll on rarity:

These rarity chances are fixed in code and are not configurable. If a rarity has no chests defined for the phase, the COMMON list is used instead; if there are no chests at all, a plain empty chest is placed.

Mobs#

When a mob is rolled, the magic block becomes STONE if it was empty and the mob spawns on top of it. With clear-blocks: true in config.yml, blocks in the way are cleared so large mobs fit.

mobs:
  COW: 150
  SPIDER: 75
  SHEEP: 75
  PIG: 150
  VILLAGER: 15
  CHICKEN: 200

Positions — fixedBlocks and holograms#

The keys in these two sections are positions within the phase, counting from 0. Position 0 is the first block of the phase, 1 the second, and so on. They are not the player's overall block count, and a position larger than the phase length is simply never reached.

fixedBlocks#

Fixed blocks are guaranteed — they bypass the weighted pool entirely. Use them for scripted moments.

fixedBlocks:
  0: GRASS_BLOCK
  1: GRASS_BLOCK
  2: GRASS_BLOCK
  3: OAK_LOG
  4: OAK_LOG
  5: OAK_LOG
  700: CHEST_WITH_WATER_BUCKET

• Defining position 0 here replaces firstBlock, which is then no longer needed.
• CHEST_WITH_<ITEM> is a shorthand that places a chest holding a single item of that material — handy for giving players a water bucket before the Ocean phase.
• Prefer blocks that do not need support. A torch, rail or sapling placed as the magic block just pops off.
• A fixed block entry can also be a custom block definition.

holograms#

Same numbering, but the value is the text to float above the magic block. & colour codes work.

holograms:
  0: "&aFirst block is grass!"
  1: "&aSecond block is grass!"
  3: "&aGood Luck!"

The very first hologram — the one shown before phase 1 begins — lives in the addon's locale file, not here.

Phase order and length — phases_index.yml#

phases:
  - file: 0_plains
    section: '0'
    name: Plains
    length: 700
  - file: 700_underground
    section: '700'
    name: Underground
    length: 1300
gotoAtEnd: 0

Start blocks are computed: each phase starts at the running total of the lengths of the enabled phases above it, beginning at 0. Reorder phases freely; a disabled or skipped phase collapses out of the progression. After the last phase the block count jumps to gotoAtEnd.

The easiest way to change all of this is in game with /[admin_command] phases, which edits the index for you. See the phase order editor notes. Once you edit a length there, adminLengths: true is written into the index and your lengths are never recomputed.

Anatomy of a phase file#

'0':                          # section name (see phases_index.yml)
  name: Plains                # display name
  icon: GRASS_BLOCK           # icon in the phases GUI (BentoBox ItemParser)
  firstBlock: GRASS_BLOCK     # the block for position 0 (optional)
  biome: PLAINS               # biome at the magic block location
  requiredMinecraftVersion: '1.21.6'   # optional version gate

  fixedBlocks: { ... }        # guaranteed blocks at positions
  holograms: { ... }          # text at positions

  blocks: { ... }             # weighted pool of blocks
  mobs: { ... }               # weighted pool of mobs — same pool
  custom-blocks: [ ... ]      # weighted pool of custom entries — same pool

  start-commands: [ ... ]
  end-commands: [ ... ]
  end-commands-first-time: [ ... ]
  requirements: { ... }

requirements:
  bank-balance: 10000
  level: 10
  permission: ready.for.battle
  cooldown: 60

Commands on phase change#

Commands run as the console unless prefixed with [SUDO], in which case they run as the player who triggered them.

Placeholders substituted into the command string:

start-commands:
- 'give [player] WOODEN_AXE 1'
- 'broadcast [player] just started OneBlock!'
end-commands-first-time:
- 'broadcast &c&l[!] &b[player] &fhas completed the &d&n[phase]&f phase for the first time.'

Chests#

Chests live in the phase's _chests.yml file, under the same top-level section name:

'0':
  chests:
    '1':
      rarity: COMMON
      contents:
        0: ==: org.bukkit.inventory.ItemStack ...
    '2':
      rarity: EPIC
      contents:
        ...

• The number keying each chest ('1', '2') is just a unique id — it is neither a weight nor a position. When a chest of a given rarity is due, one of the chests of that rarity is picked at random with equal probability.
• contents keys are inventory slot numbers.
• rarity is COMMON, UNCOMMON, RARE or EPIC.

Custom blocks#

custom-blocks: is a list of entries that are not plain materials. Each entry has a probability: field which — despite the name — is a weight, in exactly the same pool as blocks: and mobs:. probability: 10 is as likely as a block with weight 10.

custom-blocks:
  - type: block-data
    data: minecraft:chest[waterlogged=true]
    probability: 10
  - type: mob
    mob: ZOMBIE
    underlying-block: STONE
    probability: 5
  - type: itemsadder
    id: mypack:ruby_ore
    probability: 10

Custom blocks can also be used in fixedBlocks, as an object instead of a material name:

fixedBlocks:
  0:
    type: block-data
    data: minecraft:chest[waterlogged=true]
  1: GRASS_BLOCK

- type: mob-data
  data: 'breeze{CustomName:[{text:"Breezy",color:"#f90606"}],Glowing:1b}'
  underlying-block: STONE
  probability: 10

If a custom block's plugin is not installed, the block falls back to STONE and a line is written to the log.

Version gating#

A phase, an individual block or an individual mob can declare the minimum Minecraft version it needs. Anything the server is too old for is skipped with one info line in the log instead of a Tried to load invalid item error.

Whole phase — put requiredMinecraftVersion in phases_index.yml so the file is not even parsed on an old server. The phase then takes up no blocks and the phases after it collapse up.

A single block or mob — use the object form, which swaps the bare weight for a weight: field:

blocks:
  NETHERRACK: 300
  DRIED_GHAST:
    weight: 25
    requiredMinecraftVersion: '1.21.6'

mobs:
  ZOMBIFIED_PIGLIN: 100
  HAPPY_GHAST:
    weight: 5
    requiredMinecraftVersion: '1.21.6'

Chest files are read item by item, so an item your server version does not know is skipped on its own and the rest of the chest still loads.

Building a new phase#

1. Copy an existing pair of files in the phases folder — say 4000_jungle.yml and 4000_jungle_chests.yml — to volcano.yml and volcano_chests.yml.
2. Change the top-level key in both files to something unique, e.g. volcano:. It must match in both.
3. Set name: and icon:, then edit blocks: and mobs: with the weights you want. Remember the percentages are relative to the phase total.
4. Restart or reload. The addon notices the new file, adds it to phases_index.yml at the end of the order with the default length of 500, and logs: Phase index: added Volcano from volcano.yml at the end of the phase order. Move it with the admin phases GUI.
5. Position it with /[admin_command] phases — left-click to pick it up, click where it should go, shift-left-click to set its length.
6. Test it with /[admin_command] setcount <player> <number> to jump straight to the phase's start block.

Troubleshooting#

Watch the server log at startup. Every phase file loaded is logged, as is every rejected block, mob and item, and every change the index reconciler makes (lines beginning Phase index:).