RoVision Game API - це модуль на Luau, який підключає вашу Roblox-гру до RoVision. Ви кладете його в ServerScriptService, викликаєте RoVision:Init(), і сервер гри починає перевіряти гравців через API RoVision: бани, роль у команді вашої студії та білі списки.
- Бан-листКікає гравців з активним баном для вашої гри: у мережі RoVision, у вашій студії або в самій грі. Перевіряє під час входу й повторно, поки гравець грає.
- Бани й скарги з гри
BanіUnbanдля адмін-команд,Reportдля скарг модераторам RoVision з вашого античиту. - Миттєвий кікБани, зміни команди й білих списків доходять на всі сервери гри за секунди, а не під час наступної перевірки.
- Команда й ролі
IsModeratorіIsAdminзнають команду студії з сайту: адмін-командам не потрібен список Roblox ID у коді. - Білі спискиТестери, VIP, закриті сервери: перевірка
IsAllowedі закритий тест одним викликомRequireAllowed. - Безпечно за замовчуваннямЛише сервер, ключ лише в Secrets. Збій RoVision не кікає гравців і не роздає прав модератора.
Модуль нічого не продає, не торкається Robux і передає RoVision тільки Roblox ID гравців та дані банів, записів білих списків і скарг, які ви надсилаєте самі.
- Ви партнер RoVision, і гру додано в кабінеті: Кабінет, Мої ігри. Ще не партнер - подайте заявку.
- У грі ввімкнено HTTP-запити: Game Settings, Security, Allow HTTP Requests.
- API-ключ гри збережено в Secrets гри, а не в коді.
- Модуль лежить у ServerScriptService і викликається тільки з серверних скриптів (
Script). З клієнта він не працює. - Необовʼязково: ключ Roblox Open Cloud для миттєвого кіку змін, зроблених на сайті.
Модуль ходить в API RoVision (https://api.rovision.gg) звичайними HTTPS-запитами через HttpService. Кожен запит підписаний API-ключем гри із Secrets, тож ключ не потрапляє ні в код, ні на клієнт. Сервер RoVision сам вирішує, які бани, ролі й списки стосуються саме вашої гри, а модуль лише виконує відповідь.
Зворотний канал - MessagingService вашої гри. Коли бан, роль чи білий список змінюється, сервери гри отримують повідомлення в тему RoVision і одразу перепитують API про згаданих гравців. Такі повідомлення надсилають інші сервери вашої гри (після Ban, Unban, Allow і Disallow) і сам RoVision через Roblox Open Cloud, якщо ви додали ключ. Детальніше - у розділі «Миттєвий кік».
Модуль не ламає гру
[RoVision], а модуль діє безпечно - за баном нікого не кікає, а ролі й білі списки вважає відсутніми. Зупиняють скрипт з помилкою лише неправильні параметри Init і RequireAllowed, виклик RequireAllowed до Init і підключення модуля з клієнта.Ось що робить модуль для кожного гравця, коли ви вже викликали Init:
Гравець заходить на сервер
Модуль ловить
Players.PlayerAdded. Гравців, які вже на сервері в моментInit, він перевіряє одразу.Входи збираються в пачку
Модуль чекає до секунди: усі, хто зайшов за цей час, перевіряються разом, до 100 гравців у запиті.
Три перевірки в API RoVision
Паралельно, по одному запиту на кожну. Сервер RoVision сам вирішує, що з цього стосується вашої гри.
- активний бан
- роль у команді
- білі списки
Є активний бан
Спрацьовує
PlayerBanned, а зEnforce = trueгравця кікає з поясненням.Бану немає
Гравець грає. Роль і списки вже в кеші, тож
IsModeratorіIsAllowedвідповідають без очікування.Закритий тест, гравця немає в списку
Якщо ввімкнено
RequireAllowed, модуль кікає гравця з текстом закритого тесту.API не відповів
Нікого не кікають за баном (fail open), а ролі й білі списки вважаються відсутніми (fail closed).
Поки гравець у грі
Повторна перевірка всіх на сервері раз на
RecheckInterval(5 хвилин) і миттєва перевірка гравця, коли приходить повідомлення про зміну його бану, ролі чи списків.
Шість кроків, кілька хвилин у кабінеті й у Roblox Studio. Після пʼятого кроку бан-лист, ролі команди й білі списки вже працюють, шостий вмикає миттєвий кік для змін, зроблених на сайті.
- Відкрийте Кабінет, Мої ігри, оберіть гру й відкрийте розділ «Інтеграція з грою».
- У картці «API-ключі» натисніть «Створити ключ» і дайте йому назву, наприклад «Основна гра» чи «Тестове місце». Ключ виглядає як
rv_live_…. - Скопіюйте ключ одразу: повністю він показується лише один раз, далі видно тільки його початок.
Один ключ працює лише з однією грою. На гру можна мати до 5 активних ключів, наприклад окремі для основної гри й тестового місця. Якщо ключ потрапив у чужі руки, відкличте його там же й створіть новий: сервери з відкликаним ключем одразу втрачають доступ до RoVision.
У Roblox Studio: Game Settings, Security, Allow HTTP Requests. Без цього модуль не може звернутися до RoVision: він пише попередження в Output і пускає всіх гравців.
- Відкрийте Creator Dashboard, оберіть гру й знайдіть розділ Secrets.
- Додайте секрет з назвою
rovision, значенням - вашим ключем, і доменомapi.rovision.gg.
Для тестів у Studio секрет задається окремо, у налаштуваннях гри в Studio. Детальніше - у документації Roblox про Secrets.
Ключ - лише в Secrets
ApiKey підходить лише для тестів у Studio, і на живому сервері модуль попередить про це в Output. Домен секрету обмежує, куди ключ можна надіслати: з api.rovision.gg він працює тільки з API RoVision.Варіант А - готовий файл
- Завантажте
RoVision.rbxmз останнього релізу. Ту саму кнопку «Отримати модуль» ви знайдете в розділі «Інтеграція з грою». - Перетягніть файл у Studio й покладіть модуль
RoVisionу ServerScriptService.
Варіант Б - Rojo
Скопіюйте папку src з репозиторію модуля у свій проєкт і змапте її як ServerScriptService.RoVision. Наприклад, якщо ви поклали її в packages/RoVision:
{
"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….Створіть Script у ServerScriptService:
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 й відповіді:
[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.
Необовʼязково, але рекомендовано. Бани й зміни білих списків з гри (RoVision:Ban, RoVision:Allow) і так доходять на всі сервери гри за секунди. Щоб так само швидко діяли бани, зміни команди й білих списків, зроблені на сайті, додайте в кабінеті ключ Roblox Open Cloud: Кабінет, Мої ігри, гра, «Інтеграція з грою», «Миттєвий кік на всіх серверах». Покрокова інструкція - у розділі «Миттєвий кік».
Без ключа такі зміни доходять до гравців, які вже в грі, під час повторної перевірки - до 5 хвилин.
Повний робочий скрипт з основними параметрами. Модуль RoVision лежить у ServerScriptService, ключ - у секреті rovision. Назвіть скрипт інакше, ніж модуль, щоб require знайшов саме модуль:
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)- Адмін-команди з правами з команди на сайті - у розділі «Бани з гри».
- Закритий тест для тестерів - у розділі «Закритий тест».
- Усі параметри
Init- у довідці.
Один бан-лист з трьома рівнями. Ви керуєте ним на сайті, а гра - через модуль: він не пускає гравців з активним баном, дає адмінам банити з гри й надсилає скарги модераторам 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.
RoVision:Ban створює бан рівня гри. Гравця на цьому сервері модуль кікає одразу (якщо Enforce = true), на інших серверах гри - за кілька секунд (миттєвий кік), а при наступному вході - одразу. Якщо в гравця вже є бан рівня гри, новий його замінює. RoVision:Unban так само за кілька секунд доходить до всіх серверів.
Приклад адмін-команд у чаті. Права беруться з команди на сайті: команди працюють для власника, адміністраторів і модераторів, а список Roblox ID у коді не потрібен.
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 знадобиться, наприклад, щоб показати причину бану в адмін-панелі або перевірити гравця, якого немає на сервері, за UserId.
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 не означає «не заблокований».
Коли античит упевнено бачить читера, надішліть скаргу модераторам RoVision. Якщо вони її приймуть, гравець отримає мережевий бан в іграх-партнерах.
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:Ban.Якщо хочете самі вирішувати, що робити з заблокованим гравцем, вимкніть Enforce і підпишіться на PlayerBanned:
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на цьому сервері чи миттєве оновлення), а потім він знову почав діяти, подія прийде ще раз.
Модуль кікає гравця з повідомленням українською, залежно від рівня бану:
- RoVision: «Вас заблоковано в мережі ігор RoVision. Порушення: шахрайство. Причина: … Діє до 10.11.2026 14:00 UTC.»
- Студія: «Вас заблоковано в іграх цієї студії. Причина: … Блокування безстрокове.»
- Гра: «Вас заблоковано в цій грі. Причина: … Діє до …»
Рядок «Порушення» зʼявляється для категорій exploiting, scamming і botting. У повідомленні немає посилань: Roblox забороняє відправляти гравців за межі платформи, тому посилання з тексту причини модуль вирізає, а саму причину скорочує до 200 символів. Свій текст задайте через Bans.KickMessage: рядком для всіх банів або функцією, яка отримує Ban:
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
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 для цього не потрібен.
Зміни з сайту - бани (ваші, вашої студії, модераторів RoVision, а також зняті після апеляції), команда студії й білі списки - RoVision надсилає у вашу гру через Roblox Open Cloud. Для цього потрібен ключ Open Cloud:
- Відкрийте Creator Dashboard → Open Cloud, API Keys і натисніть Create API Key. Якщо гра належить групі, створюйте ключ від імені групи.
- Назвіть ключ, наприклад,
RoVision. - У Access Permissions додайте API system Messaging Service API, оберіть вашу гру й операцію Publish.
- У Security, Accepted IP Addresses додайте
0.0.0.0/0: адреса сервера RoVision може змінюватися. - Термін дії (Expiration) - на ваш розсуд. Коли ключ перестане працювати, бот RoVision вам напише.
- Збережіть ключ, скопіюйте його й вставте в Кабінет, Мої ігри, гра, «Інтеграція з грою», «Миттєвий кік на всіх серверах», потім натисніть «Зберегти й перевірити».
RoVision одразу надсилає з ключем тестове повідомлення і зберігає ключ, лише якщо Roblox його прийняв. Ключ зберігається зашифрованим, повністю його більше ніде не показують, і RoVision використовує його лише для повідомлень у тему RoVision вашої гри.
Без ключа зміни з сайту діють, як і раніше: під час входу - одразу, а для гравців, які вже в грі, - під час повторної перевірки.
Картка «Миттєвий кік на всіх серверах» у розділі «Інтеграція з грою» показує стан ключа:
| Позначка | Що означає |
|---|---|
| Не налаштовано | Ключа немає. Зміни з сайту доходять до гравців у грі під час повторної перевірки. |
| Увімкнено | Ключ працює: видно його кінець, коли його востаннє перевірено й коли RoVision востаннє доставив повідомлення. |
| Не працює | Остання доставка не вдалася: видно помилку й час останньої невдалої спроби. Бани все одно діють через повторну перевірку. |
- «Перевірити зараз» - надіслати тестове повідомлення ще раз, наприклад після виправлення ключа в Creator Dashboard.
- «Замінити ключ» - поточний ключ працює, доки Roblox не прийме новий.
- «Видалити ключ» - зміни з сайту знову доходитимуть під час перевірки. У Roblox ключ залишиться: за потреби видаліть його в Creator Dashboard.
Сервер гри з Debug = true пише про тестове повідомлення в 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. Тоді модуль не підписується на тему й не надсилає повідомлень, а зміни банів, команди й білих списків доходять під час повторної перевірки.
RoVision:Init({
Bans = { Live = false }, -- без MessagingService: зміни доходять під час повторної перевірки
})У 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).
| Роль | Хто це | На сайті | IsModerator | IsAdmin |
|---|---|---|---|---|
"owner" | Власник гри або власник студії, до якої гра зарахована. | Усе: бан-лист, апеляції, заявки в RoVision, білі списки. Власник студії керує командою й лише він призначає адміністраторів. | так | так |
"admin" | Адміністратор команди студії. | Бан-лист, апеляції й заявки в RoVision для студії та її ігор, білі списки. Запрошує, змінює ролі та прибирає модераторів і учасників. | так | так |
"moderator" | Модератор команди студії. | Бан-лист, апеляції й заявки в RoVision для студії та її ігор, білі списки. | так | ні |
"member" | Учасник команди студії. | У команді, але без прав модерації. | ні | ні |
nil | Усі інші гравці. | - | ні | ні |
Власник, адміністратори й модератори також проходять закритий тест RequireAllowed без запису в списку. Учасники (member) - ні.
Команду ведуть на сайті: Кабінет, Розробка, «Студії», студія, «Команда».
- Власник студії й адміністратори запрошують людей за юзернеймом на RoVision і обирають роль. Адміністраторів запрошує й прибирає лише власник.
- Запрошення приходить у ботах і в Кабінет, Розробка, «Команди студій» (/account/teams), де його треба прийняти. Там же людина бачить свої команди й може вийти з команди.
- Роль змінюється одразу, людина отримує сповіщення. Роль діє в усіх іграх, зарахованих до студії.
- «Історія команди» показує, хто кого запросив, хто приєднався, вийшов чи змінив роль. Записи не можна змінити чи видалити.
- Якщо гра не зарахована до студії, команди в неї немає: роль є лише у власника гри.
Роль діє лише з привʼязаним Roblox-акаунтом
IsModerator поверне для нього false. У списку команди такі люди позначені «Roblox не підключено».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) ролі не мають.
Коли роль гравця на сервері змінюється, приходить подія з новою й старою роллю:
RoVision.RoleChanged:Connect(function(player, newRole, oldRole)
print(`{player.Name}: {oldRole or "без ролі"} -> {newRole or "без ролі"}`)
end)Подія приходить, коли повторна перевірка чи миттєве оновлення показує нову роль. На першу перевірку після входу вона не спрацьовує. nil означає, що гравця немає в команді.
Ролі працюють за принципом fail closed
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), але гравці й історія зберігаються. Відновити можна будь-коли.
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….
Коли списки гравця на сервері змінюються, приходить подія з усіма його ключами. Як і RoleChanged, на першу перевірку після входу вона не спрацьовує.
RoVision.ListsChanged:Connect(function(player, lists)
if table.find(lists, "vip") then
OpenVipRoom(player)
end
end)-- Додати на 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.
Один виклик після Init - і в гру заходять лише гравці зі списку:
local RoVision = require(game.ServerScriptService.RoVision)
RoVision:Init()
-- Грати можуть лише тестери, а також власник, адміністратори й модератори команди
RoVision:RequireAllowed("testers", {
KickMessage = "Зараз іде закритий тест. Новини про відкриття - у нашій групі Roblox.",
})- Гравців, яких немає в списку, модуль кікає під час входу, а також коли їх прибирають зі списку (за секунди з миттєвим кіком, інакше під час повторної перевірки) чи закінчується строк запису (під час повторної перевірки).
- З
AllowOwnersAndTeam = true(так і за замовчуванням) власник, адміністратори й модератори команди проходять без запису в списку. Учасники (member) - ні. Як і дляIsModerator, роль діє лише з Roblox-акаунтом, підключеним до RoVision: інакше додайте себе в список, щоб гра не кікнула вас самих. - Стандартний текст кіку: «Зараз у цю гру можуть зайти лише гравці зі списку доступу. Вас у ньому немає.» Свій текст задайте через
KickMessage, без посилань. - Перевірте ключ: якщо списку з таким ключем немає, у ньому нікого немає, і в гру зайдуть лише власник і команда.
- Тестові гравці Studio (з відʼємним UserId) проходять завжди.
- Викликайте
RequireAllowedпісляInit. Повторний виклик замінює список і перевіряє всіх на сервері знову. Неправильний ключ чи параметри зупиняють скрипт з помилкою.
Збій не кікає гравців
RequireAllowed нікого не кікає: гравець лишається в грі, а модуль перевіряє його ще раз через 5, 15 і 45 секунд і далі під час повторної перевірки. Кік - лише тоді, коли точно відомо, що гравця немає в списку.Білі списки працюють за принципом fail closed
IsAllowed повертає false, false, а GetLists - порожній список і false. Краще тимчасово не дати VIP-кімнату, ніж дати її будь-кому. Виняток - RequireAllowed: він не кікає, поки не знає відповіді.Усе, що модуль дає вашим скриптам: методи, параметри, значення, що повертаються, події й типи. Методи викликаються через двокрапку: 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(options: InitOptions?)Запускає модуль. Викликайте один раз на сервер, із серверного Script, до інших методів. Не чекає відповіді API: перевірки йдуть у фоні.
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
ApiKey | Secret або string | секрет rovision | Ключ з кабінету. Рядок підходить лише для тестів у Studio: на живому сервері модуль про це попереджає. Порожній рядок - те саме, що ключа немає. |
BaseUrl | string | https://api.rovision.gg | Адреса API, починається з https://. Змінювати не потрібно. |
Debug | boolean | false | Писати в Output усі запити, відповіді й службові повідомлення. |
Bans.Enforce | boolean | true | Кікати гравців з активним баном. З false модуль лише запускає PlayerBanned. |
Bans.KickMessage | string або function(ban): string? | текст українською | Текст під час кіку за баном. Функція може повернути nil, щоб лишити стандартний текст. Детальніше. |
Bans.RecheckInterval | number | 300 | Як часто, у секундах, повторно перевіряти всіх гравців на сервері (бани, ролі й білі списки). Менше 60 модуль піднімає до 60 з попередженням. |
Bans.Live | boolean | true | Миттєвий кік: зміни банів, команди й білих списків доходять на всі сервери гри за секунди через MessagingService. З false - лише під час повторної перевірки. |
- Чекає відповіді
- Ні
- Повторний виклик
- Ігнорується з попередженням.
- Помилки
- Неправильні типи параметрів зупиняють скрипт з помилкою, наприклад
[RoVision] Init: Bans.Enforce must be a boolean, got string.Невідомі параметри модуль ігнорує з попередженням. - Без ключа
- Модуль лише попереджає: бани не перевіряються (гравців пускають),
IsModerator,IsAdminіIsAllowedповертаютьfalse, а миттєвий кік не вмикається.
RoVision.Version: stringВерсія модуля, зараз 1.0.0. У файлі з релізу вона збігається з тегом релізу. Модуль також надсилає її в API з кожним запитом. Зручно для логів і звернень у підтримку:
print("RoVision", RoVision.Version) --> RoVision 1.0.0RoVision:CheckBan(playerOrUserId: Player | number): (Ban?, boolean)Повертає активний бан, який діє у вашій грі, або nil.
- Параметри
playerOrUserId- гравець (Player) або його Roblox UserId (ціле число).- Повертає
Banабоnil; друге значення - чи відповів API.- Чекає відповіді
- Так (yield). Результат кешується на 5 хвилин або доки не прийде повідомлення про зміну бану
- Якщо API недоступний
nil, false: це не означає «не заблокований».
RoVision:Ban(playerOrUserId: Player | number, options: BanOptions): (boolean, Ban | string)Банить гравця у вашій грі (бан рівня гри). Якщо в гравця вже є бан рівня гри, новий його замінює. Гравця на цьому сервері модуль кікає одразу (з Enforce = true) і запускає PlayerBanned, інші сервери гри дізнаються про бан за кілька секунд (Bans.Live).
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
Reason | string | обовʼязковий | Причина, 1-500 символів. Її побачить гравець. |
DurationDays | number? | nil | Скільки днів, ціле число від 1 до 3650. nil - назавжди. |
Category | string? | "other" | "exploiting", "scamming", "botting" або "other". |
- Повертає
trueіBanабоfalseі текст помилки.- Чекає відповіді
- Так (yield). Збій мережі модуль повторює, до 3 спроб
- Обмеження
- Лише справжні гравці: UserId більше 0. Модуль не перевіряє, хто викликає метод, тож права перевіряйте самі (IsModerator).
RoVision:Unban(playerOrUserId: Player | number): (boolean, number | string)Знімає бани рівня гри для вашої гри. Бани студії та мережеві бани RoVision лишаються. Інші сервери гри дізнаються про це за кілька секунд (Bans.Live).
- Параметри
playerOrUserId- гравець (Player) або його Roblox UserId (ціле число).- Повертає
trueі кількість знятих банів абоfalseі текст помилки.- Чекає відповіді
- Так (yield). До 3 спроб при збоях
RoVision:Report(playerOrUserId: Player | number, report: ReportOptions): booleanСтавить скаргу модераторам RoVision у чергу. Скарга нікого не банить: її розглядає модератор. Як і коли надсилати.
| Поле | Тип | Опис |
|---|---|---|
Category | string | "exploiting", "scamming" або "botting". |
Description | string | Що сталося, 1-1000 символів. Довший текст модуль обрізає. |
Detection | table? | Дані детекту для модератора: числа, рядки, булеві значення, до 8 КБ у JSON. Масив модуль загортає в { items = … }, завеликі дані замінює позначкою truncated. |
- Повертає
true, якщо скаргу поставлено в чергу;false, якщо модуль відхилив її ще до відправки: неправильна категорія, порожній опис, переповнена черга (100 скарг), тестовий гравець Studio. Причина зʼявиться в Output.- Чекає відповіді
- Ні: скарга надсилається у фоні, до 4 спроб, а потім відкидається з попередженням.
- Закриття сервера
- Скарги, що лишились у черзі, модуль дописує через BindToClose (до 10 секунд).
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(playerOrUserId: Player | number): booleantrue для власника, адміністратора або модератора команди. Зручно для адмін-команд і модераторських інструментів у грі.
- Чекає відповіді
- Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
- Якщо API недоступний
falseі попередження[RoVision] IsModerator: the role of … is unknown…(fail closed).
RoVision:IsAdmin(playerOrUserId: Player | number): booleantrue для власника або адміністратора команди.
- Чекає відповіді
- Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
- Якщо API недоступний
falseі попередження (fail closed).
RoVision:IsAllowed(playerOrUserId: Player | number, key: string): (boolean, boolean)Чи є гравець у списку key: у списку гри чи її студії, або в мережевому списку для "rovision:<ключ>". Правила ключів.
- Повертає
- Чи є гравець у списку; друге значення - чи відповів API. Для неправильного ключа -
false, trueі попередження. - Чекає відповіді
- Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
- Кеш
- 5 хвилин або доки не прийде повідомлення про зміну списків.
- Якщо API недоступний
false, false(fail closed).
RoVision:GetLists(playerOrUserId: Player | number): ({ string }, boolean)Усі ключі списків гравця за абеткою, наприклад { "testers", "vip" }. Мережеві списки - з префіксом rovision:. Таблицю можна змінювати: це копія.
- Чекає відповіді
- Так (yield). Для гравців на сервері відповідь зазвичай уже в кеші й приходить одразу
- Якщо API недоступний
- Порожній список і
false.
RoVision:Allow(playerOrUserId: Player | number, key: string, options: AllowOptions?): (boolean, AllowlistEntry | string)Додає гравця до списку самої гри (не студії й не RoVision). Список має бути створений на сайті. Якщо гравець уже в списку, повертає його поточний запис. Інші сервери гри дізнаються про це за кілька секунд (Bans.Live).
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
DurationDays | number? | nil | Скільки днів, ціле число від 1 до 3650. nil - без кінця. |
Note | string? | nil | Примітка для тих, хто веде список, до 500 символів. |
- Повертає
trueіAllowlistEntryабоfalseі текст помилки, наприкладallowlist_not_found: ….- Чекає відповіді
- Так (yield). До 3 спроб при збоях
- Обмеження
- Лише справжні гравці (UserId більше 0) і лише списки самої гри. Права викликача перевіряйте самі.
RoVision:Disallow(playerOrUserId: Player | number, key: string): (boolean, number | string)Прибирає гравця зі списку самої гри. Якщо гравець є в списку студії з тим самим ключем, IsAllowed і далі поверне true.
- Повертає
trueі кількість прибраних записів абоfalseі текст помилки.- Чекає відповіді
- Так (yield). До 3 спроб при збоях
RoVision:RequireAllowed(key: string, options: RequireAllowedOptions?)Пускає в гру лише гравців зі списку key (закритий тест). Викликайте після Init. Повторний виклик замінює список.
| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
KickMessage | string? | текст українською | Текст під час кіку, непорожній і без посилань. |
AllowOwnersAndTeam | boolean? | 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.
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відключить і чужі обробники.
Типи, які модуль використовує й експортує для типізованих скриптів:
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:
local RoVision = require(game.ServerScriptService.RoVision)
type Ban = RoVision.Ban
local function describe(ban: Ban): string
return `{ban.Scope}: {ban.Reason}`
endНові значення
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 characters | Ban: порожня чи задовга причина. |
DurationDays must be a whole number from 1 to 3650, … | Ban чи Allow: строк не є цілим числом від 1 до 3650. |
Category must be one of: exploiting, scamming, botting, other | Ban: невідома категорія. |
Note must be text of up to 500 characters | Allow: задовга примітка. |
"…" isn't a list key | Allow чи Disallow: неправильний ключ списку. |
RoVision-wide lists can't be changed from a game | Allow чи 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 s | API не відповів за 15 секунд, навіть після повторів. |
HTTP 503 | API відповів помилкою без пояснення (код може бути іншим). |
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 | Нікого не кікає за баном, гравці заходять як звичайно. CheckBan повертає nil, false. |
| Ролі | fail closed | IsModerator і IsAdmin повертають false, GetRole - nil, false. |
| Білі списки | fail closed | IsAllowed повертає false, false, GetLists - порожній список і false. |
| Закритий тест | не кікає | RequireAllowed лишає гравців у грі й перевіряє їх знову через 5, 15 і 45 секунд, далі - під час повторної перевірки. |
| Зміни з гри | помилка | Ban, Unban, Allow і Disallow повертають false і текст помилки. |
| Скарги | повтори | Модуль надсилає скаргу повторно кілька разів, а потім відкидає її з попередженням. |
| Миттєвий кік | fail open | Без MessagingService зміни доходять до інших серверів під час повторної перевірки. |
Чому так
З Debug = true модуль пише в Output кожен запит (->) і відповідь (<-) з кодом і часом. Ось які запити ви побачите:
| Що | Запит |
|---|---|
| Перевірка банів | POST /game-api/v1/bans/check |
| Перевірка ролей | POST /game-api/v1/team/check |
| Перевірка білих списків | POST /game-api/v1/allowlists/check |
| Ban | POST /game-api/v1/bans |
| Unban | DELETE /game-api/v1/bans/<UserId> |
| Report | POST /game-api/v1/reports |
| Allow | POST /game-api/v1/allowlists/<ключ>/entries |
| Disallow | DELETE /game-api/v1/allowlists/<ключ>/entries/<UserId> |
Це внутрішні запити модуля, їх перелік - щоб читати Output. У своєму коді викликайте методи модуля: він сам подбає про пачки, кеш, повтори й ліміти.
Модуль працює лише на сервері гри, нічого не продає й не торкається Robux. Ось які дані він передає, як захищені ключі й хто що бачить на сайті.
- 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.
Цього в модулі ще немає
Чи привʼязаний Roblox-акаунт гравця до RoVision, його нік, рівень, бейджі, чи акаунт підтверджений. RoVision:GetPlayer(player) повертатиме профіль гравця на RoVision. Метод чекатиме відповіді API, тому його не варто викликати в гарячих циклах, а результат кешуватиметься на кілька хвилин.
Players.PlayerAdded:Connect(function(player)
local profile = RoVision:GetPlayer(player)
if profile.IsLinked then
print(`{player.Name} - гравець RoVision {profile.Username}, рівень {profile.Level}`)
end
end)type Profile = {
IsLinked: boolean, -- false, якщо акаунт не прив'язаний або API недоступний
Username: string?, -- нік на RoVision
Level: number?,
Xp: number?,
IsVerified: boolean?, -- акаунт підтверджено через Telegram і Discord
IsPartner: boolean?,
Badges: { string }?,
}Так можна буде, наприклад, показати тег над головою гравця RoVision або дати бонус учасникам спільноти з підтвердженим акаунтом.
Ви описуватимете досягнення в кабінеті RoVision, а в грі зараховуватимете його одним викликом. Досвід іде в рівень гравця на RoVision.
- У розділі «Інтеграція з грою» додаєте досягнення: ID (наприклад,
finish_tutorial), назву, яку побачить гравець, досвід і як часто його можна отримати: один раз, раз на день або без обмежень (у межах денного ліміту). - У грі викликаєте
Award, коли гравець його досягнув.
-- Гравець пройшов навчання
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, сесії й досягнення - у вашому кабінеті.
Дат немає, порядок може змінитися.