From 195c64691cfecc5d1acef0f2c4bc9b6ff7e100c0 Mon Sep 17 00:00:00 2001 From: tastybento Date: Fri, 7 Aug 2026 22:22:57 -0700 Subject: [PATCH 1/2] docs(ChunkBlock): add the ChunkBlock game mode section Six pages under Game Modes: the overview pitch, Claiming Chunks (the full guide to the level-as-currency territory game - credit model, the hit-the-border claim gesture, LIFO re-locking, the border enforcement, visuals, limits and admin tools), Phases (what ships, the phase index and the order editor, deferring the shared field reference to the AOneBlock guide since the formats are identical), Commands, Permissions and Placeholders. Also adds the nav entry and the chunkblock placeholder rows in data/placeholders.csv. Command and permission tables are generated from the addon's own addon.yml and locale, so they match the shipped 1.0.1 build. Cross-links from Comparison.md, GameModes.md and the homepage are deliberately NOT in this PR - they follow once the section itself is settled, and those files currently carry unrelated pending edits. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Taa2snoHkvtcZ6e5rAHDQS --- data/placeholders.csv | 22 ++ docs/gamemodes/ChunkBlock/Chunks.md | 226 ++++++++++++ docs/gamemodes/ChunkBlock/Commands.md | 87 +++++ docs/gamemodes/ChunkBlock/Permissions.md | 142 ++++++++ docs/gamemodes/ChunkBlock/Phases.md | 155 +++++++++ docs/gamemodes/ChunkBlock/Placeholders.md | 16 + docs/gamemodes/ChunkBlock/index.md | 403 ++++++++++++++++++++++ mkdocs.yml | 7 + 8 files changed, 1058 insertions(+) create mode 100644 docs/gamemodes/ChunkBlock/Chunks.md create mode 100644 docs/gamemodes/ChunkBlock/Commands.md create mode 100644 docs/gamemodes/ChunkBlock/Permissions.md create mode 100644 docs/gamemodes/ChunkBlock/Phases.md create mode 100644 docs/gamemodes/ChunkBlock/Placeholders.md create mode 100644 docs/gamemodes/ChunkBlock/index.md diff --git a/data/placeholders.csv b/data/placeholders.csv index a8ad0825..335a265f 100644 --- a/data/placeholders.csv +++ b/data/placeholders.csv @@ -138,3 +138,25 @@ TradeWinds,tradewinds_rank,The player's Seafarer rank name (Deck Hand ... Mythic TradeWinds,tradewinds_charted,How many islands the player has charted (including any admin adjustment),0.1.0 TradeWinds,tradewinds_top_name_<1-10>,Name of the sailor at this position on the charted-islands top ten,0.1.0 TradeWinds,tradewinds_top_charted_<1-10>,Charted-island count of the sailor at this position on the top ten,0.1.0 +ChunkBlock,chunkblock_island_chunks,Number of chunks the player's island has unlocked including the centre chunk,1.0.0 +ChunkBlock,chunkblock_island_max_chunks,Maximum number of chunks the player's island can unlock,1.0.0 +ChunkBlock,chunkblock_island_chunk_credit,Level credit the island has available to spend on chunks,1.0.0 +ChunkBlock,chunkblock_island_next_chunk_level,Total island level needed to afford the next chunk,1.0.0 +ChunkBlock,chunkblock_island_ring,Ring number of the outermost claimed chunk (0 is the centre chunk alone),1.0.0 +ChunkBlock,chunkblock_my_island_phase,The phase of your island,1.0.0 +ChunkBlock,chunkblock_my_island_count,The magic block count of your island,1.0.0 +ChunkBlock,chunkblock_my_island_lifetime_count,The lifetime magic block count of your island,1.0.0 +ChunkBlock,chunkblock_my_island_next_phase,The next phase for your island,1.0.0 +ChunkBlock,chunkblock_my_island_blocks_for_phase,Number of blocks in the current phase of your island,1.0.0 +ChunkBlock,chunkblock_my_island_blocks_to_next_phase,Blocks to go until the next phase or "infinite" if there is no next phase,1.0.0 +ChunkBlock,chunkblock_my_island_percent_done,Phase completion percentage of your island,1.0.0 +ChunkBlock,chunkblock_my_island_done_scale,Phase completion scale bar of your island,1.0.0 +ChunkBlock,chunkblock_my_island_phase_block_list,List of blocks that can appear in your island's current phase,1.0.0 +ChunkBlock,chunkblock_visited_island_phase,The phase of the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_count,The magic block count of the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_lifetime_count,The lifetime magic block count of the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_next_phase,The next phase for the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_blocks_to_next_phase,Blocks until the next phase for the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_percent_done,Phase completion percentage of the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_done_scale,Phase completion scale bar of the island you are standing on,1.0.0 +ChunkBlock,chunkblock_visited_island_phase_block_list,List of blocks that can appear in the current phase of the island you are standing on,1.0.0 diff --git a/docs/gamemodes/ChunkBlock/Chunks.md b/docs/gamemodes/ChunkBlock/Chunks.md new file mode 100644 index 00000000..03f845f7 --- /dev/null +++ b/docs/gamemodes/ChunkBlock/Chunks.md @@ -0,0 +1,226 @@ +# Claiming Chunks + +This is the part of ChunkBlock that is not AOneBlock. The magic block is the engine; **the chunk is the game**. + +Every island starts as exactly one chunk — 16 × 16 blocks, from bedrock to sky, with the magic block in the middle of it. Everything else in the island's protection range is locked. The island owner opens it up one chunk at a time by spending island levels at the border. + +--- + +## The currency model + +Island level is the currency. There is no separate balance to track, no shop and no cooldown. + +``` +credit = island level − levels already spent +spent = (chunks claimed) × levels-per-chunk +``` + +The centre chunk is free and does not count as spending. With the default `levels-per-chunk: 1`: + +| Island level | Chunks owned | Spent | Credit | Can claim? | +|---:|---:|---:|---:|:--| +| 0 | 1 | 0 | 0 | No — nothing to spend | +| 1 | 1 | 0 | 1 | Yes, one chunk | +| 1 | 2 | 1 | 0 | Not until the level rises | +| 7 | 3 | 2 | 5 | Yes, five more chunks | +| 4 | 6 | 5 | −1 | **Over-spent** — one chunk re-locks | + +Because credit is derived rather than stored, there is nothing to get out of sync: change `levels-per-chunk` in the config and every island is re-priced on the next level calculation. + +!!! tip "Setting the pace" + `levels-per-chunk` is the single biggest dial on how the game feels. + + - `1` (default) — generous. Early expansion is quick and the map opens as fast as players can build. + - `5`–`10` — deliberate. Players choose directions carefully and a chunk is an event. + - `50`+ — a long game. Suits servers where island level already runs into the thousands. + + Remember it interacts with the Level addon's block values: doubling the value of the blocks your players farm halves the real cost of a chunk. + +--- + +## Claiming: hit the border + +Expansion is a gesture, not a menu. + +1. The **island owner** stands inside their own territory. +2. They face the locked chunk they want. +3. They **left-click or right-click toward the wall**. + +If everything checks out, the chunk opens with a sound, a green particle sweep and a chat message telling everyone on the team how big the island is now and how much credit is left. + +!!! note "Only the owner can claim" + Team members share the territory, see the credit announcements and can run `/ch chunks`, but spending the island's levels is the owner's decision. + +### What is checked, in order + +| Check | Failure | What the player sees | +|---|---|---| +| Already yours? | `ALREADY_UNLOCKED` | Nothing — it is just an ordinary click | +| Inside the protection range and under `max-chunks`? | `BEYOND_LIMIT` | *"That chunk is beyond your island's protection area."* | +| Shares a face with a chunk you own? | `NOT_ADJACENT` | Nothing — diagonal aims are silently ignored | +| Enough credit? | `NO_CREDIT` | *"You need N more level(s) of credit to claim this chunk."* | + +Adjacency is by **face, not corner**: a diagonal chunk needs one of its two orthogonal neighbours claimed first. Territory therefore always stays a single connected blob. + +### How the aim is read + +The listener is careful not to turn ordinary mining into accidental claim attempts: + +- Clicking a block that is inside your own territory is never a claim, whatever is behind it. Mining a cobble generator two blocks from the wall does nothing. +- Clicking a block that is itself in a locked chunk targets that chunk directly. +- Clicking air walks a short ray (5 blocks) along your line of sight and takes the first locked chunk it enters — stopping at the first solid block, so you cannot claim through your own walls. +- Looking straight up or straight down never claims. +- Failure messages are rate-limited to one every two seconds per player, so a mining swing cannot spam chat. + +!!! tip "Bumping into the wall tells you what to do" + Walking into a locked chunk gives the owner a contextual hint rather than a flat refusal: *"Hit the border to claim this chunk for N level(s)!"* if they can afford it, or how many levels they still need if they cannot. Everyone else just gets *"That chunk is locked."* + +--- + +## Losing chunks + +If the island level drops below what has been spent, the most recently claimed chunks re-lock — **last claimed, first lost** — until the spending fits the new level. This is why the claim order is recorded. + +Nothing inside a re-locked chunk is touched. The builds, the chests, the mobs, the farms are all exactly where they were; they are simply unreachable until the levels come back. Because re-locking is strictly reverse-order, regaining the levels gives them back in the order they were lost. + +Level loss usually comes from one of three places: + +- **Deaths**, if the Level addon's death penalty is enabled — in ChunkBlock that penalty is a *territory* setting, so review it deliberately. +- **Removing blocks** — mining out a big cobble tower can genuinely shrink the island. +- **Admins** recalculating or adjusting a level. + +### Players standing in a chunk that closes + +With `eject-players-on-relock: true` (the default), anyone caught inside is moved to the nearest unlocked position in their own island: + +- The spot is the closest point inside a chunk they own, clamped one block in from the boundary so they do not land on the line. +- If the spot is not safe and the player is not flying, a landing block is created underneath them. This is the **only** time ChunkBlock modifies the world, and it always happens in an *unlocked* chunk. +- Flight state is preserved across the move, and fall damage is cancelled for a few seconds afterwards. An ejection never kills. +- A player who is not a member of that island is sent to their own island home instead, so nobody is ever dropped onto a stranger's island. + +With `eject-players-on-relock: false` they can walk out but not back in. + +### Ratchet mode + +```yaml +chunkblock: + relock-on-level-loss: false +``` + +Territory never shrinks. Chunks cost levels to claim, but once claimed they are permanent. Good for family servers, or if you would rather not have to explain the death penalty to everyone. + +--- + +## The border you cannot cross + +A locked chunk is locked at **every y**, from below the void to above the build limit. There is no fly-over corridor and no dig-under by construction — the check is 2D on purpose. + +=== "Players" + Movement into a locked chunk is cancelled *and* the player is teleported the short hop back, because cancelling alone does not hold at speed (sprint-jumping, elytra, riptide tridents can tunnel through a cancelled move). Gliders intercepted mid-flight get slow-falling so they are not dropped like a stone. + + Ender pearls and chorus fruit into locked chunks are cancelled — and the pearl is refunded, because the throw was an honest mistake. Any other teleport that ends up in locked territory (plugin homes, respawn anchors, commands) is allowed to fire and then quietly corrected a tick later. + + Joining and respawning are both re-checked one tick late, so "the chunk re-locked while I was offline" resolves itself. + +=== "Mounts and vehicles" + Horses, pigs, striders and boats do not reliably fire gated player-move events, so a mounted player is watched once a second and dismounted and moved back if the mount strays across the line. + + Boats and minecarts — ridden or drifting — are bounced back at the chunk edge. A vehicle carrying an exempt player passes freely. + +=== "Blocks and physics" + Nothing reaches across the border: + + - Pistons cannot push or pull blocks across it. + - Liquids stop flowing at it. + - Dispensers and droppers cannot fire through it. + - Trees do not grow into it, and fire, grass, vines and sculk do not spread into it. + - Explosions do not damage blocks on the other side. + - Placing, breaking, bucketing and interacting inside a locked chunk are all refused — including reach-across attempts from an unlocked chunk. + +=== "Mobs and items" + Natural mob spawning inside locked chunks is cancelled when `deny-mob-spawns-in-locked: true` (the default), so the forbidden zone does not quietly fill up with hostiles waiting for the day it opens. + + Dropped items are tracked for 20 seconds and bounced back the moment they cross the line, so a mistimed throw or a death near the wall does not feed your gear to the void. Turn it off with `bounce-back-items: false`. + +--- + +## Seeing the frontier + +`border.show-particles: true` draws a dust curtain on every face between your territory and a locked chunk, for any player within 5 blocks of it, redrawn a few times a second so it is visible even standing still. The colour is configurable; the section of curtain above the world height limit is drawn in orange so fliers can see where the wall continues. + +`border.client-side-barrier-blocks: true` adds a layer of barrier blocks on those same faces. They are sent per-player with `sendBlockChange` — **the world is never modified**, and the real blocks are restored when the player moves away, teleports, changes world or logs out. + +Both are purely cosmetic. Turning them off does not make the border any more crossable; it just makes it invisible. + +### `/ch chunks` + +``` +Chunks: 9/441. Credit: 3 level(s) — a chunk costs 1. +Your island territory (9/441 chunks): +□ □ □ □ □ +□ ▣ ▣ ▣ □ +□ ▣ ■ ■ ▣ +□ ▣ ■ ◆ ▣ +□ □ ▣ ▣ □ +■ yours ▣ claimable (1 level(s) each) □ locked +``` + +- **`■` green** — a chunk you own. +- **`▣` yellow** — claimable right now: adjacent, in range, under the limit. +- **`□` grey** — locked, and not claimable yet. +- **`◆` blue** — the chunk you are standing in. + +The map grows with your island up to a 15 × 15 view, which is as wide as chat comfortably holds. + +--- + +## Limits + +Two caps apply, and the smaller wins. + +**`max-chunks`** — a flat ceiling including the centre chunk. The default `441` is a full 21 × 21 square. `-1` means "no limit beyond the protection range". + +**The protection range** — claimed chunks must fit entirely inside it. The largest ring radius that fits is `(protection-range − 8) ÷ 16` rounded down, giving `(2r + 1)²` chunks: + +| `protection-range` | Ring radius | Chunks | +|---:|---:|---:| +| 120 | 7 | 225 | +| 168 | 10 | 441 | +| 240 (default) | 14 | 841 | +| 400 | 24 | 2401 | + +With the shipped defaults (`protection-range: 240`, `max-chunks: 441`) the flat cap is the one that bites, and an island tops out at a 21 × 21 square. When an island reaches its maximum, the last claim is announced with *"Your island has reached its maximum size!"* + +!!! warning "Raising the cap" + `protection-range` can never exceed `distance-between-islands`, and neither can be changed mid-game without resetting worlds and databases. Decide the ceiling before you open the server. + +!!! note "Why island centres are chunk-centred" + Island centres always land at x ≡ 8, z ≡ 8 within a chunk so the magic block sits in the middle of its chunk rather than on a seam. ChunkBlock computes the world offsets for this itself and snaps `distance-between-islands` to a multiple of 8 on load — which is why there are no `offset-x`/`offset-z` settings to get wrong. + +--- + +## Admin tools + +=== "/chadmin chunks <player>" + Shows the player's chunk count and effective maximum, the levels they have spent, and their current credit. The first stop for *"the game says I can't claim and I don't know why"*. + +=== "/chadmin chunks <player> reset" + Re-locks everything back to the centre chunk and clears the spending record. Their builds are untouched — they simply have to earn the territory again. Useful for testing, and for cleaning up after a level-calculation accident. + +=== "/chadmin bypass" + Toggles chunk-lock enforcement for yourself. Requires `chunkblock.mod.bypasschunks`, which is **not** granted to ops by default — you have to give it explicitly. While bypassing, you can move freely through locked chunks and the border curtain is hidden for you, which makes inspecting a reported build much easier. + + Spectator mode is always exempt, permission or not. + +--- + +## For developers + +Two events fire on every territory change, both after the fact and neither cancellable: + +- **`ChunkUnlockEvent`** — once per chunk claimed. +- **`ChunkRelockEvent`** — once per chunk lost, most recently claimed first. + +Both carry the island, the chunk offset relative to the centre chunk, and the index the chunk holds in the claim order. + +The **`unlocked-chunks`** request handler gives the same information to plugins with no compile-time dependency on ChunkBlock. See the [API section](index.md#api) for both. diff --git a/docs/gamemodes/ChunkBlock/Commands.md b/docs/gamemodes/ChunkBlock/Commands.md new file mode 100644 index 00000000..b2c890d9 --- /dev/null +++ b/docs/gamemodes/ChunkBlock/Commands.md @@ -0,0 +1,87 @@ +# ChunkBlock Commands + +The default player command is **`/ch`** (alias `/chunkblock`) and the default admin command is **`/chadmin`** (aliases `/chunkblockadmin`, `/cha`). Both, and several of the sub-command labels, are configurable under `chunkblock.command` in `config.yml`: + +```yaml +chunkblock: + command: + island: ch chunkblock + admin: chadmin chunkblockadmin cha + # Sub-command run on a player's very first /ch + new-player-action: create + # Sub-command run on every later bare /ch + default-action: go + count-command: count + phases-command: phases + set-count-command: setCount + bossbar-command: bossbar + actionbar-command: actionbar + respawn-block-command: respawnBlock check +``` + +Bare `/ch` creates an island the first time and teleports the player home thereafter. + +!!! note "Why `/ch` and not `/cb`" + ChunkBlock's defaults were `/cb` and `/cbadmin` in 1.0.0, which collide with CaveBlock. Since 1.0.1 fresh installs get `/ch` and `/chadmin`. Servers that already have a `config.yml` keep whatever aliases are in it. + +## ChunkBlock player commands + +These are the sub-commands unique to ChunkBlock. Everything else — `go`, `create`, `reset`, `sethome`, `team`, `ban`, `expel`, `settings`, `language`, `info`, `near` and the rest — is the standard BentoBox game-mode set. + +| Command | Description | Permission | +|---------|-------------|------------| +| `/ch chunks` | Your unlocked chunk count, maximum, spendable level credit, and a coloured chat map of your territory showing which chunks you can claim next. | `chunkblock.island.chunks` | +| `/ch count` | The island's current magic-block count and phase. | `chunkblock.count` | +| `/ch phases` | Open the phases GUI — browse the phases and, with permission, replay one already reached. Off by default. | `chunkblock.phases` | +| `/ch setcount ` | Jump the block count to a previously completed phase's start value. Subject to `set-count-cooldown` (5 minutes by default). | `chunkblock.island.setcount` | +| `/ch check` (alias `respawnBlock`) | Show the magic block's particles, or respawn it if it has gone missing. | `chunkblock.respawn-block` | +| `/ch bossbar` | Toggle the phase progress boss bar. Requires `bossbar: true` in config. | `chunkblock.island.bossbar` | +| `/ch actionbar` | Toggle the phase progress action bar. Requires `actionbar: true` in config. | `chunkblock.island.actionbar` | + +## ChunkBlock admin commands + +`/chadmin` carries the full standard BentoBox admin set (`version`, `tp`, `info`, `getrank`, `setrank`, `range`, `resets`, `deaths`, `purge`, `blueprint`, `register`, `delete`, `settings`, `reload`, `why`, `switch`, `team`, and so on) plus the ChunkBlock-specific commands below. + +| Command | Description | Permission | +|---------|-------------|------------| +| `/chadmin chunks ` | Show a player's unlocked chunk count, their effective maximum, the levels they have spent, and their remaining credit. | `chunkblock.admin.chunks` | +| `/chadmin chunks reset` | Re-lock everything back to the centre chunk and clear the spending record. Builds are untouched — the territory simply has to be re-earned. | `chunkblock.admin.chunks` | +| `/chadmin bypass` | Toggle chunk-lock enforcement for yourself. While bypassing you can move through locked chunks and the border curtain is hidden for you. | `chunkblock.mod.bypasschunks` | +| `/chadmin setcount [lifetime]` | Set a player's magic-block count, or their lifetime count. | `chunkblock.admin.setcount` | +| `/chadmin setchest ` | Save the chest you are looking at into a phase's chest file with the given rarity (`COMMON`, `UNCOMMON`, `RARE`, `EPIC`). The chest must be a filled single chest. | `chunkblock.admin.setchest` | +| `/chadmin sanity []` | Print a sanity check of the phase probabilities to the console. | `chunkblock.admin.sanity` | +| `/chadmin phases` | Open the phase order editor — reorder, resize, enable and disable phases. | `chunkblock.admin.phases` | + +!!! tip "`/chadmin bypass` needs a permission that ops do not have" + `chunkblock.mod.bypasschunks` defaults to `false`, so even an op has to be granted it explicitly before the command works. That is deliberate: staff play by the same rules until they opt in. Spectator mode is always exempt regardless. + +!!! tip "Using the phase order editor" + `/chadmin phases` lists every phase in order with its computed start block, length and state, and writes `phases_index.yml`. + + - **Left-click** picks a phase up; click where it should go, or the drop-at-end slot, to place it. Click anywhere else or close the panel to put it back unchanged. + - **Right-click** toggles a phase on or off. + - **Shift-left-click** sets a phase's length via a chat prompt. The first length edit writes `adminLengths: true` into the index so your lengths are never recomputed again. + + Disabled phases show as grey glass and version-locked ones as barriers; both can still be reordered. See [Phases](Phases.md) for the full picture. + +## Reading `/ch chunks` + +``` +Chunks: 9/441. Credit: 3 level(s) — a chunk costs 1. +Your island territory (9/441 chunks): +□ □ □ □ □ +□ ▣ ▣ ▣ □ +□ ▣ ■ ■ ▣ +□ ▣ ■ ◆ ▣ +□ □ ▣ ▣ □ +■ yours ▣ claimable (1 level(s) each) □ locked +``` + +| Glyph | Meaning | +|---|---| +| `■` green | A chunk you own | +| `▣` yellow | Claimable right now — adjacent, in range, under the limit | +| `□` grey | Locked, and not claimable yet | +| `◆` blue | The chunk you are standing in | + +The map widens as the island grows, up to a 15 × 15 view. diff --git a/docs/gamemodes/ChunkBlock/Permissions.md b/docs/gamemodes/ChunkBlock/Permissions.md new file mode 100644 index 00000000..cec29c22 --- /dev/null +++ b/docs/gamemodes/ChunkBlock/Permissions.md @@ -0,0 +1,142 @@ +# ChunkBlock Permissions + +Every ChunkBlock permission is prefixed `chunkblock.`. Defaults are chosen so a vanilla install plays the intended game with no permissions plugin at all: everything a player needs is `true`, admin tooling is OP, and the two nodes that would change the game itself — the phases GUI and the chunk-lock bypass — are off until you grant them. + +!!! warning "`chunkblock.mod.bypasschunks` is deliberately not an OP default" + It exempts the holder from chunk locking entirely and enables `/chadmin bypass`. Its default is `false`, **not** `op`, so staff play by the same rules as everyone else until you grant it explicitly in your permissions plugin. + + It is a separate node from `chunkblock.mod.bypasslock`, which is BentoBox's island *lock* bypass and does nothing for chunk locks. + +!!! note "Two nodes are off by default" + - `chunkblock.phases` — the `/ch phases` GUI. Grant it if you want players browsing and replaying phases. + - `chunkblock.island.setcount` — replaying a phase. OP only by default, and the phases GUI checks it before offering *"Click to change"*. + +## ChunkBlock-specific permissions + +| Permission | Description | Default | +|------------|-------------|---------| +| `chunkblock.admin.chunks` | Allow use of '/chadmin chunks' command - inspect, set or recalculate a player's unlocked chunks | OP | +| `chunkblock.admin.phases` | Allow use of '/chadmin phases' command - open the phase order editor | OP | +| `chunkblock.admin.sanity` | Allow use of '/chadmin sanity' command - display a sanity check of the phase probabilities in the console | OP | +| `chunkblock.admin.setchest` | Allow use of '/chadmin setchest' command - put the looked-at chest in a phase with the rarity specified | OP | +| `chunkblock.admin.setcount` | Allow use of '/chadmin setcount' command - set player's block count | OP | +| `chunkblock.count` | Allow use of '/ch count' command - show the block count and phase | `true` | +| `chunkblock.island.actionbar` | Allow use of '/ch actionbar' command - toggle the actionbar | `true` | +| `chunkblock.island.bossbar` | Allow use of '/ch bossbar' command - toggle the bossbar | `true` | +| `chunkblock.island.chunks` | Allow use of '/ch chunks' command - show your unlocked chunks and territory map | `true` | +| `chunkblock.island.setcount` | Allow use of '/ch setCount' command - set block count to previously completed value | OP | +| `chunkblock.mod.bypasschunks` | Exempts the holder from chunk locking entirely; also allows '/chadmin bypass' to toggle it. Not given to ops by default - it must be granted explicitly so staff play by the same rules until they opt in. | `false` | +| `chunkblock.phases` | Allow use of '/ch phases' command - show a list of all the phases | `false` | +| `chunkblock.respawn-block` | Allow use of '/ch respawnBlock' command - respawns magic block in situations when they disappear | `true` | + +## Complete list + +| Permission | Description | Default | +|------------|-------------|---------| +| `chunkblock.admin` | Allow use of '/chadmin' command - admin command | OP | +| `chunkblock.admin.blueprint` | Allow use of '/chadmin blueprint' command - manipulate blueprints | OP | +| `chunkblock.admin.blueprint.copy` | Allow use of '/chadmin blueprint copy' command - copy the clipboard set by pos1 and pos2 and optionally the air blocks | OP | +| `chunkblock.admin.blueprint.delete` | Allow use of '/chadmin blueprint delete' command - delete the blueprint | OP | +| `chunkblock.admin.blueprint.list` | Allow use of '/chadmin blueprint list' command - list available blueprints | OP | +| `chunkblock.admin.blueprint.load` | Allow use of '/chadmin blueprint load' command - load blueprint into the clipboard | OP | +| `chunkblock.admin.blueprint.origin` | Allow use of '/chadmin blueprint origin' command - set the blueprint's origin to your position | OP | +| `chunkblock.admin.blueprint.paste` | Allow use of '/chadmin blueprint paste' command - paste the clipboard to your location | OP | +| `chunkblock.admin.blueprint.pos1` | Allow use of '/chadmin blueprint pos1' command - set 1st corner of cuboid clipboard | OP | +| `chunkblock.admin.blueprint.pos2` | Allow use of '/chadmin blueprint pos2' command - set 2nd corner of cuboid clipboard | OP | +| `chunkblock.admin.blueprint.rename` | Allow use of '/chadmin blueprint rename' command - rename a blueprint | OP | +| `chunkblock.admin.blueprint.save` | Allow use of '/chadmin blueprint save' command - save the copied clipboard | OP | +| `chunkblock.admin.chunks` | Allow use of '/chadmin chunks' command - inspect, set or recalculate a player's unlocked chunks | OP | +| `chunkblock.admin.deaths` | Allow use of '/chadmin deaths' command - edit deaths of players | OP | +| `chunkblock.admin.deaths.add` | Allow use of '/chadmin deaths add' command - adds deaths to the player | OP | +| `chunkblock.admin.deaths.remove` | Allow use of '/chadmin deaths remove' command - removes deaths to the player | OP | +| `chunkblock.admin.deaths.reset` | Allow use of '/chadmin deaths reset' command - resets deaths of the player | OP | +| `chunkblock.admin.deaths.set` | Allow use of '/chadmin deaths set' command - sets deaths of the player | OP | +| `chunkblock.admin.delete` | Allow use of '/chadmin delete' command - deletes a player's island | OP | +| `chunkblock.admin.getrank` | Allow use of '/chadmin getrank' command - get a player's rank on their island or the island of the owner | OP | +| `chunkblock.admin.noban` | Player cannot be banned from an island | OP | +| `chunkblock.admin.noexpel` | Player cannot be expelled from an island | OP | +| `chunkblock.admin.phases` | Allow use of '/chadmin phases' command - open the phase order editor | OP | +| `chunkblock.admin.purge` | Allow use of '/chadmin purge' command - purge islands abandoned for more than [days] | OP | +| `chunkblock.admin.purge.protect` | Allow use of '/chadmin purge protect' command - toggle island purge protection | OP | +| `chunkblock.admin.purge.status` | Allow use of '/chadmin purge status' command - displays the status of the purge | OP | +| `chunkblock.admin.purge.stop` | Allow use of '/chadmin purge stop' command - stop a purge in progress | OP | +| `chunkblock.admin.purge.unowned` | Allow use of '/chadmin purge unowned' command - purge unowned islands | OP | +| `chunkblock.admin.range` | Allow use of '/chadmin range' command - admin island range command | OP | +| `chunkblock.admin.range.add` | Allow use of '/chadmin range add' command - increases the island protected range | OP | +| `chunkblock.admin.range.display` | Allow use of '/chadmin range display' command - show/hide island range indicators | OP | +| `chunkblock.admin.range.remove` | Allow use of '/chadmin range remove' command - decreases the island protected range | OP | +| `chunkblock.admin.range.reset` | Allow use of '/chadmin range reset' command - resets the island protected range to the world default | OP | +| `chunkblock.admin.range.set` | Allow use of '/chadmin range set' command - sets the island protected range | OP | +| `chunkblock.admin.register` | Allow use of '/chadmin register' command - register player to unowned island you are on | OP | +| `chunkblock.admin.reload` | Allow use of '/chadmin reload' command - reload | OP | +| `chunkblock.admin.resetflags` | Allow use of '/chadmin resetflags' command - Reset all islands to default flag settings in config.yml | OP | +| `chunkblock.admin.resets` | Allow use of '/chadmin resets' command - edit player reset values | OP | +| `chunkblock.admin.resets.add` | Allow use of '/chadmin resets add' command - adds this player's island reset count | OP | +| `chunkblock.admin.resets.remove` | Allow use of '/chadmin resets remove' command - reduces the player's island reset count | OP | +| `chunkblock.admin.resets.set` | Allow use of '/chadmin resets set' command - sets how many times this player has reset his island | OP | +| `chunkblock.admin.sanity` | Allow use of '/chadmin sanity' command - display a sanity check of the phase probabilities in the console | OP | +| `chunkblock.admin.setchest` | Allow use of '/chadmin setchest' command - put the looked-at chest in a phase with the rarity specified | OP | +| `chunkblock.admin.setcount` | Allow use of '/chadmin setcount' command - set player's block count | OP | +| `chunkblock.admin.setprotectionlocation` | Allow use of '/chadmin setprotectionlocation' command - set current location or [x y z] as center of island's protection area | OP | +| `chunkblock.admin.setrank` | Allow use of '/chadmin setrank' command - set a player's rank on their island or the island of the owner | OP | +| `chunkblock.admin.setspawn` | Allow use of '/chadmin setspawn' command - set an island as spawn for this gamemode | OP | +| `chunkblock.admin.setspawnpoint` | Allow use of '/chadmin setspawnpoint' command - set current location as spawn point for this island | OP | +| `chunkblock.admin.settings` | Allow use of '/chadmin settings' command - open settings GUI or set settings | OP | +| `chunkblock.admin.tp` | Allow use of '/chadmin tp/tpnether/tpend' command - teleport to a player's island | OP | +| `chunkblock.admin.unregister` | Allow use of '/chadmin unregister' command - unregister owner from island, but keep island blocks | OP | +| `chunkblock.admin.version` | Allow use of '/chadmin version' command - display BentoBox and addons versions | OP | +| `chunkblock.admin.why` | Allow use of '/chadmin why' command - toggle console protection debug reporting | OP | +| `chunkblock.count` | Allow use of '/ch count' command - show the block count and phase | `true` | +| `chunkblock.island` | Allow use of '/ch' command - the main island command | `true` | +| `chunkblock.island.actionbar` | Allow use of '/ch actionbar' command - toggle the actionbar | `true` | +| `chunkblock.island.ban` | Allow use of '/ch ban' or '/ch unban' or '/ch banlist' command - banned players | `true` | +| `chunkblock.island.bossbar` | Allow use of '/ch bossbar' command - toggle the bossbar | `true` | +| `chunkblock.island.chunks` | Allow use of '/ch chunks' command - show your unlocked chunks and territory map | `true` | +| `chunkblock.island.create` | Allow use of '/ch create' command - create an island, using optional blueprint (requires permission) | `true` | +| `chunkblock.island.deletehome` | Allow use of '/ch deletehome' command - delete a home location | OP | +| `chunkblock.island.expel` | Allow use of '/ch expel' command - expel a player from your island | `true` | +| `chunkblock.island.home` | Allow use of '/ch go' command - teleport you to your island | `true` | +| `chunkblock.island.homes` | Allow use of '/ch homes' command - list your homes | OP | +| `chunkblock.island.info` | Allow use of '/ch info' command - display info about your island or the player's island | `true` | +| `chunkblock.island.language` | Allow use of '/ch language' command - select language | `true` | +| `chunkblock.island.lock` | Allows island locking in settings | `true` | +| `chunkblock.island.name` | Allow use of '/ch setname' or '/ch resetname' command - your island name | `true` | +| `chunkblock.island.near` | Allow use of '/ch near' command - show the name of neighboring islands around you | `true` | +| `chunkblock.island.renamehome` | Allow use of '/ch renamehome' command - rename a home location | OP | +| `chunkblock.island.reset` | Allow use of '/ch reset' command - restart your island and remove the old one | `true` | +| `chunkblock.island.setcount` | Allow use of '/ch setCount' command - set block count to previously completed value | OP | +| `chunkblock.island.sethome` | Allow use of '/ch sethome' command - set your home teleport point | `true` | +| `chunkblock.island.settings` | Allow use of '/ch settings' command - display island settings | `true` | +| `chunkblock.island.spawn` | Allow use of '/ch spawn' command - teleport you to the spawn | `true` | +| `chunkblock.island.team` | Allow use of '/ch team' command - manage your team | `true` | +| `chunkblock.island.team.accept` | Allow use of '/ch team accept' command - accept an invitation | `true` | +| `chunkblock.island.team.coop` | Allow use of '/ch team coop, uncoop' commands | `true` | +| `chunkblock.island.team.invite` | Allow use of '/ch team invite' command - invite a player to join your island | `true` | +| `chunkblock.island.team.kick` | Allow use of '/ch team kick' command - remove a member from your island | `true` | +| `chunkblock.island.team.leave` | Allow use of '/ch team leave' command - leave your island | `true` | +| `chunkblock.island.team.promote` | Allow use of '/ch team promote, demote' command | `true` | +| `chunkblock.island.team.reject` | Allow use of '/ch team reject' command - reject an invitation | `true` | +| `chunkblock.island.team.setowner` | Allow use of '/ch team setowner' command - transfer your island ownership to a member | `true` | +| `chunkblock.island.team.trust` | Allow use of '/ch team trust, untrust' commands | `true` | +| `chunkblock.mod.bypassban` | Bypasses island ban | OP | +| `chunkblock.mod.bypasschunks` | Exempts the holder from chunk locking entirely; also allows '/chadmin bypass' to toggle it. Not given to ops by default - it must be granted explicitly so staff play by the same rules until they opt in. | `false` | +| `chunkblock.mod.bypasscooldowns` | Allow moderator to bypass cooldowns | OP | +| `chunkblock.mod.bypassdelays` | Allow moderator to bypass delays | OP | +| `chunkblock.mod.bypassexpel` | Allow moderator to bypass island expulsion | OP | +| `chunkblock.mod.bypasslock` | Bypasses an island lock | OP | +| `chunkblock.mod.bypassprotect` | Allow moderator to bypass island protection | OP | +| `chunkblock.mod.clearreset` | Allow clearing of island reset limit | `false` | +| `chunkblock.mod.deletehomes` | Allow use of '/chadmin deletehomes' command - deletes all named homes from an island | OP | +| `chunkblock.mod.info` | Allow use of '/chadmin info' command - get info on where you are or player's island | OP | +| `chunkblock.mod.lock` | Allows lock or unlock of an island | OP | +| `chunkblock.mod.resetname` | Allow use of '/chadmin resetname' command - reset player island name | OP | +| `chunkblock.mod.switch` | Allow use of '/chadmin switch' command - switch on/off protection bypass | OP | +| `chunkblock.mod.team` | Allow use of '/chadmin team' command - manage teams | `false` | +| `chunkblock.mod.team.add` | Allow use of '/chadmin team add' or '/chadmin add' command - add player to owner's team | OP | +| `chunkblock.mod.team.disband` | Allow use of '/chadmin team disband' or '/chadmin disband' command - disband owner's team | OP | +| `chunkblock.mod.team.fix` | Allow use of '/chadmin team fix' or '/chadmin fix' command - scans and fixes cross island membership in database | OP | +| `chunkblock.mod.team.kick` | Allow use of '/chadmin team kick' or '/chadmin kick' command - kick a player from a team | OP | +| `chunkblock.mod.team.setowner` | Allow use of '/chadmin team setowner' command - transfers island ownership to the player | OP | +| `chunkblock.phases` | Allow use of '/ch phases' command - show a list of all the phases | `false` | +| `chunkblock.respawn-block` | Allow use of '/ch respawnBlock' command - respawns magic block in situations when they disappear | `true` | +| `chunkblock.settings.*` | Allow use of settings on island | `true` | \ No newline at end of file diff --git a/docs/gamemodes/ChunkBlock/Phases.md b/docs/gamemodes/ChunkBlock/Phases.md new file mode 100644 index 00000000..78ffe955 --- /dev/null +++ b/docs/gamemodes/ChunkBlock/Phases.md @@ -0,0 +1,155 @@ +# 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. + +!!! abstract "Full field reference: [Customizing AOneBlock Phases](../AOneBlock/Phases.md)" + That guide is the complete walkthrough — what every number means, how the weighted raffle works with worked examples, chests, custom blocks, version gating and how to build a phase from scratch. All of it applies here unchanged. + + Only the **command names** differ: read `/oba` as `/chadmin` and `/ob` as `/ch` throughout. + +This page covers what is specific to ChunkBlock. + +--- + +## What ships + +Twenty phases, 15,500 blocks of content on a Minecraft 26.2+ server: + +| # | Phase | Length | Starts at | +|---:|---|---:|---:| +| 1 | Plains | 700 | 0 | +| 2 | Underground | 1300 | 700 | +| 3 | Winter | 1000 | 2000 | +| 4 | Ocean | 1000 | 3000 | +| 5 | Jungle | 1000 | 4000 | +| 6 | Swamp | 1000 | 5000 | +| 7 | Dungeon | 1000 | 6000 | +| 8 | Desert | 500 | 7000 | +| 9 | The Nether | 1000 | 7500 | +| 10 | Plenty | 1000 | 8500 | +| 11 | Desolation | 1000 | 9500 | +| 12 | Deep Dark | 1000 | 10500 | +| 13 | The End | 500 | 11500 | +| 14 | Lush Caves | 500 | 12000 | +| 15 | Dripstone Caves | 500 | 12500 | +| 16 | Mangrove Swamp | 500 | 13000 | +| 17 | Meadow | 500 | 13500 | +| 18 | Cherry Grove | 500 | 14000 | +| 19 | Jagged Peaks | 500 | 14500 | +| 20 | Sulfur Caves | 500 | 15000 | + +**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: + +| Field | Meaning | +|---|---| +| `file` | Base name of the phase file in the `phases` folder, without `.yml`. The chest file is `_chests.yml`. | +| `section` | The top-level key inside the phase file (historically the start block). | +| `name` | Display name, used in logs and in the `/chadmin 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**: 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. + +!!! warning "Deleting a phase" + To remove a phase permanently, delete its files, or toggle it off in `/chadmin 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 direct file loading, so a bad edit cannot leave the addon stuck. + +!!! tip "Numbers in file names are optional" + A custom `desert.yml` with a `desert:` section works fine. Chest files still pair by file name (`_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. + +--- + +## 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 ` — 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 [lifetime]` — set a player's block count, or their lifetime count. +- `/chadmin setchest ` — 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 []` — 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 + +!!! warning "The magic block is in the centre chunk, always" + The centre chunk can never be locked, so the magic block is always reachable. This is guaranteed by the data model rather than by a check: the claim list always starts with the centre chunk and re-locking can never remove it. + +!!! note "Mob-spawn block clearing respects the border" + `mobs-clear-blocks: true` lets spawning mobs break blocks to make room — a cheat prevention carried over from AOneBlock so players cannot box the magic block in and suffocate everything. Locked chunks are never modified, so this only ever affects your own territory. + +!!! tip "Phases and territory pull against each other" + Blocks the magic block produces raise island level, and island level buys chunks — so a generous phase is also a fast-expanding phase. If expansion feels too quick on your server, raising `levels-per-chunk` is usually a better lever than rebalancing phase weights. + +!!! note "The Nether and End phases still run" + The Nether and The End phases are part of the progression regardless of whether the Nether and End *worlds* are generated (both are off by default). They deliver nether and end blocks and mobs through the overworld magic block. diff --git a/docs/gamemodes/ChunkBlock/Placeholders.md b/docs/gamemodes/ChunkBlock/Placeholders.md new file mode 100644 index 00000000..f3acc4d6 --- /dev/null +++ b/docs/gamemodes/ChunkBlock/Placeholders.md @@ -0,0 +1,16 @@ +# ChunkBlock placeholders + +ChunkBlock registers the magic-block placeholders inherited from the AOneBlock engine, all prefixed `chunkblock_`, plus five territory placeholders of its own. + +!!! tip "The five you probably want on your scoreboard" + - `%chunkblock_island_chunks%` — chunks owned + - `%chunkblock_island_max_chunks%` — the ceiling + - `%chunkblock_island_chunk_credit%` — levels available to spend right now + - `%chunkblock_island_next_chunk_level%` — the island level that buys the next chunk + - `%chunkblock_island_ring%` — how far the territory reaches from the centre + + `credit` and `chunks` together are the whole progression at a glance: *"9 chunks, 3 to spend."* + +Placeholders that read a player's **own** island resolve to the island they own, even while they are standing on someone else's. The `visited_island_*` variants read the island the player is currently on. + +{{ placeholders_bundle(gamemode_name="chunkblock") }} diff --git a/docs/gamemodes/ChunkBlock/index.md b/docs/gamemodes/ChunkBlock/index.md new file mode 100644 index 00000000..9f675d71 --- /dev/null +++ b/docs/gamemodes/ChunkBlock/index.md @@ -0,0 +1,403 @@ +# ChunkBlock + +One magic block. One chunk. A wall you cannot walk through. + +**ChunkBlock** takes the OneBlock loop everyone knows — mine the magic block, it comes back as something else, phases roll past — and puts a hard border 16 blocks away. Everything outside your starting chunk is a forbidden zone: you cannot walk, fly, glide, pearl, ride or dig your way into it. The only way out is to get *richer*. + +Island levels are the currency. Build up your level, walk to the wall, and **hit it in the direction you want to grow**. The chunk on the other side opens up and the border moves out one step. Lose levels and the wall comes back in — newest chunks first — and your farm is behind it until you earn them back. + +Created and maintained by [tastybento](https://github.com/tastybento). The magic-block engine comes from [AOneBlock](../AOneBlock/index.md), so phase files are interchangeable; the chunk gating is original to ChunkBlock. + +{{ addon_description("ChunkBlock") }} + +## Why players get hooked + +- 🔒 **A border you genuinely cannot cross.** Walking, sprint-jumping, elytra, riptide tridents, ender pearls (refunded), chorus fruit, horses, boats, minecarts and creative flight are all gated — at *every* height, from the void to above the build limit. There is no fly-over corridor and no dig-under. +- 💰 **Levels are territory.** Not a shop, not a rank, not a timer. The thing your players already optimise — island level — is the thing that buys space. Every block placed is a down payment on the next chunk. +- 👊 **Expansion is a physical gesture.** No GUI, no `/buy chunk`. The owner stands at the wall, punches it, and the world opens up with a sound and a green sweep of particles. They choose the direction, so no two islands grow the same shape. +- ⚠️ **Loss has teeth — without being cruel.** Level drops re-lock the most recently claimed chunks in exact reverse order. Nothing inside is touched: the builds, the chests, the mobs are all still there when the levels come back. Prefer a gentler game? One config line makes territory a ratchet that never shrinks. +- 🗺️ **You can see the frontier.** A per-player particle curtain marks every locked face near you (optionally with client-side barrier blocks), and `/ch chunks` prints a coloured map of what you own, what you can claim next, and what it costs. +- 🧱 **Nothing leaks across.** Pistons, flowing liquids, dispensers, tree growth, fire and grass spread, explosions and natural mob spawns all stop at the line, and dropped items bounce back rather than being lost to the forbidden zone. +- ⛏️ **The full OneBlock game underneath.** 20 themed phases, 15,500 blocks of content, weighted block and mob pools, rarity chests, holograms, boss bar and action bar progress — all of it, in a box that grows. + +## How a session feels + +You spawn on a grass block in the middle of nowhere with a red wall in every direction. Mine. Mine again. Cobble, dirt, a chicken that immediately walks off the edge. Somewhere around the fiftieth block the chat says you have credit, so you turn to face the sunrise side, punch the wall, and it *falls away* — twice the world you had a second ago, and now you can actually build a wheat farm without knocking your own tower over. + +Fifty levels later your island is a 3×3 block of chunks and you are picking directions deliberately: the ocean phase is coming, and you want the room for it on the east side where the drop is. Then you die badly in the Dungeon phase, lose a chunk's worth of levels, and the newest chunk snaps shut with your furnace bank inside it. It is not gone. It is just *behind the wall* until you get those levels back. + +## Setup + +!!! warning "The Level addon is required" + Island level is the only chunk currency, so ChunkBlock will not run without [Level](../../addons/Level/index.md). If Level is missing, ChunkBlock disables itself with a clear message in the console rather than half-starting. + +0. Install BentoBox and run the server once so its folders exist. +1. Install the **Level** addon into `plugins/BentoBox/addons/`. +2. Drop the **ChunkBlock** jar into `plugins/BentoBox/addons/` and restart. +3. ChunkBlock creates `chunkblock_world`, a data folder, a `config.yml`, a `phases` folder and `phases_index.yml`. +4. Stop the server, edit `config.yml` to taste, and delete any world it created if your changes affect generation. +5. Restart. + +ChunkBlock runs happily beside AOneBlock, CaveBlock and the rest — its own world, commands (`/ch`, `/chadmin`), permissions (`chunkblock.*`), flags and database table. + +!!! tip "Recommended companions" + - **Level** — required, and worth tuning: its death penalty and block values are, in ChunkBlock, *territory* settings. + - **Border** — compatible. It draws the island's overall protection limit; the chunk frontier inside it is ChunkBlock's own curtain. + - **InvSwitcher** — keeps inventories separate from your other game modes. + - Challenges, Warps, Likes, Biomes, Greenhouses and friends all work as usual inside unlocked chunks. + +## Compatibility + +| Feature | Supported | +|---|---| +| Server | ✅ Paper / Spigot, Minecraft 1.21+ | +| BentoBox version | ✅ 3.13.0 or later | +| Java version | ✅ Java 21 | +| Level addon | ⚠️ Required — island level is the chunk currency | +| Nether / End | ⚪ Generated off by default; see below | + +## Configuration + +`config.yml` is the standard BentoBox game-mode file plus one ChunkBlock-only block. Every option is commented in the file itself; the latest copy lives at [config.yml](https://github.com/BentoBoxWorld/ChunkBlock/blob/develop/src/main/resources/config.yml). + +### The chunk settings + +```yaml +chunkblock: + # How many island levels one chunk costs to claim. Minimum 1. + levels-per-chunk: 1 + # Maximum number of chunks an island can claim, including the center chunk. + # 441 is a full 21 x 21 chunk square. -1 means "whatever the protection range holds". + max-chunks: 441 + # Losing levels below what has been spent re-locks chunks, newest first. + # false = 'ratchet mode': chunks never re-lock once claimed. + relock-on-level-loss: true + # Move players out of a chunk that re-locks under their feet. + eject-players-on-relock: true + # Cancel natural mob spawning inside locked chunks. + deny-mob-spawns-in-locked: true + # Bounce dropped items back at the border instead of losing them. + bounce-back-items: true + border: + # Per-player particle curtain on locked chunk faces. + show-particles: true + particle-color: + ==: Color + ALPHA: 255 + RED: 255 + GREEN: 0 + BLUE: 0 + # Also send client-side barrier blocks. Purely visual; the world is never modified. + client-side-barrier-blocks: false +``` + +!!! abstract "Full guide: [Claiming Chunks](Chunks.md)" + What each setting does to the feel of the game, worked credit examples, the re-lock rules, and how to tune the pace for a casual or a hardcore server. + +### World settings that matter more than usual + +=== "distance-between-islands" + !!! summary "Must be a multiple of 8" + Island centres have to land in the middle of a chunk (x ≡ 8, z ≡ 8) or the magic block would sit on a chunk seam. ChunkBlock snaps this value to the nearest multiple of 8 on load, so a hand-edited `250` quietly becomes `248`. The default is `256`. + +=== "protection-range" + !!! summary "A second, hard size cap" + Claimed chunks must fit entirely inside the island's protection range, so the range caps territory no matter what `max-chunks` says. The largest ring radius that fits is `(protection-range − 8) ÷ 16`, rounded down, giving `(2r + 1)²` chunks. + + With the defaults — `protection-range: 240` — that is a radius of 14, or 841 chunks, so `max-chunks: 441` is the setting that actually bites. If you raise `max-chunks`, check the range holds it, and remember the range can never exceed `distance-between-islands`. + +=== "offset-x / offset-z" + !!! summary "Deliberately absent" + Other game modes expose world offsets. ChunkBlock computes them internally from `start-x`/`start-z` so the magic block is always chunk-centred, and does not offer the settings at all. + +=== "nether and end" + !!! summary "Off by default" + Both `nether.generate` and `end.generate` default to `false`. Turn either on and that dimension gets its own centre chunk and the same claim rules, driven by the same island level. The magic block only ever exists in the overworld. + +### Phases + +The magic block, the phase files and `phases_index.yml` behave exactly as they do in AOneBlock — the formats are byte-for-byte compatible, so community phase packs drop straight in. + +!!! abstract "Full guide: [The Magic Block and Phases](Phases.md)" + The shipped 20-phase progression, the phase index, the admin phase editor, and where to find the complete field reference. + +### Customizable GUIs + +ChunkBlock uses the BentoBox templated-panel API for its phases GUI. On first run it creates a `panels` folder under `plugins/BentoBox/addons/ChunkBlock` containing `phases_panel.yml`. See [Customizable GUIs](../../Tutorials/generic/Customizable-GUI.md) for the mechanics; the `PREVIOUS`, `NEXT` and `PHASE` button types work as described in the [AOneBlock documentation](../AOneBlock/index.md#customizable-guis). + +## Commands + +!!! tip + The default player command is `/ch` (alias `/chunkblock`) and the default admin command is `/chadmin` (aliases `/chunkblockadmin`, `/cha`). Both are configurable under `chunkblock.command` in `config.yml`. + +=== "ChunkBlock unique player commands" + - `/ch chunks` — your chunk count, spendable credit and a chat map of your territory. + - `/ch count` — the current magic-block count and phase. + - `/ch phases` — the phases GUI. + - `/ch setcount ` — replay a phase you have already reached. + - `/ch check` — respawn the magic block, or show its particles. + - `/ch bossbar` / `/ch actionbar` — toggle the phase progress displays. + +=== "ChunkBlock unique admin commands" + - `/chadmin chunks [reset]` — inspect a player's chunks, spending and credit, or re-lock them back to the centre chunk. + - `/chadmin bypass` — toggle chunk-lock enforcement for yourself. + - `/chadmin setcount [lifetime]` — set a player's block count. + - `/chadmin setchest ` — save the chest you are looking at into a phase. + - `/chadmin sanity []` — check phase probabilities in the console. + - `/chadmin phases` — the phase order editor. + +[Complete ChunkBlock command list](Commands.md) + +## Permissions + +!!! tip + Every ChunkBlock permission is prefixed `chunkblock.`. + +!!! warning "`chunkblock.mod.bypasschunks` is not given to ops" + The chunk-lock bypass defaults to `false` — **not** `op` — so staff play by the same rules as everyone else until you grant it explicitly in your permissions plugin. It is deliberately a separate node from BentoBox's `chunkblock.mod.bypasslock`, which bypasses the island *lock* and is a different feature. + +=== "Player permissions" + - `chunkblock.island.chunks` — use `/ch chunks`. Default `true`. + - `chunkblock.count` — use `/ch count`. Default `true`. + - `chunkblock.phases` — use `/ch phases`. Default `false`. + - `chunkblock.island.setcount` — use `/ch setcount`. Default OP. + - `chunkblock.respawn-block` — use `/ch check`. Default `true`. + - `chunkblock.island.bossbar` / `chunkblock.island.actionbar` — toggle the progress displays. Default `true`. + +=== "Admin permissions" + - `chunkblock.admin.chunks` — use `/chadmin chunks`. Default OP. + - `chunkblock.mod.bypasschunks` — exempt from chunk locking, and use `/chadmin bypass`. **Default `false`.** + - `chunkblock.admin.setcount`, `chunkblock.admin.setchest`, `chunkblock.admin.sanity`, `chunkblock.admin.phases` — default OP. + +[Complete ChunkBlock permission list](Permissions.md) + +## Flags + +ChunkBlock registers its own flag IDs so it can run alongside AOneBlock without either addon losing its flags to a duplicate registration. + +| Flag | Type | Description | Default | +|---|---|---|---| +| `CHUNKBLOCK_START_SAFETY` | World Setting | Players cannot move for a short time after creating an island, so they cannot immediately fall off. Duration is `starting-safety-duration` in config. | false | +| `CHUNKBLOCK_BOSSBAR` | Island Setting | Show the phase progress boss bar. Only available with `bossbar: true` in config. | true | +| `CHUNKBLOCK_ACTIONBAR` | Island Setting | Show the phase progress action bar. Only available with `actionbar: true` in config. | true | +| `MAGIC_BLOCK` | Protection | Minimum island rank required to break the magic block. | COOP | + +!!! warning "Upgrading from 1.0.0" + These flags were called `START_SAFETY`, `ONEBLOCK_BOSSBAR` and `ONEBLOCK_ACTIONBAR` in 1.0.0. If you changed any of them from the default, re-apply the setting once after upgrading — the old values are no longer read. + +## Placeholders + +Alongside the phase placeholders inherited from the magic-block engine, ChunkBlock adds five territory placeholders: + +| Placeholder | Description | +|---|---| +| `%chunkblock_island_chunks%` | Unlocked chunk count, including the centre chunk | +| `%chunkblock_island_max_chunks%` | Maximum chunks this island can claim | +| `%chunkblock_island_chunk_credit%` | Level credit available to spend right now | +| `%chunkblock_island_next_chunk_level%` | Total island level needed to afford the next chunk | +| `%chunkblock_island_ring%` | Ring number of the outermost claimed chunk | + +[Complete ChunkBlock placeholder list](Placeholders.md) + +## FAQ + +??? question "Why can't I walk past the glowing red wall?" + That chunk is still locked. If you are the island owner and you have level credit, hit the wall and it opens. `/ch chunks` shows your credit and what is claimable. + +??? question "Can team members claim chunks?" + No — claiming is the island owner's call. Everyone on the team benefits from the space, sees the credit announcements and can use `/ch chunks`, but only the owner's punch at the border spends the levels. + +??? question "I lost levels and my farm is behind the wall now. Is it gone?" + No. Nothing inside a re-locked chunk is touched — the blocks, chests and mobs are exactly as you left them. Regain the levels and claim it back; re-locking always takes the newest chunks first, so you get them back in the order you lost them. Admins can disable re-locking entirely with `relock-on-level-loss: false`. + +??? question "A chunk re-locked while I was standing in it. What happens to me?" + You are moved to the nearest unlocked spot inside your own island — flight state preserved, fall damage cancelled, and a landing block created underneath you if the spot was not safe. Nobody is ever stranded or dropped into the void. Players who do not belong to that island are sent to their own island home instead. + +??? question "How do I get more chunks faster?" + Raise your island level: place more, and more valuable, blocks. Lower `levels-per-chunk` if you want expansion to feel generous, or raise it if you want the map to open slowly. + +??? question "Can I claim diagonally?" + Not directly. A new chunk must share a **face** with territory you already own, so a corner chunk needs one of its two neighbours claimed first. + +??? question "How big can an island get?" + Whichever is smaller: `max-chunks` (default 441, a 21×21 square) or the largest square of chunks that fits inside the island's protection range. `/ch chunks` shows the effective maximum. + +??? question "Why do I keep falling and dying?" + A chunk is not much room at the start. Build out before you build up — and remember that deaths can cost levels, and levels are territory. + +??? question "What phases are there?" + The same progression as AOneBlock: 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. See [Phases](Phases.md). + +??? question "Is there a Nether or an End?" + Both are turned off by default. Enable them in `config.yml` and each gets its own centre chunk and the same claim rules. The magic block only exists in the overworld. + +??? question "Do I need the Border addon?" + No, and you do not need to remove it either. Border draws the island's outer protection limit; ChunkBlock draws the chunk frontier inside it. They show different things and coexist fine. + +??? question "I have a bug, or a feature idea. Where do I put it?" + On the [issue tracker](https://github.com/BentoBoxWorld/ChunkBlock/issues). + +## Translations + +{{ translations("ChunkBlock") }} + +## API + +ChunkBlock stores its data in its own database table, `ChunkBlockIslands`, and exposes its territory state through events, a request handler and the addon class. + +Add it to your project as a provided dependency: + +```xml + + world.bentobox + chunkblock + 1.0.1 + provided + +``` + +### Data object + +=== "OneBlockIslands" + !!! summary "Description" + Per-island state: the magic-block progress inherited from the AOneBlock engine, plus the chunk territory. + + Link to the source: [OneBlockIslands](https://github.com/BentoBoxWorld/ChunkBlock/blob/develop/src/main/java/world/bentobox/chunkblock/dataobjects/OneBlockIslands.java) + + !!! question "Variables" + - `uniqueId` — the island unique ID, equal to the Island's `uniqueId`. + - `blockNumber` — the current broken block number. + - `lifetime` — the total number of blocks ever broken. + - `phaseName` — the current phase name. + - `hologram` — the hologram text being shown. + - `unlockedChunks` — the ordered `"dx,dz"` claim list, relative to the centre chunk. `"0,0"` is always first and can never be removed. + - `lastKnownLevel` — the island level as of the last calculation, used to detect gains and losses. + + !!! example "Code example" + ```java + public void accessChunkBlockData(@NonNull Island island) { + BentoBox.getInstance().getAddonsManager().getAddonByName("ChunkBlock") + .ifPresent(chunkBlock -> { + OneBlockIslands data = chunkBlock.getOneBlocksIsland(island); + int chunks = data.getUnlockedChunkCount(); + List claimOrder = data.getUnlockedChunks(); + + ChunkManager cm = chunkBlock.getChunkManager(); + long credit = cm.getCredit(island); + long spent = cm.getSpentLevels(island); + int max = cm.getMaxChunks(island); + boolean here = cm.isUnlocked(island, someLocation); + }); + } + ``` + +### Events + +ChunkBlock fires the AOneBlock magic-block events (`BlockClearEvent`, `MagicBlockEntityEvent`, `MagicBlockEvent`, `MagicBlockPhaseEvent` — see the [AOneBlock API section](../AOneBlock/index.md#events), same fields, in the `world.bentobox.chunkblock.events` package) plus two of its own. + +=== "ChunkUnlockEvent" + !!! summary "Description" + Fired once for each chunk an island claims. **Not cancellable** — the claim has already been decided and paid for; this is a notification. + + Link to the class: [ChunkUnlockEvent](https://github.com/BentoBoxWorld/ChunkBlock/blob/develop/src/main/java/world/bentobox/chunkblock/events/ChunkUnlockEvent.java) + + !!! question "Variables" + - `@NonNull Island island` — the island that claimed the chunk. + - `@NonNull Vector chunkOffset` — the chunk offset relative to the island's centre chunk (x and z; y is always 0). + - `int unlockIndex` — the chunk's position in the island's claim order. The centre chunk is 0. + + !!! example "Code example" + ```java + @EventHandler(priority = EventPriority.MONITOR) + public void onChunkUnlock(ChunkUnlockEvent event) { + Island island = event.getIsland(); + Vector offset = event.getChunkOffset(); + int index = event.getUnlockIndex(); + } + ``` + +=== "ChunkRelockEvent" + !!! summary "Description" + Fired once for each chunk an island loses when its level drops. **Not cancellable.** Events arrive most-recently-claimed first, matching the order the chunks are actually taken back. + + Link to the class: [ChunkRelockEvent](https://github.com/BentoBoxWorld/ChunkBlock/blob/develop/src/main/java/world/bentobox/chunkblock/events/ChunkRelockEvent.java) + + !!! question "Variables" + - `@NonNull Island island` — the island that lost the chunk. + - `@NonNull Vector chunkOffset` — the chunk offset relative to the island's centre chunk. + - `int unlockIndex` — the position the chunk held in the claim order. + + !!! example "Code example" + ```java + @EventHandler(priority = EventPriority.MONITOR) + public void onChunkRelock(ChunkRelockEvent event) { + Island island = event.getIsland(); + Vector offset = event.getChunkOffset(); + int index = event.getUnlockIndex(); + } + ``` + +### Request handlers + +Plugins that do not want a compile-time dependency can use the [Addon Request API](../../BentoBox/Request-Handler-API---How-plugins-can-get-data-from-addons.md). ChunkBlock registers `island-stats` and `location-stats` from the magic-block engine, plus: + +=== "unlocked-chunks" + !!! summary "Description" + Territory information for a player's island. Submit `"player"` → `UUID`. Returns an empty map if the player has no island in the ChunkBlock world. + + !!! question "Returned map" + - `count` — `Integer`, unlocked chunks including the centre. + - `max` — `Integer`, the maximum this island can unlock. + - `ring` — `Integer`, the ring number of the outermost unlocked chunk. + - `spent` — `Long`, levels already spent on chunks. + - `credit` — `Long`, level credit available to spend. + - `chunks` — `List`, the `"dx,dz"` offsets in claim order. + + !!! example "Code example" + ```java + Map request = Map.of("player", player.getUniqueId()); + @SuppressWarnings("unchecked") + Map result = (Map) new AddonRequestBuilder() + .addonName("ChunkBlock") + .label("unlocked-chunks") + .addMetaData(request) + .request(); + int chunks = (int) result.getOrDefault("count", 0); + ``` + +## Changelog + +??? note "What's new in v1.0.0" + **Released:** 2026-07-28 + + The first release. The OneBlock loop, in a chunk that grows when you pay for it. + + - **Claim chunks by hitting the border.** Island levels are spendable credit (`levels-per-chunk` per claim, default 1). The owner aims at the wall and punches or right-clicks to open the next chunk, in any direction. + - **Territory has consequences.** Every claim is recorded in order; if the island level drops below what has been spent, the most recently claimed chunks re-lock, newest first. Builds inside are untouched. `relock-on-level-loss: false` gives ratchet mode. + - **A border you truly cannot cross.** Walking, sprint-jumping, elytra, riptide, ender pearls (refunded), chorus fruit, mounts, boats and flight are gated at any height. Pistons, liquids, dispensers, tree growth, spread and explosions cannot reach across, and dropped items bounce back. + - **A frontier you can see.** A per-player particle curtain marks locked chunk faces, with optional client-side barrier blocks, plus celebration effects when credit is earned and chunks are claimed. The world itself is never modified. + - **`/ch chunks`** — a coloured chat map of your territory, what you can claim next, and your credit. + - **Safe by design.** Players caught in a re-locking chunk are moved to the nearest unlocked spot with flight preserved and no fall damage. + - **Requires the Level addon** — island level is the one and only chunk currency. + + [Release 1.0.0](https://github.com/BentoBoxWorld/ChunkBlock/releases/tag/1.0.0) + +!!! warning "What's new in v1.0.1 — flag IDs and default commands changed" + **Released:** 2026-07-30 + + Patch release fixing every bug reported against 1.0.0, plus two compatibility problems that only appear when running ChunkBlock alongside other game modes. + + - 🐛 **Mining near the border no longer spams claim messages.** Claim detection ignored the block you actually clicked and passed through walls, so mining a generator a few blocks from a locked chunk nagged *"You need X more level(s) of credit"* on every swing. Claims now only trigger on a genuine aim at the border, and failure feedback is rate-limited. Fixes [#14](https://github.com/BentoBoxWorld/ChunkBlock/issues/14). + - 🐛 **Respawns can no longer strand players on a stranger's island.** A respawn landing in a locked chunk of an old or abandoned island used to relocate the player *within that island*, generating a landing block. Players who do not belong to the island are now sent to their own island home. Fixes [#13](https://github.com/BentoBoxWorld/ChunkBlock/issues/13). + - 🔡 **The phases GUI respects the setcount permission.** *"Click to change"* is no longer offered to players without `chunkblock.island.setcount`, and the GUI title says *ChunkBlock* Phases. Fixes [#11](https://github.com/BentoBoxWorld/ChunkBlock/issues/11). + - 🔺 ⚙️ **Own flag IDs, no more AOneBlock collision.** The boss bar, action bar and start-safety flags are now `CHUNKBLOCK_BOSSBAR`, `CHUNKBLOCK_ACTIONBAR` and `CHUNKBLOCK_START_SAFETY`. They previously shared AOneBlock's IDs, and BentoBox rejects duplicate flag registrations — so on servers running both, whichever addon loaded second silently lost its flags. + - 🔺 ⚙️ **Default commands changed from `/cb` to `/ch`.** CaveBlock already uses `/cb` and `/cbadmin`, so the defaults are now `ch chunkblock` (player) and `chadmin chunkblockadmin cha` (admin). Existing servers keep whatever aliases are in their `config.yml`; only fresh installs get the new defaults. + - **Clean shutdown when Level is missing.** ChunkBlock now disables itself with a clear message instead of leaving half-registered listeners that spammed errors on every join and move. + + 🔺 **After upgrading:** if you changed the boss bar, action bar or start-safety world settings from their defaults, re-apply them once — the old `ONEBLOCK_*` / `START_SAFETY` values are no longer read. + + 🔡 **Locale note:** keys were renamed (`protection.flags.CHUNKBLOCK_*`, phases GUI titles). Regenerate or update customised locale files. + + **Compatibility:** BentoBox API 3.13.0+, Minecraft 1.21+, Java 21. + + [Release 1.0.1](https://github.com/BentoBoxWorld/ChunkBlock/releases/tag/1.0.1) diff --git a/mkdocs.yml b/mkdocs.yml index bac65489..acf4fb0e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,13 @@ nav: - BSkyBlock: gamemodes/BSkyBlock/index.md - Boxed: gamemodes/Boxed/index.md - CaveBlock: gamemodes/CaveBlock/index.md + - ChunkBlock: + - Overview: gamemodes/ChunkBlock/index.md + - Claiming Chunks: gamemodes/ChunkBlock/Chunks.md + - Phases: gamemodes/ChunkBlock/Phases.md + - Commands: gamemodes/ChunkBlock/Commands.md + - Permissions: gamemodes/ChunkBlock/Permissions.md + - Placeholders: gamemodes/ChunkBlock/Placeholders.md - Poseidon: gamemodes/Poseidon/index.md - SkyGrid: gamemodes/SkyGrid/index.md - Stranger Realms: gamemodes/StrangerRealms/index.md From 771e1835a7e896dfc5085aeffc1aefa5ed9c6cef Mon Sep 17 00:00:00 2001 From: tastybento Date: Fri, 7 Aug 2026 22:25:29 -0700 Subject: [PATCH 2/2] docs(TopBlock): document ChunkBlock support in v2.1.0 TopBlock 2.1.0 hooks AOneBlock, ChunkBlock, or both, keeping a separate top ten, command and placeholder set per game mode. - Rewrite the intro: TopBlock is no longer AOneBlock-only, and link both supported game modes. - Add an installation note that TopBlock needs at least one of the two game modes and hooks whichever it finds at startup. - Note that config settings are global across hooked game modes, and that refresh-time reads every island of every hooked game mode. - Explain that the topblock subcommand is registered per game mode and opens the panel for the world it was run in. - Document the new chunkblock.island.topblock and chunkblock.intopten permissions, plus a FAQ covering how intopten actually behaves: it is only checked while the owner is online, and only for the island owner. - Add the six chunkblock_island_*_top_ placeholders to placeholders.csv and explain that the sets never mix. - Add the v2.1.0 changelog entry. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01UtAC44orba7UkTpFwHEw22 --- data/placeholders.csv | 6 +++++ docs/addons/TopBlock/index.md | 47 ++++++++++++++++++++++++++++++----- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/data/placeholders.csv b/data/placeholders.csv index 335a265f..4781cf73 100644 --- a/data/placeholders.csv +++ b/data/placeholders.csv @@ -131,6 +131,12 @@ TopBlock,aoneblock_island_phase_name_top_,Name of the phase they have re TopBlock,aoneblock_island_phase_number_top_,Phase number (e.g. Plains is 1; Underground is 2) at the `` position, 1.0.1 TopBlock,aoneblock_island_count_top_,Block Count of magic blocks mined this round at the `` position, 1.0.1 TopBlock,aoneblock_island_lifetime_top_,Lifetime count of magic blocks mined at the `` position, 1.0.1 +TopBlock,chunkblock_island_player_name_top_,Island owner's name at the `` position, 2.1.0 +TopBlock,chunkblock_island_member_names_top_,Name of island team members at the `` position, 2.1.0 +TopBlock,chunkblock_island_phase_name_top_,Name of the phase they have reached at the `` position, 2.1.0 +TopBlock,chunkblock_island_phase_number_top_,Phase number (e.g. Plains is 1; Underground is 2) at the `` position, 2.1.0 +TopBlock,chunkblock_island_count_top_,Block Count of magic blocks mined this round at the `` position, 2.1.0 +TopBlock,chunkblock_island_lifetime_top_,Lifetime count of magic blocks mined at the `` position, 2.1.0 Border,Border_color,Current border color (red/green/blue) for the player,4.8.0 InvSwitcher,[gamemode]_invswitcher_balance,The player's money balance for this gamemode's world,1.18.0 InvSwitcher,[gamemode]_invswitcher_balance_formatted,The player's money balance for this gamemode's world formatted with currency name,1.18.0 diff --git a/docs/addons/TopBlock/index.md b/docs/addons/TopBlock/index.md index 7d7f8ad9..aae64bb9 100644 --- a/docs/addons/TopBlock/index.md +++ b/docs/addons/TopBlock/index.md @@ -1,6 +1,8 @@ # TopBlock -Add-on for BentoBox to calculate island levels for AOneBlock specifically. Ranks are determined by how many magic blocks have been mined - the count. +Add-on for BentoBox that produces a Top Ten ranking for magic-block game modes. Ranks are determined by how many magic blocks have been mined - the count. + +TopBlock supports [**AOneBlock**](../../gamemodes/AOneBlock/index.md) and [**ChunkBlock**](../../gamemodes/ChunkBlock/index.md). You can install either one or both — when both are present, each game mode gets its own completely separate top ten, its own `topblock` command, and its own set of placeholders. A player's standing in AOneBlock has no effect on their standing in ChunkBlock. Created and maintained by [tastybento](https://github.com/tastybento). @@ -14,6 +16,9 @@ Created and maintained by [tastybento](https://github.com/tastybento). 4. Edit the config.yml how you want. 5. Restart the server if you make a change +!!! note "TopBlock is not standalone" + TopBlock requires **at least one** of [AOneBlock](../../gamemodes/AOneBlock/index.md) or [ChunkBlock](../../gamemodes/ChunkBlock/index.md) to be installed alongside it. If neither is found, TopBlock logs an error and disables itself. It hooks whichever of the two it finds at startup, so installing or removing a game mode later only takes effect after a restart. + ## Configuration TopBlock addon has 2 general configuration things: @@ -27,11 +32,11 @@ Config file contains main functions for the addon. The latest config.yml can be found [here](https://github.com/BentoBoxWorld/TopBlock/blob/develop/src/main/resources/config.yml). -This section defines a number of overall settings for the add-on. +This section defines a number of overall settings for the add-on. These settings are global — they apply to every game mode TopBlock has hooked. There is no per-game-mode configuration. ??? note "refresh-time" How often the Top Ten should be refreshed in minutes. Minimum is 1 minute, default is 5. - Each refresh requires reading every island from the database, so this should not be done too often. + Each refresh requires reading every island of every hooked game mode from the database, so this should not be done too often. If you run both AOneBlock and ChunkBlock, each refresh reads both sets of islands, so consider leaving this at the default or raising it. Default: `5` @@ -116,13 +121,27 @@ You can find more information how BentoBox custom GUI's works here: [Custom GUI' As an example, on BSkyBlock, the default `[player_command]` is `island`, and the default `[admin_command]` is `bsbadmin`. === "Player commands" - - `/[player_command] topblock`: access to the top panel. Requires `aoneblock.island.topblock` permission. + - `/[player_command] topblock`: access to the top panel. Requires the `island.topblock` permission for that game mode (`aoneblock.island.topblock` or `chunkblock.island.topblock`). + +TopBlock registers the `topblock` subcommand on **each** game mode it hooks, so with both installed you get `/ob topblock` for AOneBlock and the equivalent under ChunkBlock's player command. Each opens the panel for the game mode whose world you ran it in — the two leaderboards are entirely separate. ## Permissions === "Player permissions" - - `aoneblock.island.topblock` - (default: `true`) - Allows player to use the `/[player_command] top` command. - - `aoneblock.intopten` - (default: `true`) - Controls whether the player's island appears in the top ten. Remove from an admin or tester to exclude them from the leaderboard. + - `aoneblock.island.topblock` - (default: `true`) - Allows player to use the `/[player_command] topblock` command in AOneBlock. + - `aoneblock.intopten` - (default: `true`) - Controls whether the player's island appears in the AOneBlock top ten. Remove from an admin or tester to exclude them from the leaderboard. + - `chunkblock.island.topblock` - (default: `true`) - Allows player to use the `/[player_command] topblock` command in ChunkBlock. + - `chunkblock.intopten` - (default: `true`) - Controls whether the player's island appears in the ChunkBlock top ten. + +??? question "How do I hide a player from the leaderboard?" + Remove (or negate) the `intopten` permission for the game mode you want to hide them from — `aoneblock.intopten` or `chunkblock.intopten`. Because the prefix is per game mode, you can hide someone from one leaderboard while leaving them visible in the other. + + Two things to be aware of: + + - The permission is only checked while the island **owner is online**. Offline owners are always included, because Bukkit cannot reliably evaluate permissions for a player who is not logged in. So remove the permission from the account that actually logs in, not from an alt. + - Only the **island owner's** permission is checked. Team members' permissions make no difference. + + The change takes effect at the next refresh, so allow up to `refresh-time` minutes for the island to drop off the list. ??? question "Something is missing?" You can find the comprehensive list of permissions in the [addon.yml](https://github.com/BentoBoxWorld/TopBlock/blob/develop/src/main/resources/addon.yml) file of this addon. @@ -131,6 +150,8 @@ You can find more information how BentoBox custom GUI's works here: [Custom GUI' ## Placeholders +Placeholders are registered separately for each game mode TopBlock has hooked, using that game mode's own prefix. The `chunkblock_` set only exists if ChunkBlock is installed, and reports ChunkBlock's own ranking — the two never mix. + {{ placeholders_source(source="TopBlock") }} ## FAQ @@ -140,6 +161,20 @@ You can find more information how BentoBox custom GUI's works here: [Custom GUI' ## Changelog +??? note "What's new in v2.1.0 — ChunkBlock support" + **Released:** 2026-08-07 + + TopBlock is no longer AOneBlock-only. It now supports **ChunkBlock** as well, and either game mode — or both together — can be installed. + + - ✨ **ChunkBlock support.** TopBlock hooks whichever of AOneBlock and ChunkBlock it finds at startup. With both installed, each keeps a completely separate top ten, `topblock` command, and placeholder set. + - ✨ **New placeholders** — the full `%chunkblock_island_*_top_%` set, mirroring the existing `aoneblock_` ones and reporting ChunkBlock's own ranking. + - ✨ **New permissions** — `chunkblock.island.topblock` and `chunkblock.intopten`, both default `true`, mirroring the AOneBlock equivalents. Because the prefix is per game mode, you can hide a player from one leaderboard while leaving them visible in the other. + - 🔺 **AOneBlock is now a soft dependency.** TopBlock previously refused to load without AOneBlock; it now only disables itself if *neither* supported game mode is present. Existing AOneBlock-only setups are unaffected and need no changes. + + ℹ️ This is a drop-in update for AOneBlock servers — no config, panel, or locale changes are required. + + [Release v2.1.0](https://github.com/BentoBoxWorld/TopBlock/releases/tag/2.1.0) + ??? warning "What's new in v2.0.0 — platform upgrade required" **Released:** 2026-04-26