Перейти к содержанию

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,
}