🚪 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	1.21.x (tested); 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.obkteam.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 <name>	Одобрить гостя и сделать его полноценным игроком	guests.admin
/guests add guest <name>	Вернуть игрока обратно в статус гостя	guests.admin
/guests list players	Показать список всех одобренных игроков	guests.admin
/guests list guests	Показать список всех текущих гостей с оставшимся временем	guests.admin
/guests info <name>	Посмотреть сохранённую информацию о любом игроке	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 (мягкая зависимость — плагин работает и без него).

Плейсхолдер	Возвращает
%guests_status%	Guest или Player (локализовано)
%guests_time_left%	Оставшееся время (например 1h 29m 55s) или ∞

---

⚙️ Конфигурация

config.yml

# Язык: 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):

welcome:
  title: "<gold><bold>Добро пожаловать!</bold></gold>"
  subtitle: "<yellow>Сейчас вы находитесь в режиме гостя</yellow>"
  discord: "<aqua>➤ Присоединяйтесь к нашему Discord:</aqua> <click:open_url:'https://discord.gg/yourserver'><underlined>discord.gg/yourserver</underlined></click>"

Чтобы добавить новый язык, создайте новый файл (например de_de.yml) в папке language/, укажите lang: de_de в конфиге и выполните перезагрузку.

---

💾 Хранение данных игроков

Все данные сохраняются в 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

Файл автоматически обновляется каждые 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 <name>.

Готово. С этого момента новые игроки будут автоматически заходить на сервер как гости.

---

🛡️ Совместимость

Программное обеспечение сервера	Paper, Purpur, Spigot и любые форки, совместимые с Paper
Версия Minecraft	1.21.x (протестировано); в целом совместимо с 1.20+
Версия Java	Java 21+
Мягкие зависимости	PlaceholderAPI (необязательно)

---

📝 Примечания

• Игроки с разрешением guests.bypass (по умолчанию OP) никогда не ограничиваются, даже если их сохранённый статус — guest. Это позволяет администраторам свободно тестировать сервер.
• Команда /guest request имеет кулдаун для каждого игрока (настраивается), чтобы предотвратить спам webhook-уведомлениями.
• Оставшееся время гостя уменьшается только пока игрок находится онлайн и сохраняется при его выходе.
• Выполнение /guests reload безопасно перезапускает все фоновые задачи и перезагружает языковые файлы без перезапуска сервера.