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

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,

Buttons

С кнопками так же просто. Дай каждой 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 при входе на каждый новый сервер).