feat(spawn): add safe cooldown teleport
Release / release (push) Failing after 11s
CI / build (push) Successful in 51s

This commit is contained in:
dmg
2026-08-08 13:33:57 -04:00
parent 12d9e7af42
commit 87dec73f8f
9 changed files with 431 additions and 18 deletions
@@ -2,7 +2,7 @@
type: User Story
title: "US-002: Teleport safely to spawn"
description: Let eligible players teleport to a safe randomized location in their current world's spawn area after a stationary warm-up.
status: backlog
status: done
---
# US-002: Teleport safely to spawn
@@ -11,23 +11,23 @@ As an **eligible player**, I want `/spawn` to take me safely to my current world
## Acceptance criteria
- [ ] `/spawn` is available after at least one qualifying unique enemy kill or an administrative grant.
- [ ] A player without access receives a message instructing them to defeat a Warden, Ender Dragon, or Wither and sees the colored progress checklist.
- [ ] A banned player cannot begin a spawn teleport.
- [ ] When an active cooldown prevents `/spawn`, the player is explicitly told that the command is unavailable and sees the remaining wait in a friendly duration format.
- [ ] Cooldowns use real elapsed time and therefore continue while the player is offline.
- [ ] An accepted teleport request starts a three-second on-screen countdown.
- [ ] The player may look around during the countdown without cancelling it.
- [ ] A change to the player's block X, Y, or Z coordinate cancels the countdown, including walking to another block, jumping, or falling.
- [ ] Teleportation or a world change during the countdown cancels it.
- [ ] The destination is sampled randomly within the circular spawn area configured for the player's current world.
- [ ] The destination provides non-hazardous solid ground, two blocks of clear headroom, and no immediate lava, fire, water, void, or other configured environmental hazard.
- [ ] Unsafe underwater, leaf-top, inaccessible Nether-roof, and void-exposed destinations are rejected.
- [ ] The safe search prefers a valid vertical position closest to the configured spawn center's elevation rather than automatically preferring the world's highest surface.
- [ ] The safe-location search uses a bounded number of attempts and reports failure clearly when no destination is found.
- [ ] Only a completed teleport starts the applicable cooldown.
- [ ] After a completed teleport, a player with unfinished boss progression is reminded that defeating each remaining unique boss permanently reduces the cooldown.
- [ ] A cancelled countdown or failed safe-location search does not consume the cooldown.
- [x] `/spawn` is available after at least one qualifying unique enemy kill or an administrative grant.
- [x] A player without access receives a message instructing them to defeat a Warden, Ender Dragon, or Wither and sees the colored progress checklist.
- [x] A banned player cannot begin a spawn teleport.
- [x] When an active cooldown prevents `/spawn`, the player is explicitly told that the command is unavailable and sees the remaining wait in a friendly duration format.
- [x] Cooldowns use real elapsed time and therefore continue while the player is offline.
- [x] An accepted teleport request starts a three-second on-screen countdown.
- [x] The player may look around during the countdown without cancelling it.
- [x] A change to the player's block X, Y, or Z coordinate cancels the countdown, including walking to another block, jumping, or falling.
- [x] Teleportation or a world change during the countdown cancels it.
- [x] The destination is sampled randomly within the circular spawn area configured for the player's current world.
- [x] The destination provides non-hazardous solid ground, two blocks of clear headroom, and no immediate lava, fire, water, void, or other configured environmental hazard.
- [x] Unsafe underwater, leaf-top, inaccessible Nether-roof, and void-exposed destinations are rejected.
- [x] The safe search prefers a valid vertical position closest to the configured spawn center's elevation rather than automatically preferring the world's highest surface.
- [x] The safe-location search uses a bounded number of attempts and reports failure clearly when no destination is found.
- [x] Only a completed teleport starts the applicable cooldown.
- [x] After a completed teleport, a player with unfinished boss progression is reminded that defeating each remaining unique boss permanently reduces the cooldown.
- [x] A cancelled countdown or failed safe-location search does not consume the cooldown.
## Related