Task API
Every time a command runs, it creates a task for every target. This task is then passed through to run, and is responsible for how long the command lives for, networking, cleanup and much more.
Methods¶
task:keep Server¶
task:keep(persistence: Persistence?)
Keeps the task alive after run returns, otherwise it's destroyed straight away. Your options are "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" and "Indefinitely". Call it more than once and the conditions combine, so the task ends on whichever happens first. See Persistence.
task:getArg Server¶
task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any
Reads the validated value of the given arg name or position. This value can be determined by its arg's default, the validated value given by the caller, a validated value a prompt changed it to, or a value set with task:setArg().
Pass true as the second argument to receive nil when the caller never gave the arg and its value only came from the arg's default. This is handy for optional args where you want to fall back to your own behaviour, like how ;message works out a duration from the text length unless one was typed.
task:setArg Server¶
task:setArg(nameOrPosition: string | number, value: any)
Changes the value of the given arg name or position.
task:buff Server¶
task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)
Changes a property, re-applies the changes to that property when buffs in the same group change, then resets the property to its original value when the task ends. See Buffs.
task:updateBuffs Server¶
task:updateBuffs(player: Player?, group: string?)
Re-runs the buffs for that player and group. This is handled automatically for most scenarious, so only useful when you forcefully want to update everything in that group.
task:redo Server¶
task:redo(player: Player?, callback: () -> ())
Runs your callback right away, then again every time the player respawns while the task is alive. Useful for effects which would otherwise vanish on respawn.
task:bindPrompt Server¶
task:bindPrompt(config)
Gives the caller a card they can adjust while the command runs, like the slider on ;speed. List the args to expose and handle onChange, or give it buttons for one-off actions. See Prompts.
task.client:run Server¶
task.client:run(player: Player?, ...)
task.client:runAll(...)
task.client:runOthers(originPlayer: Player, ...)
task.client:runNearby(originPlayer: Player?, radius: number, ...)
Runs your matching client command on players' devices, passing anything extra straight through. run targets one player, runAll everyone, runOthers everyone but the originPlayer, and runNearby those within radius studs. See Networking.
task.client:expose Server¶
task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})
Makes sure its instances have actually reached the player before your client code goes looking for them. Streaming can hold things back, so anything you create on the server and use on the client should go through here first.
task.server:replicate Client¶
task.server:replicate(...)
Sends values from a client command back up to the server, where they land on the same task. Set task.client.replicator on the server to choose who they go on to, then they arrive in that command's replication function. See Networking.
task:tween Shared¶
task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween
Plays a tween which is cleaned up with the task, so it never outlives the command.
task:createSound Shared¶
task:createSound(soundType: SoundType?): Sound
Creates a Sound which the task owns and cleans up. This sounds Volume and Pitch can then be configured by all players under their YouSettings. The SoundType defaults to "Command" if it's not set.
task:onEnded Shared¶
task:onEnded(callback: () -> ())
Runs your callback every time the task ends. This is equivalent to doing task.janitor:add(callback).
task:onEndedForGood Shared¶
task:onEndedForGood(callback: () -> ())
Runs your callback only when the task has ended, AND if no identical task is created right afterwards. This is useful for commands like ;serverLock Admin which displays a notice when the command is run ("This server has been locked for Admins") and finishes ("This server has been unlocked"), except if we were to then run ;serverLock Mod, we don't want the previous command to run its 'finish' notice, we only want to prompt the new 'run' notice.
task:destroy Shared¶
task:destroy()
Ends the task forcefully and cleans up everything it owns. This is what ;un calls behind the scenes.
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) -> ())
These are task-aware wrappers of Roblox's own task scheduling. These are essential so that the command can be kept alive while active, or so that they can be automatically cancelled when their task is cleaned up (such as someone calling undo before the task ends). Just use them as you'd normally use Roblox's task methods and HD Admin handles the rest internally.
Properties¶
task.target Server¶
task.target: Player
The player the command is running on. If your first argument is Player then there's always one, because HD Admin splits the run into a separate task for each matched player, so you can use it without checking. Commands which take a collective Players argument aren't split this way, so it's left empty. task.targetUserId holds their UserId and is there even while they're offline.
task.qualifiers Server¶
task.qualifiers: {[string]: {string}}
Who the caller targetted in their original command string. ;clone others gives you {others = {}}, while a bare ;clone gives you an empty table. It's always a table, so it's safe to read directly.
task.caller Server¶
task.caller: Player?
Whoever ran the command, or nil when the server did (or if within a server receiving a global command where the caller is not in your server). task.callerUserId is always present, so use this instead if you need their UserId.
task.janitor Shared¶
task.janitor:add(item): typeof(item)
A Janitor object which you can give instances, connections and functions to aid in their automatic cleanup. For example:
local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart
task.config Server¶
task.config: {[string]: any}
The command's own config table, including anything a pack changed through modify in Config > Commands. This is how a command reads a setting the game owner is meant to be able to change, like ;insert's allow and deny lists.
task.extra Shared¶
task.extra: {[string]: any}
A table of additional information that you can add to that outlives deactivation until a task is completely ended.
task.isActive Shared¶
task.isActive: boolean
true while the task is running, false once it starts ending. Use this within loops so your effect can stop right away if it was for example forcefully ended.
task.commandKey Shared¶
task.commandKey: string
The lowercased name of the command this task is running.
task.isReplay Server¶
task.isReplay: boolean
true when a saved permanent command is being replayed as a server starts, instead of someone running it right now. Useful for limiting prompts in perm commands that we dont want the caller to see automatically again (such as a ;music prompt when joining each new server).
