# GuestViewer<\/p>\n
A Minecraft plugin that restricts non-whitelisted players to spectator mode with movement limitations.<\/p>\n
<\/p>\n
## Download<\/p>\n
### Stable Version
\n**Download Latest Stable Version**<\/p>\n
### Bleeding Edge Version
\n**Download Latest Bleeding Edge Version**
\n\u26a0\ufe0f You will need to be logged into GitHub to download artifacts from GitHub Actions.<\/p>\n
## Server Compatibility<\/p>\n
– Tested and working on Minecraft 1.21.x
\n– Should work on Paper\/Spigot servers<\/p>\n
## Features<\/p>\n
– Permission-based whitelist system – players without the `guestviewer.bypass` permission are automatically set to spectator mode
\n– Players with the `guestviewer.bypass` permission are automatically set to survival mode
\n– Spectators can only move within 100 blocks of the player they’re spectating
\n– Permission-based free roaming near world spawn (`guestviewer.freeroam`)
\n– Chat restriction for spectators unless they have the `guestviewer.chat` permission
\n– Configurable welcome messages for both regular players and spectators
\n– Configurable join\/leave broadcast messages for both regular players and spectators
\n– Simple and lightweight<\/p>\n
## Installation<\/p>\n
1. Download the latest release from the link above
\n2. Place the JAR file in your server’s `plugins` directory
\n3. Restart your server or run `\/reload`
\n4. Configure the plugin as needed (see Configuration section)<\/p>\n
## Usage<\/p>\n
### Permissions<\/p>\n
– `guestviewer.bypass` – Players with this permission play normally (default: op)
\n– `guestviewer.admin` – Required to use admin commands like reload (default: op)
\n– `guestviewer.freeroam` – Allows spectators to roam freely within the configured distance of world spawn (default: false)
\n– `guestviewer.chat` – Allows spectators to use the chat (default: false)<\/p>\n
### Commands<\/p>\n
– `\/guestviewer` or `\/gview` – Displays plugin info
\n– `\/guestviewer reload` or `\/gview reload` – Reloads the plugin configuration<\/p>\n
## Configuration<\/p>\n
The plugin’s configuration is stored in `plugins\/GuestViewer\/config.yml`:<\/p>\n
“`yaml
\n# Maximum distance (in blocks) a spectator can move from their target
\nmax-distance: 100<\/p>\n
# Messages
\nmessages:
\n # Message shown to players when they join and are set to spectator mode
\n spectator-join: “&cYou are not whitelisted! You have been set to spectator mode.”<\/p>\n
# Message shown to players when they join and have the bypass permission
\n player-join: “&aWelcome back! You are playing in survival mode.”<\/p>\n
# Message shown when a spectator tries to move beyond the max distance
\n distance-warning: “&cYou cannot move more than 100 blocks from the player you are spectating!”<\/p>\n
# Message shown when a spectator without chat permission tries to chat
\n chat-restricted: “&cYou don’t have permission to chat. You are in spectator mode.”<\/p>\n
# Chat settings
\nchat:
\n # Whether to restrict chat for spectators without permission
\n restrict-spectator-chat: true<\/p>\n
# Broadcast notifications
\nbroadcast:
\n # Whether to broadcast when a player with bypass permission joins
\n player-join-enabled: true
\n player-join-message: “&e%player% &ahas joined the server.”<\/p>\n
# Whether to broadcast when a player with bypass permission leaves
\n player-quit-enabled: true
\n player-quit-message: “&e%player% &chas left the server.”<\/p>\n
# Whether to broadcast when a spectator joins
\n spectator-join-enabled: true
\n spectator-join-message: “&7Guest &e%player% &7has joined as a spectator.”<\/p>\n
# Whether to broadcast when a spectator leaves
\n spectator-quit-enabled: true
\n spectator-quit-message: “&7Guest &e%player% &7has left the server.”
\n“`<\/p>\n
## How it Works<\/p>\n
1. When a player joins, the plugin checks if they have the `guestviewer.bypass` permission
\n2. If they have the permission, they’re set to survival mode
\n3. If they don’t have the permission, they’re set to spectator mode
\n4. Spectators are restricted to a 100-block radius (configurable) around the player they’re spectating
\n5. Spectators with the `guestviewer.freeroam` permission can move within the configured radius of world spawn
\n6. Spectators without the `guestviewer.chat` permission cannot use the chat
\n7. If they try to move beyond allowed boundaries, they’re teleported back<\/p>\n
## Support<\/p>\n
If you encounter any issues or have suggestions, please open an issue on the GitHub repository.<\/p>\n
## License<\/p>\n
This plugin is released under the MIT License.<\/p>\n
## Development<\/p>\n
### Building from Source<\/p>\n
The project uses Maven for build automation. To build from source:<\/p>\n
“`bash
\nmvn clean package
\n“`<\/p>\n
The built jar file will be in the `target` directory.<\/p>\n
### Continuous Integration<\/p>\n
This project uses GitHub Actions to automatically build the plugin. The workflow:
\n– Builds the plugin on every push and pull request to main\/master branches
\n– Uses JDK 21 for compilation
\n– Creates artifacts that can be downloaded from the Actions tab <\/p>\n","protected":false},"excerpt":{"rendered":"
A Better Alternative to Whitelist<\/p>\n","protected":false},"featured_media":78402,"template":"","meta":{"_minecraft_slug":"guestviewer","_minecraft_project_id":"kh01mGtM","_minecraft_author":"Facha","_minecraft_license":"MIT","_minecraft_downloads":41,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"guestviewer.zip","_minecraft_size_bytes":11069,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T21:35:44.495166Z","_minecraft_date_created":"2025-04-21T20:03:23.536805Z","_minecraft_date_modified":"2025-04-19T16:11:37.616055Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/guestviewer","_minecraft_icon_attachment_id":78402,"_minecraft_imported_at":"2026-06-04T12:29:14+00:00","_minecraft_import_hash":"84360ff5ff6da3af5e7278981ab0ee88","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,127,128,129],"mod_loader":[130,132,133,134],"minecraft_version":[62,37,73,74,38,78],"class_list":["post-78401","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5"],"yoast_head":"\n