Command API
Всё, на что команда может безопасно ссылаться, лежит в CommandAPI:
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
Загрузка¶
loadCommands Server¶
CommandAPI.loadCommands(details): Commands
Через неё модули паков в Config > Commands загружают, помечают тегами и меняют свои наборы команд. Открой любой из паков там, чтобы посмотреть, как это работает.
Запросы¶
prompt Shared¶
-- In a server command module
CommandAPI.prompt(promptType: PromptType, player: Player, text: string, options: PromptOptions?): PromptHandle
-- In a client command module
CommandAPI.prompt(promptType: PromptType, text: string, options: PromptOptions?): PromptHandle
Показывает уведомление, сообщение или карточку. Запросы с кнопками описаны в bindPrompt.
| Тип запроса | Что показывает |
|---|---|
"info" "success" "warn" "error" |
Уведомление сбоку со звуком |
"message" |
Сообщение по центру экрана, например в ;message |
"hint" |
Небольшая полоса вверху экрана, например в ;hint |
"privateMessage" |
Закреплённое уведомление сбоку, по клику открывает полное сообщение |
"alert" |
Закреплённое уведомление сбоку, которое зацикливает звук, пока его не заглушат, и по клику открывает полное сообщение |
"action" |
Уведомление сбоку с кнопками и элементами управления. Создаются через task:bindPrompt |
CommandAPI.prompt("success", task.caller, "Quest complete!", {duration = 5})
Функция возвращает соединение. Вызови connection:Disconnect(), чтобы закрыть запрос. Например, можно добавить его в janitor задачи, чтобы запрос исчезал сразу вместе с командой:
task.janitor:add(CommandAPI.prompt("hint", task.target, "You're frozen until an admin releases you", {duration = 0})) -- 0 means "infinite"
Параметры
Все они необязательные и работают с любым типом запроса, если в строке не сказано иное:
| Параметр | Тип | Что делает |
|---|---|---|
title |
string | Заголовок над текстом. У privateMessage и alert он задан сам |
duration |
number | Через сколько секунд запрос закроется сам. Если не указать, время считается по длине текста. 0 оставляет запрос на экране, пока его не закроют или не отключат |
subtext |
string | Строка поменьше под текстом |
icon |
string | Картинка rbxassetid://, которая заменяет иконку уведомления |
color |
Color3 | Красит текст hint |
dismissable |
boolean | false прячет кнопку закрытия, так что убрать запрос можно только по duration или через handle |
openPage |
string | По клику на уведомление панель открывается на этой странице, например "Commands", "Roles", "Settings" или "About" |
openProfile |
boolean | По клику на уведомление открывается собственный профиль игрока |
openImage |
table | {image = "rbxassetid://...", title = "Map", ratio = 16/9}. По клику на уведомление картинка открывается по центру экрана |
linkButtons |
table | Маленькие кнопки внизу уведомления. {label = "Roles", page = "Roles"} открывает страницу, а {label = "Profile", profile = true} открывает профиль. Добавь style = "Neutral" для приглушённой кнопки и hideAfterPress = true, чтобы уведомление закрывалось после нажатия. Из LocalScript через API клиента можно передать {label = "Shop", onActivate = function() ... end, icon = "rbxassetid://..."}, тогда запустится твоя функция |
roleBadges |
table | Значки ролей под заголовком, {{name = "Admin", color = Color3.fromRGB(255, 170, 0)}} |
countdown |
number | Ведёт обратный отсчёт от этого числа секунд в тех местах текста, где стоит %TIME% |
fromUserId |
number | Показывает аватар, имя и высшую роль этого пользователя как отправителя message, privateMessage или alert |
userText |
boolean | Показывает текст ровно так, как он написан, без тегов форматирования и прочего |
CommandAPI.prompt("info", task.caller, "You've unlocked the VIP role", {
title = "New role",
openPage = "Roles",
roleBadges = {{name = "VIP", color = Color3.fromRGB(255, 170, 0)}},
})
Запросы с кнопками описаны в bindPrompt.
Персонаж¶
getHumanoid Shared¶
CommandAPI.getHumanoid(player: Player?): Humanoid?
Humanoid игрока или nil, если его персонажа сейчас нет.
getHRP Shared¶
CommandAPI.getHRP(player: Player?): BasePart?
HumanoidRootPart игрока или nil.
getHead Shared¶
CommandAPI.getHead(player: Player?): (BasePart?, Model?)
Head игрока и его персонаж или nil.
getNeck Shared¶
CommandAPI.getNeck(player: Player?): Motor6D?
Шейное соединение игрока или nil. Работает и с R6, и с R15.
getTorso Shared¶
CommandAPI.getTorso(player: Player?): Instance?
Торс игрока или nil. Работает и с R6, и с R15.
loadCharacter Server¶
CommandAPI.loadCharacter(player: Player?)
Респавнит персонажа игрока. Всегда используй её вместо player:LoadCharacter(), чтобы задачи HD Admin знали, что респавн был намеренным.
Игроки¶
getUserInfoAsync Shared¶
CommandAPI.getUserInfoAsync(userId: number | string): (boolean, UserInfo | string)
Возвращает true и UserInfo для любого пользователя, даже не в сети, либо false и причину. Результаты кэшируются, так что повторные вызовы ничего не стоят.
getNameFromUserIdAsync Shared¶
CommandAPI.getNameFromUserIdAsync(userId: number | string): (boolean, string)
Возвращает true и имя пользователя либо false и причину. Работает и для тех, кого нет в сети.
teleportAsync Server¶
CommandAPI.teleportAsync(player: Player?, cframe: CFrame): (boolean, string)
Перемещает персонажа игрока в указанный CFrame, предварительно вставая с сиденья, чтобы сиденье не поехало следом.
getAllowedTargets Server¶
CommandAPI.getAllowedTargets(task: Task, options: {players: {Player}?}?): ({Player}, {Player})
Игроки, на которых команда может подействовать. По умолчанию это все на сервере кроме тех, у кого в You Settings включено Block commands.
unequipTools Server¶
CommandAPI.unequipTools(player: Player?): (boolean, string)
Убирает инструмент из рук игрока обратно в рюкзак.
Задачи¶
getTasks Shared¶
CommandAPI.getTasks(commandKey: string?, targetUserId: number?): {Task}
Возвращает запущенные задачи, при желании отфильтрованные по команде и цели. Это те же объекты задач, что описаны в API задач.
getTasksByCallerId Shared¶
CommandAPI.getTasksByCallerId(callerUserId: number): {Task}
Все запущенные задачи, которые начал указанный вызывающий.
Чат¶
systemMessage Shared¶
-- In a server command module
CommandAPI.systemMessage(player: Player, text: string)
-- In a client command module
CommandAPI.systemMessage(text: string)
Отправляет в чат игрока системное сообщение.
checkTextLimit Server¶
CommandAPI.checkTextLimit(task: Task, textKind: "Message" | "SurfaceText" | "ChatText" | "Reason"): (boolean, number?)
Из-за политики Roblox по безопасности для разных возрастов HD Admin ограничивает отправку текстовых возможностей, и эта функция позволяет узнать об этой паузе.
Она возвращает true, когда текст можно показывать, иначе false и оставшееся время паузы.
args = {"Player", "Leaderstat", {arg = "String", textSurface = "None"}},
run = function(task)
local stat = task:getArg("Leaderstat")
local text = task:getArg("String")
if stat:IsA("StringValue") then
if not CommandAPI.checkTextLimit(task, "SurfaceText") then
return
end
end
stat.Value = text
end,
| Вид | Общий лимит для |
|---|---|
"Message" |
Сообщений, подсказок, уведомлений, алертов, личных сообщений и опросов |
"SurfaceText" |
Имён, титулов, названий команд и статистики |
"ChatText" |
Тегов и имён в чате |
"Reason" |
Причин кика и бана |
forceBubbleChat Shared¶
CommandAPI.forceBubbleChat(target: Player | Model, text: string)
Показывает облачко чата над персонажем игрока или над любой моделью или частью, которую передашь вместо него.
Образы¶
getDescription Server¶
CommandAPI.getDescription(humanoid: Humanoid): HumanoidDescription
Текущий HumanoidDescription у этого humanoid.
applyDescription Server¶
CommandAPI.applyDescription(humanoid: Humanoid?, description: HumanoidDescription?, properties: {[string]: any}?): HumanoidDescription?
Безопасно применяет HumanoidDescription и повторяет попытку, если Roblox отклонил первую. Передай properties, чтобы изменить поля поверх базового описания.
outfitBuff Server¶
CommandAPI.outfitBuff(target: Player, properties: {[string]: any})
Применяет свойства HumanoidDescription как бафф, который сам откатывается, когда задача заканчивается. Поэтому команды вроде ;wormify за собой убирают сами.
setFakeBodyParts Server¶
CommandAPI.setFakeBodyParts(character: Model, info: {[string]: any}): (() -> ())?
Подменяет части тела заменителями, созданными командой, и возвращает функцию, которая вернёт оригиналы.
clearFakeBodyParts Server¶
CommandAPI.clearFakeBodyParts(character: Model)
Снова убирает эти заменители.
runBundleId Server¶
CommandAPI.runBundleId(task: Task, bundleId: number, properties: {[string]: any}?)
Одевает цель задачи в бандл из каталога и возвращает её собственный образ, когда задача заканчивается.
Ассеты¶
registerSound Shared¶
CommandAPI.registerSound(sound: Sound)
Нужна для любого Sound, который создаёт твоя команда, чтобы к нему применялись настройки громкости и высоты звука игры.
setAnchored Shared¶
CommandAPI.setAnchored(instance: Instance, anchored: boolean)
Закрепляет или открепляет все части внутри экземпляра.
setTransparency Shared¶
CommandAPI.setTransparency(instance: Instance, transparency: number)
Делает прозрачными все части внутри экземпляра.
promptPurchaseAsync Server¶
CommandAPI.promptPurchaseAsync(assetId: number, player: Player?, infoType: Enum.InfoType?)
Предлагает игроку купить ассет, выбирая подходящий для его типа порядок покупки.
ownsAssetAsync Server¶
CommandAPI.ownsAssetAsync(assetId: number, player: Player?): boolean
Есть ли у игрока этот ассет.
isTypeAsync Server¶
CommandAPI.isTypeAsync(assetId: number, assetType: Enum.AssetType | Enum.BundleType): (boolean, string?)
Проверяет, что ассет имеет указанный тип. Возвращает true либо false и причину.
loadAssetCommand Server¶
CommandAPI.loadAssetCommand(assetType: Enum.AssetType, task: Task, assetId: number, callback: (item: Instance) -> ())
Проверяет, что ассет нужного типа и разрешён, вставляет его и передаёт в твой callback, чтобы ты его разместил. На ней работает ;gear.
getToolsInfoAsync Server¶
CommandAPI.getToolsInfoAsync(): (boolean, {ToolInfo} | string)
Возвращает true и ToolInfo для каждого инструмента, доступного в ;give, либо false и причину.
Утилиты¶
getTargets Server¶
CommandAPI.getTargets(targetType: "All" | "Others" | "Nearby" | "OthersNearby", originPlayer: Player?, radius: number?): {Player}
Превращает квалификатор в список игроков, которых он сейчас охватывает. "Nearby" и "OthersNearby" отсчитываются от исходного игрока в радиусе radius studs (по умолчанию 50).
setCameraSubject Client¶
CommandAPI.setCameraSubject(newSubject: Instance)
Направляет камеру локального игрока на новый объект, например на Humanoid другого игрока, как в ;view.
runPromptCommand Server¶
CommandAPI.runPromptCommand(promptType: PromptType, task: Task, targets: {Player}, text: string, options: PromptOptions?)
Движок, на котором работают ;message, ;hint и похожие запросы. Она фильтрует текст, показывает запрос каждой цели и держит задачу живой, пока запрос не закончится.
runEmoteId Server¶
CommandAPI.runEmoteId(task: Task, emoteId: number, speed: number?, looped: boolean?)
Проигрывает анимацию эмоции на цели задачи и останавливает её, когда задача заканчивается.
createEmoteCommand Server¶
CommandAPI.createEmoteCommand(emoteName: string, emoteId: number, properties: {[string]: any}?): Command
Возвращает готовую команду эмоции, которую можно сразу добавить в массив команд. properties переопределяет любое поле сгенерированной команды.
createBundleCommand Server¶
CommandAPI.createBundleCommand(commandName: string, bundleId: number, properties: {[string]: any}?): Command
То же самое для команд с бандлами, например ;ratdance.
bindEmotePrompt Server¶
CommandAPI.bindEmotePrompt(task: Task, target: Player, emoteId: number, emoteName: string?, isLooped: boolean?)
Привязывает к задаче карточку действий эмоции, чтобы цель могла добавить эмоцию в избранное или посмотреть её в каталоге.
openProfile Server¶
CommandAPI.openProfile(player: Player?, userId: number)
Открывает игроку всплывающий профиль указанного пользователя.
openPage Server¶
CommandAPI.openPage(player: Player?, pageId: string, tabLabel: string?)
Открывает панель игрока сразу на указанной странице, при желании на одной из её вкладок.
openEmotes Server¶
CommandAPI.openEmotes(player: Player?)
Открывает игроку окно с эмоциями.
colourRoleName Shared¶
CommandAPI.colourRoleName(role): string
Название роли, обёрнутое в её цвет для rich text.
isTableEmpty Shared¶
CommandAPI.isTableEmpty(tbl: {[any]: any}): boolean
Проверяет, что в таблице совсем нет записей, включая записи с ключами, которые #tbl пропускает.
round Shared¶
CommandAPI.round(number: number, decimalPlaces: number?): number
Округляет число до указанного количества знаков после запятой, по умолчанию до целого.
Типы¶
Commands¶
type Commands = {Command}
Массив, который возвращает модуль команд.
Command¶
Одна таблица команды внутри Commands (name, args, run и так далее). Все поля описаны в пользовательских командах.
Task¶
Объект задачи, который передаётся в каждую функцию run. Подробно он описан в API задач.
ClientCommands¶
Клиентский аналог Commands, его возвращает модуль Client.
ClientCommand¶
Одна таблица клиентской команды внутри ClientCommands.
UserInfo¶
type UserInfo = {
userId: number | string,
userName: string,
userImage: string,
userDisplayName: string,
userTopRole: {key: string, name: string, color: Color3}?,
}
userTopRole есть только у игроков на этом сервере.
ToolInfo¶
type ToolInfo = {
name: string,
textureId: string,
tool: Tool?,
}
PromptType¶
type PromptType = "info" | "success" | "warn" | "error" | "message" | "hint" | "privateMessage" | "alert" | "vote" | "voteResults" | "action"
Строки с типами запросов. Что показывает каждый из них, смотри в prompt.
PromptOptions¶
Таблица параметров, которую принимает prompt. Полный список в разделе prompt.
PromptHandle¶
Handle, который возвращает prompt. Он закрывает запрос раньше времени через handle:Disconnect().