Task API
Каждый раз, когда запускается команда, она создаёт задачу для каждой цели. Эта задача передаётся в run и отвечает за то, как долго живёт команда, за сетевую часть, очистку и многое другое.
Methods¶
task:keep Server¶
task:keep(persistence: Persistence?)
Оставляет задачу живой после того, как run завершился, иначе она уничтожается сразу. Доступны варианты "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" и "Indefinitely". Если вызвать метод несколько раз, условия объединяются, и задача закончится по тому, что случится первым. См. Persistence.
task:getArg Server¶
task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any
Читает проверенное значение аргумента по имени или позиции. Это значение может быть default аргумента, проверенным значением от вызвавшего команду, значением, которое изменил запрос, или значением, заданным через task:setArg().
Передай true вторым параметром, чтобы получить nil, когда вызвавший не указал аргумент и его значение взялось только из default. Это удобно для необязательных аргументов, когда нужно перейти на своё поведение, например как ;message считает длительность по длине текста, если её не ввели.
task:setArg Server¶
task:setArg(nameOrPosition: string | number, value: any)
Меняет значение аргумента по имени или позиции.
task:buff Server¶
task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)
Меняет свойство, заново применяет изменения, когда меняются баффы в той же группе, и возвращает свойству исходное значение, когда задача заканчивается. См. Buffs.
task:updateBuffs Server¶
task:updateBuffs(player: Player?, group: string?)
Заново запускает баффы для этого игрока и этой группы. В большинстве случаев это делается автоматически, так что нужно только когда ты хочешь принудительно обновить всё в этой группе.
task:redo Server¶
task:redo(player: Player?, callback: () -> ())
Сразу запускает твой callback, а потом запускает снова каждый раз, когда игрок возрождается, пока задача жива. Полезно для эффектов, которые иначе пропадали бы при возрождении.
task:bindPrompt Server¶
task:bindPrompt(config)
Даёт вызвавшему панель действий, привязанную к команде, например слайдер у ;speed или цвет глаз у ;laserEyes:
run = function(task: CommandAPI.Task)
task:keep("UntilCallerLeaves")
task:bindPrompt({
title = "Dangerous Script",
text = "This script uses HttpService, are you sure you want to load it?",
audience = task.caller,
duration = 20,
deactivate = false,
endOnClose = true,
buttons = {
{
label = "Load",
onActivate = function()
--loadScript()
task:destroy()
end,
},
{
label = "Cancel",
style = "Neutral",
onActivate = function()
task:destroy()
end,
},
},
})
end,
Config
| Key | Type | What it does |
|---|---|---|
title |
string | Заголовок запроса, по умолчанию название команды |
text |
string | Основной текст |
subtext |
string | Строка мельче под текстом |
audience |
Player | Кто видит запрос, по умолчанию task.target |
duration |
number | Через сколько секунд запрос закроется сам. По умолчанию 0, то есть без ограничения |
args |
table | Аргументы команды, которые нужно показать как элементы управления, см. Controls |
onChange |
function | function(argName, value), срабатывает после того, как элемент управления изменил аргумент |
toggle |
table | Дополнительный переключатель, не привязанный к аргументу, {label = "Trails", value = true, onChange = function(isOn) end} |
buttons |
table | Одноразовые кнопки действий, см. Buttons |
deactivate |
boolean | По умолчанию true: у запроса есть переключатель, который ставит команду на паузу и возобновляет её, и кнопка Stop, которая её завершает. Поставь false для запроса, где только кнопки |
rerun |
boolean | Добавляет кнопку повторного запуска, которая очищает всё и запускает команду заново. Показывается только когда deactivate равен false |
endOnClose |
boolean | По умолчанию закрытие запроса завершает задачу. Если поставить false, она продолжит работать, пока клиент не закроет запрос |
Controls
Чтобы аргумент можно было менять через панель действий, добавь его имя в args внутри bindPrompt. Number превращается в слайдер, Color в выбор цвета, Bool в переключатель и так далее. Когда клиент что-то меняет, аргумент обновляется и срабатывает твой onChange, так что просто вызови task:getArg ещё раз, чтобы прочитать новое значение. Ничего проверять тоже не нужно, каждое значение проверяется точно так же, как если бы его ввели в чат:
run = function(task: CommandAPI.Task)
local function applySpinSpeed()
local speed = task:getArg("Number")
-- spin the character at this speed
end
applySpinSpeed()
task:bindPrompt({
args = {"Number"},
onChange = applySpinSpeed,
})
end,
С кнопками так же просто. Дай каждой label и функцию onActivate, и эта функция выполнится на сервере, когда клиент нажмёт кнопку. Здесь можно спокойно делать yield (запрос покупки, обращение к datastore и так далее): кнопка просто показывает индикатор загрузки, пока ты не закончишь:
| Key | Type | What it does |
|---|---|---|
label |
string | Текст на кнопке |
onActivate |
function | Что происходит при нажатии |
style |
string | По умолчанию "Primary", либо "Neutral" для серого вида, идеально для Cancel |
confirm |
boolean | Добавляет шаг Confirm?, так что кнопка срабатывает только после двух нажатий, удобно для мощных действий вроде подтверждения бана |
Кнопка может завершить свою задачу через task:destroy(), так делают одноразовые запросы команд вроде ;teleport.
task.client:run Server¶
task.client:run(player: Player?, ...)
task.client:runAll(...)
task.client:runOthers(originPlayer: Player, ...)
task.client:runNearby(originPlayer: Player?, radius: number, ...)
Запускает соответствующую клиентскую команду на устройствах игроков, передавая всё лишнее как есть. run нацелен на одного игрока, runAll на всех, runOthers на всех, кроме originPlayer, а runNearby на тех, кто в пределах radius стадов. См. Networking.
task.client:expose Server¶
task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})
Гарантирует, что инстансы реально дошли до игрока, прежде чем клиентский код начнёт их искать. Стриминг может их задерживать, поэтому всё, что ты создаёшь на сервере и используешь на клиенте, сначала нужно пропустить через этот метод.
task.server:replicate Client¶
task.server:replicate(...)
Отправляет значения из клиентской команды обратно на сервер, где они попадают в ту же задачу. Задай task.client.replicator на сервере, чтобы выбрать, кому они пойдут дальше, и они придут в функцию replication этой команды. См. Networking.
task:tween Shared¶
task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween
Запускает твин, который очищается вместе с задачей, так что он никогда не переживёт команду.
task:createSound Shared¶
task:createSound(soundType: SoundType?): Sound
Создаёт Sound, которым владеет задача и который она сама очищает. Громкость (Volume) и высоту (Pitch) этого звука потом могут настроить все игроки в YouSettings. SoundType по умолчанию равен "Command", если не задан.
task:onEnded Shared¶
task:onEnded(callback: () -> ())
Запускает твой callback каждый раз, когда задача заканчивается. Это то же самое, что task.janitor:add(callback).
task:onEndedForGood Shared¶
task:onEndedForGood(callback: () -> ())
Запускает твой callback только когда задача закончилась И сразу после этого не создана такая же задача. Это полезно для команд вроде ;serverLock Admin, которая показывает уведомление при запуске ("This server has been locked for Admins") и при завершении ("This server has been unlocked"). Но если потом запустить ;serverLock Mod, нам не нужно, чтобы предыдущая команда показывала своё уведомление о завершении, нужно только новое уведомление о запуске.
task:destroy Shared¶
task:destroy()
Принудительно завершает задачу и очищает всё, чем она владеет. Именно это вызывает ;un под капотом.
Scheduling Shared¶
task.spawn(callback: () -> ())
task.defer(callback: () -> ())
task.delay(seconds: number, callback: (() -> ())?)
task.wait(seconds: number?)
task.iterate(count: number, callback: (index: number) -> ())
task.loop(callback: (stop: () -> (), index: number) -> ())
Это обёртки над планировщиком task из Roblox, которые учитывают задачу. Они нужны, чтобы команда оставалась живой, пока активна, и чтобы их можно было автоматически отменить при очистке задачи (например, когда кто-то вызвал undo до её окончания). Используй их так же, как обычные методы task из Roblox, остальное HD Admin сделает сам.
Properties¶
task.target Server¶
task.target: Player
Игрок, на котором запущена команда. Если твой первый аргумент Player, он есть всегда, потому что HD Admin разбивает запуск на отдельную задачу для каждого подходящего игрока, так что можно использовать его без проверки. Команды с общим аргументом Players так не разбиваются, поэтому там он пустой. task.targetUserId хранит его UserId и доступен, даже когда игрок не в сети.
task.qualifiers Server¶
task.qualifiers: {[string]: {string}}
Кого вызвавший указал в исходной строке команды. ;clone others даёт {others = {}}, а просто ;clone даёт пустую таблицу. Это всегда таблица, так что её можно читать напрямую.
task.caller Server¶
task.caller: Player?
Тот, кто запустил команду, или nil, если её запустил сервер (или если сервер получил глобальную команду, а вызвавшего нет на твоём сервере). task.callerUserId есть всегда, так что используй его, если нужен UserId.
task.janitor Shared¶
task.janitor:add(item): typeof(item)
Объект Janitor, которому можно отдавать инстансы, соединения и функции для автоматической очистки. Например:
local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart
task.config Server¶
task.config: {[string]: any}
Собственная таблица config команды, включая всё, что пак изменил через modify в Config > Commands. Так команда читает настройку, которую владелец игры должен уметь менять, например списки разрешённых и запрещённых у ;insert.
task.extra Shared¶
task.extra: {[string]: any}
Таблица для дополнительной информации, которая живёт дольше деактивации и до полного завершения задачи.
task.isActive Shared¶
task.isActive: boolean
true, пока задача работает, и false, как только она начинает завершаться. Используй это в циклах, чтобы эффект сразу останавливался, если задачу, например, завершили принудительно.
task.commandKey Shared¶
task.commandKey: string
Название команды, которую выполняет эта задача, в нижнем регистре.
task.isReplay Server¶
task.isReplay: boolean
true, когда сохранённая постоянная команда воспроизводится при старте сервера, а не запущена кем-то прямо сейчас. Полезно, чтобы ограничить запросы в постоянных командах, которые мы не хотим автоматически показывать вызвавшему снова (например, запрос ;music при входе на каждый новый сервер).