From be1ba78537140a4c9b31bff355cb13bdb90cd462 Mon Sep 17 00:00:00 2001 From: tastybento Date: Mon, 7 Sep 2026 10:54:54 -0700 Subject: [PATCH] docs(level): document per-island death tracking in Level 2.29.0 - Rewrite the deathpenalty and sumteamdeaths config notes; mark sumteamdeaths as deprecated and explain the one-time migration. - Add a FAQ entry describing the per-island death rules and which game mode deaths settings still affect levels. - Add the v2.29.0 changelog entry. - Clarify that %[gamemode]_deaths% is BentoBox's own counter, not Level's per-island count. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01SxX9oscerhv1nsozPbT5aX --- data/placeholders.csv | 2 +- docs/BentoBox/Placeholders.md | 2 +- docs/addons/Level/index.md | 50 +++++++++++++++++++++++++++++++---- 3 files changed, 47 insertions(+), 7 deletions(-) diff --git a/data/placeholders.csv b/data/placeholders.csv index c7860f81..5b1ee586 100644 --- a/data/placeholders.csv +++ b/data/placeholders.csv @@ -42,7 +42,7 @@ BentoBox,[gamemode]_owns_island,Whether the player is an owner of an island,1.14 BentoBox,[gamemode]_rank,Rank the player has on his island,1.5.0 BentoBox,[gamemode]_resets,Number of times the player has reset his island,1.5.0 BentoBox,[gamemode]_resets_left,Number of times the player can reset his island,1.5.0 -BentoBox,[gamemode]_deaths,Number of times the player died,1.12.0 +BentoBox,[gamemode]_deaths,"Number of times the player died in this game mode, as counted by BentoBox (not the per-island count used by Level 2.29.0+)",1.12.0 BentoBox,[gamemode]_on_island,Whether the player is on an island he is part of or not,1.13.0 BentoBox,[gamemode]_island_online_members_count,The number of online island members,2.0.1 BentoBox,[gamemode]_visited_island_online_members_count,The number of online visited island members,2.0.1 diff --git a/docs/BentoBox/Placeholders.md b/docs/BentoBox/Placeholders.md index 9d3eff38..acaa8431 100644 --- a/docs/BentoBox/Placeholders.md +++ b/docs/BentoBox/Placeholders.md @@ -78,7 +78,7 @@ All gamemode addons get some default placeholders automatically registered to th | %[gamemode]_rank% | Rank the player has on his island | 1.5.0 | | %[gamemode]_resets% | Number of times the player has reset his island | 1.5.0 | | %[gamemode]_resets_left% | Number of times the player can reset his island | 1.5.0 | -| %[gamemode]_deaths% | Number of times the player died | 1.12.0 | +| %[gamemode]_deaths% | Number of times the player died in this game mode, as counted by BentoBox (capped by the game mode's `deaths.max`). This is not the per-island death count used by the Level addon since Level 2.29.0. | 1.12.0 | | %[gamemode]_on_island% | Whether the player is on an island he is part of or not | 1.13.0 | ### Flag placeholders diff --git a/docs/addons/Level/index.md b/docs/addons/Level/index.md index e7c5c09a..c7ce5996 100644 --- a/docs/addons/Level/index.md +++ b/docs/addons/Level/index.md @@ -141,17 +141,19 @@ This section defines a number of overall settings for the add-on. ??? note "deathpenalty" Allows to specify the death penalty. - How many block values a player will lose per death. - Default value of 100 means that for every death, the player will lose 1 level (if levelcost is 100). - + How many block values the island will lose per death. + Default value of 100 means that for every death, the island will lose 1 level (if levelcost is 100). + + Since v2.29.0 deaths are tracked **per island** by Level itself: only deaths that happen in the island's own space, by one of its members, count against it, and they stay with the island even if that member later leaves. See [How does the death penalty work?](#faq) for the full rules and how this interacts with the game mode's `deaths` settings. + Set to zero to not use this feature. Default: `100` ??? note "sumteamdeaths" - Allows to sum all team members for the death penalty. + **Deprecated since v2.29.0.** Level now always counts every death that occurred on the island, regardless of which member died. - If false, only the leader's deaths counts. + The setting is read exactly once per island, when Level migrates the legacy per-world death counts from BentoBox on the first calculation after upgrading. If `true`, the migrated count is the sum of all members' old deaths; if `false`, only the owner's. Leave it at whatever value you had when you upgrade so migrated levels match, then ignore it. Default: `false` @@ -393,6 +395,29 @@ You can find more information how BentoBox custom GUI's works here: [Custom GUI' ??? question "Can you add a feature X?" Please add it to the list [here](https://github.com/BentoBoxWorld/Level/issues). +??? question "How does the death penalty work?" + Since v2.29.0 Level keeps its own death record for every island, separate from BentoBox's per-player death counter. The rules are: + + - A death counts against an island only if it happens **inside that island's space** and the player who died is a **member** of it. Dying in another world, or while visiting someone else's island, counts for nothing. + - **Joining a team carries nothing over.** A new member's earlier deaths stay with their own island, so inviting a player who has died a lot does not drop the team's level. + - **Leaving or being kicked does not restore the level.** The departed member's deaths on that island are kept as an anonymous count, so the handicap never drops just because a frequently-dying member left. Leaving and rejoining does not double count. + - **Island reset or deletion** clears the island's death record. + - The handicap is `deaths × deathpenalty` block values, subtracted before the `level-calc` formula runs. + - The admin level report (`/[admin_command] level `) breaks the handicap down per member by name, with a separate line for deaths by former members or migrated from the old per-world counter. + + **Game mode `deaths` settings.** Each game mode's `config.yml` has a `deaths` block. After v2.29.0 only two of its settings affect island levels: + + | Setting | Effect on Level | + |---|---| + | `counted` | Master switch. If `false`, Level records no deaths at all. | + | `max` | Caps how many deaths each member can contribute to an island's penalty. | + | `team-join-reset` | None. Only affects BentoBox's own counter and the `%[gamemode]_deaths%` placeholder. | + | `reset-on-new-island` | None. Level clears an island's own record on reset or deletion. | + + BentoBox's `/[admin_command] deaths set|add|reset` commands change BentoBox's counter, not Level's per-island record, so they no longer affect levels either. + + **Upgrading from an earlier version.** Existing death counts are migrated once per island the first time it is calculated, a member dies on it, or a member leaves. The migrated value reproduces what the old formula would have computed at that moment (using `sumteamdeaths`), so island levels do not change on upgrade. + ??? question "How to make that `level-cost` increases after each level?" The `level-cost` setting is a fixed value and cannot be made to increase iteratively per level, because BentoBox calculates island levels by applying a single formula to the total block count — not by iterating level by level. @@ -523,6 +548,21 @@ You can find more information how BentoBox custom GUI's works here: [Custom GUI' [Release v2.28.1](https://github.com/BentoBoxWorld/Level/releases/tag/2.28.1) +??? warning "What's new in v2.29.0 — behaviour change" + **Released:** September 2026 + + Compatibility: BentoBox API 3.16.0, Minecraft 1.21.x and 26.1.x, Java 21. + + - 🔺 **Deaths are now tracked per island.** Level no longer reads BentoBox's per-player, per-world death counter when calculating. A death counts only if it happens in the island's own space and the player is a member; joining a team carries nothing over; deaths of members who later leave stay with the island; island reset clears the record. This fixes team levels collapsing when a player with a long death history was invited, and bouncing back when they were kicked. See [How does the death penalty work?](#faq). + - ⚙️ **`sumteamdeaths` is deprecated.** It is read once per island to migrate the old count and otherwise ignored. Existing levels do not change on upgrade. + - 🔺 The game mode's `team-join-reset` and `reset-on-new-island` settings, and the `/[admin_command] deaths` commands, no longer influence levels. `counted` and `max` still do. + - The admin level report lists deaths per member by name, plus a line for former-member and migrated deaths. + - 🐛 Opening the details panel from the top-ten panel's View button without an island no longer throws an error. + - 🐛 The value panel no longer errors on a malformed block key when building an icon. + - 🆕 Traditional Chinese (`zh-TW`) locale added. Thanks @qwe664! + + [Release v2.29.0](https://github.com/BentoBoxWorld/Level/releases/tag/2.29.0) + ## Translations {{ translations("Level") }}