--- type: Log title: Spigot Tyrant Design Log description: Chronological record of material decisions affecting the Spigot Tyrant design. --- # Spigot Tyrant Design Log ## 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 `, 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 ` 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/`.