diff --git a/docs/BentoBox/About/Protections.md b/docs/BentoBox/About/Protections.md index 0b4acb08..bdc61310 100644 --- a/docs/BentoBox/About/Protections.md +++ b/docs/BentoBox/About/Protections.md @@ -1,129 +1,7 @@ # Protection -BentoBox provides a full-featured world and island protection system for island GameModes. Configuration is done in-game via the admin or player settings, and out of game via permissions and config files. -## What is Protection? -Multiplayer Minecraft provides no built-in protection for the map except for the area immediately around spawn. As a result, any random player can damage or "grief" someone else's area that they have put time into. With BentoBox, players have their own islands and the protection system prevents or limits what other players can do in this space. +This page has moved. Protection, flags, ranks, world settings and the admin settings panel are all covered on **[Protection, Flags & Ranks](../Island-Protection,-Flags-&-Ranks.md)**. -Protection also extends to limiting which commands can be executed. For example, an admin can prevent teleportation commands from being run when a player is falling to prevent them cheating fall damage. - -### What about WorldGuard? -WorldGuard is a protection plugin that also provides protection functions. BentoBox does not use WorldGuard and it is recommended that it is turned off in BentoBox worlds to avoid clashes. Admins can use WorldGuard if they like in BentoBox worlds, but they should consider that there may be clashes between the two systems. - -## How is Protection Managed In BentoBox? -BentoBox uses the concept of "flags" to manage protection settings. There are three types of flags: - - 1. **Protection flags** - these are explicitly designed to allow or disallow some facet of world or island protection. - 2. **Settings flags** - these are generally true/false or on/off settings that can be applied. They may provide protection. - 3. **World Settings flags** - these are settings flags that determine how things operate in the game world in general. - -### Protected areas -BentoBox has two areas of protection: - - 1. The player's island - 2. Everywhere else, the rest of the world - -These areas are generally handled independently, but certain world settings may apply to the player's island. Island owners generally have the ability to set the settings for their own island and admins configure the settings for everywhere else. Admins also can determine the default settings for an island to have by adjusting the game mode's `config.yml`. - -The player's island protection area is set by default in the game mode's `config.yml` and can be expanded or reduced in-game via admin commands or by the player having a permission. The maximum protection size is governed by the distance between islands, which is also set in the game mode `config.yml`. - -### Changing Settings -BentoBox provides an island settings GUI to island owners that enables them to see the island settings. Admins can reduce the island settings visible via the admin settings GUI. Admins can allow players to change settings via permissions. The default is that players can change all the settings they can see. - -## Protection Provided -There are a lot of protection flags and new ones are added regularly. Protections can be restricted by rank, so you can allow trusted players to do things visitors cannot: - - - Visitor - - Coop - - Trusted - - Member - - Sub-Owner - -Owners can always do everything. - -Every time a player tries to do something in a protected area, BentoBox checks whether they have the right to do it. If they do not, they are blocked and told why. - -### Finding out why something can or cannot be done -BentoBox provides an admin diagnostic tool: the `why ` command, e.g., `/bsb why tastybento`. When active, the server console logs the reason for every action that player takes — allowed or blocked, and which flag caused it. This makes it easy to diagnose misconfigured settings. - -If the `why` command says a player *can* do something but in-game they cannot, that indicates another plugin or the server itself is blocking the action, not BentoBox. - -### What is protected - -- Breaking and placing blocks -- Block interaction: containers, furnaces, crafting tables, enchanting tables, anvils, brewing stands, cauldrons, barrels, beehives, composters, jukeboxes, note blocks, levers, buttons, doors, trapdoors, beds, beacons, dragon eggs, item frames, gates, cake, berry bushes -- Redstone-related blocks -- Breeding animals -- Bucket use -- Dye, egg, and elytra use -- Vehicles: boats, minecarts, ridable animals -- Villager trading -- Name tag use -- Item/experience pickup and item dropping -- Fire: ignition, spreading, burning, lightning -- Damaging or killing mobs and animals -- Leash and lectern use -- Portal use -- Shearing -- Teleportation (chorus fruit, ender pearls) -- Throwing items including potions -- TNT and other explosion damage - -## Settings Island Owners Can Change - -Island owners open the settings GUI with `/island settings`. Admins can hide individual settings from players if they prefer to control them centrally. - -| Setting | What it does | -|---|---| -| **PVP (Player vs Player)** | Whether players can attack each other on this island. Off by default. | -| **Leaf decay** | Whether leaf blocks decay naturally when logs are removed. | -| **Mob spawning** | Whether monsters or animals can spawn on the island, including from spawner blocks. | - -### Viewing the World Rules Off-Island - -Since BentoBox 3.22.0, `/island settings` also works when the player is not standing on an island and does not own one — out in the wilderness, or in a game mode where players never own islands at all. - -In that case the panel opens with a single read-only **World Protections** tab listing each protection flag as active or disabled for the world. That is what actually governs a player off-island: with no island underneath them, a protection flag resolves to the world's on/off switch rather than to any rank. Nothing is clickable, and the island settings tab is not shown, since there is no island to configure. - -Players who are on or own an island see exactly the panel they always did. - -## World Settings Admins Control - -These settings apply to the whole game mode world. Only admins can change them, via `/[admin_command] settings`. Players can view (but not change) these in a read-only mode so they understand the server rules. - -| Setting | What it does | Default | -|---|---|---| -| **Always-allowed entity types** | Entities that spawn no matter what the animal and monster spawning flags say, on islands and in the world. Use it to let village iron farms work on a server, or an island, that has animal spawning turned off. Iron Golem is allowed by default. The block list (*Global mob spawning*) still wins. See [Mob spawning precedence](#mob-spawning-precedence). | Iron Golem | -| **Chest explosion damage** | Protects chests from being destroyed by explosions (Creepers, TNT, Withers, Ghasts). Prevents grief but means chests can be used to make explosion-proof rooms. | On | -| **Clean Super Flat** | If the world generator stops working, new chunks generate as flat grass. This setting detects and repairs those chunks. Leave it off unless you have this problem — it is resource-intensive. | Off | -| **Coarse Dirt Tilling** | Prevents players from converting coarse dirt into regular dirt using a hoe. Dirt is scarce and valuable in most game modes; coarse dirt tilling can be exploited to generate it cheaply if gravel is easy to obtain. | Off (prevention on) | -| **Creeper explosions** | Prevent Creeper explosion damage to island blocks. Creepers are the most common cause of island destruction. Preventing this makes the game easier, but reduces admin support load. | On | -| **Creeper visitor ignition** | Prevent visitors from using flint & steel to prime Creepers on someone else's island — a common griefing method. | On | -| **Ender Chests** | Block access to and crafting of Ender Chests, which can smuggle items between game mode worlds. Disable if you use a per-world Ender Chest plugin. | On (blocked) | -| **Enderman block theft** | Prevent Endermen from picking up blocks from islands. Without this, players lose blocks they did not remove themselves. | On | -| **Geo-limiting mobs** | Prevent certain mobs (e.g. the Wither, flying mobs) from leaving the island they were spawned on. If they cross the boundary they are removed. | On | -| **Visitor protection** | Protect visitors from most types of damage while on another player's island. Also teleports visitors to safety if they fall into the void. | On | -| **Item frame protection** | Prevent item frames from being broken or having their items knocked out by non-members. | On | -| **Global mob spawning** | Set which mob types can spawn anywhere in the world, overriding all other spawning settings. For example, disable Phantoms server-wide. | Varies | -| **Liquid flow outside islands** | Stop lava and water from flowing beyond island protection boundaries, preventing cobblestone formation between islands or floods. | On | -| **Mob spawning outside islands** | Prevent mobs from spawning in the areas between islands, concentrating spawning inside island zones. Not recommended for AcidIsland as it looks unnatural. | Off | -| **Obsidian scooping** | Allow players to right-click an isolated single obsidian block with an empty bucket to recover lava. Helps new players who accidentally make obsidian during cobblestone generator setup. | On | -| **Offline plant growth** | Stop crops and plants from growing on an island when no team members are online, even if a visitor is loading the chunks. | Off | -| **Offline Redstone** | Disable Redstone circuits on an island when no team members are online. | Off | -| **Piston outside boundary** | Stop pistons from pushing blocks beyond the island's protection boundary — a common exploit for griefing adjacent islands. | On | -| **Remove mobs on teleport** | Clear hostile mobs from the area when a player teleports to their island home, preventing surprise deaths on arrival. | On | -| **Spawner type protection** | Prevent players from changing the mob type of spawner blocks using spawn eggs. Useful when spawners are given as rewards. | On | -| **Tree growth boundary** | Prevent trees from growing beyond the island protection boundary. Without this, trees can intrude on other islands or create unreachable blocks. | On | -| **Wither damage** | Limit the destruction the Wither can cause on and between islands. | On | - -### Mob spawning precedence - -Natural and spawner mob spawning is decided in this order. The first rule that matches wins. - -1. **Global mob spawning** block list (`protection.block-mobs` in the game mode config). A blocked type never spawns. -2. **Always-allowed entity types** allow list. An allowed type spawns regardless of the flags below. -3. The island's **Animal natural spawn**, **Monster natural spawn**, **Animal spawners spawn** and **Monster spawners spawn** settings, or the world's defaults for those flags when there is no island. - -Spawns caused directly by a player, such as breeding, spawn eggs or building a golem, are never gated by any of these. - -!!! note "Where the allow list is stored" - Unlike the other world settings, the allow list is not in the game mode's `config.yml`. BentoBox stores it itself, one record per game mode, in its database: with the default flat-file database it is `plugins/BentoBox/database/CoreWorldSettings/.json`. It is seeded with `IRON_GOLEM` the first time the game mode is seen; after that only the admin's edits in the panel apply. Clearing the record restores the seed. +- [What each world setting does](../Island-Protection,-Flags-&-Ranks.md#what-each-world-setting-does) +- [Mob spawning precedence](../Island-Protection,-Flags-&-Ranks.md#mob-spawning-precedence) +- [Bypass the protection](../Island-Protection,-Flags-&-Ranks.md#bypass-the-protection) diff --git a/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md b/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md index f3c1498f..6a743187 100644 --- a/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md +++ b/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md @@ -227,7 +227,49 @@ World settings can also be set from the console or chat: ``` !!! new "Added in BentoBox 3.23.6" - The **Always-allowed entity types** item (iron ingot) opens a list of every living entity type. Green types spawn even when animal or monster spawning is off, on any island or in the world; Iron Golem is green by default so village iron farms keep working. The **Global mob spawning** block list still takes priority. The list is stored by BentoBox, not in the game mode's `config.yml`; see [Mob spawning precedence](About/Protections.md#mob-spawning-precedence). Requires `[gamemode].admin.settings.ALLOW_MOBS`. + The **Always-allowed entity types** item (iron ingot) opens a list of every living entity type. Green types spawn even when animal or monster spawning is off, on any island or in the world; Iron Golem is green by default so village iron farms keep working. The **Global mob spawning** block list still takes priority. The list is stored by BentoBox, not in the game mode's `config.yml`; see [Mob spawning precedence](#mob-spawning-precedence). Requires `[gamemode].admin.settings.ALLOW_MOBS`. + +#### What each world setting does + +These are the world settings most servers will want to review. Defaults are for BSkyBlock; other game modes may differ. Every flag is listed in [Flags](Flags.md). + +| Setting | What it does | Default | +|---|---|---| +| **Always-allowed entity types** | Entities that spawn no matter what the animal and monster spawning flags say, on islands and in the world. Use it to let village iron farms work on a server, or an island, that has animal spawning turned off. Iron Golem is allowed by default. The block list (*Global mob spawning*) still wins. See [Mob spawning precedence](#mob-spawning-precedence). | Iron Golem | +| **Chest explosion damage** | Protects chests from being destroyed by explosions (Creepers, TNT, Withers, Ghasts). Prevents grief but means chests can be used to make explosion-proof rooms. | On | +| **Clean Super Flat** | If the world generator stops working, new chunks generate as flat grass. This setting detects and repairs those chunks. Leave it off unless you have this problem — it is resource-intensive. | Off | +| **Coarse Dirt Tilling** | Prevents players from converting coarse dirt into regular dirt using a hoe. Dirt is scarce and valuable in most game modes; coarse dirt tilling can be exploited to generate it cheaply if gravel is easy to obtain. | Off (prevention on) | +| **Creeper explosions** | Prevent Creeper explosion damage to island blocks. Creepers are the most common cause of island destruction. Preventing this makes the game easier, but reduces admin support load. | On | +| **Creeper visitor ignition** | Prevent visitors from using flint & steel to prime Creepers on someone else's island — a common griefing method. | On | +| **Ender Chests** | Block access to and crafting of Ender Chests, which can smuggle items between game mode worlds. Disable if you use a per-world Ender Chest plugin. | On (blocked) | +| **Enderman block theft** | Prevent Endermen from picking up blocks from islands. Without this, players lose blocks they did not remove themselves. | On | +| **Geo-limiting mobs** | Prevent certain mobs (e.g. the Wither, flying mobs) from leaving the island they were spawned on. If they cross the boundary they are removed. | On | +| **Visitor protection** | Protect visitors from most types of damage while on another player's island. Also teleports visitors to safety if they fall into the void. | On | +| **Item frame protection** | Prevent item frames from being broken or having their items knocked out by non-members. | On | +| **Global mob spawning** | Set which mob types can spawn anywhere in the world, overriding all other spawning settings. For example, disable Phantoms server-wide. | Varies | +| **Liquid flow outside islands** | Stop lava and water from flowing beyond island protection boundaries, preventing cobblestone formation between islands or floods. | On | +| **Mob spawning outside islands** | Prevent mobs from spawning in the areas between islands, concentrating spawning inside island zones. Not recommended for AcidIsland as it looks unnatural. | Off | +| **Obsidian scooping** | Allow players to right-click an isolated single obsidian block with an empty bucket to recover lava. Helps new players who accidentally make obsidian during cobblestone generator setup. | On | +| **Offline plant growth** | Stop crops and plants from growing on an island when no team members are online, even if a visitor is loading the chunks. | Off | +| **Offline Redstone** | Disable Redstone circuits on an island when no team members are online. | Off | +| **Piston outside boundary** | Stop pistons from pushing blocks beyond the island's protection boundary — a common exploit for griefing adjacent islands. | On | +| **Remove mobs on teleport** | Clear hostile mobs from the area when a player teleports to their island home, preventing surprise deaths on arrival. | On | +| **Spawner type protection** | Prevent players from changing the mob type of spawner blocks using spawn eggs. Useful when spawners are given as rewards. | On | +| **Tree growth boundary** | Prevent trees from growing beyond the island protection boundary. Without this, trees can intrude on other islands or create unreachable blocks. | On | +| **Wither damage** | Limit the destruction the Wither can cause on and between islands. | On | + +#### Mob spawning precedence + +Natural and spawner mob spawning is decided in this order. The first rule that matches wins. + +1. **Global mob spawning** block list (`protection.block-mobs` in the game mode config). A blocked type never spawns. +2. **Always-allowed entity types** allow list. An allowed type spawns regardless of the flags below. +3. The island's **Animal natural spawn**, **Monster natural spawn**, **Animal spawners spawn** and **Monster spawners spawn** settings, or the world's defaults for those flags when there is no island. + +Spawns caused directly by a player, such as breeding, spawn eggs or building a golem, are never gated by any of these. + +!!! note "Where the allow list is stored" + Unlike the other world settings, the allow list is not in the game mode's `config.yml`. BentoBox stores it itself, one record per game mode, in its database: with the default flat-file database it is `plugins/BentoBox/database/CoreWorldSettings/.json`. It is seeded with `IRON_GOLEM` the first time the game mode is seen; after that only the admin's edits in the panel apply. Clearing the record restores the seed. ### World Protections @@ -350,3 +392,9 @@ Operators bypass every protection flag. Test with a non-op account. `/[admin_com **I don't know which flag is blocking an action.** Run `/[admin_command] why ` to log every protection check for that player to the console, then do the action. The log names the flag, the location and the result. Run the command again to stop. + +**`why` says the action is allowed, but the player is still blocked.** +Something other than BentoBox is blocking it: another plugin, or the server itself (for example spawn protection in `server.properties`). + +**Should I use WorldGuard in BentoBox worlds?** +You don't need it: BentoBox protects islands and the space between them. If you do use WorldGuard there, its regions and BentoBox's flags both apply, which can block things unexpectedly. Keep WorldGuard regions out of game mode worlds, or check them first when something is blocked. diff --git a/docs/BentoBox/Release-Notes.md b/docs/BentoBox/Release-Notes.md index bdcc0294..f17dfe77 100644 --- a/docs/BentoBox/Release-Notes.md +++ b/docs/BentoBox/Release-Notes.md @@ -7,7 +7,7 @@ Highlights of recent BentoBox releases for server admins. For every change, see No `config.yml` changes. Compatibility: Paper Minecraft 1.21.5 – 26.3, Java 25+. - - 🔡 **Always-allowed entity types (`ALLOW_MOBS`).** A new world setting in each game mode's admin settings panel (iron ingot icon) lists entity types that spawn even when animal or monster spawning is off, at world and island level. Iron Golem is on the list by default, so village iron farms keep working. The **Limit entity type spawning** block list still wins if a type is on both. Permission: `[gamemode].admin.settings.ALLOW_MOBS`. See [Mob spawning precedence](About/Protections.md#mob-spawning-precedence). + - 🔡 **Always-allowed entity types (`ALLOW_MOBS`).** A new world setting in each game mode's admin settings panel (iron ingot icon) lists entity types that spawn even when animal or monster spawning is off, at world and island level. Iron Golem is on the list by default, so village iron farms keep working. The **Limit entity type spawning** block list still wins if a type is on both. Permission: `[gamemode].admin.settings.ALLOW_MOBS`. See [Mob spawning precedence](Island-Protection,-Flags-&-Ranks.md#mob-spawning-precedence). - 🔺 **"All blueprints loaded" could fail to fire.** With several game modes loading blueprints at once, BentoBox could miss a completion and never reach its ready state, so addon `allLoaded()` hooks, ready-gated commands and `BentoBoxReadyEvent` never ran. Fixed, along with four related main-thread/async races. - 📊 **bStats:** failed commands now report the locale key the player saw as the reason and are counted per server; a new `worldSize` chart reports the on-disk size of island worlds as a bracket. - Fixed a spurious first-run `File not found` log from the new core world settings store. @@ -133,7 +133,7 @@ Highlights of recent BentoBox releases for server admins. For every change, see - ⚙️ 🔺 **Commands are registered with Paper's Brigadier API.** Players now see BentoBox subcommands and completions *as they type* — `/island t…` offers `team` in the chat bar — instead of the client knowing nothing until enter or TAB. The subcommand tree is advertised to a depth of 4; deeper subcommands still work, they just are not pre-advertised. Aliases and the `plugin:label` form are sent as redirects rather than duplicated trees. A new `general.brigadier-commands` option in `config.yml` defaults **on**; set it to `false` and `/bbox reload` to fall back to the legacy command map if another plugin conflicts. BentoBox also falls back automatically if it cannot hook the registrar. - 🔺 **Structure searches are suppressed automatically in worlds that generate no structures.** A cartographer rolling an explorer-map trade — or an Eye of Ender, dolphin or treasure map — used to run a synchronous structure search that could never succeed in a void world, scanning to the radius cap and blowing past the 60-second watchdog. BentoBox now asks the world's generator whether it places structures at all and skips the search if it does not, with **no configuration needed**. AOneBlock and BSkyBlock get this automatically; SkyGrid, Boxed, CaveBlock and AcidIsland are unaffected because they do generate structures. A per-world `structures` entry of `true` still force-enables a structure, as an escape hatch for converted worlds that contain pre-existing ones. This complements the opt-in `world.disabled-structures` list added in 3.20.0. - - **`/island settings` now opens out in the world.** Players away from any island, or in a game mode where they never own one, used to get "You do not have an island!". The panel now opens with a read-only **World Protections** tab showing which protection flags are active for the world — which is exactly what governs them where they are standing. See [Protection](About/Protections.md#viewing-the-world-rules-off-island). + - **`/island settings` now opens out in the world.** Players away from any island, or in a game mode where they never own one, used to get "You do not have an island!". The panel now opens with a read-only **World Protections** tab showing which protection flags are active for the world — which is exactly what governs them where they are standing. See [Protection](Island-Protection,-Flags-&-Ranks.md#world-protection-view). - 🐛 **Addon data queued during shutdown is no longer discarded.** Anything an addon saved from `onDisable()` was queued into a database pipeline that had already stopped draining, so it was silently, intermittently lost on every restart. Nine bundled addons save on disable — Boxed, AOneBlock, Raft, Challenges, Limits, DragonFights, CheckMeOut, ControlPanel and InvSwitcher — and with InvSwitcher the stale stored inventory was then re-applied on join, making it a rollback rather than just a lost write. Shutdown writes are now drained before the database closes. - 🐛 **BentoBox commands work from NPCs, signs and GUI plugins again.** Brigadier registration had taken BentoBox commands out of the Bukkit command map that other plugins dispatch through, so an NPC running `/oneblock go` answered with the server's no-permission message and ran nothing. Commands are now registered with the command map as well. This only ever affected 3.22.0 development builds. - 🐛 **`Island.setFlag` no longer discards writes.** Setting a protection rank on an island that had no entry yet for that flag — which is every freshly created island — silently did nothing. `SETTING` and `WORLD_SETTING` flags were unaffected. diff --git a/docs/Glossary.md b/docs/Glossary.md index d401fc18..2a0f55f2 100644 --- a/docs/Glossary.md +++ b/docs/Glossary.md @@ -23,7 +23,7 @@ A temporary island rank given to players who are not full team members. A coop p An addon that adds extra functionality (challenges, fly, warps, etc.) on top of a game mode. Feature addons are optional. See [Addons](BentoBox/About/Addons.md). ## Flag -A single protection or settings toggle that controls what is or isn't allowed on an island or in the game world. Flags are managed through the in-game settings GUI. Examples: whether visitors can break blocks, whether creepers can explode, whether leaf blocks decay. See [Protection](BentoBox/About/Protections.md). +A single protection or settings toggle that controls what is or isn't allowed on an island or in the game world. Flags are managed through the in-game settings GUI. Examples: whether visitors can break blocks, whether creepers can explode, whether leaf blocks decay. See [Protection](BentoBox/Island-Protection,-Flags-&-Ranks.md). ## Game Mode An addon that defines the type of game world players play in — the world type, how islands are generated, and the overall challenge. Examples: BSkyBlock, AcidIsland, AOneBlock. You must install at least one game mode for BentoBox to do anything. See [Game Modes](BentoBox/About/GameModes.md). @@ -65,4 +65,4 @@ A permanent guest rank for players who are not full team members. Unlike [coop]( The default rank for any player who is on an island they do not own or belong to. What visitors can do is controlled by the island owner through the settings GUI. ## World Settings -Protection and behaviour settings that apply to the entire game mode world, not just individual islands. Only admins can change these. Accessed via `/[admin_command] settings`. See [Protection](BentoBox/About/Protections.md). +Protection and behaviour settings that apply to the entire game mode world, not just individual islands. Only admins can change these. Accessed via `/[admin_command] settings`. See [Protection](BentoBox/Island-Protection,-Flags-&-Ranks.md). diff --git a/mkdocs.yml b/mkdocs.yml index 4822b30a..5a4ca8e5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,7 +15,6 @@ nav: - Glossary: Glossary.md - "Player Guide": BentoBox/Player-Guide.md - Admin Guides: - - Protection: BentoBox/About/Protections.md - "Protection, Flags & Ranks": "BentoBox/Island-Protection,-Flags-&-Ranks.md" - "Teams & Ranks": BentoBox/About/Teams.md - Islands: BentoBox/About/IslandManagement.md