Guests Control

🚪 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

- Persistent storage — every new player is instantly made a guest on first join - Persistent storage — guests cannot break blocks, place blocks, open containers, attack entities, pick up items, use redstone, or interact with anything in the world - Persistent storage — `ADVENTURE` (default) or `SPECTATOR` - Persistent storage — guests are kicked after a configurable time (default 1 hour); remaining time is saved across disconnects - Persistent storage — guests always see their remaining time; color shifts green → yellow → red as it runs out - Persistent storage — idle guests are automatically removed after a configurable timeout - Persistent storage — periodic nudges reminding guests how to apply for full access - Persistent storage — guests can run `/guest request` to send a webhook ping straight to your Discord server - Persistent storage — `%guests_status%` and `%guests_time_left%` - Persistent storage — English (`en_us`) and Russian (`ru_ru`) out of the box, fully configurable - Persistent storage — all messages support colors, gradients, hover text, and clickable links - Persistent storage — 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`

```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: "<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`:

```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 <name>`.

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

---

🛡️ Compatibility

| | | |---|---| | Soft dependencies | Paper, Purpur, Spigot, and any Paper-compatible fork | | Soft dependencies | 1.21.x (tested); broadly compatible with 1.20+ | | Soft dependencies | Java 21+ | | Soft dependencies | PlaceholderAPI (optional) |

---

📝 Notes

- Players with the `guests.bypass` permission (OPs by default) are only while the player is online 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.

---

<details> <summary>RU (описание на русском)</summary>

🚪 Guests — Плагин управления гостями

Контролируйте, кто действительно играет на вашем сервере. Новые игроки присоединяются как гости с режимом только для чтения и могут стать полноценными участниками только после одобрения администратора — идеально подходит для серверов с вайтлистом, RP-серверов или любых серверов, где требуется ручная проверка игроков.

Если вы это читаете — заходите на мой ванила+ сервер OBK: play.obkteam.fun! Плагин создавался именно для него.

---

✨ Возможности

* Постоянное хранение данных — каждый новый игрок автоматически становится гостем при первом входе * Постоянное хранение данных — гости не могут ломать блоки, ставить блоки, открывать контейнеры, атаковать сущности, подбирать предметы, использовать редстоун или взаимодействовать с чем-либо в мире * Постоянное хранение данных — `ADVENTURE` (по умолчанию) или `SPECTATOR` * Постоянное хранение данных — гости кикаются после настраиваемого времени (по умолчанию 1 час); оставшееся время сохраняется даже после выхода с сервера * Постоянное хранение данных — гости всегда видят оставшееся время; цвет меняется зелёный → жёлтый → красный по мере его уменьшения * Постоянное хранение данных — бездействующие гости автоматически удаляются после настраиваемого тайм-аута * Постоянное хранение данных — периодические сообщения, напоминающие гостям, как подать заявку на полный доступ * Постоянное хранение данных — гости могут использовать `/guest request`, чтобы отправить webhook-уведомление прямо на ваш Discord-сервер * Постоянное хранение данных — `%guests_status%` и `%guests_time_left%` * Постоянное хранение данных — английский (`en_us`) и русский (`ru_ru`) из коробки, полностью настраиваемые * Постоянное хранение данных — все сообщения поддерживают цвета, градиенты, 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`

```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: "<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`:

```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 <name>`.

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

---

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

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

---

📝 Примечания

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