API des tâches
Chaque fois qu'une commande s'exécute, elle crée une tâche pour chaque cible. Cette tâche est ensuite transmise à run et décide de la durée de vie de la commande, du réseau, du nettoyage et de bien d'autres choses.
Méthodes¶
task:keep Server¶
task:keep(persistence: Persistence?)
Garde la tâche en vie après le retour de run, sinon elle est détruite immédiatement. Les options sont "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" et "Indefinitely". Si tu l'appelles plusieurs fois, les conditions se cumulent, et la tâche se termine dès que l'une d'elles se produit en premier. Voir Persistence.
task:getArg Server¶
task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any
Lit la valeur validée de l'argument dont tu donnes le nom ou la position. Cette valeur peut venir du default de l'argument, de la valeur validée donnée par l'appelant, d'une valeur validée qu'une invite a modifiée, ou d'une valeur définie avec task:setArg().
Passe true en second paramètre pour recevoir nil quand l'appelant n'a pas donné l'argument et que sa valeur vient uniquement du default. C'est pratique pour les arguments optionnels quand tu veux retomber sur ton propre comportement, comme ;message qui calcule une durée à partir de la longueur du texte tant qu'aucune n'a été saisie.
task:setArg Server¶
task:setArg(nameOrPosition: string | number, value: any)
Change la valeur de l'argument dont tu donnes le nom ou la position.
task:buff Server¶
task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)
Modifie une propriété, réapplique les changements sur cette propriété quand les buffs du même groupe changent, puis remet la propriété à sa valeur d'origine à la fin de la tâche. Voir Buffs.
task:updateBuffs Server¶
task:updateBuffs(player: Player?, group: string?)
Relance les buffs pour ce joueur et ce groupe. C'est géré automatiquement dans la plupart des cas, donc ce n'est utile que si tu veux forcer la mise à jour de tout ce groupe.
task:redo Server¶
task:redo(player: Player?, callback: () -> ())
Exécute ton callback tout de suite, puis à nouveau à chaque respawn du joueur tant que la tâche est active. Utile pour les effets qui disparaîtraient sinon au respawn.
task:bindPrompt Server¶
task:bindPrompt(config)
Donne à l'appelant une invite d'action liée à la commande, comme le curseur de ;speed ou la couleur des yeux 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,
Config
| Key | Type | What it does |
|---|---|---|
title |
string | Le titre de l'invite, par défaut le nom de la commande |
text |
string | Le texte principal |
subtext |
string | Une ligne plus petite sous le texte |
audience |
Player | Qui voit l'invite, par défaut task.target |
duration |
number | Nombre de secondes avant que l'invite se ferme toute seule. Vaut 0 par défaut, ce qui représente une durée infinie |
args |
table | Les arguments de la commande à exposer comme contrôles, voir Controls |
onChange |
function | function(argName, value), s'exécute après qu'un contrôle a modifié un argument |
toggle |
table | Un interrupteur supplémentaire qui n'est lié à aucun argument, {label = "Trails", value = true, onChange = function(isOn) end} |
buttons |
table | Des boutons d'action ponctuels, voir Buttons |
deactivate |
boolean | Vaut true par défaut, ce qui donne à l'invite un interrupteur qui met la commande en pause et la relance, et un bouton Stop qui la termine. Mets false pour une invite qui ne contient que des boutons |
rerun |
boolean | Ajoute un bouton de relance qui nettoie puis relance la commande. S'affiche uniquement quand deactivate vaut false |
endOnClose |
boolean | Par défaut, fermer l'invite termine la tâche. Avec false, elle continue de tourner jusqu'à ce que le client la ferme |
Contrôles
Pour qu'un argument soit contrôlable depuis l'invite d'action, ajoute son nom à args dans bindPrompt. Un Number devient un curseur, un Color un sélecteur de couleur, un Bool un interrupteur, etc. Dès que le client en modifie un, l'argument est mis à jour et ton onChange se déclenche, donc il suffit de rappeler task:getArg pour lire la nouvelle valeur. Pas besoin de valider quoi que ce soit non plus, chaque valeur est vérifiée exactement comme si elle avait été tapée dans le 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,
Les boutons sont tout aussi simples. Donne à chacun un label et une fonction onActivate, et cette fonction s'exécute sur le serveur chaque fois que le client appuie dessus. Tu peux aussi y mettre des yields (une invite d'achat, un appel DataStore, etc.), le bouton affiche simplement un indicateur de chargement jusqu'à ce que tu aies fini :
| Key | Type | What it does |
|---|---|---|
label |
string | Le texte du bouton |
onActivate |
function | Ce qui se passe quand on appuie dessus |
style |
string | "Primary" par défaut, ou "Neutral" pour un aspect grisé, idéal pour Cancel |
confirm |
boolean | Ajoute une étape Confirm? pour qu'il ne se déclenche qu'après deux appuis, pratique pour tout ce qui est puissant comme une confirmation de bannissement |
Un bouton peut terminer sa propre tâche avec task:destroy(), ce que font les invites à usage unique comme celle de ;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, ...)
Exécute ta commande client correspondante sur les appareils des joueurs, en transmettant tel quel tout ce que tu ajoutes. run cible un seul joueur, runAll tout le monde, runOthers tout le monde sauf l'originPlayer, et runNearby ceux qui sont dans un rayon de radius studs. Voir Networking.
task.client:expose Server¶
task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})
S'assure que ses instances sont bien arrivées chez le joueur avant que ton code client ne parte les chercher. Le streaming peut les retenir, donc tout ce que tu crées côté serveur et utilises côté client doit passer par ici d'abord.
task.server:replicate Client¶
task.server:replicate(...)
Renvoie des valeurs d'une commande client vers le serveur, où elles arrivent sur la même tâche. Définis task.client.replicator sur le serveur pour choisir à qui elles sont ensuite transmises, puis elles arrivent dans la fonction replication de cette commande. Voir Networking.
task:tween Shared¶
task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween
Joue un tween qui est nettoyé avec la tâche, donc il ne survit jamais à la commande.
task:createSound Shared¶
task:createSound(soundType: SoundType?): Sound
Crée un Sound que la tâche possède et nettoie. Le Volume et le Pitch de ce son peuvent ensuite être réglés par chaque joueur dans ses YouSettings. Le SoundType vaut "Command" par défaut s'il n'est pas défini.
task:onEnded Shared¶
task:onEnded(callback: () -> ())
Exécute ton callback chaque fois que la tâche se termine. C'est équivalent à task.janitor:add(callback).
task:onEndedForGood Shared¶
task:onEndedForGood(callback: () -> ())
Exécute ton callback uniquement quand la tâche est terminée ET qu'aucune tâche identique n'est créée juste après. C'est utile pour des commandes comme ;serverLock Admin, qui affiche une notification quand la commande est lancée ("This server has been locked for Admins") et quand elle se termine ("This server has been unlocked"). Si on lance ensuite ;serverLock Mod, on ne veut pas que la commande précédente affiche sa notification de fin, on veut seulement la nouvelle notification de lancement.
task:destroy Shared¶
task:destroy()
Termine la tâche de force et nettoie tout ce qu'elle possède. C'est ce qu'appelle ;un en coulisses.
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) -> ())
Ce sont des versions de la planification task de Roblox qui connaissent la tâche. Elles sont indispensables pour que la commande reste en vie tant qu'elle est active, et pour qu'elles soient annulées automatiquement quand leur tâche est nettoyée (par exemple quand quelqu'un lance undo avant la fin de la tâche). Utilise-les comme tu utiliserais les méthodes task de Roblox, HD Admin s'occupe du reste en interne.
Propriétés¶
task.target Server¶
task.target: Player
Le joueur sur lequel la commande s'exécute. Si ton premier argument est Player, il y en a toujours un, car HD Admin sépare l'exécution en une tâche distincte pour chaque joueur trouvé, donc tu peux l'utiliser sans vérifier. Les commandes qui prennent un argument collectif Players ne sont pas séparées ainsi, donc il reste vide. task.targetUserId contient son UserId et existe même quand il est hors ligne.
task.qualifiers Server¶
task.qualifiers: {[string]: {string}}
Qui l'appelant a ciblé dans sa chaîne de commande d'origine. ;clone others te donne {others = {}}, alors qu'un simple ;clone te donne une table vide. C'est toujours une table, donc tu peux la lire directement sans risque.
task.caller Server¶
task.caller: Player?
Celui qui a lancé la commande, ou nil quand c'est le serveur (ou dans un serveur qui reçoit une commande globale dont l'appelant n'est pas dans ton serveur). task.callerUserId est toujours présent, donc utilise-le plutôt si tu as besoin de son UserId.
task.janitor Shared¶
task.janitor:add(item): typeof(item)
Un objet Janitor auquel tu peux confier des instances, des connexions et des fonctions pour qu'elles soient nettoyées automatiquement. Par exemple :
local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart
task.config Server¶
task.config: {[string]: any}
La table config propre à la commande, y compris tout ce qu'un pack a changé via modify dans Config > Commands. C'est ainsi qu'une commande lit un paramètre que le propriétaire du jeu doit pouvoir modifier, comme les listes d'autorisation et de refus de ;insert.
task.extra Shared¶
task.extra: {[string]: any}
Une table d'informations supplémentaires que tu peux remplir, et qui survit à la désactivation jusqu'à la fin complète de la tâche.
task.isActive Shared¶
task.isActive: boolean
true tant que la tâche tourne, false dès qu'elle commence à se terminer. Utilise-le dans tes boucles pour que ton effet s'arrête tout de suite s'il a été terminé de force, par exemple.
task.commandKey Shared¶
task.commandKey: string
Le nom de la commande que cette tâche exécute, en minuscules.
task.isReplay Server¶
task.isReplay: boolean
true quand une commande permanente sauvegardée est rejouée au démarrage d'un serveur, au lieu d'être lancée par quelqu'un à l'instant. Utile pour limiter les invites dans les commandes permanentes que l'appelant ne doit pas revoir automatiquement (comme l'invite de ;music à chaque arrivée dans un nouveau serveur).