🚪 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 безопасно перезапускает все фоновые задачи и перезагружает языковые файлы без перезапуска сервера.