Saltar a contenido

Task API

Cada vez que se ejecuta un comando, crea una tarea por cada objetivo. Esa tarea se pasa a run y se encarga de cuánto tiempo vive el comando, de la red, de la limpieza y de mucho más.

Métodos

task:keep Server

task:keep(persistence: Persistence?)

Mantiene viva la tarea después de que run termine. Si no lo usas, se destruye de inmediato. Tus opciones son "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" y "Indefinitely". Si lo llamas más de una vez, las condiciones se combinan, así que la tarea termina con la que ocurra primero. Consulta Persistence.


task:getArg Server

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

Lee el valor validado del argumento con ese nombre o posición. Ese valor puede venir del default del argumento, del valor validado que dio quien ejecutó el comando, de un valor validado al que lo cambió un mensaje, o de un valor establecido con task:setArg().

Pasa true como segundo argumento para recibir nil cuando quien ejecutó el comando nunca dio el argumento y su valor solo vino del default. Es útil para argumentos opcionales en los que quieres usar tu propio comportamiento por defecto, como hace ;message, que calcula la duración a partir del largo del texto salvo que se haya escrito una.


task:setArg Server

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

Cambia el valor del argumento con ese nombre o posición.


task:buff Server

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

Cambia una propiedad, vuelve a aplicar los cambios a esa propiedad cuando cambian los buffs del mismo grupo, y luego restablece la propiedad a su valor original cuando termina la tarea. Consulta Buffs.


task:updateBuffs Server

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

Vuelve a ejecutar los buffs de ese jugador y grupo. Esto se maneja automáticamente en la mayoría de los casos, así que solo sirve cuando quieres forzar la actualización de todo ese grupo.


task:redo Server

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

Ejecuta tu callback de inmediato y luego otra vez cada vez que el jugador reaparece mientras la tarea sigue viva. Es útil para efectos que de otra forma desaparecerían al reaparecer.


task:bindPrompt Server

task:bindPrompt(config)

Le da a quien ejecutó el comando un mensaje de acción ligado al comando, como el control deslizante de ;speed o el color de ojos de ;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,

Configuración

Key Type What it does
title string El encabezado del mensaje, por defecto el nombre del comando
text string El texto principal
subtext string Una línea más pequeña debajo del texto
audience Player Quién ve el mensaje, por defecto task.target
duration number Segundos antes de que el mensaje se cierre solo. Por defecto es 0, que representa una duración infinita
args table Los argumentos del comando que se exponen como controles, consulta Controles
onChange function function(argName, value), se ejecuta después de que un control cambia un argumento
toggle table Un interruptor extra de activado/desactivado que no está ligado a un argumento, {label = "Trails", value = true, onChange = function(isOn) end}
buttons table Botones de acción únicos, consulta Botones
deactivate boolean Por defecto es true, lo que le da al mensaje un interruptor que pausa y reanuda el comando, y un botón Stop que lo termina. Ponlo en false para un mensaje que solo tiene botones
rerun boolean Agrega un botón para volver a ejecutar que limpia y ejecuta el comando otra vez. Solo aparece cuando deactivate es false
endOnClose boolean Por defecto, cerrar el mensaje termina la tarea. Si lo pones en false, sigue ejecutándose hasta que el cliente lo cierre

Controles

Para que un argumento se pueda controlar desde el mensaje de acción, agrega su nombre a args dentro de bindPrompt. Un Number se convierte en un control deslizante, un Color en un selector de color, un Bool en un interruptor, etc. Cada vez que el cliente cambia uno, el argumento se actualiza y se dispara tu onChange, así que solo llama a task:getArg otra vez para leer el nuevo valor. Tampoco necesitas validar nada, cada valor se comprueba igual que si se hubiera escrito en el 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,

Botones

Los botones son igual de fáciles. Dale a cada uno un label y una función onActivate, y esa función se ejecuta en el servidor cada vez que el cliente lo presiona. También puedes yieldear ahí (un mensaje de compra, una llamada a un DataStore, etc.), porque el botón simplemente muestra un indicador de carga hasta que termines:

Key Type What it does
label string El texto del botón
onActivate function Lo que pasa al presionarlo
style string "Primary" por defecto, o "Neutral" para un aspecto en gris, ideal para Cancel
confirm boolean Agrega un paso Confirm? para que solo se active al presionarlo dos veces, útil para cualquier cosa poderosa como la confirmación de un vetado

Un botón puede terminar su propia tarea con task:destroy(), que es lo que hacen los mensajes de comando de un solo uso como ;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, ...)

Ejecuta tu comando de cliente correspondiente en los dispositivos de los jugadores, pasando tal cual cualquier dato extra. run apunta a un jugador, runAll a todos, runOthers a todos menos al originPlayer, y runNearby a quienes estén dentro de radius studs. Consulta Networking.


task.client:expose Server

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

Se asegura de que sus instancias hayan llegado al jugador antes de que tu código de cliente vaya a buscarlas. El streaming puede retener cosas, así que todo lo que crees en el servidor y uses en el cliente debería pasar primero por aquí.


task.server:replicate Client

task.server:replicate(...)

Envía valores de un comando de cliente de vuelta al servidor, donde llegan a la misma tarea. Define task.client.replicator en el servidor para elegir a quién se los pasa después, y luego llegan a la función replication de ese comando. Consulta Networking.


task:tween Shared

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

Reproduce un tween que se limpia junto con la tarea, así que nunca dura más que el comando.


task:createSound Shared

task:createSound(soundType: SoundType?): Sound

Crea un Sound que pertenece a la tarea y que ella limpia. El Volume y el Pitch de este sonido pueden ser configurados por todos los jugadores en YouSettings. El SoundType por defecto es "Command" si no lo defines.


task:onEnded Shared

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

Ejecuta tu callback cada vez que la tarea termina. Es equivalente a hacer task.janitor:add(callback).


task:onEndedForGood Shared

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

Ejecuta tu callback solo cuando la tarea ha terminado Y no se crea una tarea idéntica justo después. Es útil para comandos como ;serverLock Admin, que muestra un aviso cuando se ejecuta ("This server has been locked for Admins") y otro cuando termina ("This server has been unlocked"). Pero si después ejecutáramos ;serverLock Mod, no queremos que el comando anterior muestre su aviso de 'fin', solo queremos que aparezca el nuevo aviso de 'inicio'.


task:destroy Shared

task:destroy()

Termina la tarea a la fuerza y limpia todo lo que posee. Esto es lo que llama ;un internamente.


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

Son versiones de los métodos de programación task de Roblox que están al tanto de la tarea. Son esenciales para que el comando se mantenga vivo mientras está activo, o para que se cancelen automáticamente cuando se limpia su tarea (por ejemplo, cuando alguien llama a undo antes de que la tarea termine). Úsalos como usarías normalmente los métodos task de Roblox y HD Admin se encarga del resto internamente.

Propiedades

task.target Server

task.target: Player

El jugador sobre el que se ejecuta el comando. Si tu primer argumento es Player, siempre hay uno, porque HD Admin divide la ejecución en una tarea separada por cada jugador que coincide, así que puedes usarlo sin comprobar nada. Los comandos que reciben un argumento colectivo Players no se dividen así, por lo que queda vacío. task.targetUserId guarda su UserId y está disponible incluso cuando está desconectado.


task.qualifiers Server

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

A quién apuntó quien ejecutó el comando en su texto original. ;clone others te da {others = {}}, mientras que un ;clone solo te da una tabla vacía. Siempre es una tabla, así que es seguro leerla directamente.


task.caller Server

task.caller: Player?

Quien ejecutó el comando, o nil cuando lo ejecutó el servidor (o cuando un servidor recibe un comando global y quien lo ejecutó no está en tu servidor). task.callerUserId siempre está presente, así que úsalo si necesitas su UserId.


task.janitor Shared

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

Un objeto Janitor al que puedes darle instancias, conexiones y funciones para que se limpien automáticamente. Por ejemplo:

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


task.config Server

task.config: {[string]: any}

La tabla config propia del comando, incluido cualquier cambio que un paquete haya hecho mediante modify en Config > Commands. Así es como un comando lee un ajuste que el propietario del juego debe poder cambiar, como las listas de permitidos y denegados de ;insert.


task.extra Shared

task.extra: {[string]: any}

Una tabla de información adicional a la que puedes agregar datos y que sobrevive a la desactivación hasta que la tarea termina por completo.


task.isActive Shared

task.isActive: boolean

true mientras la tarea se está ejecutando, false una vez que empieza a terminar. Úsalo dentro de bucles para que tu efecto se detenga de inmediato si, por ejemplo, la tarea se terminó a la fuerza.


task.commandKey Shared

task.commandKey: string

El nombre en minúsculas del comando que ejecuta esta tarea.


task.isReplay Server

task.isReplay: boolean

true cuando un comando permanente guardado se vuelve a ejecutar al iniciar un servidor, en lugar de que alguien lo ejecute en ese momento. Es útil para limitar los mensajes en comandos permanentes que no queremos que quien los ejecutó vea automáticamente otra vez (como un mensaje de ;music al entrar a cada servidor nuevo).