UnicoreConnect

Что умеет плагин UnicoreConnect и какие ручки за это отвечают

UnicoreConnect — плагин для Spigot/Paper/Sponge, который связывает игровой сервер с сайтом в обе стороны: забирает покупки, синхронизирует экономику, шлёт баны и статистику.

Всё, что он делает, доступно через API. Если плагин вам не подходит, дёргайте те же ручки из своего кода.

Подключение

Выпустите API-ключ с правом kernel.connect и укажите в разрешённых адресах IP игрового сервера. Ключ и адрес API впишите в конфиг плагина.

Один ключ на сервер

Выписать один ключ на все игровые серверы можно, но удобнее выдать по ключу на сервер: такой отзывается точечно, и в списке разрешённых адресов ровно один IP.

Склад покупок

Игрок купил на сайте, покупка легла на склад, плагин её забрал.

Метод	Путь	Что делает
`GET`	`/store/warehouse/:uuid/:server`	Что лежит на складе у игрока
`POST`	`/store/warehouse`	Отметить позиции выданными

Плагин получает список, выдаёт предметы в игре и отчитывается о выдаче. Пока отчёт не пришёл, позиция остаётся на складе. Если сервер упадёт посреди выдачи, покупка не потеряется.

Экономика

Внутриигровая валюта хранится на сайте и разложена по серверам.

Метод	Путь	Что делает
`GET`	`/cabinet/money/user/:server/:uuid`	Баланс игрока на сервере
`POST`	`/cabinet/money/user`	Установить баланс
`POST`	`/cabinet/money/user/deposit`	Начислить
`POST`	`/cabinet/money/user/withdraw`	Списать
`GET`	`/cabinet/money/top/:server`	Топ по балансу

Начислять и списывать отдельными ручками нужно, чтобы не терять деньги при гонках: два одновременных deposit дадут сумму, а два одновременных «установить» — то значение, которое пришло вторым.

Привилегии

Метод	Путь	Что отдаёт
`GET`	`/donates/groups/user/:server/:uuid`	Группы игрока на сервере
`GET`	`/donates/permissions/user/:server/:uuid`	Отдельные права игрока

Плагин дёргает обе ручки при заходе игрока и выдаёт ему группу.

Баны

Метод	Путь	Что делает
`GET`	`/bans/:uuid`	Активный бан игрока
`POST`	`/bans`	Забанить
`DELETE`	`/bans/:uuid`	Разбанить

Забанить можно из игры и из админки, список у них общий. В кабинете игрок увидит свой бан с причиной и сроком.

Наигранное время

Метод	Путь	Что делает
`PATCH`	`/cabinet/playtime`	Отправить время пачкой
`GET`	`/cabinet/playtime/user/:server/:uuid`	Время игрока на сервере
`GET`	`/cabinet/playtime/top/:server`	Топ по времени

PATCH принимает массив, поэтому плагин копит данные и шлёт их пачками, а не по игроку на запрос.

На наигранное время завязана реферальная программа: награду за приглашённого начислят, когда тот наиграет заданный порог.

Товар из игры

POST /store/products/from_game

Плагин отправляет предмет прямо из рук администратора, так что игровой ID и NBT приезжают в каталог готовыми. Руками остаётся вписать цену и картинку.

Так проще всего завести зачарованный сет: набрать такой NBT вручную практически невозможно.

Выдача до сервера доходит одним из двух путей, способ выбирается в карточке сервера: Серверы → Выдача → «Как выдавать товары и привилегии». Вариант RCON — сайт сам подключается к серверу и выполняет команды. Вариант Плагин (UnicoreConnect) — команды копятся в очереди на сайте, а забирает и выполняет их плагин.

Метод	Путь	Что делает
`GET`	`/rcon/:server/commands`	Забрать пачку команд, отдаётся до 200 штук
`POST`	`/rcon/:server/commands/ack`	Отчитаться: `{ "done": [id], "failed": [id] }`

Забранная пачка помечается «в работе» и второй раз не выдаётся. Если отчёт не пришёл за пять минут, сайт возвращает команды в очередь сам — сервер, упавший посреди выдачи, ничего не теряет.

Плагин дёргает GET по событию run_commands и дополнительно раз в минуту, на случай оборванного вебсокета.

Зачем это вместо RCON

Порт RCON открывать не нужно, и команды не теряются, пока сервер лежит. Плюс это единственный путь для сборок, где выдача идёт не одной командой: плагин выполняет их последовательностью, как они записаны в очереди.

События в реальном времени

Плагин может держать вебсокет-соединение и получать события сразу, не опрашивая API:

Событие	Когда
`give_group`	Игрок купил привилегию
`take_group`	Срок привилегии вышел
`give_permission`	Куплено отдельное право
`take_permission`	Срок права вышел
`run_commands`	В очереди сервера появились команды для плагина

События уходят в комнату kernel.connect, их получают все клиенты с этим правом. Поэтому в каждом событии приходит сервер, к которому оно относится (run_commands — полем serverId), и свой сервер нужно отфильтровать самому. Ключ, у которого заданы серверы, получает только их события. Подробнее в разделе Вебсокеты.

Если плагин не подходит

Довести покупку до сервера можно и без него, через RCON: сайт сам выполняет команды в консоли. Работает с любым сервером, ставить на него ничего не надо. Но офлайн-игроков RCON не умеет, а команды придётся описать шаблонами.