👁️ SpySpectator

SpySpectator is a modern, high-performance spectator mode, moderation, and minigame utility plugin tailored for Minecraft servers running Paper, Purpur, and Folia (1.21.1+).

By combining a customized, collision-free Adventure Flight Engine with native First-Person Camera Locking and Minecraft Target Operators (@s, @p, @a, @r), SpySpectator delivers the ultimate spectator experience without vanilla noclip chunk lag.

✨ What's New in v3.0.1

🎯 Target Operator Support: Full support for @s, @p, @a, and @r in /spectate and /spectator switch.
🎥 First-Person Camera Spectating: Right-click any player while in spectator mode to lock directly into their view; sneak (Shift) to detach back into free-flight!
💾 Lossless Inventory Reboot Persistence: Inventories and armor are serialized in Base64—no item loss across server reboots.
⚡ Zero Chunk-Loading Lag: Replaced synchronous chunk loading with non-blocking loaded chunk verification.
📄 Paginated Teleporter GUI: Browse unlimited players across multiple pages with health, world, and gamemode indicators.
🔒 Off-Hand Item Protection: Spectator hotbar utility tools can no longer be moved or bypassed using the 'F' key.
⚙️ Fully Wired config.yml: Customize all messages, item slots, titles, lores, and flight speeds.

🛠️ Interactive Hotbar Tools

When entering spectator mode, players receive 4 locked utility items (slots and lores are configurable in config.yml):

🧭 Compass (Slot 4): Opens an interactive, paginated GUI displaying online player heads for instant 1-click teleportation.
📜 Paper (Slot 2): Left-click to toggle spectator chat; right-click to open a player-by-player ignore menu.
👁️ Ender Eye (Slot 6): Left-click to toggle spectator visibility; right-click to hide specific spectators.
🛏️ Red Bed (Slot 8): Right-click to exit spectator mode and safely restore your survival inventory.

💻 Commands & Permissions

Command	Description	Permission	Default
`/spectator`	Toggle spectator mode for yourself	`spyspectator.use`	Everyone
`/spectator leave [player\|@selector]`	Exit spectator mode and restore inventory	`spyspectator.use`	Everyone
`/spectator switch <player\|@selector>`	Toggle spectator mode for target player(s)	`spyspectator.admin.switch`	OP
`/spectator reload`	Reload configuration settings and messages	`spyspectator.admin`	OP
`/spectator lobby [set\|remove]`	Manage the server exit spectator lobby	`spyspectator.admin`	OP
`/spectate [player\|@selector]`	Enter spectator mode and spectate a target	`spyspectator.use`	OP for others

📥 Installation

Download the latest SpySpectator-3.0.1.jar release.
Ensure your server runs Paper, Purpur, or Folia on Minecraft 1.21.1+ with Java 21.
Place SpySpectator-3.0.1.jar into your server's plugins/ directory.
Restart your server.
(Optional) Run /spectator lobby set to define an exit spawn point.

🔧 Developer API

import com.spygamingog.spyspectator.api.SpySpectatorAPI;
import org.bukkit.entity.Player;

// Check if player is spectating
boolean spectating = SpySpectatorAPI.isSpectator(player);

// Programmatically enable or disable spectator mode
SpySpectatorAPI.enableSpectator(player);
SpySpectatorAPI.disableSpectator(player, false, true);

Listen to cancelable events PlayerSpectateEvent and PlayerUnspectateEvent to control transitions in minigames and arenas.

📖 Documentation & Links

📚 Full Documentation: DOCUMENTATION.md
🔌 API Documentation: apidoc.md
📝 Release Changelog: changelog.md

📄 License

This project is licensed under the MIT License.