GuestViewer

A Minecraft plugin that restricts non-whitelisted players to spectator mode with movement limitations.

Download

Stable Version

Download Latest Stable Version

Bleeding Edge Version

Download Latest Bleeding Edge Version
⚠️ You will need to be logged into GitHub to download artifacts from GitHub Actions.

Server Compatibility

• Tested and working on Minecraft 1.21.x
• Should work on Paper/Spigot servers

Features

• Permission-based whitelist system - players without the guestviewer.bypass permission are automatically set to spectator mode
• Players with the guestviewer.bypass permission are automatically set to survival mode
• Spectators can only move within 100 blocks of the player they're spectating
• Permission-based free roaming near world spawn (guestviewer.freeroam)
• Chat restriction for spectators unless they have the guestviewer.chat permission
• Configurable welcome messages for both regular players and spectators
• Configurable join/leave broadcast messages for both regular players and spectators
• Simple and lightweight

Installation

1. Download the latest release from the link above
2. Place the JAR file in your server's plugins directory
3. Restart your server or run /reload
4. Configure the plugin as needed (see Configuration section)

Usage

Permissions

• guestviewer.bypass - Players with this permission play normally (default: op)
• guestviewer.admin - Required to use admin commands like reload (default: op)
• guestviewer.freeroam - Allows spectators to roam freely within the configured distance of world spawn (default: false)
• guestviewer.chat - Allows spectators to use the chat (default: false)

Commands

• /guestviewer or /gview - Displays plugin info
• /guestviewer reload or /gview reload - Reloads the plugin configuration

Configuration

The plugin's configuration is stored in plugins/GuestViewer/config.yml:

# Maximum distance (in blocks) a spectator can move from their target
max-distance: 100

# Messages
messages:
  # Message shown to players when they join and are set to spectator mode
  spectator-join: "&cYou are not whitelisted! You have been set to spectator mode."
  
  # Message shown to players when they join and have the bypass permission
  player-join: "&aWelcome back! You are playing in survival mode."
  
  # Message shown when a spectator tries to move beyond the max distance
  distance-warning: "&cYou cannot move more than 100 blocks from the player you are spectating!"
  
  # Message shown when a spectator without chat permission tries to chat
  chat-restricted: "&cYou don't have permission to chat. You are in spectator mode."

# Chat settings
chat:
  # Whether to restrict chat for spectators without permission
  restrict-spectator-chat: true

# Broadcast notifications
broadcast:
  # Whether to broadcast when a player with bypass permission joins
  player-join-enabled: true
  player-join-message: "&e%player% &ahas joined the server."
  
  # Whether to broadcast when a player with bypass permission leaves
  player-quit-enabled: true
  player-quit-message: "&e%player% &chas left the server."
  
  # Whether to broadcast when a spectator joins
  spectator-join-enabled: true
  spectator-join-message: "&7Guest &e%player% &7has joined as a spectator."
  
  # Whether to broadcast when a spectator leaves
  spectator-quit-enabled: true
  spectator-quit-message: "&7Guest &e%player% &7has left the server."

How it Works

1. When a player joins, the plugin checks if they have the guestviewer.bypass permission
2. If they have the permission, they're set to survival mode
3. If they don't have the permission, they're set to spectator mode
4. Spectators are restricted to a 100-block radius (configurable) around the player they're spectating
5. Spectators with the guestviewer.freeroam permission can move within the configured radius of world spawn
6. Spectators without the guestviewer.chat permission cannot use the chat
7. If they try to move beyond allowed boundaries, they're teleported back

Support

If you encounter any issues or have suggestions, please open an issue on the GitHub repository.

License

This plugin is released under the MIT License.

Development

Building from Source

The project uses Maven for build automation. To build from source:

mvn clean package

The built jar file will be in the target directory.

Continuous Integration

This project uses GitHub Actions to automatically build the plugin. The workflow:

• Builds the plugin on every push and pull request to main/master branches
• Uses JDK 21 for compilation
• Creates artifacts that can be downloaded from the Actions tab