54 lines
5.3 KiB
Markdown
54 lines
5.3 KiB
Markdown
---
|
|
type: User Story
|
|
title: "US-004: Inspect and manage player stealth"
|
|
description: Give administrators durable controls for online and offline progression, unlocks, and active concealment.
|
|
status: done
|
|
---
|
|
|
|
# US-004: Inspect and manage player stealth
|
|
|
|
As a **server administrator**, I want to inspect and correct player stealth state so that I can support players whether they are online or offline.
|
|
|
|
## Acceptance criteria
|
|
|
|
- [x] `/stealthadmin status <player|uuid>` reports accumulated time, unlock status, prepared-login state, and current concealment state.
|
|
- [x] Status inspection works for online players and known offline players selected by exact current or previously recorded name or UUID.
|
|
- [x] `/stealthadmin grant <player|uuid>` grants the unlock to an online or known offline player without altering accumulated time unnecessarily.
|
|
- [x] Granting an already-owned unlock is safe and clearly reports that no change was needed.
|
|
- [x] Granting the unlock sends the normal full-screen title and chat notification when the target is online.
|
|
- [x] `/stealthadmin reset <player|uuid> confirm` clears accumulated time, unlock ownership, prepared-login state, and current concealment for an online or known offline player.
|
|
- [x] Reset requires explicit confirmation and safely restores an online concealed player to ordinary identity presentation.
|
|
- [x] `/stealthadmin list` lists every currently online concealed player and clearly reports when there are none.
|
|
- [x] Concealed players remain absent from administrators' ordinary tab lists and retain scrambled overhead names; the admin command is the supported discovery mechanism.
|
|
- [x] An administrator joining while concealed players are online receives a private count and a hint to use `/stealthadmin list`.
|
|
- [x] When a concealed player joins, online administrators receive a private arrival notice, the updated concealed-player count, and the command hint.
|
|
- [x] Notifications require `spigotstealth.admin`; ordinary players receive no administrative notice.
|
|
- [x] Counts include the newly joined concealed player, and a joining concealed administrator receives only one administrative notification.
|
|
- [x] An administrator joining when no concealed players are online receives no notification.
|
|
- [x] Commands clearly reject unknown, ambiguous, malformed, or otherwise invalid targets without creating unintended player records.
|
|
- [x] Administrative inspection and modification require an operator-default administrative permission.
|
|
- [x] State-changing operations persist before success is reported and are safe under retries.
|
|
- [x] Grant and reset actions record the administrator, target UUID, and action in the server log without blocking the server tick thread.
|
|
- [x] `/stealthadmin` tab-completes `status`, `grant`, `reset`, and `list`, filtered by the entered prefix.
|
|
- [x] Target positions for `status`, `grant`, and `reset` suggest known player names, and reset's final argument suggests `confirm`.
|
|
- [x] Administrative completions require the administrative permission, and irrelevant positions return no suggestions instead of Bukkit's generic player list.
|
|
- [x] `/stealthadmin list unlocked` lists every known online or offline player with stealth unlocked.
|
|
- [x] The unlocked list is sorted case-insensitively, identifies nameless records by UUID, and clearly reports when it is empty.
|
|
- [x] Existing `/stealthadmin list` behavior continues to list currently concealed online players.
|
|
- [x] `/stealthadmin sleepcount status` reports whether concealed players are included in or excluded from sleep-percentage calculations.
|
|
- [x] `/stealthadmin sleepcount <include|exclude>` persists the policy before reporting success, applies it immediately, and records the administrator and policy in the server log.
|
|
- [x] The `sleepcount`, `status`, `include`, and `exclude` arguments are permission-gated and contextually tab-completed.
|
|
|
|
## Validation
|
|
|
|
Automated tests verify exact offline name and UUID resolution, ambiguous and unknown rejection without record creation, complete status output, idempotent grants and notification, complete resets with presentation cleanup, online concealed-player filtering, online and offline unlocked-player listing, contextual permission-gated completion, durable sleep-count status and policy changes, immediate policy refresh, confirmation and permission gates, persisted-before-success replies, and audit records. The complete `./gradlew clean check jar` lifecycle passes.
|
|
|
|
Login notice verification (2026-09-06): `./gradlew --offline clean check jar` passed all 70 tests and OKF validation. New tests first failed against the absent listener, then passed after implementation. Tests cover permission gates, zero-count silence, singular/plural counts, concealed-admin deduplication, ordinary-join silence for existing admins, and a prepared-login transition followed by an accurate administrative notice. Live-server verification remains pending.
|
|
|
|
Implementation: [admin join listener](../../src/main/java/games/dmg/spigotstealth/StealthAdminJoinListener.java), registered at `MONITOR` after the session listener's `HIGHEST` login transition. Notices expose only counts; names remain available through `/stealthadmin list`.
|
|
|
|
## Related
|
|
|
|
- [Rejoin without a visible identity](us-002-rejoin-without-visible-identity.md)
|
|
- [Configure and persist stealth progression](us-005-configure-and-persist-progression.md)
|