# 🚪 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 ` | Approve a guest as a full player | `guests.admin` | | `/guests add guest ` | 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 ` | 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](https://modrinth.com/plugin/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`** ```yaml # 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`): ```yaml welcome: title: "Welcome!" subtitle: "You are currently in guest mode" discord: "➤ Join our Discord: discord.gg/yourserver" ``` 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`: ```yaml 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 `. 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` безопасно перезапускает все фоновые задачи и перезагружает языковые файлы без перезапуска сервера.

ObKich