Pular para conteúdo

Task API

Toda vez que um comando roda, ele cria uma tarefa para cada alvo. Essa tarefa é passada para run e controla por quanto tempo o comando continua vivo, a rede, a limpeza e muito mais.

Métodos

task:keep Servidor

task:keep(persistence: Persistence?)

Mantém a tarefa viva depois que run retorna. Sem isso, ela é destruída na hora. As opções são "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" e "Indefinitely". Se você chamar mais de uma vez, as condições se combinam e a tarefa termina na que acontecer primeiro. Veja Persistência.


task:getArg Servidor

task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any

Lê o valor validado do argumento com o nome ou a posição indicados. Esse valor pode vir do default do argumento, do valor validado informado por quem executou o comando, de um valor validado para o qual um prompt o mudou, ou de um valor definido com task:setArg().

Passe true como segundo argumento para receber nil quando quem executou o comando não informou o argumento e o valor veio apenas do default dele. Isso é útil em argumentos opcionais quando você quer usar seu próprio comportamento, como o ;message faz ao calcular a duração pelo tamanho do texto, a menos que uma tenha sido digitada.


task:setArg Servidor

task:setArg(nameOrPosition: string | number, value: any)

Muda o valor do argumento com o nome ou a posição indicados.


task:buff Servidor

task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)

Altera uma propriedade, reaplica as alterações nela quando os buffs do mesmo grupo mudam e, quando a tarefa termina, devolve a propriedade ao valor original. Veja Buffs.


task:updateBuffs Servidor

task:updateBuffs(player: Player?, group: string?)

Executa os buffs de novo para aquele jogador e grupo. Isso já é tratado automaticamente na maioria dos casos, então só serve quando você quer forçar a atualização de tudo naquele grupo.


task:redo Servidor

task:redo(player: Player?, callback: () -> ())

Executa seu callback na hora e depois de novo toda vez que o jogador renasce enquanto a tarefa estiver viva. Útil para efeitos que sumiriam ao renascer.


task:bindPrompt Servidor

task:bindPrompt(config)

Dá a quem executou o comando um prompt de ação ligado ao comando, como o controle deslizante do ;speed ou a cor dos olhos do ;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,

Configuração

Chave Tipo O que faz
title string O título do prompt, o padrão é o nome do comando
text string O texto principal
subtext string Uma linha menor abaixo do texto
audience Player Quem vê o prompt, o padrão é task.target
duration number Segundos até o prompt se fechar sozinho. O padrão é 0, que representa duração infinita
args table Os argumentos do comando que serão expostos como controles, veja Controles
onChange function function(argName, value), roda depois que um controle muda um argumento
toggle table Um interruptor extra de ligar e desligar que não está ligado a nenhum argumento, {label = "Trails", value = true, onChange = function(isOn) end}
buttons table Botões de ação avulsos, veja Botões
deactivate boolean O padrão é true, que dá ao prompt um interruptor para pausar e retomar o comando e um botão Stop que o encerra. Use false para um prompt que tem só botões
rerun boolean Adiciona um botão de reexecutar, que faz a limpeza e roda o comando de novo. Só aparece quando deactivate é false
endOnClose boolean Por padrão, fechar o prompt encerra a tarefa. Com false ela continua rodando até o cliente dispensar o prompt

Controles

Para deixar um argumento controlável pelo prompt de ação, coloque o nome dele em args dentro de bindPrompt. Um Number vira um controle deslizante, um Color um seletor de cor, um Bool um interruptor, e assim por diante. Sempre que o cliente muda um deles, o argumento é atualizado e seu onChange é chamado, então basta chamar task:getArg de novo para ler o novo valor. Você também não precisa validar nada, todo valor é verificado exatamente como se tivesse sido digitado no chat:

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,

Botões

Os botões são igualmente simples. Dê a cada um um label e uma função onActivate, e essa função roda no servidor sempre que o cliente apertar o botão. Também pode yieldar ali (um prompt de compra, uma chamada de datastore, etc), porque o botão só mostra um indicador de carregamento até você terminar:

Chave Tipo O que faz
label string O texto do botão
onActivate function O que acontece quando ele é apertado
style string "Primary" por padrão, ou "Neutral" para um visual acinzentado, ideal para Cancel
confirm boolean Adiciona uma etapa Confirm?, então ele só dispara se for apertado duas vezes, útil para qualquer coisa poderosa, como a confirmação de um banimento

Um botão pode encerrar a própria tarefa com task:destroy(), que é o que os prompts de uso único, como o do ;teleport, fazem.


task.client:run Servidor

task.client:run(player: Player?, ...)
task.client:runAll(...)
task.client:runOthers(originPlayer: Player, ...)
task.client:runNearby(originPlayer: Player?, radius: number, ...)

Executa o comando de cliente correspondente nos dispositivos dos jogadores, repassando direto qualquer argumento extra. run atinge um jogador, runAll todos, runOthers todos menos o originPlayer, e runNearby quem estiver dentro de radius studs. Veja Rede.


task.client:expose Servidor

task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})

Garante que as instâncias realmente chegaram ao jogador antes de o seu código de cliente ir procurar por elas. O streaming pode segurar coisas, então tudo que você criar no servidor e usar no cliente deve passar por aqui primeiro.


task.server:replicate Cliente

task.server:replicate(...)

Envia valores de um comando de cliente de volta para o servidor, onde eles chegam na mesma tarefa. Defina task.client.replicator no servidor para escolher para quem eles seguem, e então eles chegam na função replication daquele comando. Veja Rede.


task:tween Compartilhado

task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween

Toca um tween que é limpo junto com a tarefa, então nunca dura mais que o comando.


task:createSound Compartilhado

task:createSound(soundType: SoundType?): Sound

Cria um Sound que pertence à tarefa e é limpo por ela. O Volume e o Pitch desse som podem então ser configurados por todos os jogadores em YouSettings. O SoundType é "Command" por padrão, se não for definido.


task:onEnded Compartilhado

task:onEnded(callback: () -> ())

Executa seu callback toda vez que a tarefa termina. Equivale a fazer task.janitor:add(callback).


task:onEndedForGood Compartilhado

task:onEndedForGood(callback: () -> ())

Executa seu callback só quando a tarefa terminou E nenhuma tarefa idêntica foi criada logo em seguida. Isso é útil para comandos como ;serverLock Admin, que mostra um aviso quando o comando roda ("This server has been locked for Admins") e quando termina ("This server has been unlocked"). Se em seguida rodarmos ;serverLock Mod, não queremos que o comando anterior mostre o aviso de 'fim', só queremos o novo aviso de 'início'.


task:destroy Compartilhado

task:destroy()

Encerra a tarefa à força e limpa tudo que pertence a ela. É isso que o ;un chama por baixo dos panos.


Agendamento Compartilhado

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) -> ())

São versões do agendador task do próprio Roblox que reconhecem a tarefa. Elas são essenciais para que o comando continue vivo enquanto estiver ativo, ou para que sejam canceladas automaticamente quando a tarefa for limpa (como quando alguém usa undo antes de a tarefa terminar). Use-as como você usaria os métodos de task do Roblox e o HD Admin cuida do resto internamente.

Propriedades

task.target Servidor

task.target: Player

O jogador em quem o comando está rodando. Se o seu primeiro argumento é Player, sempre existe um, porque o HD Admin divide a execução em uma tarefa separada para cada jogador encontrado, então você pode usá-lo sem verificar. Comandos que recebem um argumento coletivo Players não são divididos assim, então ele fica vazio. task.targetUserId guarda o UserId dele e existe mesmo com o jogador offline.


task.qualifiers Servidor

task.qualifiers: {[string]: {string}}

Quem foi escolhido como alvo na string original do comando. ;clone others resulta em {others = {}}, enquanto um ;clone sozinho resulta em uma tabela vazia. É sempre uma tabela, então dá para ler direto com segurança.


task.caller Servidor

task.caller: Player?

Quem executou o comando, ou nil quando foi o servidor (ou quando, em um servidor que recebe um comando global, quem executou não está no seu servidor). task.callerUserId sempre existe, então use esse se você precisar do UserId.


task.janitor Compartilhado

task.janitor:add(item): typeof(item)

Um objeto Janitor ao qual você pode dar instâncias, conexões e funções para ajudar na limpeza automática delas. Por exemplo:

local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart


task.config Servidor

task.config: {[string]: any}

A tabela config do próprio comando, incluindo qualquer coisa que um pacote tenha mudado por meio de modify em Config > Commands. É assim que um comando lê uma configuração que o dono do jogo deve poder mudar, como as listas de permitidos e bloqueados do ;insert.


task.extra Compartilhado

task.extra: {[string]: any}

Uma tabela de informações adicionais que você pode preencher e que continua existindo após a desativação, até a tarefa ser completamente encerrada.


task.isActive Compartilhado

task.isActive: boolean

true enquanto a tarefa está rodando, false a partir do momento em que ela começa a terminar. Use dentro de loops para que o efeito pare na hora se, por exemplo, a tarefa for encerrada à força.


task.commandKey Compartilhado

task.commandKey: string

O nome do comando que esta tarefa está executando, em minúsculas.


task.isReplay Servidor

task.isReplay: boolean

true quando um comando permanente salvo está sendo reexecutado na inicialização de um servidor, em vez de alguém tê-lo executado agora. Útil para limitar prompts em comandos permanentes que não queremos que quem executou veja automaticamente de novo (como um prompt do ;music ao entrar em cada servidor novo).