SSP - Scripted Server Plugin

# SSP — Changelog

New `/ssp inventory` tab. Global, server-wide gear sets: save a loadout once,
deploy it to anyone.

- `/ssp inventory save <id>` — captures your hotbar, main inventory, armour,
  offhand, held slot, and XP level/progress.
- `/ssp inventory load <id> [<@user>]` — applies a preset to yourself or, with
  a target, force-equips it onto any online player.
- `/ssp inventory list` — every saved id with author, date, and item count.
- `/ssp inventory delete <id>` — permanently removes the preset file.

Presets live as one YAML file each under `plugins/SSP/presets/`, so every
operator sees the same library and it survives restarts. `ItemStack` implements
`ConfigurationSerializable`, which is what carries enchantments, custom names,
lore and the rest of the item meta through the round trip — no hand-rolled NBT
writing involved.

Gated on its own `ssp.admin.inventory` node, which every operator holds
automatically through `ssp.admin`'s children — so loadout management can be
delegated to someone without handing over the rest of the plugin.

Loading is **destructive and has no undo**. Every load onto someone other than
yourself, and every delete, is logged to console — the same paper trail
`clearinventory` leaves.

Preset ids are restricted to `[a-z0-9_-]`, max 32 characters. That is a
security boundary, not tidiness: the id becomes a filename, so `../`,
backslashes, absolute paths and null bytes must never reach the filesystem.

Empty slots are stored as nulls rather than being skipped — dropping them would
shift every following item one slot left on load.

### Auto-expire duration option

Every toggle-style command across `/ssp troll`, plus `/ssp admin freeze` and
`vanish`, plus the state-holding `/ssp illusion` commands (`fakenametag`,
`fakeplayer spawn`, `hologram spawn`), now accepts an optional trailing
`for <amount> <unit>` clause — the same `TimeArg` parser `/ssp admin ban`
already uses, now also accepting `sec`/`seconds` for shorter durations.

- `/ssp troll shock qzvp for 30 sec` turns itself off after 30 seconds instead
  of running until you toggle it again.
- Applies to: `shock`, `lift`, `isolate`, `paranoia`, `blind`, `nausea`,
  `firework`, `rain`, `spin`, `actionbar` (troll); `freeze`, `vanish` (admin);
  `fakenametag`, `fakeplayer spawn`, `hologram spawn` (illusion).
- **Not** added to `/ssp plotarmor` — it persists to disk and survives
  restarts by design, so a real duration there needs a stored expiry
  timestamp like bans/timeouts have, not a simple in-memory timer. Separate
  change if wanted.
- `for` is a literal keyword, chosen specifically to stay unambiguous next to
  commands that take a free-text message afterward (`actionbar`,
  `fakenametag`). One accepted tradeoff: a message that happens to start with
  something parseable as "for <number> <word>" is rejected with a usage error
  rather than silently treated as plain text.

Effects whose "force off" path bypasses the public toggle — `lift`, `firework`
and `spin` all release internally when the target goes offline — cancel their
pending timer from that path instead. Without it, a player who quit mid-effect
would leave a timer armed that later fires and re-applies the effect to
someone who is not even online.

## 1.0.0

First release. Communications control, identity scrambling, a survival lock,
and admin tooling, all behind a command tree that does not exist as far as
non-operators are concerned.

### The golden rule

`/ssp` is gated on the `ssp.admin` permission (`default: op`). A non-holder
gets the vanilla "unknown command" message, and `ssp` is stripped from their
tab-completion list too, so the plugin's existence is never hinted at.

### Communications

- `/ssp chat enable | disable` — global chat lockdown.
- `/ssp chat add <@user> | remove <@user>` — whitelist that bypasses the lockdown.
- `/ssp chat spy` — see messages muted players tried to send.
- `/ssp sign enable | disable` — sign lockdown, enforced three ways: blocks the
  editor opening, force-closes one already open, and blanks text from clients
  that skip the UI entirely.
- `/ssp sign bypass <@user> | remove <@user>` — whitelist for signs.
- Proximity voice gate (requires Simple Voice Chat): microphones are muted
  unless the speaker holds `ssp.voice`, granted by nothing automatically.

### Identity scrambler

- `/ssp random player <both|name|skin> <@user>` — disguise one player with a
  random identity.
- `/ssp random player select <both|name|skin> <username> [<@user>]` — disguise
  as a **specific** chosen account instead of a random one.
- `/ssp random player disable <@user>` — revert to the true identity, and
  exempt from the global scramble so it survives a relog.
- `/ssp random player bypass <@user>` — permanent immunity to scrambling.
- `/ssp random player save <@user>` — make the current disguise survive restarts.
- `/ssp random enable <both|name|skin> | disable` — scramble/restore everyone.
- `/ssp random reveal [<@user>]` — privately see who is really behind a disguise.
- `/ssp random diagnose [<@user>]` — reports exactly what the running server
  supports for skin/name changes, for troubleshooting.
- Random identities are **invented usernames checked against the real Mojang
  API**, not a fixed list of celebrities — every disguise is a genuine,
  unknown account with its real skin. `identity.exclude` blocks specific
  names outright.
- Skin changes are applied through SkinsRestorer when it is installed (so the
  wearer sees their own new skin instantly, no relog needed), falling back to
  Paper's profile API, then direct profile editing on plain Spigot.
- `identity.auto-save` persists a disguise the moment it's applied, so it
  survives a relog instead of needing a separate `save` step.
- The vanilla "X (formerly known as Y) joined the game" broadcast — which
  would otherwise announce the disguise to the whole server — is suppressed.

### Plot armour (survival lock)

- `/ssp plotarmor enable | disable <@user>` — a fatal hit with a totem pops it
  normally; without one, the hit is cancelled and health is pinned at half a
  heart. No death event fires: no message, no dropped items, no stat change.

### Admin toolkit

Real moderation and utility tools. Anything that actually takes something
away from a player lives here, not under `/ssp troll`.

- `/ssp admin ban <@user> <amount> <min|hour|day>` — timed ban with a custom
  kick screen showing time remaining.
- `/ssp admin timeout <@user> <amount> <min|hour|day>` — full comms blackout:
  chat, voice, signs, and anvil renaming.
- `/ssp admin unban | untimeout <@user>` — lift either one early.
- `/ssp admin kick <@user> [reason]`.
- `/ssp admin freeze | unfreeze <@user>` — pin them exactly where they stand,
  for holding a suspected cheater still while you investigate.
- `/ssp admin vanish` — the operator disappears from every other player's view.
- `/ssp admin invsee <@user>` — open their real, live inventory.
- `/ssp admin heal | feed <@user>`.
- `/ssp admin gamemode <@user> <mode>`.
- `/ssp admin tp <@user> <@destination>` and `tphere <@user>`.
- `/ssp admin broadcast <message>`.
- `/ssp admin clearinventory <@user>` — genuinely destructive; every use is
  logged to console regardless of chat scrollback. Clears main slots, armour
  **and** offhand: `Inventory#clear()` alone only empties the 36 main slots.
- Operators are exempt from every restriction in the plugin — chat, signs,
  voice, the anvil — so an operator can never lock themselves out.

### Troll toolkit

Cinematic and disorienting, but reversible — no item loss, no lasting damage,
nothing that outlives the toggle.

- `/ssp troll shock <@user>` — cosmetic lightning strikes, no damage.
- `/ssp troll lift <@user>` — suspend in the air, frozen, until released.
- `/ssp troll isolate <@user>` — hide every other player from their screen.
- `/ssp troll paranoia <@user>` — random creepy sound cues only they can hear.
- `/ssp troll blind | nausea <@user>` — looping potion effects.
- `/ssp troll firework <@user>` — harmless particle bursts, never a real
  Firework entity.
- `/ssp troll rain <@user>` — personal weather; nobody else's sky changes.
- `/ssp troll spin <@user>` — spins their camera.
- `/ssp troll launch <@user>` — a free bounce; the landing never hurts them.
- `/ssp troll title | actionbar <@user> <message>` — on-screen messages only
  they see.

### Illusion toolkit

Fake, cosmetic-only output for staging a moment on camera. Nothing here is
real: no message was sent by who it claims, nobody named is actually
connecting, nothing counted down actually shuts the server off.

- `/ssp illusion fakemessage <text>` — a styled system-message line, no real
  sender.
- `/ssp illusion fakejoin | fakeleave <name>` — a vanilla-styled join/leave
  line for a name that is not actually connecting.
- `/ssp illusion fakepm <@user> <fromname> <message>` — a private-message-styled
  line only the target sees, from any name you type.
- `/ssp illusion scarescreen <@user> [message]` — a big red warning title and
  sound. Not a real kick.
- `/ssp illusion fakeplayer spawn <name> [skin-source] | remove | list` — an
  armor-stand statue wearing a real skin on its head. Read the limitation: the
  body is always the plain grey mannequin — only the head can carry a real
  skin texture, so this is a prop for a screenshot, not a body double.
- `/ssp illusion hologram spawn <id> <text> | remove | list` — floating text;
  `|` in the text stacks multiple lines.
- `/ssp illusion fakeserverstop <seconds> <message> | cancel` — a countdown
  title building to a fake restart. No real shutdown.
- `/ssp illusion fakemotd <text> [seconds] | reset` — overrides what shows in
  the multiplayer server list before anyone joins.
- `/ssp illusion fakenametag <@user> <text> | clear` — a prefix layered onto
  their tab-list entry and floating nametag via a scoreboard team. If another
  plugin already put them on a team, this replaces it.
- `/ssp illusion fakedeathmessage <@user> <cause text>` — a vanilla-styled
  death broadcast with no real death.