Server API
Всё, что описано здесь, находится в CoreServerAPI и запускается из серверного Script:
local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd.Core.ServerAPI)
Команды¶
requestCommand Server¶
ServerAPI.requestCommand(message: string, fromPlayer: Player?): (boolean, {any}, {Task})
Выполняет сообщение с командой точно так же, как если бы его написали в чат. Если игрок не указан, вместо вызывающего подставляется Server User, поэтому команды можно запускать из любого места кода игры без проверок разрешений. Если игрок указан, учитываются его роли, разрешения и лимиты частоты, а все уведомления для вызывающего отправляются ему. Возвращает, одобрена ли команда, созданные уведомления и созданные задачи.
-- Run as the server
ServerAPI.requestCommand(";fly all")
-- Or on behalf of a player
ServerAPI.requestCommand(";fly me", player)
getTasks Server¶
ServerAPI.getTasks(commandName: string?, target: Target?): {Task}
Возвращает запущенные задачи. Оба фильтра необязательны. ServerAPI.getTasks() возвращает все задачи, ServerAPI.getTasks("fly") все задачи fly, а ServerAPI.getTasks("fly", player) только задачи fly этого игрока.
endTasks Server¶
ServerAPI.endTasks(commandName: string?, target: Target?): number
Завершает подходящие задачи и возвращает, сколько их было завершено. Это ;unCommand в виде кода, с теми же необязательными фильтрами, что и у getTasks.
-- End every fly in the server
ServerAPI.endTasks("fly")
-- Clear everything running on one player
ServerAPI.endTasks(nil, player)
canUseCommandAsync Server¶
ServerAPI.canUseCommandAsync(target: Target, commandName: string): (boolean, string?)
Проверяет, позволяют ли роли цели выполнить указанную команду. Возвращает true, либо false и причину.
disableCommands Server¶
ServerAPI.disableCommands(player: Player)
Запрещает игроку выполнять новые команды, пока не вызван enableCommands или пока он не зайдёт заново. Удобно, пока игрок находится в раунде миниигры или в катсцене. Его уже запущенные задачи продолжают работать, так что если хочешь их тоже сбросить, добавь endTasks. Можно спокойно вызывать прямо из PlayerAdded.
enableCommands Server¶
ServerAPI.enableCommands(player: Player)
Снова разрешает игроку выполнять команды.
Роли¶
Названия ролей сравниваются без учёта регистра, так что "VIP" и "vip" обращаются к одной и той же роли.
giveRoleAsync Server¶
ServerAPI.giveRoleAsync(target: Target, roleName: string, options: ActionOptions?): (boolean, string?)
Выдаёт цели роль и возвращает true, либо false и причину, по которой не вышло. Постоянные выдачи сохраняются, работают межсерверно и действуют даже для игроков не в сети.
| Option | What it does |
|---|---|
scope |
"perm" сохраняет навсегда (по умолчанию), "server" действует только на этом сервере, "expire" снимается сам через duration |
duration |
Секунды, обязателен для scope "expire" |
reason |
Причина выдачи |
callerUserId |
UserId того, кто выдал роль, по нему проверяется ранг |
-- Reward a purchase forever
ServerAPI.giveRoleAsync(player, "VIP")
-- A 24 hour trial, granted by an offline head admin
ServerAPI.giveRoleAsync(player, "Mod", {
scope = "expire",
duration = 24 * 3600,
callerUserId = 1234567,
})
takeRoleAsync Server¶
ServerAPI.takeRoleAsync(target: Target, roleName: string, options: ActionOptions?): (boolean, string?)
Забирает у цели роль, включая постоянные выдачи, сделанные на других серверах или пока игрок был не в сети. В options можно передать scope ("perm" или "server") и callerUserId, как и в giveRoleAsync.
getRolesAsync Server¶
ServerAPI.getRolesAsync(target: Target): (boolean, {Role} | string)
Возвращает true и роли цели, отсортированные от самого высокого ранга к низкому, либо false и причину. Цель должна находиться на этом сервере.
local success, roles = ServerAPI.getRolesAsync(player)
if success then
for _, role in roles do
print(role.name, role.rank)
end
end
getTopRoleAsync Server¶
ServerAPI.getTopRoleAsync(target: Target): (boolean, (Role | string)?)
Возвращает true и самую старшую роль цели (nil, если ролей нет), либо false и причину. Цель должна находиться на этом сервере.
hasRoleAsync Server¶
ServerAPI.hasRoleAsync(target: Target, roleName: string): boolean
Проверяет, есть ли у цели эта роль прямо сейчас. Цель должна находиться на этом сервере.
getRole Server¶
ServerAPI.getRole(roleName: string): Role?
Возвращает Role по указанному имени, либо nil, если такой роли нет.
getAllRoles Server¶
ServerAPI.getAllRoles(): {Role}
Возвращает все роли из конфигурации игры.
Модерация¶
banAsync Server¶
ServerAPI.banAsync(target: Target, options: BanOptions): (boolean, string?)
Банит цель, не давая ей заходить в твою игру, и кикает её, если она сейчас на любом сервере. Возвращает true и новый banId, либо false и причину, по которой не вышло. Работает и для игроков не в сети.
| Option | What it does |
|---|---|
reason |
Обязательно, показывается игроку при попытке зайти |
scope |
"perm" (по умолчанию), "server" только для этого сервера или "expire" |
duration |
Секунды, для scope "expire" |
expiresAt |
Абсолютное epoch-время, которое заменяет duration |
banAlts |
По умолчанию true, банит альт-аккаунты через BanService от Roblox |
callerUserId |
UserId, на который записывается бан и по которому проверяется ранг. Если не указывать, это системный бан без ограничений |
-- A 7 day ban issued by your own anti-cheat
ServerAPI.banAsync(player, {
reason = "Exploiting",
scope = "expire",
duration = 7 * 24 * 3600,
})
unbanAsync Server¶
ServerAPI.unbanAsync(target: Target, banId: string?, options: UnbanOptions?): (boolean, string?, number?)
Снимает баны с цели и возвращает (success, failReason, totalBansCleared). Передай banId, чтобы снять один конкретный бан, или nil, чтобы снять все. В options можно передать scope и callerUserId.
getBanAsync Server¶
ServerAPI.getBanAsync(target: Target): (BanRecord?, string?)
Возвращает действующий BanRecord цели и её banId, проверяя в том числе записи игроков не в сети, либо nil, если цель не забанена.
local ban, banId = ServerAPI.getBanAsync(userId)
if ban then
print(`Banned for '{ban.reason}' by {ban.bannedBy}`)
end
Запросы¶
prompt Shared¶
ServerAPI.prompt(promptType: PromptType, player: Player, text: string, options: PromptOptions?): PromptHandle
Показывает игроку уведомление, сообщение или карточку через собственный интерфейс HD Admin, из любого серверного Script. Это та же функция, что и prompt из Command API: там описаны все типы запросов, полный список опций и карточки действий с кнопками и ползунками.
ServerAPI.prompt("success", player, "Quest complete!", {duration = 5})
Текст¶
filterTextAsync Server¶
ServerAPI.filterTextAsync(text: string, author: Target, viewer: Target?): (boolean, string)
Пропускает текст через фильтр Roblox и возвращает true и отфильтрованный текст, либо false и причину. Не указывай viewer, чтобы фильтровать для всех: это подходит для всего, что видят все игроки, и для текста, который ты сохраняешь. Передай viewer, чтобы отфильтровать только для этого игрока. Автор должен находиться на этом сервере, потому что фильтр Roblox отказывается работать для тех, кого здесь нет. Текст, который вернулся одними решётками, считается неудачей, так что пустой результат ты никогда не покажешь.
local success, result = ServerAPI.filterTextAsync(petName, player)
if success then
nameLabel.Text = result
else
ServerAPI.prompt("warn", player, "That name can't be used")
end
Информация¶
getSetting Shared¶
ServerAPI.getSetting(settingName: string, player: Player?): any
Возвращает значение настройки игры, например ServerAPI.getSetting("Prefix"). Передай игрока, чтобы дополнительно применить его личные You Settings, и тогда ты получишь точное значение, которое видит именно этот игрок.
getVersion Shared¶
ServerAPI.getVersion(): string
Запущенная версия HD Admin, например "v2.0.0".
Изоляция¶
isolateServer Server¶
ServerAPI.isolateServer()
Отрезает этот сервер от сохранения данных и от отправки чего-либо на другие серверы. Всё по-прежнему будет выглядеть так, будто работает как обычно: постоянные баны, изменения ролей, настройки игры, глобальные команды и глобальные голосования. Но ничего из этого на самом деле не сохраняется и не доходит до других серверов, поэтому всё исчезнет, когда сервер закроется. Сохранённые данные при этом читаются как обычно, так что сервер стартует с твоими настоящими ролями, банами, настройками и так далее. Личные предпочтения каждого игрока, например его You settings и любимые эмоции, всё равно сохраняются, потому что влияют только на этого игрока.
Это полезно для приватных и зарезервированных серверов, где ты хочешь выдать кому-то "Owner", не затрагивая остальную вселенную твоей игры.
local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd:WaitForChild("Core"):WaitForChild("ServerAPI"))
ServerAPI.isolateServer()
isServerIsolated Server¶
ServerAPI.isServerIsolated(): boolean
Возвращает true, если на этом сервере уже вызвали isolateServer.
Ограничения¶
restrictServer Server¶
ServerAPI.restrictServer(options: RestrictOptions?)
Ограничивает все возможности, которые действуют на всю игру: настройки игры, изменения ролей, постоянные роли, постоянные баны и разбаны, проверку, сохранённые задачи, а также постоянные, глобальные и входные модификаторы. Команды ролей из commandsInRoles и команды, названные в commands, тоже ограничиваются. В панели всё по-прежнему выглядит как обычно, пока не будет использована сама возможность или команда: тогда вместо результата показывается уведомление об ошибке. Любой, у кого есть роль из bypassRoles, обходит все ограничения.
В отличие от isolateServer, данные по-прежнему сохраняются и доходят до других серверов. Например, HD Admin Hub использует это, чтобы выдать каждому игроку "Dev" и показать панель администратора, но при этом ограничивает многие опасные команды и возможности, чтобы серверы нельзя было разрушить.
| Option | What it does |
|---|---|
commandsInRoles |
Названия или ключи ролей, чьи команды отклоняются |
commands |
Названия или ключи команд, которые отклоняются дополнительно |
bypassRoles |
Названия или ключи ролей, которые обходят все ограничения |
warning |
Заменяет "This is restricted in this game", уведомление, которое показывается при любом отказе |
local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd:WaitForChild("Core"):WaitForChild("ServerAPI"))
ServerAPI.restrictServer({
commandsInRoles = {"Dev", "Owner"},
commands = {"BuildingTools", "Music"},
bypassRoles = {"Owner"},
warning = "This is restricted in this demo",
})
isServerRestricted Server¶
ServerAPI.isServerRestricted(): boolean
Возвращает true, если на этом сервере уже вызвали restrictServer.
Эмоции¶
getEmoteById Server¶
ServerAPI.getEmoteById(emoteId: number): Emote?
Возвращает зарегистрированную Emote с указанным id, либо nil.
getEmoteByName Server¶
ServerAPI.getEmoteByName(emoteName: string, matchLength: boolean?): Emote?
Возвращает зарегистрированную Emote с указанным именем, либо nil.
getRandomEmote Server¶
ServerAPI.getRandomEmote(): Emote?
addEmoteAsync Server¶
ServerAPI.addEmoteAsync(emote: IncompleteEmote, dontRegister: boolean?): (boolean, Emote | string)
Регистрирует новую эмоцию по ассету анимации эмоции, чтобы её можно было проиграть через ;emote и чтобы она появилась в меню эмоций. Обязателен только emoteId, недостающие данные подтянутся сами. Возвращает true и готовую Emote, либо false и причину, по которой не вышло.
Типы¶
Role¶
Полная таблица конфигурации роли, в точности как она задана в ConfigRoles. См. Roles.
BanRecord¶
type BanRecord = {
type: "perm" | "expire" | "server",
source: "admin" | "loader",
bannedBy: number | string,
bannedAt: number,
expiresAt: number?,
grantedOnJobId: string?, -- only present on server-scope bans
reason: string,
banAlts: boolean,
}
banId не входит в саму запись, поэтому getBanAsync отдаёт его вторым возвращаемым значением.
Task¶
См. Task API.
Emote¶
type Emote = {
name: string,
originalName: string?,
order: number,
animationId: number,
emoteId: number,
}