Guests Control

Minecraft 版本： 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11 26.1 26.1.1 26.1.2 26.2

平台： bukkit paper purpur spigot

标签： management social utility

? Guests — Guest Management Plugin

Control who actually plays on your server.
New players join as read-only guests and can only become full members after admin approval — perfect for whitelisted communities, roleplay servers, or any server that needs manual vetting.

---

✨ Features

• Automatic guest assignment — every new player is instantly made a guest on first join
• Full world protection — guests cannot break blocks, place blocks, open containers, attack entities, pick up items, use redstone, or interact with anything in the world
• Configurable guest gamemode — ADVENTURE (default) or SPECTATOR
• Time limit system — guests are kicked after a configurable time (default 1 hour); remaining time is saved across disconnects
• BossBar countdown — guests always see their remaining time; color shifts green → yellow → red as it runs out
• AFK kick — idle guests are automatically removed after a configurable timeout
• Repeat reminder messages — periodic nudges reminding guests how to apply for full access
• Discord integration — guests can run /guest request to send a webhook ping straight to your Discord server
• PlaceholderAPI support — %guests_status% and %guests_time_left%
• Dual language support — English (en_us) and Russian (ru_ru) out of the box, fully configurable
• MiniMessage formatting — all messages support colors, gradients, hover text, and clickable links
• Offline player management — approve or demote players even when they're not online
• Persistent storage — all player data survives server restarts via playerlist.yml

---

?️ Commands

Command	Description	Permission
/guests help	Show all available commands	guests.admin
/guests add player <name>	Approve a guest as a full player	guests.admin
/guests add guest <name>	Set a player back to guest status	guests.admin
/guests list players	List all approved players	guests.admin
/guests list guests	List all current guests with remaining time	guests.admin
/guests info <name>	View stored info for any player	guests.admin
/guests reload	Reload config and language files	guests.admin
/guest request	Send a join request to Discord	guests.request

---

? Permissions

Permission	Description	Default
guests.admin	Full access to all /guests subcommands	OP
guests.add	Permission to add/promote players	OP
guests.list	Permission to list players	OP
guests.info	Permission to view player info	OP
guests.reload	Permission to reload the plugin	OP
guests.request	Permission to use /guest request	Everyone
guests.bypass	Bypass all guest restrictions entirely	OP

---

? PlaceholderAPI

Requires PlaceholderAPI (soft dependency — plugin works without it).

Placeholder	Returns
%guests_status%	Guest or Player (localized)
%guests_time_left%	Remaining time (e.g. 1h 29m 55s) or ∞

---

⚙️ Configuration

config.yml

# Language: en_us or ru_ru
lang: en_us

# Gamemode for guests: ADVENTURE or SPECTATOR
guest-gamemode: ADVENTURE

# Guest time limit
guest-time-limit:
  enabled: true
  seconds: 3600  # 1 hour

# Periodic reminder message
repeat-message:
  enabled: true
  interval-seconds: 120

# AFK kick for guests
afk-kick:
  enabled: false
  timeout-seconds: 300

# /guest request command
request-command:
  enabled: true
  cooldown-seconds: 300

# Discord webhook
discord:
  webhook-url: "https://discord.com/api/webhooks/..."
  role-id: ""   # Role ID to ping (optional)
  user-id: ""   # User ID to ping (optional)

---

? Language Files

Language files live in plugins/Guests/language/.
The active language is set with lang: en_us (or ru_ru) in config.yml.

All messages use MiniMessage format — you can use colors, gradients, bold, italic, hover events, and clickable links anywhere.

Example (from en_us.yml):

welcome:
  title: "<gold><bold>Welcome!</bold></gold>"
  subtitle: "<yellow>You are currently in guest mode</yellow>"
  discord: "<aqua>➤ Join our Discord:</aqua> <click:open_url:'https://discord.gg/yourserver'><underlined>discord.gg/yourserver</underlined></click>"

To add a new language, create a new file (e.g. de_de.yml) in the language/ folder, set lang: de_de in config, and reload.

---

? Player Storage

All data is stored in plugins/Guests/playerlist.yml:

players:
  Steve:
    uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    status: player
  Alex:
    uuid: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
    status: guest
    remaining-time: 3450

The file is updated automatically every 60 seconds while the server is running, and always on disconnect and on /guests reload.

---

? Quick Setup

1. Drop the JAR into your plugins/ folder and start the server.
2. Open plugins/Guests/config.yml and set your preferred options.
3. (Optional) Paste your Discord webhook URL under discord.webhook-url.
4. (Optional) Edit the message files in plugins/Guests/language/ to match your server's branding.
5. Run /guests reload to apply changes without restarting.
6. When a player is ready to be approved, run /guests add player <name>.

That's it. New players will automatically join as guests from this point on.

---

?️ Compatibility

Server software	Paper, Purpur, Spigot, and any Paper-compatible fork
Minecraft version	26.x; 1.21.x; broadly compatible with 1.20+
Java version	Java 21+
Soft dependencies	PlaceholderAPI (optional)

---

? Notes

• Players with the guests.bypass permission (OPs by default) are never restricted, even if their stored status is guest. This lets admins test the server freely.
• The /guest request command has a per-player cooldown (configurable) to prevent webhook spam.
• Remaining guest time counts down only while the player is online and is persisted when they disconnect.
• Running /guests reload safely restarts all background tasks and reloads language files without a server restart.

---

RU (описание на русском) # ? Guests — Плагин управления гостями **Контролируйте, кто действительно играет на вашем сервере.** Новые игроки присоединяются как гости с режимом только для чтения и могут стать полноценными участниками только после одобрения администратора — идеально подходит для серверов с вайтлистом, RP-серверов или любых серверов, где требуется ручная проверка игроков. Если вы это читаете — заходите на мой ванила+ сервер OBK: **play.obk6.fun**! Плагин создавался именно для него! --- ## ✨ Возможности * **Автоматическое назначение гостя** — каждый новый игрок автоматически становится гостем при первом входе * **Полная защита мира** — гости не могут ломать блоки, ставить блоки, открывать контейнеры, атаковать сущности, подбирать предметы, использовать редстоун или взаимодействовать с чем-либо в мире * **Настраиваемый режим игры для гостей** — `ADVENTURE` (по умолчанию) или `SPECTATOR` * **Система лимита времени** — гости кикаются после настраиваемого времени (по умолчанию 1 час); оставшееся время сохраняется даже после выхода с сервера * **BossBar-таймер** — гости всегда видят оставшееся время; цвет меняется зелёный → жёлтый → красный по мере его уменьшения * **AFK-кик** — бездействующие гости автоматически удаляются после настраиваемого тайм-аута * **Повторяющиеся напоминания** — периодические сообщения, напоминающие гостям, как подать заявку на полный доступ * **Интеграция с Discord** — гости могут использовать `/guest request`, чтобы отправить webhook-уведомление прямо на ваш Discord-сервер * **Поддержка PlaceholderAPI** — `%guests_status%` и `%guests_time_left%` * **Поддержка двух языков** — английский (`en_us`) и русский (`ru_ru`) из коробки, полностью настраиваемые * **Форматирование MiniMessage** — все сообщения поддерживают цвета, градиенты, hover-текст и кликабельные ссылки * **Управление офлайн-игроками** — можно одобрять или понижать игроков даже если они не онлайн * **Постоянное хранение данных** — все данные игроков сохраняются после перезапуска сервера через `playerlist.yml` --- ## ?️ Команды | Команда | Описание | Разрешение | | --------------------------- | --------------------------------------------------------- | ---------------- | | `/guests help` | Показать все доступные команды | `guests.admin` | | `/guests add player ` | Одобрить гостя и сделать его полноценным игроком | `guests.admin` | | `/guests add guest ` | Вернуть игрока обратно в статус гостя | `guests.admin` | | `/guests list players` | Показать список всех одобренных игроков | `guests.admin` | | `/guests list guests` | Показать список всех текущих гостей с оставшимся временем | `guests.admin` | | `/guests info ` | Посмотреть сохранённую информацию о любом игроке | `guests.admin` | | `/guests reload` | Перезагрузить конфиг и языковые файлы | `guests.admin` | | `/guest request` | Отправить запрос на вступление в Discord | `guests.request` | --- ## ? Разрешения | Разрешение | Описание | По умолчанию | | ---------------- | --------------------------------------------- | ------------ | | `guests.admin` | Полный доступ ко всем подкомандам `/guests` | OP | | `guests.add` | Разрешение добавлять/повышать игроков | OP | | `guests.list` | Разрешение просматривать список игроков | OP | | `guests.info` | Разрешение просматривать информацию об игроке | OP | | `guests.reload` | Разрешение перезагружать плагин | OP | | `guests.request` | Разрешение использовать `/guest request` | Все | | `guests.bypass` | Полностью обходить все ограничения гостей | OP | --- ## ? PlaceholderAPI Требуется [PlaceholderAPI](https://modrinth.com/plugin/placeholderapi) (мягкая зависимость — плагин работает и без него). | Плейсхолдер | Возвращает | | -------------------- | ------------------------------------------------ | | `%guests_status%` | `Guest` или `Player` (локализовано) | | `%guests_time_left%` | Оставшееся время (например `1h 29m 55s`) или `∞` | --- ## ⚙️ Конфигурация **`config.yml`** ```yaml # Язык: en_us или ru_ru lang: en_us # Режим игры для гостей: ADVENTURE или SPECTATOR guest-gamemode: ADVENTURE # Лимит времени для гостей guest-time-limit: enabled: true seconds: 3600 # 1 час # Периодическое сообщение-напоминание repeat-message: enabled: true interval-seconds: 120 # AFK-кик для гостей afk-kick: enabled: false timeout-seconds: 300 # Команда /guest request request-command: enabled: true cooldown-seconds: 300 # Discord webhook discord: webhook-url: "https://discord.com/api/webhooks/..." role-id: "" # ID роли для пинга (необязательно) user-id: "" # ID пользователя для пинга (необязательно) ``` --- ## ? Языковые файлы Языковые файлы находятся в `plugins/Guests/language/`. Активный язык задаётся через `lang: en_us` (или `ru_ru`) в `config.yml`. Все сообщения используют формат **MiniMessage** — вы можете использовать цвета, градиенты, жирный текст, курсив, hover-события и кликабельные ссылки где угодно. **Пример** (из `en_us.yml`): ```yaml welcome: title: "Добро пожаловать!" subtitle: "Сейчас вы находитесь в режиме гостя" discord: "➤ Присоединяйтесь к нашему Discord: discord.gg/yourserver" ``` Чтобы добавить новый язык, создайте новый файл (например `de_de.yml`) в папке `language/`, укажите `lang: de_de` в конфиге и выполните перезагрузку. --- ## ? Хранение данных игроков Все данные сохраняются в `plugins/Guests/playerlist.yml`: ```yaml players: Steve: uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx status: player Alex: uuid: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy status: guest remaining-time: 3450 ``` Файл автоматически обновляется каждые 60 секунд во время работы сервера, а также всегда при выходе игрока и при выполнении `/guests reload`. --- ## ? Быстрая установка 1. Поместите JAR-файл в папку `plugins/` и запустите сервер. 2. Откройте `plugins/Guests/config.yml` и настройте нужные параметры. 3. (Необязательно) Вставьте ваш Discord webhook URL в `discord.webhook-url`. 4. (Необязательно) Отредактируйте файлы сообщений в `plugins/Guests/language/`, чтобы они соответствовали стилю вашего сервера. 5. Выполните `/guests reload`, чтобы применить изменения без перезапуска сервера. 6. Когда игрок готов к одобрению, выполните `/guests add player `. Готово. С этого момента новые игроки будут автоматически заходить на сервер как гости. --- ## ?️ Совместимость | | | | ----------------------------------- | -------------------------------------------------------- | | **Программное обеспечение сервера** | Paper, Purpur, Spigot и любые форки, совместимые с Paper | | **Версия Minecraft** | 26.x; 1.21.x (протестировано); в целом совместимо с 1.20+ | | **Версия Java** | Java 21+ | | **Мягкие зависимости** | PlaceholderAPI (необязательно) | --- ## ? Примечания * Игроки с разрешением `guests.bypass` (по умолчанию OP) **никогда не ограничиваются**, даже если их сохранённый статус — `guest`. Это позволяет администраторам свободно тестировать сервер. * Команда `/guest request` имеет кулдаун для каждого игрока (настраивается), чтобы предотвратить спам webhook-уведомлениями. * Оставшееся время гостя уменьшается **только пока игрок находится онлайн** и сохраняется при его выходе. * Выполнение `/guests reload` безопасно перезапускает все фоновые задачи и перезагружает языковые файлы без перезапуска сервера.