AOneBlock#
One block. That's it. That's where you start.
Mine it and it comes back as something else — a grass block, a tree, a chest, a mob. Mine it again. Keep going. Slowly, painstakingly, you build an island from nothing, unlocking new phases as you progress: Plains, Underground, Ocean, Jungle, Nether, and beyond. Each phase brings new blocks, new mobs, and new surprises. Some very hostile surprises.
AOneBlock is BentoBox's take on IJAminecraft's beloved OneBlock map — rebuilt as a full multiplayer server experience with 20 themed phases, 15,000+ blocks of content, loot chests of varying rarity, and enough depth to keep players coming back for weeks.
Created and maintained by tastybento.
Useful links
Installation#
- Install BentoBox and run it on the server at least once to create its data folders.
- Place this jar in the addons folder of the BentoBox plugin.
- Restart the server.
- The addon will create worlds and a data folder and inside the folder will be a config.yml and config files in phases folder.
- Stop the server.
- Edit config.yml and the .yml config files how you want.
- Delete any worlds that were created by default if you made changes that would affect them.
- Restart the server.
Configuration#
The main config.yml file contains basic information about game-mode addon setup.
phases contains all information about phases that will be present in your AOneBlock world.
panels allows you to customize some user accessible panels.
config.yml#
After addon is successfully installed, it will create a config.yml file. Every option in this file comes with comments about them. Please check file for more information. You can find the latest config file: config.yml
Since AOneBlock 1.27.0 — island.save-every
How often island progress is written to the database, in blocks broken. Progress is also saved on every phase change, when a player logs out, and at shutdown, so this only decides how much can be lost if the server dies without shutting down cleanly (a crash, a kill -9, a hosting-panel force-restart). Lower is safer but writes more often; the minimum is 1.
Default: 10 (replacing the old hardcoded 50). Existing configs pick up the default automatically.
The Phase Index — phases_index.yml#
Added in AOneBlock 1.26.0
phases_index.yml sits next to the phases folder and 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 — and any items inside it — ever being touched.
Each entry in the phases: list takes these fields:
| Field | Meaning |
|---|---|
file | Base name of the phase file in the phases folder, without .yml. The chest file is <file>_chests.yml. |
section | The top-level key inside the phase file (historically the start block). |
name | Display name, used in logs and in the /[admin_command] phases panel. |
length | Number of blocks in the phase. |
enabled | Optional, defaults to true. Set false to leave a phase out. |
requiredMinecraftVersion | Optional. The phase is skipped — taking up no blocks at all — on servers older than this version. |
Start blocks are computed: they are the running sum of the lengths of the enabled phases above, starting at 0. That means phases can be reordered freely and a skipped phase collapses out of the progression. After the last phase the block count jumps to gotoAtEnd.
A top-level adminLengths: true is written automatically the first time you edit a length in /[admin_command] phases. From then on reconciliation never recomputes lengths, so your values survive later file additions, renames and upgrades.
Reconciliation#
Since 1.26.1 the phases folder is the source of truth
The index is reconciled with the files actually on disk on every load, and on every save from the admin panel, so what /[admin_command] phases shows is what your server really runs. Watch the startup log for lines beginning Phase index: — they say exactly what was changed.
- An entry whose file was renamed across addon versions is re-pointed at your file by phase name, so the phase loads again.
- An entry whose file is missing but shipped in the jar is restored automatically. This is what makes new phases appear on upgraded servers, since files in
phases/are 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, so the panel never lists phases that do not exist.
- When repair was needed, lengths are recomputed from your files' legacy start-block keys, preserving the layout your server actually ran before the index existed — unless
adminLengthsis set.
Deleting a phase
To remove a phase permanently, delete its files, or toggle it off in /[admin_command] phases. Deleting only its index entry does not work — reconciliation re-adds any phase file it finds in the folder.
A malformed index falls back to the old direct file loading, so a bad edit cannot leave the addon stuck.
Phase Config Files#
Full guide: Customizing Phases
A complete walkthrough of phase files — what every number means, how the weighted block/mob pool works with worked examples, chests, custom blocks, version gating, and how to build a phase from scratch.
The config files to make the phases are in the phases folder.
There are two files per phase - a file that contains the blocks and mobs, and a file that contains the chests.
The first number of any file is how many blocks need to be mined to reach that phase. This is the phase's key number.
Numbers in phase file names are optional since 1.26.1
Custom phase files no longer need a numeric start block in the file name or as the YAML section key — desert.yml with a desert: section works. Chest files still pair by file name (<file>_chests.yml). The numbers in the shipped files are historical: with the index in charge, the panel's start and length values are the truth. Numeric keys remain useful because they tell reconciliation where a file belongs and how long it was.
Description
The display name for phases. This name will be displayed in all spots where player try to view a phase.
Description
The icon of the phase is used only in the phases panel.
The icon is created using BentoBox ItemParser
Description
The fixedBlocks section allows forcing certain blocks when player breaks it. The first is a number of block in phase, and then it follows with Bukkit Material. The first block in phase has the index 0, while adding number that is larger than phase running time, will mean that it will not be reached.
Available values you can find here: Materials
We recomend to use blocks that does not require a support block (like torch, rails, plants).
Example
0: GRASS_BLOCK
1: GRASS_BLOCK
2: GRASS_BLOCK
50: SPONGE
CHEST_WITH_X notation
Fixed blocks entries can use the CHEST_WITH_X shorthand to place a chest pre-filled with a specific item, for example CHEST_WITH_WATER_BUCKET. The item must be a valid Bukkit material name.
Description
AOneBlock uses native holograms to show these lines. The first line that is shown before any phase has started is located in aoneblock locales file.
Similar to the fixedBlocks, holograms also start with a number when it should be displayed that follows with a displayed text.
Example
0: "&aFirst block is grass!"
1: "&aSecond block is grass!"
2: "&cWhat if there will be no next block?"
3: "&aGood Luck!"
Description
biome is an experimental option. However, it changes biome only for the "magic" block location. So we would suggest to use the Biomes addon that has an option to change the biome on whole island. You can do it with phase start commands which would trigger biome change.
Description
Since 1.26.0, a phase, a single block, or a single mob can declare the minimum Minecraft version it needs. Anything the server is too old for is skipped with a single info log line instead of throwing Tried to load invalid item or ConfigurationSerialization errors.
At the phase level the value belongs in phases_index.yml as well, so the phase can be skipped before its file is parsed at all. Set at the phase level, the phase takes up no blocks on an older server and the phases after it collapse up.
Individual blocks and mobs entries take an object form with weight plus their own requiredMinecraftVersion. 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.
Example
blocks:
NETHERRACK: 300
DRIED_GHAST:
weight: 25
requiredMinecraftVersion: '1.21.6'
Description
start-commands section allows defining commands that will be triggered when player starts this phase.
Commands are run as the Console unless the command is prefixed with [SUDO], then the command is run as the player triggering the commands.
These placeholders in the command string will be replaced with the appropriate value:
[island]- Island name[owner]- Island owner's name[player]- The name of the player who broke the block triggering the commands[phase]- the name of this phase[blocks]- the number of blocks broken[level]- your island level (Requires Levels Addon)[bank-balance]- your island bank balance (Requires Bank Addon)[eco-balance]- player's economy balance (Requires Vault and an economy plugin)
Example
start-commands:
- 'give [player] WOODEN_AXE 1'
- 'broadcast [player] just started OneBlock!'
- 'obadmin biomes set [player] aoneblock_fields ISLAND!'
Description
end-commands section allows defining commands that will be triggered when player finishes this phase.
Commands are run as the Console unless the command is prefixed with [SUDO], then the command is run as the player triggering the commands.
These placeholders in the command string will be replaced with the appropriate value:
[island]- Island name[owner]- Island owner's name[player]- The name of the player who broke the block triggering the commands[phase]- the name of this phase[blocks]- the number of blocks broken[level]- your island level (Requires Levels Addon)[bank-balance]- your island bank balance (Requires Bank Addon)[eco-balance]- player's economy balance (Requires Vault and an economy plugin)
Example
end-commands:
- '[SUDO]say Just finished [phase]'
Description
end-commands-first-time section allows defining commands that will be triggered only the first time a player completes this phase. These will not run on subsequent completions.
Commands are run as the Console unless the command is prefixed with [SUDO], then the command is run as the player triggering the commands.
These placeholders in the command string will be replaced with the appropriate value:
[island]- Island name[owner]- Island owner's name[player]- The name of the player who broke the block triggering the commands[phase]- the name of this phase[blocks]- the number of blocks broken[level]- your island level (Requires Levels Addon)[bank-balance]- your island bank balance (Requires Bank Addon)[eco-balance]- player's economy balance (Requires Vault and an economy plugin)
Example
end-commands-first-time:
- 'broadcast &c&l[!] &b[player] &fhas completed the &d&n[phase]&f phase for the first time.'
Description
requirements section allows limiting access to the next phase until specified requirements are met. Currently, there are 5 requirement fields:
economy-balance- the minimum player's economy balance (Requires Vault and an economy plugin)bank-balance- the minimum island bank balance (requires Bank Addon)level- the island level (Requires Levels Addon)permission- a permission stringcooldown- the minimum number of seconds that must pass since the phase was last started (prevents rapid phase switching)
Example
requirements:
bank-balance: 10000
level: 10
permission: ready.for.battle
cooldown: 60
Description
The blocks section lists Bukkit Materials followed by a weight.
A weight is not how many of that block will appear, and it is not a percentage — it is that entry's share of a raffle. Every time the magic block is broken, all the weights in the phase are added up and one entry is picked at random in proportion to its weight:
chance of an entry = its weight ÷ total of all weights in the phase
Because only the ratio matters, STONE: 1000, DIRT: 200 behaves exactly like STONE: 10, DIRT: 2. The shipped files use large numbers so that a rare entry can be added at a small weight without rescaling everything else.
Available values you can find here: Materials
See Customizing Phases for worked examples and tuning advice.
Example
blocks:
GRASS_BLOCK: 2
STONE: 3
This example shows that there is 40% chance to spawn a grass block while 60% to spawn stone. (2 / (2+3)) and (3 / (2+3))
CHEST is special
When CHEST is rolled, it is filled from that phase's _chests.yml file. Its weight is the chance of getting a chest; the rarity is then a second, separate roll — COMMON 62%, UNCOMMON 25%, RARE 9%, EPIC 4%. Those rarity chances are fixed in code.
Description
The mob section lists mobs that can spawn and their weight. You can only list entities that are alive and can spawn in this list. EntityTypes
Mobs share the same pool as blocks
mobs: is not a separate roll. Mob weights are added to the same total as the blocks: and custom-blocks: weights, so CHICKEN: 200 is exactly as likely as a block of weight 200 — and adding mobs makes every block slightly rarer.
Example
mobs:
COW: 150
SPIDER: 75
In the shipped Plains phase the block weights total 11450 and the mob weights another 665, giving a phase total of 12115. So COW: 150 is 150 / 12115 = 1.2% of broken blocks.
Description
Since version 1.11 you can now specify custom blocks (thanks to @HSGamer). You can do it in both places: blocks and fixed-blocks.
To define custom blocks in blocks section, you need to add - before each element. Also, blocks must be defined with type, data and probability values.
The probability field is a weight, exactly like the numbers in blocks: and mobs:, and it joins the same pool — probability: 10 is as likely as a block of weight 10.
You can also keep the map-form blocks: section untouched and put custom entries in a sibling custom-blocks: list instead. It takes the same entries and feeds the same pool.
Supported types are:
block-data: uses/setblockcommand to place a block in the world. Requiresdatafieldmob: uses Spawn Entity API to create requested entity. Requiresmobfield, and optionallyunderlying-blockfield (default: STONE)itemsadder: uses ItemsAdder API to create block. Requiresidfield. ItemsAdder plugin must be installed.nexo: uses Nexo API to create block. Requiresidfield. Nexo plugin must be installed.craftengine: uses CraftEngine API to create block. Requiresidfield. CraftEngine plugin must be installed. Requires BentoBox 3.15.0+.
Example
fixedBlocks:
0:
type: block-data
data: minecraft:chest[waterlogged=true]
1: GRASS_BLOCK
2: GRASS_BLOCK
blocks:
- type: block-data
data: minecraft:chest[waterlogged=true]
probability: 10
- type: block-data
data: minecraft:chest
probability: 10
- type: mob
mob: ZOMBIE
underlying-block: STONE
probability: 5
- type: itemsadder
id: mypack:ruby_ore
probability: 10
- type: nexo
id: mypack:custom_block
probability: 10
- type: craftengine
id: mypack:custom_block
probability: 10
- DIRT: 10 # old syntax still works.
ItemsAdder and Nexo
To use custom blocks from ItemsAdder or Nexo, the respective plugin must be installed on your server. AOneBlock automatically detects these plugins on startup and registers the appropriate block handlers. If you configure an itemsadder or nexo block but the plugin is not installed, the block will fall back to STONE.
In the chests file, it just has the phase number and a chests section.
Description
If CHEST is listed in the blocks section, then it will be randomly filled according to this section. You can define as many chests as you like. The first number is a unique chest number. Then follows the chest contents that includes the slot number and the item stack contents. Finally, there is the chest's rarity, which can be COMMON, UNCOMMON, RARE or EPIC. The chances for them are hard-codded with values: 62%, 25%, 9%, and 4%.
The best way to set chests is to do it in game. Fill a chest with the contents you want and then while looking at it enter the command /[admin_cmd] setchest <phase> <rarity> where
Be very careful when editing the chest items and check that the material is a true Bukkit material and spelled correctly.
Customizable GUI's#
BentoBox 1.17 API introduced a function that allows to implement customizable GUI's. This addon is one of the first one which uses this functionality. We tried to be as simple as possible for customization, however, some features requires explanation. You can find more information how BentoBox custom GUI's works here: Custom GUI's
How can I customize GUI's
To customize Addon GUI's you need to have version 1.10. This is a first version that has implemented them. Addon will create a new directory under /plugins/BentoBox/addons/AOneBlock with a name panels
What does PREVIOUS|NEXT button type?
The PREVIOUS and NEXT button types allows creating automatic paging, when you have more islands than spaces in GUI. These types have extra parameters under data:
indexing- indicates if button will show page number.
Example:
icon: tipped_arrow[potion_contents={custom_color:11546150}]
title: aoneblock.gui.buttons.previous.name
description: aoneblock.gui.buttons.previous.description
data:
type: PREVIOUS
indexing: true
actions:
previous:
click-type: LEFT
tooltip: aoneblock.gui.tips.click-to-previous
What is PHASE button type?
This button allows players to view phase name and requirements. If users has access to phase changing, and they already have reached a phase, they can select it again and replay it.
icon, title and description is generated dynamically based on phase properties. However, you can change it manually.
Example:
# icon: PLAYER_HEAD
# title: aoneblock.gui.buttons.phase.name
# description: aoneblock.gui.buttons.phase.description
data:
type: PHASE
actions:
select:
click-type: LEFT
tooltip: aoneblock.gui.tips.click-to-change
Commands#
Tip
[player_command] and [admin_command] are commands that differ depending on the gamemode you are running.
The Gamemodes' config.yml file contains options that allows you to modify these values.
As an example, on AOneBlock, the default [player_command] is ob, and the default [admin_command] is oba.
Be aware, that this addon allows changing player commands aliases in addon config.yml file.
/[player_command] count: sends a message in chat about current phase progress./[player_command] phases: opens a GUI that allows the viewing and choosing of phases./[player_command] setcount <number>: allows changing the current phase where<number>is the phase start number./[player_command] check: spawns particles around the magic block or respawns it, if for some reason it was missing./[player_command] bossbar: toggles the boss bar display showing phase progress. (Since 1.21.2, requiresbossbar: truein config)/[player_command] actionbar: toggles the action bar display showing phase progress. (Since 1.21.2, requiresactionbar: truein config)
/[admin_command] sanity [<phase>]: sends a message if phases (or<phase>) chests are correct./[admin_command] setcount <player> <number>: allows changing the current phase to a<player>where<number>is the phase start number./[admin_command] setchest <phase> <rarity>: saves a chest that player is looking at into<phase>chests section with<rarity>./[admin_command] phases: opens the phase order editor. (Since 1.26.0)
Using the phase order editor
/[admin_command] phases 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 (since 1.26.1). The panel closes and a chat prompt shows the current length; type a whole number to apply it, or
cancelto keep it. Invalid input re-prompts, and the prompt times out after 60 seconds. The first length edit writesadminLengths: trueinto the index so your values are never recomputed again.
Disabled phases show as gray glass and version-locked ones as barriers — both can still be reordered. A phase with no configured icon uses its first block.
By default, BentoBox GameMode addons comes with the default sub-command set, however, each addon may introduce even more sub commands.
Complete AOneBlock Command List
Permissions#
Tip
[gamemode] prefix in every place for AOneBlock addon must be replaced with aoneblock.
aoneblock.count- Let the player use the '/[player_command] count' command. Enabled by default.aoneblock.phases- Let the player use the '/[player_command] phases' command. Disabled by default.aoneblock.island.setcount- Let the player use the '/[player_command] setcount' command. Disabled by default.aoneblock.respawn-block- Let the player use the '/[player_command] check' command. Enabled by default.aoneblock.island.bossbar- Let the player use the '/[player_command] bossbar' command. Enabled by default. (Requiresbossbar: truein config)aoneblock.island.actionbar- Let the player use the '/[player_command] actionbar' command. Enabled by default. (Requiresactionbar: truein config)
aoneblock.admin.sanity- Let the player use the '/[admin_command] sanity' command. Default OP.aoneblock.admin.setchest- Let the player use the '/[admin_command] setchest' command. Default OP.aoneblock.admin.setcount- Let the player use the '/[admin_command] setcount' command. Default OP.aoneblock.admin.phases- Let the player use the '/[admin_command] phases' command to open the phase order editor. Default OP. (Since 1.26.0)
By default, BentoBox GameMode addons comes with the default sub-permission set, however, each addon may introduce even more sub-permissions.
Complete AOneBlock Permission List
Flags#
AOneBlock introduces several custom flags that control gameplay behavior:
| Flag | Type | Description | Default |
|---|---|---|---|
START_SAFETY | World Setting | When enabled, players cannot move for a brief period when they create a new island, preventing them from falling off immediately. Duration is set by starting-safety-duration in config. | false |
ONEBLOCK_BOSSBAR | Island Setting | Toggles whether the OneBlock phase progress boss bar is shown for the player. Only available if bossbar: true is set in config. | true |
ONEBLOCK_ACTIONBAR | Island Setting | Toggles whether the OneBlock phase progress action bar is shown for the player. Only available if actionbar: true is set in config. | true |
MAGIC_BLOCK | Protection | Sets the minimum island rank required to break the magic block. Default rank is Coop. | COOP |
Placeholders#
AOneBlock addon has its own unique placeholders. These placeholders relates to the data AOneBlock is storing.
| Placeholder | Description | AOneBlock Version |
|---|---|---|
| %aoneblock_my_island_phase% | the phase of your island | 1.1.2 |
| %aoneblock_my_island_count% | the block count of your island | 1.1.2 |
| %aoneblock_visited_island_phase% | the phase of the island you are standing on | 1.1.2 |
| %aoneblock_visited_island_count% | the block count of the island you are standing on | 1.1.2 |
| %aoneblock_my_island_next_phase% | the next phase for your island | 1.1.2 |
| %aoneblock_visited_island_next_phase% | the next phase for the island you are standing on | 1.1.2 |
| %aoneblock_my_island_blocks_to_next_phase% | blocks to go until the next phase, or "infinite" if there is no next phase | 1.5.2 |
| %aoneblock_visited_island_blocks_to_next_phase% | blocks until the next phase for the island you are standing on | 1.5.2 |
| %aoneblock_my_island_percent_done% | phase completion percentage | 1.5.2 |
| %aoneblock_visited_island_percent_done% | phase completion percentage of the island you are standing on | 1.5.2 |
| %aoneblock_my_island_done_scale% | phase completion scale of your island | 1.5.2 |
| %aoneblock_visited_island_done_scale% | phase completion scale of the island you are standing on | 1.5.2 |
| %aoneblock_my_island_lifetime_count% | the block count of lifetime for your island | 1.10.0 |
| %aoneblock_visited_island_lifetime_count% | the block count of lifetime for the island you are standing on | 1.10.0 |
By default, BentoBox GameMode addons comes with default placeholders set, however, each addon may introduce even more placeholders.
Complete AOneBlock Placeholder List
FAQ#
Can you add a feature X?
Please add it to the list here.
I have a bug, where should I report it?
Please add it to the list here.
What phases are there?
There are 20 shipped phases, in this order: Plains, Underground, Winter, Ocean, Jungle, Swamp, Dungeon, Desert, The Nether, Plenty, Desolation, Deep Dark, The End, Lush Caves, Dripstone Caves, Mangrove Swamp, Meadow, Cherry Grove, Jagged Peaks, and Sulfur Caves.
Each phase features a set of blocks, items, and mobs appropriate for the setting.
Sulfur Caves requires Minecraft 26.2 or later. On older servers it is skipped and Jagged Peaks runs to the loop point instead. You can reorder, disable and resize phases yourself with /[admin_command] phases, and add your own phase files to the phases folder.
How many blocks are there in all the phases?
15,500 blocks with the shipped phases on a Minecraft 26.2+ server, or 15,000 without the Sulfur Caves phase.
What happens after the last phase?
The phases repeat — the block count jumps back to the gotoAtEnd value in phases_index.yml, which is 0 by default.
Why do I keep falling and dying!
There are tricks to surviving, but it might be difficult! You need to build defenses.
Why do certain blocks spawn more frequently than others?
They just do! You can set the relative probability in the config files in the phases folder.
How do I know which is the magic block?
Hit it and it will give out green particles.
My magic block is no longer there! How do I get another one?
You will have to place a block there. Worse case, kill yourself and one will be generated.
My magic block is liquid! How can I mine it?
Use a bucket.
How do I stop visitors mining other players' magic blocks?
This option already exists — you do not need a new config setting. If visitors are mining someone else's block, that island's owner has set the Break Blocks and Magic Block protection settings to allow it. The fix is to reset those settings across the world and then hide the icons so owners cannot turn them back on.
Do these steps in this order, or step 3 will undo step 1.
1. Set the defaults for new islands
Run /oba settings and open the Island Defaults tab (the cracked stone bricks icon). Left-click Break Blocks and Magic Block until both read Member. This saves to the AOneBlock config.yml automatically.
2. Reload
Run /bbox reload, or restart the server.
3. Apply those defaults to all existing islands
/oba resetflags BREAK_BLOCKS
/oba resetflags MAGIC_BLOCK
Confirm each one. This overwrites whatever every island currently has with the default you set in step 1, so it must come after step 1.
4. Hide the settings so owners cannot change them back
As an Op, stand on an island, run /ob settings, and SHIFT-LEFT-CLICK Break Blocks and Magic Block. Each one gains a Curse of Vanishing glow, meaning it is now hidden. Ops still see it; everyone else no longer has the icon in their panel at all.
Every island will now refuse anyone below Member rank breaking blocks, including the magic block, and players cannot change it.
Tip
SHIFT-LEFT-CLICK hides any protection setting this way, per world, and the hidden list is saved to the game mode's config. SHIFT-LEFT-CLICK a hidden setting again to bring it back.
Which mobs can spawn?
Each phase has a different set of mobs that can spawn. Be careful because they may push you off! If you listen carefully, you may hear hostile mobs coming.
I have no chance to react to hostile mobs spawning!
Be prepared. Listen carefully when you mine a block and you will hear hostile mobs coming before they spawn. If you are in a hostile phase, then expect mobs and build defenses to protect yourself. You can mine a block from quite far away.
When mobs spawn, my defenses are destroyed! Why?
Mobs make space to spawn. If there's anything in the way, it'll be broken and dropped. You'll have to build accordingly.
Do chests spawn?
Yes. Chests spawn with random items in them from the current phase. There are common, uncommon, rare and epic chests. Chests with sparkles are good.
Is it possible to reach the Nether or End in this map?
The vanilla Nether exists by default but there is no End world.
However, BentoBox is customizable, and you can enable nether islands and end world in AOneBlock config file.
Be aware, magic block is located only in overworld.
What is the end goal?
It's whatever you want it to be!
How to use holograms?
AOneBlock uses Holographic Displays for holograms if you use 1.12.3 and below. You need to install this plugin to use holograms sections!
However, since 1.13 version and Minecraft 1.19.4, you do not need any extra plugins for holograms. They will be displayed using Minecraft Text Entity.
Hologram text accepts legacy & colour codes, &#RRGGBB hex colours and MiniMessage tags (gradients included) — the hex and MiniMessage forms since 1.27.0. See Customizing Phases.
Should I use the Levels addon?
It's up to you, but if you do be aware that levels could get high because players have an infinite block. I prefer not to use it and instead use the Likes addon.
Translations#
Help us keep translations accurate
Most BentoBox and addon translations are now generated with the help of AI, so the bulk of the work is already done — but AI is not perfect. What we really need from the community is error reports and corrections.
- Spotted a mistake or awkward phrasing? Open an issue or a PR on the relevant repository at bentobox.world (a short link to our GitHub org), or tell us on Discord.
- Want to add a brand-new language? Open a PR adding a new locale file to
src/main/resources/locales/in the relevant repo, or ask on Discord and we'll get you started.
| Language | Language code | Progress |
|---|---|---|
| English (United States) | en-US | 100% (Default) |
| Chinese, China | zh-CN | 77% |
| Chinese, Taiwan | zh-TW | 100% |
| Croatian | hr | 77% |
| Czech | cs | 77% |
| French | fr | 77% |
| German | de | 77% |
| Hungarian | hu | 77% |
| Indonesian | id | 77% |
| Italian | it | 77% |
| Japanese | ja | 77% |
| Polish | pl | 77% |
| Portuguese | pt | 77% |
| Russian | ru | 77% |
| Spanish | es | 77% |
| Turkish | tr | 77% |
| Ukrainian | uk | 77% |
| Vietnamese | vi | 77% |
Api#
Since BentoBox 1.17 API implemented a feature that solved an issue with classloaders. Plugins that wants to use access to the code directly, now can do it.
You just need to add AOneBlock to your project as dependency. You can use Maven for that:
<dependency>
<groupId>world.bentobox</groupId>
<artifactId>aoneblock</artifactId>
<version>1.10.0</version>
<scope>provided</scope>
</dependency>
AOneBlock addon stores data in a separate database table.
Description
OneBlockIslands stores all information about island progress through phases.
Link to the source code: OneBlockIslands
Variables
- "uniqueId": the island unique ID. It is equal to the Island uniqueId.
- "blockNumber": the current broken block number.
- "lifetime": the overall number of broken blocks.
- "phaseName": the current phase name.
- "hologram": the hologram text that is shown.
Code example
To access this data, you need to access to AOneBlock addon. It can be several ways, but example bellow shows a generic way that is accessible from everywhere.
public void accessToAOneBlockData(@NonNull Island island) {
BentoBox.getInstance().getAddonsManager().<AOneBlock>getAddonByName("AOneBlock").ifPresent(aOneBlock -> {
OneBlockIslands oneBlockData = aOneBlock.getOneBlocksIsland(island);
String islandUniqueId = oneBlockData.getUniqueId();
int brokenBlocks = oneBlockData.getBlockNumber();
long lifetimeBlocks = oneBlockData.getLifetime();
String phase = oneBlockData.getPhaseName();
String hologram = oneBlockData.getHologram();
});
}
Events#
AOneBlock has some custom events that are called only in AOneBlock. But BentoBox GameMode events are still triggered in AOneBlock.
Description
This event is triggered before entity is spawned. It contains a list of blocks that will be cleared or replaced with water.
Can be cancelled.
Link to the class: BlockClearEvent
Variables
Entity entity- entity that is spawned.List<Block> airBlocks- the list of blocks that will be replaced with air.List<Block> waterBlocks- the list of blocks that will be replaced with water.boolean cancelled- the boolean that indicates if event is cancelled.
Code example
@EventHandler(priority = EventPriority.MONITOR)
public void onBlockClear(BlockClearEvent event) {
Entity entity = event.getEntity();
List<Block> airBlocks = event.getAirBlocks();
List<Block> waterBlocks = event.getWaterBlocks();
boolean cancelled = event.isCancelled();
}
Description
This event is triggered after entity is spawned. It just contains basic information about spawned entity.
Link to the class: MagicBlockEntityEvent
Variables
EntityType entityType- entityType that is spawned.@NonNull Island island- the island where entity is summoned@Nullable UUID playerUUID- the user id who triggered entity spawning. Can be Null.@NonNull Block block- the magic block location.
Code example
@EventHandler(priority = EventPriority.MONITOR)
public void onMagicBlockEntity(MagicBlockEntityEvent event) {
EntityType entityType = event.getEntityType();
Island island = event.getIsland();
UUID playerUUID = event.getPlayerUUID();
Block block = event.getBlock();
}
Variables
@Nullable ItemStack tool- the tool that broke magic block.@NotNull Material nextBlockMaterial- the next magic block material.@NonNull Island island- the island where block is summoned.@Nullable UUID playerUUID- the user id who broke magic block. Can be Null.@NonNull Block block- the magic block location.
Code example
@EventHandler(priority = EventPriority.MONITOR)
public void onMagicBlock(MagicBlockEvent event) {
ItemStack tool = event.getTool();
Material nextBlockMaterial = event.getNextBlockMaterial();
Island island = event.getIsland();
UUID playerUUID = event.getPlayerUUID();
Block block = event.getBlock();
}
Description
This event is triggered after a new phase has started.
Link to the class: MagicBlockPhaseEvent
Variables
String phase- the name of the new phase.String oldPhase- the name of previous phase.int blockNumber- the block number when new phase starts.@NonNull Island island- the island where block is summoned.@Nullable UUID playerUUID- the user id who broke magic block. Can be Null.@NonNull Block block- the magic block location.
Code example
@EventHandler(priority = EventPriority.MONITOR)
public void onMagicBlockPhase(MagicBlockPhaseEvent event) {
String phase = event.getPhase();
String oldPhase = event.getOldPhase();
int blockNumber = event.getBlockNumber();
Island island = event.getIsland();
UUID playerUUID = event.getPlayerUUID();
Block block = event.getBlock();
}
Changelog#
What's new in v1.23.0 — locale and config update required
Released: 2026-04-11
- Nexo custom block support. AOneBlock now supports Nexo custom blocks in phase definitions (alongside the existing ItemsAdder support). Define them with
type: nexoand anidfield in your phases config. - HEX / MiniMessage color support in action bar. The
/ob actionbartext now correctly renders HEX colors and full MiniMessage formatting. - 🔡 Russian locale updated to MiniMessage format with grammar corrections.
- Several action bar locale and translation bug fixes.
🔺 Nexo support is a new config option. If you use Nexo, add Nexo-type block entries to your phase .yml files.
🔡 Regenerate locale files if you have customisations.
What's new in v1.24.0 — requires BentoBox 3.15.0
Released: 2026-04-26
- CraftEngine custom block support. Phases can now spawn CraftEngine blocks using
type: craftenginein phase definitions. Requires BentoBox 3.15.0+. - Configurable chest particles per rarity. The particle type and color shown above UNCOMMON/RARE/EPIC chests are now configurable in
config.ymlunderworld.chest-particles. Set a particle toNONEto disable it. CHEST_WITH_Xfixed-block notation. PhasefixedBlocksnow acceptCHEST_WITH_<ITEM>entries to place a chest pre-filled with that item (e.g.CHEST_WITH_WATER_BUCKET).OBSIDIAN_SCOOPINGnow off by default. New installs have this flag set tofalse. Existing servers with an explicit setting are unaffected.- 🔡 Placeholder defaults for islandless players:
%aoneblock_my_island_phase%,%aoneblock_my_island_count%, and%aoneblock_my_island_percent_done%now returnUnknown,0, and0%instead of empty strings.
🔺 Requires BentoBox 3.15.0 or later — this release will not load against older BentoBox versions.
⚙️ New config section world.chest-particles — copy from the latest config.yml if you want configurable particle effects.
🔡 Regenerate locale files to pick up new keys.
What's new in v1.25.0
Released: 2026-05-03
- Populated bee nest in Plenty. The Plenty phase now spawns a
bee_nest(3 bees inside,honey_level=0) at the same density as the existing honey items, closing the long-standing honey-farming gap. - Magic block client-side resync after mob rolls. When the magic block rolled a mob, the cancelled break event left the block looking transparent client-side until the next chunk resync. The block state is now resent to the mining player immediately.
- 🐛 CraftEngine startup-order fix.
AOneBlock'sonEnableruns before CraftEngine has populated its block registry, which previously caused a flood of falseBad custom blockerrors. The block parser now trusts an explicittype: craftenginedeclaration at config-load time and validates the ID at placement instead. - 🐛 Stricter CraftEngine block-ID validation at config load. Blank IDs and IDs missing the
namespace:keyform are now rejected at config-load time instead of silently accepted and failing later. - 🐛 Configurable chest particles no longer crash on non-
DUSTtypes. Particle types whose data type is non-Void(e.g.ITEM,BLOCK,ENTITY_EFFECT) used to throwIllegalArgumentException. They are now detected, logged as a warning, and skipped.DUSTand void-data particles work unchanged.
🔺 If you want the new bee nest, copy the new entry into your phases/8500_plenty.yml (or delete the phases folder so it regenerates) — customised phase files are not overwritten on upgrade.
What's new in v1.25.1
Released: 2026-07-03
Bug-fix release — drop-in replacement, no config or locale changes.
- 🐛 Miner minions can mine the magic block again. Breaking the magic block with a JetsMinions Miner minion threw a
NullPointerExceptionand left the block missing until it was manually restored with/ob respawnblock. The minion break path no longer runs the player-only magic-block protection check that caused the crash, so the block cycles and respawns as expected. This regression had been present since 1.22.0. - 🐛
my_island_*placeholders fixed for visiting team members. When a player who belongs to a team visited another island, themy_island_*placeholders resolved to the visited island's team data instead of the player's own island. They now always resolve to the player's own island.
What's new in v1.25.2
Released: 2026-07-18
Bug-fix release — drop-in replacement, no config or locale changes.
- 🐛 Jobs Reborn infinite-reward exploit closed. When the
MAGIC_BLOCKflag denied a player from breaking the magic block, plugins that listen for block breaks — such as Jobs Reborn — still saw the break as successful and paid out rewards. Because the block instantly respawns, a visitor could mine the same valuable block indefinitely for infinite job rewards. The denied break is now cancelled before other plugins process it. - 🐛
actionbar: falsenow actually disables the action bar. If the boss bar was enabled, the action bar progress display kept showing even withactionbar: falseset, and the same applied in reverse to the boss bar. Both settings are now respected, and the progress displays are no longer updated twice per block break when both are enabled.
What's new in v1.26.0 — the phase index (review after upgrading)
Released: 2026-07-20
Adds the Sulfur Caves phase for Minecraft 26.2 servers, and — because shipping a 26.2-only phase to an addon that also runs on 1.21.x needed real version handling — introduces the phase index that controls which phases load, in what order, and on which server versions. Compatibility: BentoBox API 3.15.0+ · Minecraft 1.21.5 or later · Java 21.
- Sulfur Caves phase. A new phase at the 15000 spot: sulfur and cinnabar layered through typical underground blocks, with Sulfur Cubes, cave spiders and friends at the wiki's spawn weights, plus themed chests that can drop the Bounce music disc. The end-of-game loop moves from 15000 to 15500. The phase declares
requiredMinecraftVersion: '26.2', so it appears automatically on 26.2+ servers and is skipped with a single info log on older ones — Jagged Peaks simply runs to the loop point instead. - 🔺 New
phases_index.yml. Now the source of truth for phase order, length, enabled state and required Minecraft version. Start blocks are the running sum of the lengths above, so phases can be moved freely and a skipped phase collapses out of the progression. The index is read before any phase file is parsed, which kills theTried to load invalid itemandConfigurationSerializationstack traces that newer-version items used to cause on older servers. See the Configuration section above. - Version-gated blocks, mobs and chest items. Chest files are now read item by item, so an item this server version does not know is skipped with one log line and the rest of the chest loads. Block and mob entries accept an object form with a per-entry
requiredMinecraftVersion. - 🔡 New
/[admin_command] phasespanel (permissionaoneblock.admin.phases, OP by default) to reorder, insert and toggle phases by clicking them around an inventory panel.
🔺 A phases_index.yml is generated on first start from the phase files in your data folder, and from then on it controls phase order and lengths. Worth a quick review after the first boot, especially if you have hand-edited phases. A malformed index falls back to the old direct file loading, so nothing can get stuck.
🔺 Existing installs do not get the new phase files automatically. Files in addons/AOneBlock/phases/ are never overwritten. On 1.26.0 you had to copy 15000_sulfur_caves.yml and 15000_sulfur_caves_chests.yml from the jar yourself; from 1.26.1 reconciliation restores them for you.
🔡 New locale keys were added for the phase order editor — regenerate or update translated locale files.
What's new in v1.26.1 — the phases folder is now the source of truth
Released: 2026-07-21
A bug-fix release for the 1.26.0 phase index. In 1.26.0 upgrading servers received the stock phases_index.yml, which references the current jar's file names — but existing phases/ folders hold older or customized layouts. Phases silently failed to load, Sulfur Caves never appeared on upgraded servers, and /[admin_command] phases showed a preset instead of the server's reality.
- 🔺 Self-healing phase index. The index is now reconciled with the
phases/folder on every load and on every panel save: entries renamed across addon versions are re-pointed at your file by phase name, entries missing but shipped in the jar are restored (so Sulfur Caves appears on upgraded 26.2 servers), custom phase files are added automatically, and entries whose files are gone for good are removed with a warning. Where repair was needed, lengths are recomputed from your files' legacy start-block keys, preserving the layout your server actually ran. - 🔡 Set phase lengths in the panel. Shift-left-click a phase to set its length via a chat prompt. The first length edit writes
adminLengths: trueintophases_index.yml, after which reconciliation never recomputes lengths again. - Numbers in phase file names are now optional. A custom
desert.ymlwith adesert:section works; chest files still pair by file name. - 🔡 Panel polish. Phase icons fall back to the phase's first block instead of stone, the "How to use" book wraps onto four lines, and the per-phase lore is shorter for small monitors.
🔺 Your phases_index.yml will likely be rewritten on the first boot to match the files in your phases folder. Watch the log for lines starting Phase index: — they say exactly what was re-pointed, restored, added or removed. Phases that vanished after the 1.26.0 upgrade come back on their own.
🔺 To remove a phase permanently, delete its files, or toggle it off in the panel. Deleting only its index entry no longer works — reconciliation re-adds any phase file it finds.
🔡 New and changed locale keys for the length prompt and the reworked panel text.
What's new in v1.26.2
Released: 2026-07-25
Bug-fix release for a loot regression introduced in 1.26.0. If you are on 1.26.0 or 1.26.1, update.
-
🐛 Chest items keep their meta again. Since 1.26.0 chest files have been read with plain SnakeYAML rather than
YamlConfiguration, so that an item unknown to your server version can be skipped on its own instead of taking down the whole chest file. The side effect was that nothing was deserialized on the way in: an item'smetasection arrived as a plain map, and Bukkit's item deserializer silently ignores meta that is not already anItemMeta. Enchantments, potion effects and names were dropped without a line in the log — most visibly the enchanted books from the Plains chests, but it applied to every chest item in every phase, including potions, tipped arrows, custom-named items, banners, player heads and written books.Chest item definitions are now walked properly and their meta is deserialized before the item is built. The 1.26.0 behaviour is unchanged — an item that does not exist on your Minecraft version is still skipped with a log line — and a meta section that cannot be read now costs only its meta, and says so in the log, rather than losing the item.
No phase file changes are needed: the old-style enchantment names in the shipped phase YAML (PROTECTION_FALL and friends) are still translated by the server, so customized chest files work as they are. Items players have already looted stay as they are — the meta was lost when the chest was filled, so there is nothing to repair after the fact. Every chest generated from now on is correct.
What's new in v1.26.3
Released: 2026-07-29
Bug-fix release for the phases GUI — drop-in replacement, with no config, locale or phase file changes.
- 🐛 "Click to change" is only offered when the click can succeed. The
/[player_command] phasespanel decided whether to offer the phase-change action from island state and phase requirements alone, and never checked whether the player held theaoneblock.island.setcountpermission that the click actually uses. On servers where that permission is negated for some or all ranks, players saw the tooltip on every eligible phase and got "You don't have the permission to execute this command" when they clicked. The panel now checks the permission before offering the action. If the subcommand cannot be resolved for any reason the panel stays permissive as before, so no phase becomes unclickable because of this change. Players who do hold the permission see no difference.
Compatibility: BentoBox API 3.15.0+, Minecraft 1.21.5 or later (the Sulfur Caves phase itself activates on Minecraft 26.2+), Java 21.
What's new in v1.27.0 — requires BentoBox 3.22.0 and Java 25
Released: 2026-08-08
Fixes silent, repeated loss of island progress on restart, and adds MiniMessage and hex colours to phase text. Compatibility: BentoBox API 3.22.0+ · Minecraft 26.x or 1.21.5+ (the Sulfur Caves phase activates on 26.2+) · Java 25 server.
- 🔺 🐛 Island progress is no longer lost on restart. If a player was online when the server restarted, their block count rolled back to the last checkpoint — up to 49 blocks of mining undone, every restart. AOneBlock is a Pladdon, so the server disables it before BentoBox, and the shutdown save went into a queue that every BentoBox before 3.22.0 discarded silently. The shutdown save is now a direct write, independent of the core.
- ⚙️ New
island.save-everyoption — how often progress is written to the database, in blocks broken. Defaults to 10, replacing the old hardcoded 50, so at most 9 blocks can be lost to a crash rather than 49. Progress is also saved on phase change, logout and shutdown. Added to existing configs automatically. See the Configuration section above. - 🎨 MiniMessage and hex colours in phase text. Holograms only understood the sixteen legacy
&codes, and the action bar used a different serializer; both now accept legacy codes,&#RRGGBBhex, MiniMessage tags and gradients, mixed freely — the same applies to locale strings. Also fixes§codes appearing as literal text in the starting hologram and action bar. Existing&codes keep working; nothing needs changing. - 📄
0_plains.ymlnow explains what the numbers mean — weights inblocks:/mobs:/custom-blocks:, positions infixedBlocks:/holograms:— and documents the accepted colour syntaxes.
🔺 Update BentoBox to 3.22.0 or newer first. api-version has been raised, so on an older core BentoBox refuses to load the addon ("Cannot load AOneBlock because it requires BentoBox version 3.22.0 or greater"). BentoBox 3.22.0 in turn needs a Java 25 server — upgrade the JVM before either jar if you are still on Java 21.
What's new in v1.27.1
Released: 2026-08-29
Bug-fix release — no config or phase file changes, and existing locale customisations keep working. Compatibility: BentoBox API 3.22.0+ · Minecraft 26.x or 1.21.5+ · Java 25.
- 🐛
my_island_*placeholders work for team members again. Since 1.26.0,%aoneblock_my_island_count%,%aoneblock_my_island_percent_done%,%aoneblock_my_island_phase%and the rest only worked for the island owner; team members got the empty defaults (0,0%,Unknown). The lookup is now a preference order: an island the player owns wins, and a player who owns none falls back to the team island they belong to. - 🐛 Boss bar no longer breaks under minion/NPC plugins. When JetsMinions (or any plugin that breaks blocks via armor-stand entities) mined the magic block, the
MagicBlockEventcarried no player UUID and the boss bar listener threwIllegalArgumentExceptionon every break. It now returns early when there is nobody to show a bar to. - 🐛 Glow lichen and vines survive being placed. Multiface plants (
GLOW_LICHEN,VINE,SCULK_VEIN,RESIN_CLUMP) spawned attached to no face, so the first neighbouring block update deleted them and bone meal could not spread them. They are now attached to whatever solid neighbours exist; if nothing is there, the magic block becomes a support block (moss, or sculk for sculk veins) with the plant growing on it. - 🔡 All 18 bundled locale files converted to MiniMessage. Legacy
&codes still parse, so customised files inlocales/keep working unchanged. - 🔡 Traditional Chinese (
zh-TW) completed by @qwe664 — the 26 keys missing since 1.27.0 added and terminology revised.