AstralStaff Overview

Features at a glance

See Commands for full syntax/permissions and Configuration for config.yml/messages.yml. Vanish's extensive event-blocking behavior and the invsee/ecview mirror's click semantics each get their own page: Vanish, Invsee & Ender Chest.

Vanish

/vanish toggles a boolean per player, tracked in-memory by VanishServiceImpl and persisted through StaffPlayerData.vanished (see Cross-server sync). While vanished, a player is hidden from Player#hidePlayer for everyone lacking staff.vanish.see, filtered out of outbound tab-complete and player-info packets via a PacketEvents listener, and has ~24 gameplay events cancelled so vanishing has no side effects other players could detect (block break/place, damage, mob targeting, bucket use, raids, sculk/turtle-egg/dripleaf triggers, etc.). See Vanish for the full list.

VanishServiceImpl implements AstralCore's VanishService interface and is registered globally via AstralPaperAPI.registerService(VanishService.class, this.vanish) — other plugins on the same server can resolve it through AstralPaperAPI.getService(VanishService.class) to check isVanished(UUID) without depending on AstralStaff directly.

Freeze

/freeze <player> toggles an in-memory (non-persistent) frozen flag on FreezeService. While frozen, the target's commands (PlayerCommandPreprocessEvent), teleports, and any move that changes block position are cancelled at HIGHEST priority. The flag is cleared automatically on quit — it does not survive a restart or a player rejoining (FreezeService keeps a plain in-memory Set<UUID>; there is a TODO in source to back it with Redis/a database for cross-restart persistence).

Invsee & ender chest inspection

/invsee <player> and /ecview <player> open a view-only mirror of the target's live player inventory or ender chest, respectively. The mirror is never itself authoritative: every click is intercepted, denied by default, and the intended effect is re-applied directly to the target's live inventory — this makes item duplication or deletion through the mirror structurally impossible rather than merely guarded against. See Invsee & Ender Chest for the click-by-click behavior.

Both commands refuse to let a player view their own inventory/ender chest (cannot-view-self) — doing so through the mirror would alias the source with the viewer's own inventory and break the duplication guarantees above.

Network-wide random teleport

/srtp (alias /mrtp) teleports the sender to a random online player anywhere on the network, not just the local server. The eligible pool comes from AstralCore's network-wide online-player cache, excludes the sender and any vanished player, and the actual cross-server hop is delegated to AstralCore's TeleportationService.

Every player visited is placed on a 10-minute cooldown recorded as a key in the shared Redis cache (astralstaff:rtp:cooldown:<uuid>), so the same player can't be repeatedly visited and the exclusion applies network-wide (any server's /srtp sees the same cooldown). The cooldown claim is written before the teleport is attempted, so two concurrent /srtp runs on different servers can't both pick the same target; it is released again if the teleport fails. A Redis read failure while checking cooldowns is treated as "not on cooldown" (fails open) so a transient cache outage can't lock the command out entirely.

Cross-server sync

AstralStaff registers one SnapshotAdapter<StaffPlayerData> (StaffSnapshotAdapter, key astralstaff:data) with AstralSync. StaffPlayerData is a single boolean vanished field. On apply() (fired on cross-server data hydration/join), the player is hidden or shown to match the stored flag — this is what makes /vanish state follow a player across a server switch. AstralStaff is not declared as an AstralSync-dependent module in any config beyond the plugin.yml hard depend on AstralSync.

Vanish state is additionally broadcast live (not just synced on join) over a dedicated Redis pub/sub messaging channel (staff.vanish, packet VanishToggledPacket, opcode 0x00): toggling vanish on one server immediately marks/unmarks the player as vanished in every other server's in-memory VanishServiceImpl map, so isVanished(...) checks elsewhere on the network (e.g. /srtp's candidate filter) are correct without waiting for a sync round-trip.

Dependencies