spigot-trigger-spawn/design/log.md

type, title, description

type	title	description
Log	Trigger Spawn Design Log	Chronological record of significant Trigger Spawn design decisions.

Trigger Spawn Design Log

2026-08-08 — Initial user stories

• Target Spigot 26.2 and Java 17 with a Gradle and Gitea Actions pipeline modeled on spigot-event-producer.
• Unlock /spawn after the first observed Warden, Ender Dragon, or Wither kill.
• Use real elapsed time for cooldowns, with defaults of eight, four, and one hour as unique boss kills accumulate.
• Support administrator-defined cooldown grants, complete access resets, and bans.
• Maintain a separate circular spawn area in each world, with a default radius of 20 blocks and safe randomized destinations.
• Require a stationary three-second warm-up that is cancelled by walking to another block, jumping, falling, teleportation, or world changes.

2026-08-08 — Progression reminders and rewards

• Remind players with incomplete progression that remaining unique boss kills permanently reduce the /spawn cooldown.
• Clear the active cooldown immediately after each newly credited unique boss kill.
• When cooldown prevents /spawn, explicitly report that it is unavailable and show the remaining wait in a friendly format.

2026-08-08 — Build and release foundation

• Added the Java 17 Gradle project targeting Spigot API 26.2, with JUnit 5 verification and versioned resource processing.
• Added Gitea CI and semantic-release workflows modeled on spigot-event-producer.
• Documented local builds, public releases, and the required RELEASE_TOKEN repository secret.

2026-08-08 — Configuration and persistence

• Added validated, independently configurable real-time cooldown tiers with documented defaults.
• Added atomic YAML persistence for UUID-based player access state and per-world spawn settings.
• Invalid persisted access values fail closed, while invalid required configuration disables the plugin rather than allowing partial startup.
• Added friendly duration formatting and the administrative permission declaration.

2026-08-08 — Per-world spawn areas

• Added /spawnadmin set, distance, and info for player-operated configuration of the current world.
• Worlds default to their native spawn and an independently persisted 20-block radius.
• Circular target sampling is uniform by area, preserves configured facing, and supports a zero-block radius.

2026-08-08 — Administrative access grants

• Added custom /spawn cooldown grants with safe, friendly duration parsing.
• Added complete access resets and a paginated view of naturally and administratively eligible players.
• Administrative targets resolve online players, persisted names, server-known offline players, and known UUIDs while state remains keyed by UUID.

2026-08-08 — Spawn bans

• Added persistent /spawn bans, unbans, and paginated ban listing for online and resolvable offline players.
• Banning immediately clears grants, boss progress, and cooldown state; unbanning restores none of them.
• Banned player state cannot retain natural or granted access.

2026-08-08 — Boss progression

• Added player-attributed Warden, Ender Dragon, and Wither kill observation without importing historical accomplishments.
• Unique kills unlock and improve the configured cooldown tier in any order; duplicate kills do not count.
• Each credited kill persists UUID-based progress, clears the current cooldown, and displays an on-screen reward plus colored checklist.