feat(spawning): add spawnable block overlay

2026-08-10 22:46:02 -04:00
parent 26aeb8c416
commit 259ea9410c
30 changed files with 988 additions and 46 deletions
@@ -19,3 +19,4 @@ description: Catalog of user stories for the Spigot Base plugin.
 11. [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
 12. [US-012: Build and release the plugin](us-012-build-and-release-plugin.md)
 13. [US-013: Visualize the base border](us-013-visualize-base-border.md)
+14. [US-014: Highlight spawnable blocks](us-014-highlight-spawnable-blocks.md)
@@ -0,0 +1,34 @@
+---
+type: User Story
+title: "US-014: Highlight spawnable blocks"
+description: Unlock an owner-only red particle overlay for nearby hostile-mob spawnable blocks after 250 placements anywhere.
+status: done
+---
+
+# US-014: Highlight spawnable blocks
+
+As a **player with an established base**, I want to highlight nearby blocks where hostile mobs can spawn so that I can find lighting gaps in my base.
+
+## Acceptance criteria
+
+- [x] Every block placed in Survival mode anywhere contributes to a persistent total-placement counter.
+- [x] The overlay unlocks permanently at a configurable 250 total placements by default.
+- [x] Existing players begin with at least their persisted in-base placement count because those placements are known to qualify.
+- [x] `/basesettings spawnable enable` enables the unlocked overlay idempotently, and `/basesettings spawnable disable` disables it idempotently.
+- [x] `spawnable`, `enable`, and `disable` are offered through contextual autocomplete.
+- [x] Enabling requires both the placement unlock and an established base; the persisted preference defaults to disabled.
+- [x] `/basesettings status` and `/baseadmin status` display placement progress, unlock state, and preference.
+- [x] Administrators can change a player's total-placement counter through `/baseadmin setprogress`.
+- [x] Administrators can persistently change the required placement threshold through `/baseadmin config spawnable-overlay-unlock-placements`.
+- [x] Administrators can enable or disable an unlocked player's overlay through `/baseadmin setsetting <player> spawnable <enable|disable>`.
+- [x] Owner-only red particles mark nearby candidate hostile-mob spawning surfaces inside the current base bounds.
+- [x] Candidate surfaces have block light zero, a solid spawning surface, and two passable blocks above them.
+- [x] Scanning is bounded to 16 horizontal blocks, eight vertical blocks, and a fixed per-update work and particle budget.
+- [x] A complete administrative reset clears total-placement progress and disables the overlay.
+
+## Related
+
+- [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
+- [US-009: View progression and notifications](us-009-view-progression-and-notifications.md)
+- [US-010: Administer player progression](us-010-administer-player-progression.md)
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)