From cbef1d7a88b90e4d9d65cfee7603a79b0eff27e4 Mon Sep 17 00:00:00 2001
From: Michael Burgess <msburgess3200@hotmail.com>
Date: Sat, 8 Aug 2026 11:36:29 -0400
Subject: [PATCH] Document round-difficulty ramp and powerups config in README

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 720a64e..43bcf98 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,11 @@ work fine from console.
   saved `generated-layout` itself is never modified, so a restart or another `/bp generate`
   still starts from the original. Set `shuffle-each-round: false` to always restore the exact
   saved layout unchanged instead.
+- While shuffling, the target color's share of the floor shrinks each round instead of always
+  averaging ~1/(palette size) — round 1 starts at `floor.starting-target-fraction` (default
+  `0.5`) and drops by `floor.target-fraction-reduction-per-round` (default `0.04`) per round,
+  never going below `floor.minimum-target-fraction` (default `0.06`), so the target color gets
+  progressively rarer and harder to spot as a match goes on.
 
 ### Billboards
 
@@ -177,14 +182,51 @@ nothing leaks.
   future/optional batched floor operations — round-end removal and each round's floor reset
   are always instantaneous, all blocks at once, by design),
   `defaults.*` (used only when `/bp create` seeds a new arena), `default-floor-materials`
-  (the full 16-color concrete palette by default), `floor.shuffle-each-round`, `music.*`
-  (see "Music" below), `rewards.winner.commands`, and `integrations.placeholderapi`.
+  (the full 16-color concrete palette by default), `floor.shuffle-each-round` and
+  `floor.*-target-fraction*` (difficulty ramp, see above), `powerups.*` (see "Powerups"
+  below), `music.*` (see "Music" below), `rewards.winner.commands`, and
+  `integrations.placeholderapi`.
 - **`messages.yml`** — every user-facing string, in [MiniMessage](https://docs.advntr.dev/minimessage/format.html)
   format (Adventure, bundled with Paper). Placeholders like `%player%`, `%arena%`, `%round%`,
   `%time%`, `%color%` are substituted per-message.
 - **`arenas/<name>.yml`** — one file per arena; a broken file only disables that one arena
   (the rest still load) and the error is logged.
 
+### Powerups
+
+Temporary abilities that spawn on the floor during a match, on by default:
+
+```yaml
+powerups:
+  enabled: true
+  spawn-chance-per-round: 0.35
+  max-active: 1
+  min-lifetime-rounds: 2
+  max-lifetime-rounds: 3
+  types:
+    super-speed:
+      marker-block: TORCH
+      duration-seconds: 8
+      amplifier: 1
+    air-blast:
+      marker-block: END_ROD
+      radius: 4.0
+      strength: 1.4
+```
+
+Each round, a powerup may appear as a marker block (`torch`/`end rod` by default) floating just
+above a random floor cell — it never removes a player's footing, since it sits in their foot
+space rather than replacing the floor block itself. Claim one by walking into its marker or
+left-clicking it:
+
+- **Super Speed** — a temporary Speed potion effect (`duration-seconds` / `amplifier`).
+- **Air Blast** — pushes every other player within `radius` blocks away from the claimer,
+  scaled by distance (`strength`).
+
+Unclaimed powerups disappear after a random 2-3 rounds (`min-lifetime-rounds` /
+`max-lifetime-rounds`). Every claim is recorded per-player as a `powerups_used` stat, shown in
+`/blockparty stats`.
+
 ### Music
 
 Optional background music for the duration of a match, off by default: