spigot-tyrant/design/log.md

type, title, description

type	title	description
Log	Spigot Tyrant Design Log	Chronological record of material decisions affecting the Spigot Tyrant design.

Spigot Tyrant Design Log

2026-08-23 — Arena containment and idle boss corrected

• Corrected shared-arena containment with a validated 12-block barrier wall extending below the arena floor and active-fight block placement and breaking protection.
• Kept red or blue role particles visible at multiple wall heights during fights so challengers can see the otherwise invisible barrier from inside.
• Arena bosses now remain AI-disabled at the center until an eligible challenger enters, move normally within the arena during combat, and return healed and idle only on reset or boundary escape.
• Verified wall geometry, safe restoration, boundary visibility policy, build protection, idle/combat boss transitions, configuration validation, compiler warnings, 119 automated tests, and packaging with ./gradlew clean check jar.

2026-08-23 — Shared Tyrant and Vigilante arena succession completed

• Completed US-020 and reopened related succession, inactivity, administration, configuration, and Vigilante-arena stories so non-player Tyrant replacement is earned rather than random.
• Environmental Tyrant death, inactivity, and relinquishment now clear the reign and open the shared one-player Tyrant boss challenge; a directly credited player killer still succeeds immediately.
• The shared arena prioritizes a vacant Tyrant with a red particle circle, then opens a vacant Vigilante challenge with a blue circle after a Tyrant becomes active; neutral particles remain while neither challenge is open.
• Both roles share the configured location, boss balance, barriers, containment, mob exclusion, reset behavior, notifications, and restart protections, while an active Tyrant remains unable to enter.
• Removed new random and pending role selection, retained safe migration of legacy pending state and the legacy maintenance-interval configuration key, and verified 115 automated tests plus ./gradlew clean check jar.

2026-08-23 — Vigilante arena succession completed

• Completed US-019 and reopened related administration, Vigilante, inactivity, participation, persistence, control-panel, and completion stories to replace automatic Vigilante selection with an earned arena challenge.
• Vigilante vacancies caused by death, inactivity, relinquishment, initial startup, or a new Tyrant reign now open a configured one-player enhanced-zombie fight only while a Tyrant is active.
• Added a persistent administrator-set arena center, continuous particle boundary, temporary safe BARRIER wall, entrant and respawn containment, mob exclusion, sunlight-safe boss behavior, full fight reset, and boss-victory assignment.
• Opted-in players receive vacancy coordinates when the challenge opens or they join; opted-out players are excluded from notices and entry.
• Verified arena policy, geometry, succession, configuration persistence and validation, barrier restoration, command handling and completion, compiler warnings, 109 automated tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Contextual command completion completed

• Completed US-018 with registered completers for /tyrant, /vigilante, and /tyrantadmin, replacing Bukkit's unconditional online-player fallback.
• Suggestions now follow argument position, filter case-insensitively, expose eligible assignment and recruitment targets, identify current Followers for dismissal, and gate administration by permission.
• Administrative completion remains available to permitted console senders, while player-only commands return no console suggestions.
• Verified syntax, eligibility, membership, permissions, prefix filtering, compiler warnings, tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Contextual command completion started

• US-018 begins a test-first replacement of Bukkit's player-name fallback with syntax-aware Tyrant, Vigilante, and administrative command suggestions.
• Player arguments will be filtered by the applicable assignment or membership rules, while administrative suggestions remain permission-gated.

2026-08-21 — Single-mob Tamer custody completed

• Completed US-007 with an authoritative one-mob custody limit that rejects a second capture before inventory, entity, or state mutation and tells the Tamer to release the held mob first.
• Releasing or dropping custody permits another capture immediately, while durable state preserves the limit across logout, restart, recovery, and repeated interaction.
• Legacy excess custody retains the oldest mob and safely releases extras; offline or failed releases remain durable for periodic retry.
• Verified domain rejection, listener ordering, legacy reconciliation, compiler warnings, tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Single-mob Tamer custody started

• US-007 begins a test-first one-mob custody limit for active Tamers.
• New captures will be rejected before mutation while custody exists, and legacy excess custody will be released safely with failed releases retained for retry.

2026-08-21 — Former Tamer automatic release completed

• Completed US-004 and US-007 so every captured mob is released automatically after its holder loses the Tamer class, regardless of the class-removal path.
• Online former Tamers release at a validated safe location; offline, dead, unsafe, malformed, or otherwise unspawnable custody remains durable and retries periodically after login or movement.
• Custody records and captured-mob items are removed only for successful spawns, while ordinary inventory remains untouched.
• Verified former-Tamer filtering, offline deferral, partial success, custody preservation, compiler warnings, tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Former Tamer automatic release started

• US-004 and US-007 begin a test-first implementation that automatically releases captured mobs when a player loses the Tamer class.
• Release will preserve ordinary inventory, remove custody only after successful spawning, and defer safely for offline players or unsafe locations before retrying.

2026-08-21 — Bound role control items completed

• Completed US-017 and the reopened US-015 and US-016 criteria with configurable owner-bound Tyrant and Vigilante control items that open their respective panels.
• Role items are reconciled on login and periodically after role transitions, deduplicated, removed after role loss, and recoverable through /tyrant item or /vigilante item without dropping overflow.
• Drop, pickup, container, drag, hopper, placement, dispenser, item-frame, death, stale-owner, and stale-role paths prevent transfer or remove invalid items.
• Added default Tyrant Control Nether Star and Vigilante Control Compass settings and validation.
• Verified role policy, delayed reconciliation, panel interaction, command recovery, settings defaults, compiler warnings, tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Bound role control item implementation started

• US-015, US-016, and US-017 begin a test-first implementation of configurable owner-bound Tyrant and Vigilante control items.
• Delivery, command recovery, interaction, role validation, transfer prevention, role-loss cleanup, and duplicate resistance will build on the existing bound-item patterns.

2026-08-21 — Bound role control items planned

• Added US-017 for secure owner-bound Tyrant and Vigilante inventory items that open the corresponding control panels.
• The Tyrant item defaults to a Nether Star named Tyrant Control, and the Vigilante item defaults to a Compass named Vigilante Control; both material and name are configurable.
• Planned automatic role-assignment and login delivery, command recovery, full transfer prevention, removal on role loss or inventory departure, and duplicate resistance.
• Reopened US-015 and US-016 in the backlog to track control-panel access through the new role items.

2026-08-21 — Vigilante control panel completed

• Completed US-016 and the reopened US-008 criteria with resistance overview, recruitment, Follower management, and confirmed role-relinquishment screens.
• /vigilante and /vigilante menu open the panel, while existing invitation, acceptance, dismissal, leave, and relinquishment commands remain available.
• Added a 100-tick login delay with online, lifecycle, role, and already-opened session checks so only the current Vigilante receives one automatic panel per login.
• Pending invitations are visible and idempotent, existing Followers cannot be reinvited, and all menu mutations delegate to authoritative command and domain rules.
• Verified command routing, authorization, overview state, invitation rules, delayed opening safeguards, compiler warnings, tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Vigilante control panel implementation started

• US-008 and US-016 begin a test-first implementation of the Vigilante control panel, delayed login opening, resistance overview, recruitment, dismissal, and role relinquishment.
• The panel will reuse authoritative Follower and relinquishment rules while preserving all existing command alternatives.

2026-08-21 — Vigilante control panel planned

• Added US-016 for a graphical Vigilante control panel covering resistance overview, recruitment, Follower management, and confirmed role relinquishment while preserving command alternatives.
• Planned automatic control-panel opening five seconds after the active Vigilante joins a running event, with lifecycle, role, disconnect, and duplicate-opening safeguards.
• Reopened US-008 in the backlog to track the approved control-panel interactions and nearby-Follower combat contribution display.

2026-08-21 — Tyrant control panel completed

• Completed US-015 and the reopened US-003, US-004, and US-009 control-panel criteria with overview, unlock purchase confirmation, class assignment, and ability screens.
• The active Tyrant can open the panel with /tyrant or /tyrant menu; existing command alternatives remain available and provide the authoritative mutations behind menu actions.
• Added a 100-tick login delay with online, lifecycle, role, and already-opened session checks so only the current Tyrant receives one automatic panel per login.
• Verified command routing, authorization, overview state, delayed opening safeguards, compiler warnings, tests, and packaging with ./gradlew clean check jar.

2026-08-21 — Tyrant control panel implementation started

• US-003, US-004, US-009, and US-015 begin a test-first implementation of the Tyrant control panel and its delayed login opening.
• The installed Spigot API does not expose a native dialog API, so the control panel will use a server-rendered inventory menu while preserving command alternatives.

2026-08-21 — Tyrant control panel planned

• Added US-015 for a graphical Tyrant control panel covering reign overview, unlock purchases, class assignments, and roster intelligence while retaining command alternatives.
• Planned automatic control-panel opening five seconds after the active Tyrant joins a running event, with lifecycle, role, disconnect, and duplicate-opening safeguards.
• Reopened US-003, US-004, and US-009 in the backlog to track their approved control-panel interactions.

2026-08-18 — Preserve ordinary potion effects

• Corrected Assassin effect maintenance so it refreshes active Tyrant abilities without removing invisibility, Speed, or Weakness supplied by potions, commands, or other plugins.
• Expired or inapplicable Tyrant-managed effects stop refreshing and expire naturally within their short 30-tick maintenance duration, while double-jump flight cleanup remains immediate.
• Reopened and completed US-005 with regression coverage; verified ./gradlew clean check jar.

2026-08-14 — Opt-out proximity glow completed

• Extended US-011 with a globally visible green outline for opted-out players in the Tyrant's world and configured range while the event is running.
• A periodic controller removes the glow when eligibility, proximity, world, lifecycle, or player availability changes and clears managed state on logout and shutdown.
• Scoreboard presentation records and restores each player's previous team and glowing state instead of permanently replacing unrelated presentation.
• Verified inclusive range behavior, lifecycle and availability gating, green presentation, restoration, and the full Gradle build.

2026-08-14 — Opt-out proximity glow started

• US-011 is reopened for a test-first green outline on opted-out players near the Tyrant during a running event, using the existing configurable Tyrant range.
• Cleanup will cover range, world, participation, lifecycle, availability, shutdown, and restoration of pre-existing scoreboard-team membership.

2026-08-14 — Join messaging refinement completed

• Updated US-011 so join output no longer announces running, paused, or unstarted lifecycle state.
• Eligible unassigned players now see the neutral prompt, Use /tyrant optout if you do not want to participate in Tyrant events.
• Role, class, ability, cooldown, and existing opt-out details remain unchanged.
• Verified both assigned and unassigned join output with automated tests.

2026-08-14 — Join messaging refinement started

• US-011 is reopened to remove lifecycle announcements from join output and make the opt-out prompt refer generally to Tyrant events.

2026-08-14 — Opt-out combat protection completed

• Extended US-011 with bidirectional combat isolation between opted-out players and the Tyrant, Assassin, Fixer, or Tamer while the event is running.
• Direct player attacks and player-fired projectiles are cancelled at highest event priority, and the attacker is told that the target has chosen not to participate in the Tyrant event.
• Paused, unstarted, and unrelated combat remains ordinary Minecraft gameplay.
• Verified both attack directions, every Tyrant-side class, projectile attribution, lifecycle gating, and unrelated combat with automated tests.

2026-08-14 — Opt-out combat protection started

• US-011 is reopened for test-first running-event combat isolation between opted-out players and the Tyrant or Tyrant-side class holders.
• Paused and unstarted gameplay remains ordinary Minecraft combat; blocked direct and projectile attackers receive a concise Tyrant event participation message.

2026-08-14 — Tamer completed

• Completed US-007 with the no-cooldown owner-bound Tamer's Lead, server-generated entity snapshots, durable capture IDs, and one bound Captured Mob item per entity.
• Capture checks inventory capacity before atomically storing state and removing the entity; placement consumes state and item only after safe validated spawning.
• Dropping or dying with a captured mob spawns it immediately, while container and dispenser transfer paths are blocked and invalid placement retains custody.
• Ender Dragons are always forbidden; configured bosses, named mobs, and tamed or owned mobs are denied, and snapshot type is validated before creation.
• Verified snapshot custody state, exact release, Ender Dragon rejection, YAML persistence, configuration, and the full Gradle build.

2026-08-14 — Tamer implementation started

• US-007 begins with test-first snapshot custody, no-cooldown capture items, safe placement/drop/death spawning, and duplication-resistant state transitions.

2026-08-14 — Tyrant abilities completed

• Completed US-009 with configurable permanent Strength and Resistance purchases continuously restored for the active Tyrant throughout the running reign.
• Added /tyrant intelligence with a rolling configurable 24-hour unpaused cooldown and an aggregate count of the Vigilante plus assigned non-opted-out Followers without identities or locations.
• Ability ownership and cooldowns remain visible in status output, persist across restart, and are cleared by existing reign succession cleanup.
• Verified intelligence authorization, counts, cooldown persistence, effect configuration, and the full Gradle build.

2026-08-14 — Tyrant ability implementation started

• US-009 begins with test-first permanent effect ownership, automatic reapplication, and rolling-24-hour opposition roster intelligence.

2026-08-14 — Fixer completed

• Completed US-006 with the named owner-bound Fixer's Wrench, one-hour cooldown, and ten-minute Strength and Health Boost activation.
• Activation records a fixed normal two-row or near-Tyrant three-row heart tier using same-world configurable proximity at use time.
• Continuously refreshed effects survive death, login, milk, and ordinary removal; expiry and class loss remove effects and clamp health safely to the resulting maximum.
• Verified activation tiers, active and cooldown deadlines, item consumption/readiness, persistence, and the full Gradle build.

2026-08-14 — Fixer implementation started

• US-006 begins with test-first bound-item combat boosts, activation-time proximity tiers, persistent cooldowns, and safe health cleanup.

2026-08-14 — Assassin completed

• Completed US-005 with named owner-bound Assassin Cloak activation, one-hour cooldown, particle-free ten-minute invisibility, and activation-time doubling within the Tyrant's configurable range.
• Added 60-second double-jump gating, upward launch, 15-second Speed, 20-second Weakness III, and grounded readiness restoration.
• Active effects and cooldowns persist as UTC deadlines and are continuously restored after death, login, milk, or ordinary removal while valid.
• Verified duration tiers, cooldown consumption and refresh, jump effect deadlines, class constraints, persistence, and the full Gradle build.

2026-08-14 — Assassin implementation started

• US-005 begins with test-first bound-item invisibility, near-Tyrant duration doubling, and cooldown-gated double-jump effects.

2026-08-14 — Bound ability items completed

• Completed US-014 with configurable named standard items carrying hidden owner and ability metadata, interaction cancellation, and owner-validated Assassin, Fixer, and Tamer activation.
• Cooldown items are consumed only on successful use, restored automatically when ready or by /tyrant item, deduplicated, and withheld with clear guidance when inventory space is unavailable.
• Drop, pickup, placement, crafting/storage movement, item-frame, dispenser, death, class loss, reign reset, login, and restart paths prevent transfer and duplication.
• Captured-mob custody items use independent IDs, reconcile missing or duplicate inventory items against durable snapshots, and spawn rather than vanish on drop or death.
• Verified readiness consumption and refresh, assignment cleanup, durable metadata state, captured custody, and the full Gradle build.

2026-08-14 — Bound ability item implementation started

• US-014 begins with test-first item readiness and recovery, owner metadata, transfer prevention, cooldown redelivery, and Tamer item permanence.

2026-08-14 — Vigilante and Followers completed

• Completed US-008 with /vigilante invitation, acceptance, dismissal, and leave flows while preserving independent Tyrant-side class assignments.
• Added Tyrant/Vigilante combat tracking and continuously refreshed Strength and Resistance based on living same-world Followers within the configurable 50-block range, capped at Strength V and Resistance IV by default.
• Every Vigilante death now awards progression only to the Tyrant killer, clears Followers, and applies normal recently-active replacement with previous-holder fallback.
• Verified membership, dual alignment, scaling and caps, role maintenance, command metadata, and death/progression components with the Gradle suite.

2026-08-14 — Vigilante and Follower implementation started

• US-008 begins with test-first invitation membership, death reroll and Tyrant reward integration, combat tracking, and proximity-scaled capped effects.

2026-08-14 — Participation completed

• Completed US-011 with /tyrant status, optout, optin, and confirmed relinquish flows plus comprehensive join messages for lifecycle, roles, classes, abilities, and cooldowns.
• Opt-out clears ordinary classes and Follower membership, persists until the player explicitly opts back in, and enforces the configurable seven-day unpaused waiting period.
• Central role holders must safely relinquish first; Tyrant relinquishment performs full succession and Vigilante relinquishment performs a normal Vigilante reroll.
• Updated all assignment and candidate paths to exclude opted-out players and verified status, persistence, cleanup, cooldown, and relinquishment behavior with the Gradle suite.

2026-08-14 — Participation implementation started

• US-011 begins with test-first opt-out/opt-in state, seven-day re-entry gating, safe role relinquishment guidance, and complete join status messages.

2026-08-14 — Role maintenance completed

• Completed US-010 with configurable periodic role maintenance, exact 48-hour inactivity handling, and 24-hour recently-active candidate filtering.
• Added online confirmation for pending roles, 24-hour expiry and reroll, former-holder fallback rules, vacant-role retries, opt-out filtering, and Tyrant/Vigilante conflict prevention.
• Tyrant inactivity uses full reign succession cleanup; Vigilante inactivity clears only that role's Followers before replacement.
• Verified confirmation, expiry reroll, Follower cleanup, exact inactivity boundary, full Tyrant succession, and pause-safe scheduler integration with the Gradle suite.

2026-08-14 — Role maintenance implementation started

• US-010 begins with test-first inactivity replacement, pending confirmation and expiry, conflict-safe candidate retries, and pause awareness.

2026-08-14 — Tyrant succession completed

• Completed US-002 with player-killer transfer, recent-player environmental succession, former-holder avoidance, pending offline confirmation, and distinct replacement Vigilante selection.
• Tyrant death clears all classes, Followers, cooldowns, item readiness, purchases, levels, and choices before granting the successor one starting choice.
• Added death-event integration, server announcements, and a scoreboard-team-backed red Tyrant name and glowing outline that is restored on login and removed on pause or shutdown.
• Verified succession attribution, random exclusion, reign cleanup, role separation, death integration, and red presentation with the Gradle suite.

2026-08-14 — Tyrant succession implementation started

• US-002 begins with test-first killer and environmental succession, reign-wide cleanup, replacement Vigilante selection, and red Tyrant presentation.

2026-08-14 — Administrative lifecycle completed

• Completed US-001 with permission-gated /tyrantadmin start, status, pause, resume, and confirmed reset operations.
• Initial Vigilantes may be assigned explicitly or selected among eligible recently active players, with offline selections persisted as pending confirmations.
• Pause/resume preserves progression and assignments, shifts every cooldown, participation, inactivity, and pending-selection deadline, and invokes managed effect suppression/restoration.
• Added detailed operator status output and verified lifecycle, timer shifting, permissions, confirmation safety, candidate filtering, metadata, and effect hooks with the Gradle suite.

2026-08-14 — Administrative lifecycle implementation started

• US-001 begins with test-first game start, pause/resume deadline freezing, permission-gated administration, inspection, and confirmed reset behavior.

2026-08-14 — Tyrant class assignment completed

• Completed US-004 with /tyrant assign <class> <player>, purchased-class authorization, UUID state, one holder per class, and one Tyrant-side class per player.
• Preserved dual alignment so Vigilantes and Followers can hold a Tyrant-side class, while rejecting the Tyrant and opted-out targets.
• Added reassignment and reign cleanup for class cooldown/item state, online assignment/removal notices, and login control reminders.
• Verified assignment constraints, dual alignment, cleanup, commands, notifications, and reminders with the Gradle test suite.

2026-08-14 — Tyrant class assignment implementation started

• US-004 begins with test-first purchased-class authorization, one-holder constraints, dual alignment, reassignment cleanup, and reign-wide removal.

2026-08-14 — Tyrant progression completed

• Completed US-003 with exact Tyrant-on-Vigilante kill attribution, level and choice rewards, pause guards, one-time purchases, and reign reset behavior.
• Added /tyrant choices status output and /tyrant buy <unlock> with durable atomic state updates and clear failure feedback.
• Verified progression, duplicate purchase, authorization, paused-state, reset, command presentation, metadata, and persistence behavior with the Gradle test suite.

2026-08-14 — Tyrant progression implementation started

• US-003 begins with test-first kill attribution, one-time unlock purchases, and player-visible choice status.

2026-08-14 — Configuration and persistence completed

• Completed US-012 with validated defaults for ranges, timers, effects, items, messages, and mob restrictions, including runtime Bukkit section parsing.
• Added immutable lifecycle and player state for roles, dual-alignment classes, progression, participation, cooldowns, bound items, and captured mobs.
• Added RFC 3339 UTC timestamp persistence, paused deadline shifting, atomic YAML replacement, invalid-record rejection, unknown-field preservation, periodic saves, and shutdown saves.
• Verified all state, settings, bundled configuration, corruption, forward-compatibility, and pause-time tests with ./gradlew clean check jar.

2026-08-14 — Configuration and persistence implementation started

• US-012 begins with test-first validated defaults, immutable UUID-keyed domain state, paused-time-aware clocks, and defensive atomic YAML persistence.

2026-08-14 — Build and release foundation completed

• Completed US-013 with a Java 17 Gradle build, Spigot 26.2 API, strict compiler linting, JUnit 5 and Mockito dependencies, plugin metadata, and a minimal plugin entrypoint.
• Added Gitea push and pull-request CI, conventional-commit validation, development artifacts, semantic versioning, and versioned Gitea release assets modeled on ../spigot-base/.
• Verified ./gradlew clean check jar, a release-version 1.2.3 JAR and embedded plugin version, workflow delivery settings, and OKF conformance.

2026-08-14 — Build and release implementation started

• Approved implementation begins with US-013 and a test-driven Java 17, Gradle, Spigot, and Gitea Actions foundation modeled on ../spigot-base/.

2026-08-14 — Initial game design

• The game has one Tyrant and one Vigilante, with Followers aligned to the Vigilante and Assassin, Fixer, and Tamer classes assigned by the Tyrant.
• A player who kills the Tyrant becomes the next Tyrant; a Tyrant death without a player killer causes random succession among recently active eligible players.
• Every Tyrant death clears all class and Follower assignments and resets the former Tyrant's reign progression.
• Every Vigilante death rerolls the role among eligible players active in the preceding 24 hours. The previous Vigilante is reused only when no other eligible non-Tyrant player exists.
• A Tyrant levels and earns one unlock choice only by personally killing the Vigilante.
• Class abilities use named bound items where appropriate. Consumed cooldown items return when ready, and /tyrant item recovers missing ready items.
• The Tamer has no cooldown and uses a named fishing rod plus a separate captured-mob item.
• Game timers freeze while administratively paused.
• The project will follow the Java 17, Gradle, testing, Gitea CI, and semantic-release structure demonstrated by ../spigot-base/.