RoVision
RoVision Game APIВерсія 1.0.0

Документація Game API

Модуль на Luau, який підключає Roblox-гру партнера до RoVision: спільний бан-лист з миттєвим кіком на всіх серверах, ролі команди студії для адмін-команд і білі списки гравців. Тут описано все, що модуль уміє зараз, і як його підключити.

Огляд

RoVision Game API - це модуль на Luau, який підключає вашу Roblox-гру до RoVision. Ви кладете його в ServerScriptService, викликаєте RoVision:Init(), і сервер гри починає перевіряти гравців через API RoVision: бани, роль у команді вашої студії та білі списки.

Що вміє модуль

Модуль нічого не продає, не торкається Robux і передає RoVision тільки Roblox ID гравців та дані банів, записів білих списків і скарг, які ви надсилаєте самі.

Вимоги

  • Ви партнер RoVision, і гру додано в кабінеті: Кабінет, Мої ігри. Ще не партнер - подайте заявку.
  • У грі ввімкнено HTTP-запити: Game Settings, Security, Allow HTTP Requests.
  • API-ключ гри збережено в Secrets гри, а не в коді.
  • Модуль лежить у ServerScriptService і викликається тільки з серверних скриптів (Script). З клієнта він не працює.
  • Необовʼязково: ключ Roblox Open Cloud для миттєвого кіку змін, зроблених на сайті.

Як модуль звʼязується з RoVision

Модуль ходить в API RoVision (https://api.rovision.gg) звичайними HTTPS-запитами через HttpService. Кожен запит підписаний API-ключем гри із Secrets, тож ключ не потрапляє ні в код, ні на клієнт. Сервер RoVision сам вирішує, які бани, ролі й списки стосуються саме вашої гри, а модуль лише виконує відповідь.

Зворотний канал - MessagingService вашої гри. Коли бан, роль чи білий список змінюється, сервери гри отримують повідомлення в тему RoVision і одразу перепитують API про згаданих гравців. Такі повідомлення надсилають інші сервери вашої гри (після Ban, Unban, Allow і Disallow) і сам RoVision через Roblox Open Cloud, якщо ви додали ключ. Детальніше - у розділі «Миттєвий кік».

Модуль не ламає гру

Методи модуля не кидають винятків: якщо щось пішло не так, в Output зʼявляється попередження з префіксом [RoVision], а модуль діє безпечно - за баном нікого не кікає, а ролі й білі списки вважає відсутніми. Зупиняють скрипт з помилкою лише неправильні параметри Init і RequireAllowed, виклик RequireAllowed до Init і підключення модуля з клієнта.

Що відбувається під час входу

Ось що робить модуль для кожного гравця, коли ви вже викликали Init:

Схема: що відбувається, коли гравець заходить у гру з модулем RoVision
  1. Гравець заходить на сервер

    Модуль ловить Players.PlayerAdded. Гравців, які вже на сервері в момент Init, він перевіряє одразу.

  2. Входи збираються в пачку

    Модуль чекає до секунди: усі, хто зайшов за цей час, перевіряються разом, до 100 гравців у запиті.

  3. Три перевірки в API RoVision

    Паралельно, по одному запиту на кожну. Сервер RoVision сам вирішує, що з цього стосується вашої гри.

    • активний бан
    • роль у команді
    • білі списки
    • Є активний бан

      Спрацьовує PlayerBanned, а з Enforce = true гравця кікає з поясненням.

    • Бану немає

      Гравець грає. Роль і списки вже в кеші, тож IsModerator і IsAllowed відповідають без очікування.

    • Закритий тест, гравця немає в списку

      Якщо ввімкнено RequireAllowed, модуль кікає гравця з текстом закритого тесту.

    • API не відповів

      Нікого не кікають за баном (fail open), а ролі й білі списки вважаються відсутніми (fail closed).

  4. Поки гравець у грі

    Повторна перевірка всіх на сервері раз на RecheckInterval (5 хвилин) і миттєва перевірка гравця, коли приходить повідомлення про зміну його бану, ролі чи списків.

Швидкий старт

Шість кроків, кілька хвилин у кабінеті й у Roblox Studio. Після пʼятого кроку бан-лист, ролі команди й білі списки вже працюють, шостий вмикає миттєвий кік для змін, зроблених на сайті.

1. API-ключ у кабінеті

  1. Відкрийте Кабінет, Мої ігри, оберіть гру й відкрийте розділ «Інтеграція з грою».
  2. У картці «API-ключі» натисніть «Створити ключ» і дайте йому назву, наприклад «Основна гра» чи «Тестове місце». Ключ виглядає як rv_live_….
  3. Скопіюйте ключ одразу: повністю він показується лише один раз, далі видно тільки його початок.

Один ключ працює лише з однією грою. На гру можна мати до 5 активних ключів, наприклад окремі для основної гри й тестового місця. Якщо ключ потрапив у чужі руки, відкличте його там же й створіть новий: сервери з відкликаним ключем одразу втрачають доступ до RoVision.

2. HTTP-запити

У Roblox Studio: Game Settings, Security, Allow HTTP Requests. Без цього модуль не може звернутися до RoVision: він пише попередження в Output і пускає всіх гравців.

3. Ключ у Secrets

  1. Відкрийте Creator Dashboard, оберіть гру й знайдіть розділ Secrets.
  2. Додайте секрет з назвою rovision, значенням - вашим ключем, і доменом api.rovision.gg.

Для тестів у Studio секрет задається окремо, у налаштуваннях гри в Studio. Детальніше - у документації Roblox про Secrets.

Ключ - лише в Secrets

Не вставляйте ключ у код: його побачить кожен, хто отримає копію місця. Рядок в ApiKey підходить лише для тестів у Studio, і на живому сервері модуль попередить про це в Output. Домен секрету обмежує, куди ключ можна надіслати: з api.rovision.gg він працює тільки з API RoVision.

4. Модуль у грі

Варіант А - готовий файл

  1. Завантажте RoVision.rbxm з останнього релізу. Ту саму кнопку «Отримати модуль» ви знайдете в розділі «Інтеграція з грою».
  2. Перетягніть файл у Studio й покладіть модуль RoVision у ServerScriptService.

Варіант Б - Rojo

Скопіюйте папку src з репозиторію модуля у свій проєкт і змапте її як ServerScriptService.RoVision. Наприклад, якщо ви поклали її в packages/RoVision:

default.project.json
{
    "name": "MyGame",
    "tree": {
        "$className": "DataModel",
        "ServerScriptService": {
            "RoVision": { "$path": "packages/RoVision" }
        }
    }
}

У грі модуль - це один ModuleScript RoVision з дочірніми модулями (Bans, Team, Allowlists, Live та інші). Дочірні модулі не перейменовуйте й не розносьте: головний модуль знаходить їх за назвами.

Не кладіть модуль туди, де його бачить клієнт

ReplicatedStorage, StarterPlayer та інші місця, доступні клієнту, не підходять. Якщо підключити модуль з клієнта, він зупиниться з помилкою [RoVision] RoVision runs only on the server….

5. Запуск: Init

Створіть Script у ServerScriptService:

ServerScriptService › Script
local RoVision = require(game.ServerScriptService.RoVision)

RoVision:Init({
	Bans = {
		Enforce = true, -- кікати заблокованих гравців (так і за замовчуванням)
	},
})

Модуль сам читає ключ із секрету rovision. Якщо секрет має іншу назву, передайте його явно:

Інша назва секрету
local HttpService = game:GetService("HttpService")
local RoVision = require(game.ServerScriptService.RoVision)

RoVision:Init({
	ApiKey = HttpService:GetSecret("my-rovision-key"), -- ваша назва секрету
})

Цього достатньо: модуль перевіряє кожного гравця під час входу, а всіх на сервері - раз на 5 хвилин, і кікає тих, у кого є активний бан для вашої гри. Разом з банами він одразу дізнається роль гравця в команді й білі списки, у яких той є, тож IsModerator і IsAllowed зазвичай відповідають без очікування.

Перевірка в Studio

Додайте Debug = true і запустіть гру в Studio. В Output зʼявиться рядок про запуск, а далі запити до API й відповіді:

Output
[RoVision] v1.0.0 started: https://api.rovision.gg, Enforce = true, RecheckInterval = 300 s, Live = true
[RoVision] -> POST /game-api/v1/bans/check {"robloxUserIds":["…"]}
[RoVision] <- 200 POST /game-api/v1/bans/check in … ms {…}

Відповідь 200 означає, що ключ, секрет і HTTP-запити налаштовано правильно. Якщо замість неї зʼявилось попередження, знайдіть його в розділі «Вирішення проблем». Перед публікацією приберіть Debug.

6. Миттєвий кік

Необовʼязково, але рекомендовано. Бани й зміни білих списків з гри (RoVision:Ban, RoVision:Allow) і так доходять на всі сервери гри за секунди. Щоб так само швидко діяли бани, зміни команди й білих списків, зроблені на сайті, додайте в кабінеті ключ Roblox Open Cloud: Кабінет, Мої ігри, гра, «Інтеграція з грою», «Миттєвий кік на всіх серверах». Покрокова інструкція - у розділі «Миттєвий кік».

Без ключа такі зміни доходять до гравців, які вже в грі, під час повторної перевірки - до 5 хвилин.

Готовий скрипт

Повний робочий скрипт з основними параметрами. Модуль RoVision лежить у ServerScriptService, ключ - у секреті rovision. Назвіть скрипт інакше, ніж модуль, щоб require знайшов саме модуль:

ServerScriptService › RoVisionSetup (Script)
local RoVision = require(game.ServerScriptService.RoVision)

RoVision:Init({
	Debug = false, -- true: писати в Output усі запити (зручно для перевірки в Studio)
	Bans = {
		Enforce = true, -- кікати гравців з активним баном
		Live = true, -- миттєвий кік на всіх серверах через MessagingService
	},
})

-- Необов'язково: лог для вашої аналітики
RoVision.PlayerBanned:Connect(function(player, ban)
	print(`[Bans] {player.Name} ({player.UserId}): {ban.Scope}, {ban.Category}`)
end)

Бан-лист

Один бан-лист з трьома рівнями. Ви керуєте ним на сайті, а гра - через модуль: він не пускає гравців з активним баном, дає адмінам банити з гри й надсилає скарги модераторам RoVision з вашого античиту. Повні правила: rovision.gg/legal/network-bans.

Три рівні банів

Рівні банів
РівеньХто банить і знімає банДе діє
RoVision (мережа)Лише модератори RoVision. Партнери надсилають їм заявки з доказами або автоматичні скарги античиту.У всіх іграх-партнерах, де ввімкнено «Застосовувати бан-лист RoVision».
СтудіяВласник студії, а також адміністратори й модератори її команди.У всіх іграх, зарахованих до студії.
ГраВласник гри, власник студії, до якої гра зарахована, та адміністратори й модератори команди цієї студії.Лише в цій грі. Банити можна на сайті або з гри через RoVision:Ban.

Правила коротко

  • Мережеві бани RoVision - лише за три категорії: читерство й експлойти (exploiting), шахрайство з предметами, обмінами чи акаунтами (scamming), боти й автоматизація (botting). Токсичність чи порушення правил окремої гри - не привід для мережевого бану: такі речі кожна гра модерує сама банами рівня гри чи студії.
  • Партнери й ігри не банять у мережі. Вони надсилають скарги з доказами або автоматичні скарги античиту. Кожну скаргу розглядає модератор, автоматично нікого не блокують.
  • Бани студії й гри - за будь-яку причину, повʼязану з вашими іграми (категорія може бути other). Причина обовʼязкова, її бачить гравець. Апеляції на ці бани розглядаєте ви. Модератори RoVision можуть зняти бан, який порушує правила платформи: помста, дискримінація, шантаж, бан за речі поза грою.
  • Тривалість - від 1 до 3650 днів або назавжди.
  • Бан діє лише в іграх-партнерах з модулем. Він не зачіпає ні Roblox-акаунт, ні акаунт на сайті RoVision.

Які бани діють у грі

Сервер RoVision сам вирішує, які бани стосуються вашої гри, а модуль лише виконує відповідь:

  • бани рівня гри - завжди;
  • бани студії - якщо гра зарахована до студії;
  • мережеві бани RoVision - якщо ввімкнено перемикач «Застосовувати бан-лист RoVision» у Кабінет, Мої ігри, гра, «Інтеграція з грою». Він увімкнений за замовчуванням, а бани вашої гри та студії діють незалежно від нього.

Якщо гравець має кілька банів, модуль отримує найдовший.

Керування на сайті

Бан-лист живе в Кабінет, Розробка, «Бан-лист» (/account/ban-list). Розділ бачать партнери, а також адміністратори й модератори команд студій. Угорі оберіть список: гру, студію чи «Глобальний бан-лист RoVision». Бан-лист конкретної гри відкривається й кнопкою «Бани цієї гри» в розділі «Інтеграція з грою».

  • «Бани» - бани обраної гри чи студії з пошуком за ніком або ID і фільтром за статусом. Бани, видані з гри через RoVision:Ban, теж зʼявляються тут.
  • «Новий бан» - гравець (нік у Roblox або ID), де діє (гра чи студія), категорія, причина, яку побачить гравець, строк і внутрішня нотатка.
  • «Редагувати» - категорія, причина, строк і нотатка; бан гри чи студії можна перенести в іншу вашу студію чи гру. Гравець отримає сповіщення, якщо зміниться місце, категорія, причина чи строк.
  • «Розширити на студію» - бан гри стає баном студії, до якої гра зарахована: гравця блокує в усіх її іграх.
  • «Подати в глобальну базу RoVision» - заявка в мережевий бан-лист з бану вашої гри чи студії. Те саме без бану - кнопка «Подати заявку» у «Глобальному бан-листі RoVision». У заявці - категорія (exploiting, scamming або botting), опис і докази: посилання (https://) або скріншоти, до 10 зображень, хоча б щось одне. Рішення модератора приходить у кабінет і в ботах, а всі ваші заявки видно на вкладці «Заявки в RoVision».
  • «Зняти бан» - з причиною зняття.
  • «Історія» кожного бану - хто і коли його видав, змінив чи зняв. Записи не можна змінити чи видалити.
  • «Глобальний бан-лист RoVision» - активні мережеві бани для перегляду: Roblox ID, нік, категорія, публічна причина й дати.

Апеляції гравців

Гравець входить на RoVision з привʼязаним Roblox-акаунтом і відкриває Кабінет, «Блокування» (/account/bans). Там видно всі бани його Roblox-акаунта в іграх партнерів: рівень (RoVision, назва студії чи гри), причину, строк, і там же подається апеляція.

  • Одна відкрита апеляція на бан. Після відмови наступну можна подати через 30 днів.
  • Прийнята апеляція знімає бан. Рішення приходить гравцю в кабінет і в ботах.
  • Апеляції на бани ваших ігор і студій - на вкладці «Апеляції» бан-листа: їх розглядають власник і команда студії, а гравець бачить вашу відповідь. Апеляції на мережеві бани розглядають модератори RoVision.

Бани з гри: Ban і Unban

RoVision:Ban створює бан рівня гри. Гравця на цьому сервері модуль кікає одразу (якщо Enforce = true), на інших серверах гри - за кілька секунд (миттєвий кік), а при наступному вході - одразу. Якщо в гравця вже є бан рівня гри, новий його замінює. RoVision:Unban так само за кілька секунд доходить до всіх серверів.

Приклад адмін-команд у чаті. Права беруться з команди на сайті: команди працюють для власника, адміністраторів і модераторів, а список Roblox ID у коді не потрібен.

ServerScriptService › AdminCommands (Script)
local Players = game:GetService("Players")
local RoVision = require(game.ServerScriptService.RoVision)

local function findPlayer(name)
	for _, player in Players:GetPlayers() do
		if string.lower(player.Name) == string.lower(name) then
			return player
		end
	end
	return nil
end

Players.PlayerAdded:Connect(function(admin)
	admin.Chatted:Connect(function(message)
		if string.sub(message, 1, 1) ~= "!" then
			return -- звичайне повідомлення, не команда
		end
		-- Власник, адміністратор або модератор команди. Якщо RoVision недоступний - false.
		if not RoVision:IsModerator(admin) then
			return
		end

		-- !ban <нік> <днів, 0 = назавжди> <причина>
		local name, days, reason = string.match(message, "^!ban%s+(%S+)%s+(%d+)%s+(.+)$")
		if name then
			local target = findPlayer(name)
			if not target then
				warn(`Гравця {name} немає на сервері`)
				return
			end
			local ok, result = RoVision:Ban(target, {
				Reason = reason,
				DurationDays = if days == "0" then nil else tonumber(days),
			})
			print(if ok then `{target.Name} заблоковано` else `Не вдалося: {result}`)
			return
		end

		-- !unban <UserId>
		local userId = tonumber(string.match(message, "^!unban%s+(%d+)$"))
		if userId then
			local ok, result = RoVision:Unban(userId)
			print(if ok then `Знято банів: {result}` else `Не вдалося: {result}`)
		end
	end)
end)

Права перевіряєте ви

Модуль не перевіряє, хто викликає Ban, Unban, Allow чи Disallow: перевірка прав - на вашому боці, наприклад через RoVision:IsModerator. Не викликайте їх з RemoteEvent без перевірки на сервері, інакше читер зможе банити інших.
  • Ban і Unban чекають відповіді API й повертають true і результат або false і текст помилки. Параметри - у довідці.
  • Unban знімає лише бани рівня гри для цієї гри. Бани студії та мережеві бани RoVision лишаються: їх знімають на сайті ті, хто їх видав.
  • Якщо MessagingService недоступний або Bans.Live = false, інші сервери побачать зміну під час наступної повторної перевірки (до RecheckInterval, 5 хвилин за замовчуванням).

Перевірка вручну: CheckBan

Зазвичай нічого перевіряти вручну не треба: модуль робить це сам. CheckBan знадобиться, наприклад, щоб показати причину бану в адмін-панелі або перевірити гравця, якого немає на сервері, за UserId.

Luau
local ban, checked = RoVision:CheckBan(player) -- або Roblox UserId
if ban then
	print(ban.Scope, ban.Category, ban.Reason, ban.ExpiresAt or "назавжди")
elseif not checked then
	warn("RoVision зараз недоступний") -- ban == nil, але це не означає «не заблокований»
end

Метод чекає відповіді (до секунди довше, бо запити збираються в пачки), результат кешується на 5 хвилин або доки не прийде повідомлення про зміну бану. Друге значення - false, якщо API недоступний: тоді nil не означає «не заблокований».

Скарги з античиту: Report

Коли античит упевнено бачить читера, надішліть скаргу модераторам RoVision. Якщо вони її приймуть, гравець отримає мережевий бан в іграх-партнерах.

Luau
RoVision:Report(player, {
	Category = "exploiting",
	Description = "Телепорт на 312 студів за 0.1 с",
	Detection = { -- необов'язково: дані для модератора
		check = "teleport",
		distance = 312.4,
		placeVersion = game.PlaceVersion,
	},
})
  • Метод не чекає відповіді: скарга стає в чергу й надсилається у фоні. Під час закриття сервера модуль дописує чергу.
  • Category - лише exploiting, scamming або botting.
  • Description - від 1 до 1000 символів, довший текст обрізається.
  • Detection - таблиця з числами, рядками й булевими значеннями, до 8 КБ у JSON. Замість Vector3 чи Instance передавайте числа й рядки. Завеликі дані модуль замінює позначкою truncated.
  • Скарги на того самого гравця з тією ж категорією частіше ніж раз на 30 секунд обʼєднуються в одну (з останнім описом і даними). На сервері RoVision скарги з вашої гри на одного гравця за 24 години теж зливаються в одну з лічильником повторів.
  • Разом зі скаргою модуль надсилає JobId сервера, щоб модератор знав, де це сталося.

Скарга нікого не банить

Її розглядає модератор RoVision. Надсилайте лише впевнені детекти, а не кожну підозру. Поки скаргу розглядають, гравця можна забанити у вашій грі через RoVision:Ban.

Подія PlayerBanned

Якщо хочете самі вирішувати, що робити з заблокованим гравцем, вимкніть Enforce і підпишіться на PlayerBanned:

Luau
RoVision:Init({
	Bans = { Enforce = false },
})

RoVision.PlayerBanned:Connect(function(player, ban)
	if ban.Scope == "rovision" and ban.Category == "botting" then
		Matchmaking.SendToSoloServer(player) -- ваша власна логіка
	else
		player:Kick("Вас заблоковано в цій грі.")
	end
end)
  • PlayerBanned спрацьовує і з Enforce = true (перед кіком), тож ним зручно, наприклад, писати логи.
  • Подія приходить під час входу, повторної перевірки, після RoVision:Ban на цьому сервері й після миттєвого оновлення з сайту чи з інших серверів.
  • Для одного й того самого бану подія приходить один раз за сесію гравця. Виняток: якщо бан зняли (RoVision:Unban на цьому сервері чи миттєве оновлення), а потім він знову почав діяти, подія прийде ще раз.

Текст кіку: KickMessage

Модуль кікає гравця з повідомленням українською, залежно від рівня бану:

  • RoVision: «Вас заблоковано в мережі ігор RoVision. Порушення: шахрайство. Причина: … Діє до 10.11.2026 14:00 UTC.»
  • Студія: «Вас заблоковано в іграх цієї студії. Причина: … Блокування безстрокове.»
  • Гра: «Вас заблоковано в цій грі. Причина: … Діє до …»

Рядок «Порушення» зʼявляється для категорій exploiting, scamming і botting. У повідомленні немає посилань: Roblox забороняє відправляти гравців за межі платформи, тому посилання з тексту причини модуль вирізає, а саму причину скорочує до 200 символів. Свій текст задайте через Bans.KickMessage: рядком для всіх банів або функцією, яка отримує Ban:

Luau
RoVision:Init({
	Bans = {
		KickMessage = function(ban)
			if ban.Scope == "game" then
				return `You are banned from this game. Reason: {ban.Reason}`
			end
			return nil -- для інших рівнів - стандартний текст
		end,
	},
})

Функція може повернути nil, щоб лишити стандартний текст. Якщо вона падає з помилкою чи повертає не рядок, модуль теж бере стандартний текст і пише попередження в Output. Посилань у власному тексті теж не додавайте.

Повторні перевірки й збої

Крім перевірки під час входу, модуль раз на Bans.RecheckInterval секунд (300 за замовчуванням, мінімум 60) повторно перевіряє всіх гравців на сервері: бани, ролі й білі списки. Так бан, виданий на сайті, діє навіть без миттєвого кіку - до 5 хвилин. Інтервал має невеликий випадковий розкид, щоб сервери, запущені разом, не зверталися до API одночасно.

Якщо API недоступний

Бани працюють за принципом fail open: помилково кікнути гравця через збій гірше, ніж на кілька хвилин пропустити заблокованого. Якщо RoVision не відповідає, немає ключа чи вимкнено HTTP-запити, модуль нікого не кікає за баном, CheckBan повертає nil, false, а в Output зʼявляється попередження. Під час наступної перевірки модуль спробує знову.

Бани - fail open, права - fail closed

Через збій RoVision модуль нікого не кікає за баном. Ролі й білі списки навпаки: поки API недоступний, IsModerator, IsAdmin і IsAllowed повертають false. Детальніше - у розділі «Fail open і fail closed».

Миттєвий кік

Коли бан, роль у команді чи білий список гравця змінюється, сервери вашої гри дізнаються про це за кілька секунд, а не під час наступної повторної перевірки (до 5 хвилин). Зміни з гри працюють так одразу, для змін із сайту потрібен ключ Roblox Open Cloud.

Як це працює

Модуль підписується на тему RoVision у MessagingService вашої гри. Коли бан, роль чи запис у білому списку змінюється, у тему приходить повідомлення з Roblox ID гравців, і сервер, на якому такий гравець зараз грає, одразу перевіряє його через API RoVision. Саме повідомлення не містить даних про зміну: відповідь завжди дає API.

  • Бан почав діяти - модуль кікає гравця (або запускає PlayerBanned, якщо Enforce = false).
  • Бан зняли - модуль лише оновлює кеш, і гравця одразу пускають на будь-який сервер.
  • Змінилась роль - IsModerator і IsAdmin відповідають по-новому, приходить RoleChanged.
  • Змінились білі списки - IsAllowed відповідає по-новому, приходить ListsChanged, а RequireAllowed кікає гравця, якого прибрали зі списку.

Зміни з гри

RoVision:Ban, Unban, Allow і Disallow доходять на всі сервери гри миттєво й без жодних налаштувань: після успішного виклику модуль сам надсилає повідомлення іншим серверам гри. Ключ Open Cloud для цього не потрібен.

Зміни з сайту: ключ Open Cloud

Зміни з сайту - бани (ваші, вашої студії, модераторів RoVision, а також зняті після апеляції), команда студії й білі списки - RoVision надсилає у вашу гру через Roblox Open Cloud. Для цього потрібен ключ Open Cloud:

  1. Відкрийте Creator Dashboard → Open Cloud, API Keys і натисніть Create API Key. Якщо гра належить групі, створюйте ключ від імені групи.
  2. Назвіть ключ, наприклад, RoVision.
  3. У Access Permissions додайте API system Messaging Service API, оберіть вашу гру й операцію Publish.
  4. У Security, Accepted IP Addresses додайте 0.0.0.0/0: адреса сервера RoVision може змінюватися.
  5. Термін дії (Expiration) - на ваш розсуд. Коли ключ перестане працювати, бот RoVision вам напише.
  6. Збережіть ключ, скопіюйте його й вставте в Кабінет, Мої ігри, гра, «Інтеграція з грою», «Миттєвий кік на всіх серверах», потім натисніть «Зберегти й перевірити».

RoVision одразу надсилає з ключем тестове повідомлення і зберігає ключ, лише якщо Roblox його прийняв. Ключ зберігається зашифрованим, повністю його більше ніде не показують, і RoVision використовує його лише для повідомлень у тему RoVision вашої гри.

Без ключа зміни з сайту діють, як і раніше: під час входу - одразу, а для гравців, які вже в грі, - під час повторної перевірки.

Статус у кабінеті

Картка «Миттєвий кік на всіх серверах» у розділі «Інтеграція з грою» показує стан ключа:

Стан миттєвого кіку в кабінеті
ПозначкаЩо означає
Не налаштованоКлюча немає. Зміни з сайту доходять до гравців у грі під час повторної перевірки.
УвімкненоКлюч працює: видно його кінець, коли його востаннє перевірено й коли RoVision востаннє доставив повідомлення.
Не працюєОстання доставка не вдалася: видно помилку й час останньої невдалої спроби. Бани все одно діють через повторну перевірку.
  • «Перевірити зараз» - надіслати тестове повідомлення ще раз, наприклад після виправлення ключа в Creator Dashboard.
  • «Замінити ключ» - поточний ключ працює, доки Roblox не прийме новий.
  • «Видалити ключ» - зміни з сайту знову доходитимуть під час перевірки. У Roblox ключ залишиться: за потреби видаліть його в Creator Dashboard.

Сервер гри з Debug = true пише про тестове повідомлення в Output:

Output
[RoVision] Live updates: ping from RoVision received; this server gets changes instantly.

Що ще варто знати

Тема RoVision зарезервована для модуля

Не використовуйте тему RoVision у своїх скриптах і не надсилайте в неї власних повідомлень.
  • Модуль бере небагато з лімітів MessagingService: одна підписка на сервер і одне повідомлення на кожен успішний Ban, Unban, Allow чи Disallow.
  • Повідомлення, що приходять майже одночасно (протягом пів секунди), модуль обʼєднує в одну перевірку, і такі перевірки йдуть не частіше ніж раз на 2 секунди.
  • Якщо підписатися не вдалося (збій Roblox, Studio без доступу до API), модуль пише попередження й пробує знову у фоні з паузою, що зростає до 5 хвилин. Зміни тим часом доходять під час повторної перевірки. Через помилку модуль нікого не кікає.
  • Якщо не вдалося повідомити інші сервери після Ban чи Allow, зміна все одно збережена: інші сервери побачать її під час повторної перевірки.
  • Без API-ключа модуль не підписується на тему: перевіряти гравців однаково не вийде.

Щоб вимкнути миттєвий кік, передайте Bans.Live = false. Тоді модуль не підписується на тему й не надсилає повідомлень, а зміни банів, команди й білих списків доходять під час повторної перевірки.

Luau
RoVision:Init({
	Bans = { Live = false }, -- без MessagingService: зміни доходять під час повторної перевірки
})

Тести в Studio

У Studio миттєвий кік із сайту не працює. Roblox доставляє повідомлення Open Cloud лише на живі сервери, а тест у Studio таким не є. Тому в Studio модуль на старті пише попередження [RoVision] Live updates don't work in Studio… і перевіряє гравців кожні 15 секунд замість RecheckInterval: бан із сайту спрацює протягом цих 15 секунд.

Щоб перевірити саме миттєвий кік, опублікуйте гру й зайдіть у неї через Roblox (живий сервер). BaseUrl має бути доступним з інтернету: localhost з серверів Roblox не відкривається.

Команда й ролі

Модуль знає команду вашої студії з сайту, тож права для адмін-команд не треба зашивати в код списком Roblox ID. Ви ведете команду в кабінеті, а гра питає RoVision:IsModerator(player).

Ролі

Ролі команди
РольХто цеНа сайтіIsModeratorIsAdmin
"owner"Власник гри або власник студії, до якої гра зарахована.Усе: бан-лист, апеляції, заявки в RoVision, білі списки. Власник студії керує командою й лише він призначає адміністраторів.тактак
"admin"Адміністратор команди студії.Бан-лист, апеляції й заявки в RoVision для студії та її ігор, білі списки. Запрошує, змінює ролі та прибирає модераторів і учасників.тактак
"moderator"Модератор команди студії.Бан-лист, апеляції й заявки в RoVision для студії та її ігор, білі списки.такні
"member"Учасник команди студії.У команді, але без прав модерації.ніні
nilУсі інші гравці.-ніні

Власник, адміністратори й модератори також проходять закритий тест RequireAllowed без запису в списку. Учасники (member) - ні.

Команда на сайті

Команду ведуть на сайті: Кабінет, Розробка, «Студії», студія, «Команда».

  • Власник студії й адміністратори запрошують людей за юзернеймом на RoVision і обирають роль. Адміністраторів запрошує й прибирає лише власник.
  • Запрошення приходить у ботах і в Кабінет, Розробка, «Команди студій» (/account/teams), де його треба прийняти. Там же людина бачить свої команди й може вийти з команди.
  • Роль змінюється одразу, людина отримує сповіщення. Роль діє в усіх іграх, зарахованих до студії.
  • «Історія команди» показує, хто кого запросив, хто приєднався, вийшов чи змінив роль. Записи не можна змінити чи видалити.
  • Якщо гра не зарахована до студії, команди в неї немає: роль є лише у власника гри.

Роль діє лише з привʼязаним Roblox-акаунтом

Модуль впізнає людей за Roblox ID, тому роль працює лише для тих, хто підключив Roblox-акаунт до RoVision. Це стосується й власника: без підключеного Roblox-акаунта IsModerator поверне для нього false. У списку команди такі люди позначені «Roblox не підключено».

Ролі в грі

Luau
local role, checked = RoVision:GetRole(player) -- "owner", "admin", "moderator", "member" або nil

if RoVision:IsModerator(player) then
	-- власник, адміністратор або модератор
end

if RoVision:IsAdmin(player) then
	-- власник або адміністратор
end
  • Ролі гравців модуль запитує під час входу разом з перевіркою банів, тож IsModerator зазвичай відповідає одразу.
  • Для гравця, якого немає на сервері (за UserId), метод чекає відповіді API, до секунди довше. Результат кешується на 5 хвилин.
  • Зміни команди на сайті доходять до серверів за секунди з миттєвим кіком, інакше під час повторної перевірки.
  • Тестові гравці Studio (з відʼємним UserId) ролі не мають.

Подія RoleChanged

Коли роль гравця на сервері змінюється, приходить подія з новою й старою роллю:

Luau
RoVision.RoleChanged:Connect(function(player, newRole, oldRole)
	print(`{player.Name}: {oldRole or "без ролі"} -> {newRole or "без ролі"}`)
end)

Подія приходить, коли повторна перевірка чи миттєве оновлення показує нову роль. На першу перевірку після входу вона не спрацьовує. nil означає, що гравця немає в команді.

Якщо API недоступний

Ролі працюють за принципом fail closed

Якщо API недоступний, IsModerator і IsAdmin повертають false, GetRole - nil, false, а в Output зʼявляється попередження. Бани - навпаки: через збій модуль нікого не кікає. Краще на кілька хвилин лишити модератора без команд, ніж дати команди будь-кому.

Друге значення GetRole показує, чи відповів API: так можна відрізнити «не в команді» (nil, true) від «не вдалося перевірити» (nil, false).

Білі списки

Білі списки - це списки гравців, які отримують щось особливе у ваших іграх: тестери, VIP, закритий сервер, бета. Ви ведете їх на сайті, а гра питає модуль, чи є гравець у списку з певним ключем.

Де діють списки

Де діють білі списки
СписокДе дієХто ведеКлюч у грі
ГриЛише в цій грі.Власник гри, власник студії, адміністратори й модератори її команди.testers
СтудіїУ всіх іграх, зарахованих до студії.Власник студії, адміністратори й модератори її команди.testers
RoVisionУ всіх партнерських іграх з модулем RoVision.Команда RoVision.rovision:testers

Ключі списків

  • Ключ - від 2 до 32 символів: малі латинські літери, цифри, - і _, починається з літери чи цифри. Наприклад, testers. На сайті він показаний як «Ключ у грі» з кнопкою копіювання.
  • Списки гри та її студії гра питає за простим ключем: "testers". Якщо такий ключ є і в гри, і в студії, гравець проходить, коли він хоча б в одному з цих списків.
  • Мережеві списки RoVision - з префіксом: "rovision:<ключ>". Так вони не плутаються зі списками гри й студії.
  • Великі літери в ключі модуль переводить у малі, пробіли на краях прибирає.
  • Змінити ключ списку потім не можна. Коли список архівують, його ключ звільняється для нового списку.

Керування на сайті

Білі списки живуть у Кабінет, Розробка, «Білі списки» (/account/allowlists). Розділ бачать партнери, а також адміністратори й модератори команд студій. Списки конкретної гри відкриваються й кнопкою «Білі списки цієї гри» в картці «Білі списки» розділу «Інтеграція з грою».

  • Угорі оберіть, «Де діють» списки: гра, студія чи RoVision.
  • «Новий список» - назва для людей («Тестери», «VIP»), ключ для гри й необовʼязковий опис.
  • «Додати гравця» - нік у Roblox або числовий ID, необовʼязкова нотатка й строк (до 3650 днів або без кінця). «Додати кількох» - цілий список ніків одразу, невідомих і тих, хто вже в списку, буде пропущено. Якщо гравець привʼязав Roblox до RoVision, бот повідомить його про це.
  • Запис можна редагувати (нотатка, строк) або «Прибрати зі списку». Записи не видаляються: прибраних і тих, у кого минув строк, видно у фільтрах, а кожна зміна потрапляє в «Історію» списку.
  • «Архівувати» - список перестає діяти в іграх (IsAllowed для його гравців поверне false), але гравці й історія зберігаються. Відновити можна будь-коли.

Перевірка: IsAllowed і GetLists

Luau
local allowed, checked = RoVision:IsAllowed(player, "vip")
if allowed then
	OpenVipRoom(player) -- ваша власна логіка
end

local lists = RoVision:GetLists(player) -- усі ключі гравця, наприклад { "testers", "vip" }
  • Списки гравців модуль запитує під час входу разом з банами й ролями, тож IsAllowed зазвичай відповідає одразу. Для гравця, якого немає на сервері, метод чекає відповіді API. Результат кешується на 5 хвилин.
  • Зміни на сайті доходять за секунди з миттєвим кіком, інакше під час повторної перевірки. Так само модуль помічає записи, у яких минув строк.
  • Друге значення показує, чи відповів API: так можна відрізнити «немає в списку» від «не вдалося перевірити».
  • GetLists повертає всі ключі гравця за абеткою: ключі списків гри й студії без префікса, списків RoVision - з префіксом rovision:.
  • Якщо ключ неправильний, IsAllowed повертає false і один раз пише попередження [RoVision] IsAllowed: "…" isn't a list key….

Подія ListsChanged

Коли списки гравця на сервері змінюються, приходить подія з усіма його ключами. Як і RoleChanged, на першу перевірку після входу вона не спрацьовує.

Luau
RoVision.ListsChanged:Connect(function(player, lists)
	if table.find(lists, "vip") then
		OpenVipRoom(player)
	end
end)

Зміни з гри: Allow і Disallow

Luau
-- Додати на 14 днів з приміткою
local ok, entry = RoVision:Allow(player, "testers", { DurationDays = 14, Note = "Хвиля 2" })

-- Прибрати
local ok, removed = RoVision:Disallow(userId, "testers")
  • З гри можна змінювати лише списки самої гри, не студії й не RoVision. Список треба спершу створити на сайті, інакше повернеться помилка allowlist_not_found. Для ключа з префіксом rovision: модуль одразу повертає помилку, не звертаючись до API.
  • Якщо гравець уже в списку, Allow повертає його поточний запис. Disallow повертає кількість прибраних записів.
  • Зміна за кілька секунд доходить до всіх серверів гри.
  • Модуль не перевіряє, хто викликає Allow і Disallow: перевірка прав - на вашому боці, наприклад через IsModerator.

Закритий тест: RequireAllowed

Один виклик після Init - і в гру заходять лише гравці зі списку:

ServerScriptService › RoVisionSetup (Script)
local RoVision = require(game.ServerScriptService.RoVision)

RoVision:Init()

-- Грати можуть лише тестери, а також власник, адміністратори й модератори команди
RoVision:RequireAllowed("testers", {
	KickMessage = "Зараз іде закритий тест. Новини про відкриття - у нашій групі Roblox.",
})
  • Гравців, яких немає в списку, модуль кікає під час входу, а також коли їх прибирають зі списку (за секунди з миттєвим кіком, інакше під час повторної перевірки) чи закінчується строк запису (під час повторної перевірки).
  • З AllowOwnersAndTeam = true (так і за замовчуванням) власник, адміністратори й модератори команди проходять без запису в списку. Учасники (member) - ні. Як і для IsModerator, роль діє лише з Roblox-акаунтом, підключеним до RoVision: інакше додайте себе в список, щоб гра не кікнула вас самих.
  • Стандартний текст кіку: «Зараз у цю гру можуть зайти лише гравці зі списку доступу. Вас у ньому немає.» Свій текст задайте через KickMessage, без посилань.
  • Перевірте ключ: якщо списку з таким ключем немає, у ньому нікого немає, і в гру зайдуть лише власник і команда.
  • Тестові гравці Studio (з відʼємним UserId) проходять завжди.
  • Викликайте RequireAllowed після Init. Повторний виклик замінює список і перевіряє всіх на сервері знову. Неправильний ключ чи параметри зупиняють скрипт з помилкою.

Збій не кікає гравців

Якщо API недоступний, RequireAllowed нікого не кікає: гравець лишається в грі, а модуль перевіряє його ще раз через 5, 15 і 45 секунд і далі під час повторної перевірки. Кік - лише тоді, коли точно відомо, що гравця немає в списку.

Якщо API недоступний

Білі списки працюють за принципом fail closed

Якщо API недоступний, IsAllowed повертає false, false, а GetLists - порожній список і false. Краще тимчасово не дати VIP-кімнату, ніж дати її будь-кому. Виняток - RequireAllowed: він не кікає, поки не знає відповіді.

Довідка API

Усе, що модуль дає вашим скриптам: методи, параметри, значення, що повертаються, події й типи. Методи викликаються через двокрапку: RoVision:Ban(…), події - через крапку: RoVision.PlayerBanned.

Усі методи

Усі методи модуля
МетодЩо робитьЧекає відповідіЯкщо API недоступний
InitЗапускає модульніНе залежить: перевірки йдуть у фоні
CheckBanАктивний бан гравцятакnil, false
BanБан рівня гритакfalse, текст помилки
UnbanЗнімає бани рівня гритакfalse, текст помилки
ReportСкарга модераторам RoVisionніКілька спроб у фоні, потім відкидає
GetRoleРоль у командітак*nil, false
IsModeratorВласник, адмін чи модератортак*false
IsAdminВласник чи адмінтак*false
IsAllowedЧи є гравець у спискутак*false, false
GetListsУсі списки гравцятак*{}, false
AllowДодає в список гритакfalse, текст помилки
DisallowПрибирає зі списку гритакfalse, текст помилки
RequireAllowedЗакритий тестніНікого не кікає, перевіряє знову

* Для гравців на сервері роль і списки модуль завантажує під час входу, тож відповідь зазвичай приходить одразу. «Чекає відповіді» (yield) означає, що виклик зупиняє ваш потік до відповіді API, до секунди довше через пачки запитів.

Методи, що приймають гравця, приймають і його Roblox UserId - ціле число. Для тестових гравців Studio (з відʼємним UserId) перевірки відповідають одразу й без запиту: бану, ролі й списків немає. Ban, Unban, Allow, Disallow і Report для них не працюють. Методи, викликані до Init, пишуть попередження й повертають «порожню» відповідь, а RequireAllowed зупиняє скрипт з помилкою.

RoVision:Init

RoVision:Init(options: InitOptions?)

Запускає модуль. Викликайте один раз на сервер, із серверного Script, до інших методів. Не чекає відповіді API: перевірки йдуть у фоні.

Параметри Init
ПараметрТипЗа замовчуваннямОпис
ApiKeySecret або stringсекрет rovisionКлюч з кабінету. Рядок підходить лише для тестів у Studio: на живому сервері модуль про це попереджає. Порожній рядок - те саме, що ключа немає.
BaseUrlstringhttps://api.rovision.ggАдреса API, починається з https://. Змінювати не потрібно.
DebugbooleanfalseПисати в Output усі запити, відповіді й службові повідомлення.
Bans.EnforcebooleantrueКікати гравців з активним баном. З false модуль лише запускає PlayerBanned.
Bans.KickMessagestring або function(ban): string?текст українськоюТекст під час кіку за баном. Функція може повернути nil, щоб лишити стандартний текст. Детальніше.
Bans.RecheckIntervalnumber300Як часто, у секундах, повторно перевіряти всіх гравців на сервері (бани, ролі й білі списки). Менше 60 модуль піднімає до 60 з попередженням.
Bans.LivebooleantrueМиттєвий кік: зміни банів, команди й білих списків доходять на всі сервери гри за секунди через MessagingService. З false - лише під час повторної перевірки.
Чекає відповіді
Ні
Повторний виклик
Ігнорується з попередженням.
Помилки
Неправильні типи параметрів зупиняють скрипт з помилкою, наприклад [RoVision] Init: Bans.Enforce must be a boolean, got string. Невідомі параметри модуль ігнорує з попередженням.
Без ключа
Модуль лише попереджає: бани не перевіряються (гравців пускають), IsModerator, IsAdmin і IsAllowed повертають false, а миттєвий кік не вмикається.

RoVision.Version

RoVision.Version: string

Версія модуля, зараз 1.0.0. У файлі з релізу вона збігається з тегом релізу. Модуль також надсилає її в API з кожним запитом. Зручно для логів і звернень у підтримку:

Luau
print("RoVision", RoVision.Version) --> RoVision 1.0.0

RoVision:CheckBan

RoVision:CheckBan(playerOrUserId: Player | number): (Ban?, boolean)

Повертає активний бан, який діє у вашій грі, або nil.

Параметри
playerOrUserId - гравець (Player) або його Roblox UserId (ціле число).
Повертає
Ban або nil; друге значення - чи відповів API.
Чекає відповіді
Так (yield). Результат кешується на 5 хвилин або доки не прийде повідомлення про зміну бану
Якщо API недоступний
nil, false: це не означає «не заблокований».

RoVision:Ban

RoVision:Ban(playerOrUserId: Player | number, options: BanOptions): (boolean, Ban | string)

Банить гравця у вашій грі (бан рівня гри). Якщо в гравця вже є бан рівня гри, новий його замінює. Гравця на цьому сервері модуль кікає одразу (з Enforce = true) і запускає PlayerBanned, інші сервери гри дізнаються про бан за кілька секунд (Bans.Live).

Параметри Ban
ПараметрТипЗа замовчуваннямОпис
ReasonstringобовʼязковийПричина, 1-500 символів. Її побачить гравець.
DurationDaysnumber?nilСкільки днів, ціле число від 1 до 3650. nil - назавжди.
Categorystring?"other""exploiting", "scamming", "botting" або "other".
Повертає
true і Ban або false і текст помилки.
Чекає відповіді
Так (yield). Збій мережі модуль повторює, до 3 спроб
Обмеження
Лише справжні гравці: UserId більше 0. Модуль не перевіряє, хто викликає метод, тож права перевіряйте самі (IsModerator).

RoVision:Unban

RoVision:Unban(playerOrUserId: Player | number): (boolean, number | string)

Знімає бани рівня гри для вашої гри. Бани студії та мережеві бани RoVision лишаються. Інші сервери гри дізнаються про це за кілька секунд (Bans.Live).

Параметри
playerOrUserId - гравець (Player) або його Roblox UserId (ціле число).
Повертає
true і кількість знятих банів або false і текст помилки.
Чекає відповіді
Так (yield). До 3 спроб при збоях

RoVision:Report

RoVision:Report(playerOrUserId: Player | number, report: ReportOptions): boolean

Ставить скаргу модераторам RoVision у чергу. Скарга нікого не банить: її розглядає модератор. Як і коли надсилати.

Поля Report
ПолеТипОпис
Categorystring"exploiting", "scamming" або "botting".
DescriptionstringЩо сталося, 1-1000 символів. Довший текст модуль обрізає.
Detectiontable?Дані детекту для модератора: числа, рядки, булеві значення, до 8 КБ у JSON. Масив модуль загортає в { items = … }, завеликі дані замінює позначкою truncated.
Повертає
true, якщо скаргу поставлено в чергу; false, якщо модуль відхилив її ще до відправки: неправильна категорія, порожній опис, переповнена черга (100 скарг), тестовий гравець Studio. Причина зʼявиться в Output.
Чекає відповіді
Ні: скарга надсилається у фоні, до 4 спроб, а потім відкидається з попередженням.
Закриття сервера
Скарги, що лишились у черзі, модуль дописує через BindToClose (до 10 секунд).

RoVision:GetRole

RoVision:GetRole(playerOrUserId: Player | number): (Role?, boolean)

Повертає роль гравця в команді гри: "owner", "admin", "moderator", "member" або nil (не в команді чи Roblox-акаунт не привʼязаний до RoVision). Що означає кожна роль.

Параметри
playerOrUserId - гравець (Player) або його Roblox UserId (ціле число).
Повертає
Роль або nil; друге значення - чи відповів API.
Чекає відповіді
Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
Кеш
5 хвилин або доки не прийде повідомлення про зміну команди.
Якщо API недоступний
nil, false (fail closed).

RoVision:IsModerator

RoVision:IsModerator(playerOrUserId: Player | number): boolean

true для власника, адміністратора або модератора команди. Зручно для адмін-команд і модераторських інструментів у грі.

Чекає відповіді
Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
Якщо API недоступний
false і попередження [RoVision] IsModerator: the role of … is unknown… (fail closed).

RoVision:IsAdmin

RoVision:IsAdmin(playerOrUserId: Player | number): boolean

true для власника або адміністратора команди.

Чекає відповіді
Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
Якщо API недоступний
false і попередження (fail closed).

RoVision:IsAllowed

RoVision:IsAllowed(playerOrUserId: Player | number, key: string): (boolean, boolean)

Чи є гравець у списку key: у списку гри чи її студії, або в мережевому списку для "rovision:<ключ>". Правила ключів.

Повертає
Чи є гравець у списку; друге значення - чи відповів API. Для неправильного ключа - false, true і попередження.
Чекає відповіді
Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
Кеш
5 хвилин або доки не прийде повідомлення про зміну списків.
Якщо API недоступний
false, false (fail closed).

RoVision:GetLists

RoVision:GetLists(playerOrUserId: Player | number): ({ string }, boolean)

Усі ключі списків гравця за абеткою, наприклад { "testers", "vip" }. Мережеві списки - з префіксом rovision:. Таблицю можна змінювати: це копія.

Чекає відповіді
Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
Якщо API недоступний
Порожній список і false.

RoVision:Allow

RoVision:Allow(playerOrUserId: Player | number, key: string, options: AllowOptions?): (boolean, AllowlistEntry | string)

Додає гравця до списку самої гри (не студії й не RoVision). Список має бути створений на сайті. Якщо гравець уже в списку, повертає його поточний запис. Інші сервери гри дізнаються про це за кілька секунд (Bans.Live).

Параметри Allow
ПараметрТипЗа замовчуваннямОпис
DurationDaysnumber?nilСкільки днів, ціле число від 1 до 3650. nil - без кінця.
Notestring?nilПримітка для тих, хто веде список, до 500 символів.
Повертає
true і AllowlistEntry або false і текст помилки, наприклад allowlist_not_found: ….
Чекає відповіді
Так (yield). До 3 спроб при збоях
Обмеження
Лише справжні гравці (UserId більше 0) і лише списки самої гри. Права викликача перевіряйте самі.

RoVision:Disallow

RoVision:Disallow(playerOrUserId: Player | number, key: string): (boolean, number | string)

Прибирає гравця зі списку самої гри. Якщо гравець є в списку студії з тим самим ключем, IsAllowed і далі поверне true.

Повертає
true і кількість прибраних записів або false і текст помилки.
Чекає відповіді
Так (yield). До 3 спроб при збоях

RoVision:RequireAllowed

RoVision:RequireAllowed(key: string, options: RequireAllowedOptions?)

Пускає в гру лише гравців зі списку key (закритий тест). Викликайте після Init. Повторний виклик замінює список.

Параметри RequireAllowed
ПараметрТипЗа замовчуваннямОпис
KickMessagestring?текст українськоюТекст під час кіку, непорожній і без посилань.
AllowOwnersAndTeamboolean?trueПускати власника, адміністраторів і модераторів команди без запису в списку.
Чекає відповіді
Ні
Помилки
Виклик до Init, неправильний ключ чи параметри зупиняють скрипт з помилкою.
Якщо API недоступний
Нікого не кікає: перевіряє гравців знову через 5, 15 і 45 секунд і під час повторної перевірки.

Події

Події модуля
ПодіяАргументиКоли приходить
PlayerBanned(player: Player, ban: Ban)Гравець на сервері має активний бан: під час входу, повторної перевірки, після Ban на цьому сервері чи миттєвого оновлення. Перед кіком. Для одного бану - раз за сесію.
RoleChanged(player: Player, newRole: Role?, oldRole: Role?)Роль гравця на сервері змінилася. nil - гравця немає в команді. Не приходить на першу перевірку після входу.
ListsChanged(player: Player, lists: { string })Змінилися білі списки гравця на сервері; lists - усі його ключі. Не приходить на першу перевірку після входу.

Кожна подія має методи Connect, Once і Wait. Connect і Once повертають зʼєднання з полем Connected і методом Disconnect.

Luau
local connection = RoVision.PlayerBanned:Connect(function(player, ban)
	print(player.Name, ban.Id)
end)

connection:Disconnect() -- більше не слухати

local player, ban = RoVision.PlayerBanned:Wait() -- чекати наступного разу
  • Кожен обробник виконується у власному потоці: помилка чи очікування у вашому обробнику не зачіпає модуль та інші обробники.
  • Службові методи Fire і DisconnectAll не призначені для ваших скриптів: Fire запустить подію для всіх підписників, а DisconnectAll відключить і чужі обробники.

Типи

Типи, які модуль використовує й експортує для типізованих скриптів:

Типи RoVision
type BanScope = "rovision" | "studio" | "game"
type BanCategory = "exploiting" | "scamming" | "botting" | "other"
type ReportCategory = "exploiting" | "scamming" | "botting" -- для Report

type Ban = {
	Id: string,
	Scope: BanScope, -- рівень бану
	Category: BanCategory,
	Reason: string, -- публічна причина
	ExpiresAt: string?, -- дата закінчення в ISO 8601 (UTC); nil - назавжди
}

type Role = "owner" | "admin" | "moderator" | "member"

type AllowlistEntry = {
	Id: string,
	Key: string, -- ключ списку
	UserId: number,
	Username: string?, -- нік у Roblox
	Note: string?,
	ExpiresAt: string?, -- дата закінчення в ISO 8601 (UTC); nil - без кінця
}

type BanOptions = {
	Reason: string,
	DurationDays: number?, -- nil - назавжди
	Category: BanCategory?, -- nil - "other"
}

type AllowOptions = {
	DurationDays: number?, -- nil - без кінця
	Note: string?,
}

type ReportOptions = {
	Category: ReportCategory,
	Description: string,
	Detection: { [any]: any }?,
}

type RequireAllowedOptions = {
	KickMessage: string?,
	AllowOwnersAndTeam: boolean?, -- за замовчуванням true
}

type InitOptions = {
	ApiKey: (Secret | string)?,
	BaseUrl: string?,
	Debug: boolean?,
	Bans: BansOptions?,
}

type BansOptions = {
	Enforce: boolean?,
	KickMessage: (string | (ban: Ban) -> string?)?,
	RecheckInterval: number?,
	Live: boolean?,
}

type Connection = {
	Connected: boolean,
	Disconnect: (self: Connection) -> (),
}

Модуль експортує Ban, BanScope, BanCategory, ReportCategory, Role, AllowlistEntry, BanOptions, AllowOptions, ReportOptions, RequireAllowedOptions, InitOptions, BansOptions, Connection і Signal:

Luau
local RoVision = require(game.ServerScriptService.RoVision)

type Ban = RoVision.Ban

local function describe(ban: Ban): string
	return `{ban.Scope}: {ban.Reason}`
end

Нові значення

Якщо API колись поверне новий рівень бану, категорію чи роль, модуль передасть їх як є, рядком. Пишіть перевірки з гілкою else. Невідомі ролі не дають прав: IsModerator і IsAdmin для них повертають false.

Тексти помилок

Ban, Unban, Allow і Disallow повертають false і текст помилки англійською. Його зручно показати адміну чи записати в лог.

Тексти помилок
ТекстЩо сталося
RoVision:Init was not calledМетод викликано до Init.
expected a Player or a positive UserIdПередано не гравця й не ціле число, або UserId 0 чи відʼємний (тестовий гравець Studio).
options must be a table …Параметри Ban чи Allow - не таблиця.
Reason must be text of 1-500 charactersBan: порожня чи задовга причина.
DurationDays must be a whole number from 1 to 3650, …Ban чи Allow: строк не є цілим числом від 1 до 3650.
Category must be one of: exploiting, scamming, botting, otherBan: невідома категорія.
Note must be text of up to 500 charactersAllow: задовга примітка.
"…" isn't a list keyAllow чи Disallow: неправильний ключ списку.
RoVision-wide lists can't be changed from a gameAllow чи Disallow з ключем rovision:…: мережеві списки з гри не змінюються.
<код>: <опис>Помилка від API RoVision, наприклад allowlist_not_found: … - у гри немає списку з таким ключем.
no API key (see the warning printed at Init)Немає ключа: секрет не прочитався або ApiKey порожній.
requests are paused after an earlier errorПісля недійсного ключа, втрати статусу партнера чи помилки секрету модуль на 10 хвилин припинив запити (після вимкнених HTTP-запитів - на хвилину).
no response in 15 sAPI не відповів за 15 секунд, навіть після повторів.
HTTP 503API відповів помилкою без пояснення (код може бути іншим).
unexpected response from the APIВідповідь API не вдалося розібрати.

Попередження в Output

Усе, що модуль пише в Output, має префікс [RoVision]. Однакові попередження він повторює не частіше ніж раз на хвилину чи кілька хвилин, щоб не засмічувати Output; з Debug = true видно всі. Що робити з кожним - у розділі «Вирішення проблем».

Порада: перед викликами, які змінюють дані, перевіряйте права через IsModerator чи IsAdmin, а результат ok, result показуйте адміну, щоб він бачив, чому дія не вдалася.

Як працює модуль

Модуль розрахований на живі сервери з десятками гравців і на збої з будь-якого боку. Ось що відбувається всередині, щоб ви знали, чого очікувати від Output і лімітів Roblox.

Пачки запитів

  • Гравці, які зайшли протягом секунди, перевіряються разом: один запит на кожну перевірку (бани, ролі, білі списки), до 100 гравців у запиті. Отже гравець, що зайшов, коштує один запит на кожну перевірку, а сотня гравців, що зайшли за ту саму секунду, - стільки ж.
  • Ручні виклики (CheckBan, GetRole, IsAllowed для гравця не з кешу) потрапляють у ту саму пачку, тому чекають до секунди довше.
  • Перевірка банів іде першою в пачці.

Кеш і попереднє завантаження

  • Відповіді (бан, роль, списки гравця) зберігаються 5 хвилин.
  • Під час входу модуль одразу запитує всі три відповіді, тому IsModerator і IsAllowed для гравців на сервері зазвичай відповідають з кешу, без очікування.
  • Повідомлення про зміну (миттєвий кік) одразу скидає кеш для згаданих гравців. Власні Ban, Unban, Allow і Disallow оновлюють або скидають кеш на цьому сервері одразу.
  • Бан, строк якого вже минув, модуль не застосовує, навіть якщо він ще в кеші.
  • Тестові гравці Studio (з відʼємним UserId) не потрапляють у запити: бану, ролі й списків у них немає.

Повторні перевірки

Раз на Bans.RecheckInterval секунд (300 за замовчуванням, мінімум 60) модуль перевіряє всіх гравців на сервері: бани, ролі й білі списки. Інтервал щоразу трохи змінюється (до 10% в обидва боки), щоб сервери, запущені разом, не зверталися до API одночасно. Відповіді, отримані за останні 10 секунд, повторно не запитуються. Саме під час повторної перевірки спрацьовують RoleChanged і ListsChanged, а RequireAllowed помічає записи з минулим строком.

Миттєві оновлення

  • Модуль підписується на тему RoVision у MessagingService. Повідомлення містить лише тип зміни й Roblox ID гравців, тому відповідь модуль завжди бере з API.
  • Повідомлення, що приходять протягом пів секунди, обʼєднуються: модуль перевіряє всіх згаданих гравців на сервері одним запитом на кожну перевірку, в обхід кешу, не частіше ніж раз на 2 секунди.
  • Гравців, яких немає на цьому сервері, модуль не перевіряє, а лише забуває їхні відповіді в кеші.
  • Якщо підписка не вдалася, модуль пробує знову з паузою, що зростає від 5 секунд до 5 хвилин.

Повтори й паузи

  • Мережеві помилки, відповіді 5xx і 429 модуль повторює з паузою, що зростає (приблизно 1, 2 і 4 секунди), з невеликим випадковим розкидом. Перевірки й скарги - до 4 спроб, Ban, Unban, Allow і Disallow - до 3. Інші помилки 4xx не повторюються: запит неправильний, повтор не допоможе.
  • Кожна спроба чекає відповіді до 15 секунд.
  • Відповідь 429 (забагато запитів) призупиняє всі запити модуля на час із заголовка Retry-After (до 60 секунд).
  • Недійсний ключ (401) чи власник гри більше не партнер (403 partner_required): модуль на 10 хвилин припиняє запити, щоб не засипати Output і API. Так само після помилки секрету (інший домен). Після вимкнених HTTP-запитів - на хвилину.
  • Якщо сервер вичерпав ліміт HttpService від Roblox (спільний з іншими скриптами гри), модуль відкладає свої запити на 15 секунд.

Ліміт запитів

Roblox обмежує HTTP-запити з одного сервера: близько 500 за хвилину на всі скрипти гри разом. Модуль бере щонайбільше 120 за хвилину (до 20 одразу), а решта лишається вашим скриптам. Завдяки пачкам звичайній грі цього бюджету вистачає з великим запасом. Якщо бачите [RoVision] RoVision API rate limit reached (429)…, перевірте, чи CheckBan, Ban або Report не викликаються в циклі.

Закриття сервера

Модуль підписується на game:BindToClose: коли сервер закривається, він відписується від MessagingService і дописує скарги, що лишились у черзі, паралельно й без пауз, до 10 секунд із 30, які Roblox дає на закриття. Якщо щось не встигло, модуль напише в попередженні, скільки скарг не надіслано.

Fail open і fail closed

Модуль поводиться по-різному залежно від того, що поставлено на кону:

Що робить модуль, коли API RoVision недоступний
ЩоПринципПоведінка під час збою
Баниfail openНікого не кікає за баном, гравці заходять як звичайно. CheckBan повертає nil, false.
Роліfail closedIsModerator і IsAdmin повертають false, GetRole - nil, false.
Білі спискиfail closedIsAllowed повертає false, false, GetLists - порожній список і false.
Закритий тестне кікаєRequireAllowed лишає гравців у грі й перевіряє їх знову через 5, 15 і 45 секунд, далі - під час повторної перевірки.
Зміни з грипомилкаBan, Unban, Allow і Disallow повертають false і текст помилки.
СкаргиповториМодуль надсилає скаргу повторно кілька разів, а потім відкидає її з попередженням.
Миттєвий кікfail openБез MessagingService зміни доходять до інших серверів під час повторної перевірки.

Чому так

Помилково кікнути гравця через збій гірше, ніж на кілька хвилин пропустити заблокованого. З правами навпаки: краще тимчасово не дати модераторську команду чи VIP-кімнату, ніж дати її будь-кому. Під час наступної перевірки модуль спробує знову, і все запрацює саме.

Запити в Output

З Debug = true модуль пише в Output кожен запит (->) і відповідь (<-) з кодом і часом. Ось які запити ви побачите:

Запити модуля до API RoVision
ЩоЗапит
Перевірка банівPOST /game-api/v1/bans/check
Перевірка ролейPOST /game-api/v1/team/check
Перевірка білих списківPOST /game-api/v1/allowlists/check
BanPOST /game-api/v1/bans
UnbanDELETE /game-api/v1/bans/<UserId>
ReportPOST /game-api/v1/reports
AllowPOST /game-api/v1/allowlists/<ключ>/entries
DisallowDELETE /game-api/v1/allowlists/<ключ>/entries/<UserId>

Це внутрішні запити модуля, їх перелік - щоб читати Output. У своєму коді викликайте методи модуля: він сам подбає про пачки, кеш, повтори й ліміти.

Безпека й приватність

Модуль працює лише на сервері гри, нічого не продає й не торкається Robux. Ось які дані він передає, як захищені ключі й хто що бачить на сайті.

Які дані отримує RoVision

  • Roblox ID гравців на сервері - для перевірки банів, ролей і білих списків. Ніків, чату, IP чи інших даних модуль сам не надсилає.
  • Те, що ви надсилаєте самі: бани з гри (Ban), записи білих списків (Allow), скарги (Report), а разом зі скаргою - JobId сервера.
  • Версію модуля - у заголовку кожного запиту.
  • Через MessagingService сервери вашої гри отримують лише Roblox ID гравців, чиї бани, ролі чи списки змінились.

Без персональних даних

Не пишіть у Reason, Description, Detection чи Note персональні дані (справжні імена, контакти, IP) чи повідомлення з чату.

Ключі

  • API-ключ гри - лише в Secrets гри з доменом api.rovision.gg: так його немає в коді місця, і Roblox надсилає його лише в API RoVision. Повністю ключ показується один раз. Один ключ - одна гра, до 5 активних ключів на гру.
  • Ключ потрапив у чужі руки - відкличте його в «Інтеграція з грою» і створіть новий. Сервери зі старим ключем одразу втратять доступ.
  • Ключ Open Cloud потребує лише дозволу Messaging Service API → Publish для вашої гри. RoVision зберігає його зашифрованим, повністю більше ніде не показує й використовує лише для повідомлень у тему RoVision вашої гри.

Лише сервер

  • Модуль зупиняється з помилкою, якщо його підключити з клієнта, тож випадково віддати його клієнту не вийде. Тримайте його в ServerScriptService.
  • Ban, Unban, Allow і Disallow не перевіряють, хто їх викликає. Якщо даєте до них доступ через RemoteEvent, перевіряйте права на сервері через IsModerator чи IsAdmin і не довіряйте даним від клієнта.
  • Права з команди працюють за принципом fail closed: збій RoVision не дасть модераторських прав випадковому гравцю.

Хто що бачить

  • Активні мережеві бани RoVision бачать усі партнери й модератори: Roblox ID, нік, категорію, публічну причину й дати.
  • Бани студії та гри бачать лише ті, хто ними керує (власник і команда студії), і модератори RoVision.
  • Докази, дані детекту й внутрішні нотатки бачать лише ті, хто керує відповідним рівнем (для мережевих банів - модератори RoVision).
  • Гравець бачить усі свої бани в Кабінет → Блокування разом з рівнем (RoVision, назва студії чи гри) і причиною.
  • Нотатки до записів білих списків бачать лише ті, хто керує списком.

Вирішення проблем

Знайдіть повідомлення з Output (усі вони починаються з [RoVision]) або симптом. Щоб бачити всі запити й відповіді, тимчасово ввімкніть Debug = true.

Повідомлення й симптоми
Повідомлення в Output чи симптомЩо робити
[RoVision] HTTP requests are disabled…Увімкніть HTTP-запити (крок 2).
[RoVision] No API key: the secret "rovision" can't be read…Секрет не додано (крок 3) або він має іншу назву. У Studio його треба додати окремо.
Can't find secret with given keyВи самі викликаєте HttpService:GetSecret, а секрету немає. Додайте його (крок 3) або приберіть ApiKey з Init: модуль прочитає секрет сам.
[RoVision] Invalid API key (401 invalid_api_key)…Ключ відкликано або скопійовано з помилкою. Створіть новий ключ і оновіть секрет rovision. Модуль на 10 хвилин припиняє запити й пускає всіх гравців.
[RoVision] The API key secret can't be used for…У секрету інший домен. Вкажіть api.rovision.gg.
[RoVision] The owner of this game is no longer a RoVision partner…Власник гри більше не партнер RoVision. Напишіть нам.
[RoVision] RoVision API rate limit reached (429)…Забагато запитів з цим ключем. Перевірте, чи CheckBan, Ban або Report не викликаються в циклі.
[RoVision] The server reached Roblox's HttpService request limit…Ліміт HTTP-запитів сервера вичерпали скрипти гри разом. Модуль відкладає свої запити; перевірте, хто ще шле запити в циклі.
[RoVision] Ban check failed…API тимчасово недоступний, тому модуль пускає всіх. Минає само; якщо триває довго - напишіть нам.
[RoVision] Report queue is full…Античит надсилає забагато скарг. Надсилайте лише впевнені детекти.
[RoVision] Live updates: can't subscribe to MessagingService…Модуль пробує знову сам, а зміни тим часом доходять під час повторної перевірки. У Studio це нормально, якщо гру не опубліковано або не ввімкнено Game Settings, Security, Enable Studio Access to API Services. На живому сервері це тимчасовий збій Roblox.
[RoVision] Live updates: couldn't tell other servers…Зміну збережено, але повідомлення іншим серверам не надіслано (збій чи ліміт MessagingService, Studio без доступу до API). Інші сервери побачать її під час повторної перевірки.
Зміни з сайту (бан, команда, білий список) доходять до гравців у грі лише за кілька хвилинНе додано ключ Open Cloud або він перестав працювати. Перегляньте статус і останню помилку в «Інтеграція з грою», «Миттєвий кік на всіх серверах» (інструкція) і перевірте, що Bans.Live не вимкнено.
Кабінет не приймає ключ Open CloudКлючу бракує дозволу Messaging Service API → Publish для цієї гри, в Accepted IP Addresses немає 0.0.0.0/0, ключ прострочений або скопійований не повністю. Відповідь Roblox - у тексті помилки.
[RoVision] Role check failed…, [RoVision] IsModerator: the role of … is unknown…API тимчасово недоступний. Поки він не відповідає, IsModerator і IsAdmin повертають false, тож адмін-команди не працюють. Минає само; якщо триває довго - напишіть нам.
IsModerator повертає false для власника чи модератораЛюдина не підключила Roblox-акаунт до RoVision, не прийняла запрошення в команду (Кабінет, Розробка, «Команди студій»), має роль member, або гра не зарахована до студії. Якщо в Output є попередження про недоступний API - див. рядок вище.
[RoVision] Whitelist check failed…API тимчасово недоступний: IsAllowed повертає false, а RequireAllowed лишає гравців у грі й перевіряє їх знову.
[RoVision] RequireAllowed: can't tell whether…Модуль кілька разів не зміг перевірити гравця, тому лишив його в грі. Він спробує знову під час повторної перевірки.
[RoVision] IsAllowed: "…" isn't a list key…Ключ - від 2 до 32 малих латинських літер, цифр, - і _, починається з літери чи цифри; для списків RoVision - rovision:<ключ>. Скопіюйте «Ключ у грі» з розділу «Білі списки» на сайті.
allowlist_not_found у результаті Allow чи DisallowУ гри немає списку з таким ключем. Створіть його на сайті. З гри можна змінювати лише списки самої гри, не студії й не RoVision.
RequireAllowed не пускає нікого, крім власника й командиПеревірте ключ: якщо списку з таким ключем немає, у ньому нікого немає. Для мережевих списків RoVision потрібен префікс rovision:.
[RoVision] RoVision runs only on the server…Модуль лежить у ReplicatedStorage або його викликає LocalScript. Перенесіть його в ServerScriptService.
[RoVision] Init was already called; this call is ignored.Init викликається з кількох скриптів. Залиште один виклик на сервер.
Заблокованого гравця не кікнулоПеревірте Bans.Enforce, перемикач «Застосовувати бан-лист RoVision» (для мережевих банів) і чи гра зарахована до студії (для банів студії). Увімкніть Debug.

Немає потрібної відповіді - напишіть нам: rovision.gg/contact або @RoVisionBot у Telegram. Додайте версію модуля (RoVision.Version) і текст із Output.

Незабаром

Цього в модулі ще немає

Бан-лист, миттєвий кік, ролі команди й білі списки вже працюють. Можливостей нижче ще немає: API RoVision поки їх не підтримує, а інтерфейс може змінитися до релізу. Не викликайте ці методи в коді гри.

Гравці RoVision: GetPlayer

Чи привʼязаний Roblox-акаунт гравця до RoVision, його нік, рівень, бейджі, чи акаунт підтверджений. RoVision:GetPlayer(player) повертатиме профіль гравця на RoVision. Метод чекатиме відповіді API, тому його не варто викликати в гарячих циклах, а результат кешуватиметься на кілька хвилин.

Luau
Ще не працює
Players.PlayerAdded:Connect(function(player)
	local profile = RoVision:GetPlayer(player)
	if profile.IsLinked then
		print(`{player.Name} - гравець RoVision {profile.Username}, рівень {profile.Level}`)
	end
end)
Тип Profile
Ще не працює
type Profile = {
	IsLinked: boolean, -- false, якщо акаунт не прив'язаний або API недоступний
	Username: string?, -- нік на RoVision
	Level: number?,
	Xp: number?,
	IsVerified: boolean?, -- акаунт підтверджено через Telegram і Discord
	IsPartner: boolean?,
	Badges: { string }?,
}

Так можна буде, наприклад, показати тег над головою гравця RoVision або дати бонус учасникам спільноти з підтвердженим акаунтом.

Досвід за досягнення: Award

Ви описуватимете досягнення в кабінеті RoVision, а в грі зараховуватимете його одним викликом. Досвід іде в рівень гравця на RoVision.

  1. У розділі «Інтеграція з грою» додаєте досягнення: ID (наприклад, finish_tutorial), назву, яку побачить гравець, досвід і як часто його можна отримати: один раз, раз на день або без обмежень (у межах денного ліміту).
  2. У грі викликаєте Award, коли гравець його досягнув.
Luau
Ще не працює
-- Гравець пройшов навчання
RoVision:Award(player, "finish_tutorial")

-- Щоденне досягнення з частотою «раз на день»
Players.PlayerAdded:Connect(function(player)
	RoVision:Award(player, "daily_login")
end)
  • Досвід отримуватимуть лише гравці з привʼязаним і підтвердженим акаунтом RoVision. Для решти виклик просто нічого не робитиме.
  • Award не чекатиме відповіді: події збиратимуться в пачки й надсилатимуться у фоні. Повтор понад ліміт досягнення RoVision не зарахує, а кожна подія матиме свій ID, тож повтори при збоях не зарахують її двічі.
  • RoVision:Flush() негайно надсилатиме накопичені події. Зазвичай він не знадобиться: модуль робитиме це сам кожні кілька секунд і під час закриття сервера.

Правила досвіду:

  • Досвід - за справжні досягнення: пройдений рівень, виконаний квест, серія днів. Не нараховуйте його за час AFK.
  • Не обіцяйте досвід RoVision за лайки, «Улюблене», підписки чи відгуки. Правила Roblox забороняють заохочувати такі дії.
  • Досвід RoVision не має грошової цінності: його не можна обміняти на Robux чи гроші.
  • Ліміти й блокування. RoVision обмежуватиме, скільки досвіду гра може видати за день. Ключі ігор, які порушують ці правила, можуть бути відкликані.

Сесії

Модуль сам фіксуватиме вхід і вихід гравців. З цього будуватимуться квести на кшталт «грав 3 дні поспіль» і статистика у вашому кабінеті. Вимкнути це можна буде параметром TrackSessions = false в Init.

Що буде далі

  • Нагороди за коїни RoVision. Гравці обмінюють коїни на нагороди у вашій грі, а модуль доставляє їх у гру.
  • Новини в грі. Новини, які ви пишете на RoVision, зʼявляються на дошці оголошень у грі.
  • Статистика. Гравці з RoVision, сесії й досягнення - у вашому кабінеті.

Дат немає, порядок може змінитися.