Aller au contenu

Commandes personnalisées

Tip

Tu peux parcourir des commandes bonus ici.

Commandes

Les commandes sont simplement des tables d'informations qui décrivent ce qu'elles sont et comment elles doivent s'exécuter. Elles sont conçues ainsi pour quelques raisons clés :

Mémoire Quand une commande est lancée, elle peut maintenant être représentée comme une "tâche" que le staff peut facilement voir et annuler. Les tâches se nettoient toutes seules, donc la mémoire n'est jamais perdue, et elles sont conçues pour que tu n'aies même pas à écrire une fonction undo séparée.
Portée Comme les tâches ne dépendent plus d'un joueur précis qui lance la commande (c'est-à-dire l'appelant), n'importe quelle commande fonctionne avec n'importe quel modificateur, ce qui veut dire que les commandes que tu écris peuvent être diffusées tout de suite à tous les serveurs.
Sécurité Les arguments sont validés avant que run soit appelé, donc un argument Player arrive comme un vrai Player, un Number arrive toujours dans la plage autorisée, etc. Ton code ne manipule jamais de texte brut, et les appelants ne peuvent jamais lancer une commande que leurs rôles ne permettent pas.
Interface La page Run, les suggestions de la barre de commandes et les autocomplétions sont générées automatiquement à partir de tes args, donc chaque commande que tu écris est tout de suite utilisable par les joueurs qui ne peuvent pas utiliser le chat.
Typé Les commandes sont entièrement typées, donc annoter tes commandes avec CommandAPI.Commands te donne des autocomplétions et des avertissements de type pendant que tu écris.

Crée les tiennes

Dans ConfigCommands, étends simplement le module Custom existant, ou ajoute ton propre module avec autant de tables de commandes que tu veux :

image

--!strict
-- LOCAL
local TAGS = {"CoolCommands"}
local StarterPlayer = game:GetService("StarterPlayer")
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
local getHumanoid = CommandAPI.getHumanoid
local getHRP = CommandAPI.getHRP

-- COMMANDS
local commands: CommandAPI.Commands = {

    --------------------
    {
        name = "Jump",
        args = {"Player"},
        tags = TAGS,
        run = function(task: CommandAPI.Task)
            local target = task.target
            local humanoid = getHumanoid(target)
            if not humanoid then return end
            humanoid.Jump = true
        end,
    },

    --------------------
    {
        name = "Fire",
        args = {"Player"},
        tags = TAGS,
        run = function(task: CommandAPI.Task)
            local target = task.target
            local hrp = getHRP(target)
            if not hrp then return end
            task:keep("UntilTargetRespawns")
            local fire = task.janitor:add(Instance.new("Fire"))
            fire.Parent = hrp
        end,
    },

    --------------------

}

return commands

Commandes client

Par défaut, le code d'une commande n'est disponible et exécuté que sur le serveur, alors que tu peux avoir besoin qu'il tourne sur le client. Pour ça, tu peux ajouter un ModuleScript nommé Client sous le module de commandes, avec des tables de commandes dont les valeurs name correspondent aux commandes du serveur :

image

--!strict
-- LOCAL
local TAGS = {script.Name}
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)

-- COMMANDS
local commands: CommandAPI.Commands = {

    --------------------
    {
        name = "Flash",
        args = {"Player"},
        tags = TAGS,
        run = function(task: CommandAPI.Task)
            local target = task.target
            task.client:run(target)
        end,
    },

    --------------------

}

return commands

image

--!strict
-- LOCAL
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
local Players = game:GetService("Players")
local TweenService = game:GetService("TweenService")

-- COMMANDS
local clientCommands: CommandAPI.ClientCommands = {

    --------------------
    {
        name = "Flash",
        run = function(task: CommandAPI.Task)
            local localPlayer = Players.LocalPlayer
            local playerGui = localPlayer:FindFirstChildOfClass("PlayerGui")
            if not playerGui then
                return
            end
            local screenGui = Instance.new("ScreenGui")
            screenGui.Name = "HDCustomFlash"
            screenGui.IgnoreGuiInset = true
            screenGui.DisplayOrder = 999
            local frame = Instance.new("Frame")
            frame.BackgroundColor3 = Color3.new(1, 1, 1)
            frame.Size = UDim2.fromScale(1, 1)
            frame.Parent = screenGui
            screenGui.Parent = playerGui
            local tween = TweenService:Create(frame, TweenInfo.new(1), {BackgroundTransparency = 1})
            tween.Completed:Once(function()
                screenGui:Destroy()
            end)
            tween:Play()
        end,
    },

    --------------------

}

return clientCommands

Contient des images clignotantes. Clique pour voir

Info

Tu n'as rien à répliquer toi-même. Le framework détecte tout module enfant nommé Client et le déplace automatiquement chez les joueurs.


Champs d'une commande

Tous les champs sauf name sont optionnels :

Nom
name Shared Le titre de la commande affiché, et ce que les joueurs tapent après leur préfixe. Il sert aussi de nom d'annulation, donc ;speed se termine avec ;unspeed
aliases Server D'autres noms qui déclenchent cette commande``
undoAliases Server Des noms qui annulent la commande au lieu de la lancer (par ex. NoClip utilise {"Clip"})
description Server Une phrase affichée sous la commande sur sa page Run
credit Server Qui créditer pour la commande (par ex. {"GigsD4X"})
Exécution
args Server Les arguments que prend ta commande (par ex. "Player", "Text", "Number", etc. Tu trouves la liste complète dans MainModuleValueModulesParserArgs
run Shared Le code de ta commande. Sur le serveur, il reçoit une tâche et les arguments validés, alors que sur le client il reçoit une tâche puis ce que le serveur lui a passé dans task.client:run
replication Client Une fonction où arrivent les données renvoyées par le serveur. Ton client appelle task.server:replicate, le task.client.replicator du serveur choisit qui les reçoit, puis cette fonction s'exécute sur leur client
config Server Des valeurs par défaut que les créateurs de jeux peuvent changer via modify quand ils chargent les commandes internes
cooldown Server Le nombre de secondes à attendre après la fin de la commande avant qu'elle puisse être relancée
stackable Server En général une seule commande peut être active à la fois sur un joueur ou un serveur, mais quand c'est true, plusieurs peuvent l'être en même temps
groups Server Les commandes d'un même groupe s'annulent entre elles sur le même joueur (par ex. Fly et NoClip sont toutes les deux dans le groupe "Flight", donc en lancer une termine l'autre) et partagent un cooldown. Deux groupes ont un sens particulier : "Prompt" marque les commandes de type message, qui consomment la limite de texte d'une par minute même sans rien taper et sont filtrées par le paramètre Block prompts, et "Map" marque les commandes qui modifient la map, donc la première à s'exécuter garde discrètement une copie pour ;clearmap
Portée
tags Server Les tags dont cette commande héritera, que les rôles utilisent ensuite pour décider quelles commandes hériter
disableModifiers Server Empêche d'utiliser des modificateurs sur la commande
disableGlobalModifiers Server Empêche d'utiliser les modificateurs globaux (par ex. global, perm, join, etc) sur la commande
Interface
order Server Sa position sur la page des commandes. Les nombres les plus petits passent en premier
hide Server Cache la commande de la page Commands
autoPreview Server Quand une commande est lancée via le chat ou le bouton d'aperçu rapide, elle ouvre la page Run au lieu de s'exécuter (par ex. Ban l'utilise pour confirmer les détails d'abord)

Arguments personnalisés

Les arguments intégrés (dans MainModuleValueModulesParserArgs) couvrent la plupart de ce dont tu as besoin, mais si tu veux créer les tiens, tu peux le faire dans Config > Args :

image

return function(Args)
    return {

        ["Radius"] = Args.createAliasOf("Number", {
            display = "Radius",
            min = 0,
            max = 500,
            step = 1,
            default = 50,
        }),

    }
end

Warning

Vérifie que le nom que tu choisis ne correspond à aucun argument intégré de HD Admin, sinon un avertissement s'affichera au démarrage et l'un des deux prendra le dessus sur l'autre.

Si tu veux modifier le ou les arguments d'une seule commande, tu peux à la place remplacer le nom de l'argument par une table d'argument :

args = {
    "Player",
    {arg = "Number", display = "Speed", default = 50, min = 0, max = 1000, step = 1, logarithmic = true},
},
args = {
    "Player",
    "Number",
},

Tip

C'est pratique quand tu veux changer les contraintes d'un argument sans remplacer entièrement son comportement : image

Texte que les autres joueurs voient

Les politiques de sécurité d'âge de Roblox limitent à un par minute le texte qu'un joueur montre aux autres. HD Admin filtre chaque argument texte et consomme une limite d'une minute pour son type, que partagent toutes les commandes de ce type :

Arg À utiliser pour
"Text" Tout ce qui est affiché comme message, indice, notification, alerte ou sondage
"SurfaceText" Les noms, titres et libellés affichés au-dessus d'un joueur ou dans le monde
"ChatText" Les tags de chat et les noms de chat
"Reason" Les raisons d'expulsion et de bannissement

Pour choisir le type toi-même, ajoute textSurface à une table d'argument, comme {arg = "Text", textSurface = "SurfaceText"}. Utilise "None" pour du texte qui ne s'affiche aux autres que parfois, puis appelle checkTextLimit au moment où il s'affiche.


Args

Pour récupérer un argument d'une commande, utilise task:getArg() en précisant son nom ou son index :

args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
    local target = task:getArg("Player")
    local number = task:getArg("Number")
    -- ...
end
args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
    local target = task:getArg(1)
    local number = task:getArg(2)
    -- ...
end

Note

Récupérer un argument par son index est nécessaire quand une commande a deux arguments identiques ou plus : {"Player", "Number", "Number"}

Quand "Player" est utilisé comme premier argument, la commande est lancée séparément sur chaque joueur ciblé. Dans ce cas, tu peux utiliser task.target pour désigner le "Player" :

args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
    local target = task.target
    local number = task:getArg("Number")
    -- ...
end

Persistance

Une tâche est détruite dès que run se termine. C'est bien pour des commandes comme ;jump qui finissent tout de suite... mais moins pour des commandes comme music dont les effets doivent rester. Du coup, toute commande qu'on veut garder en vie doit passer par task:keep :

task:keep("UntilTargetRespawns")
Persistance La tâche se termine quand
"UntilTargetRespawns" la cible réapparaît ou quitte le jeu
"UntilTargetLeaves" la cible quitte le jeu
"UntilCallerRespawns" celui qui a lancé la commande réapparaît ou quitte le jeu
"UntilCallerLeaves" celui qui a lancé la commande quitte le jeu
"Indefinitely" quelqu'un la termine avec ;un, ou le joueur quitte le jeu

Tip

Tu peux combiner plusieurs "keeps". Par exemple, faire task:keep("UntilTargetLeaves") et task:keep("UntilCallerLeaves") terminera la commande dès que son appelant ou sa cible quitte le serveur.


Buffs

Changer des propriétés, comme WalkSpeed dans les humanoïdes, est en général simple. Tu mets la propriété à la valeur voulue et c'est fini. Ça devient un peu plus compliqué quand plusieurs commandes sont impliquées.

Imaginons que ta vie est à 100, et que tu lances ;health me 500 puis ;god me. ;health met d'abord ta vie à 500, puis ;god la change en 99999. Ça marche bien... mais que se passe-t-il si tu veux ensuite retirer la tâche god en gardant health ? Dans beaucoup de systèmes d'admin, annuler god remettrait simplement ta vie à 100, en ignorant la tâche health encore active. Ce n'est pas souhaitable, et c'est là que les buffs sont utiles :

task:buff(target, "WalkSpeed", function(hasEnded: boolean, original: any)
    local humanoid = getHumanoid(target)
    local before = if humanoid then humanoid.WalkSpeed else StarterPlayer.CharacterWalkSpeed
    if humanoid then
        humanoid.WalkSpeed = if hasEnded then original else task:getArg("Number")
    end
    return before
end)

Un buff, c'est juste ton code plus le groupe auquel il appartient (comme "WalkSpeed" dans cet exemple). À chaque fois qu'une tâche de ce groupe démarre ou se termine, tous ses buffs sont relancés dans l'ordre, donc ta propriété finit toujours sur la valeur voulue par la dernière commande.

Tu peux aussi renvoyer une valeur d'origine, c'est-à-dire la valeur retenue par le tout premier buff du groupe. Quand le dernier buff est retiré, ta propriété peut être remise à cette valeur d'origine, donc ta vie revient à 100 plutôt qu'à ce que la commande précédente a laissé derrière elle.


Réseau

Pour atteindre nos commandes client depuis le serveur, on utilise task.client :

local part = Instance.new("Part")
task.client:expose(target, part)
task.client:run(target, part , "Hello this is a part from the server")
run = function(task: CommandAPI.Task, part, message)
    print("part, message =", part, message)
end

Important

Utiliser task:expose est indispensable pour les instances et modèles nouvellement créés sur le serveur qu'on veut partager avec les clients, sinon ils risquent de ne pas être reçus

Il arrive souvent que le client veuille aussi partager des informations avec le serveur, ou même avec d'autres clients. Par exemple, avec ;laserEyes, on veut que les autres clients voient nos rayons laser et où on les pointe. Pour ça, on utilise task.server :

-- The client's device knows something that others don't
task.server:replicate(targetCFrame, lookCFrame)
-- Your chance to pick who sees it, and to throw out anything dodgy
task.client.replicator = function(replicateTo, targetCFrame, lookCFrame)
    if typeof(targetCFrame) ~= "CFrame" or typeof(lookCFrame) ~= "CFrame" then
        return
    end
    for _, player in getTargets("OthersNearby", target, 100) do
        replicateTo(player, target, targetCFrame, lookCFrame)
    end
end
-- Runs on every client the server chose in the same client module
replication = function(target: Player, targetCFrame: CFrame, lookCFrame: CFrame)
    -- Show it happening on their screen
end,

Important

Il est important de vérifier que les valeurs reçues dans le replicator sont bien celles que tu attends, car le client peut toujours envoyer des valeurs malveillantes ou différentes

Info

Rien n'arrive à un autre joueur si ton replicator ne l'envoie pas, donc un client ne peut pas diffuser discrètement ce qu'il veut. Le nombre de requêtes de réplication est aussi plafonné en interne, et les abus possibles côté client sont pris en compte


Invites

Lancer des commandes, c'est bien... mais les ajuster pendant qu'elles tournent, c'est encore mieux. C'est là que tu peux utiliser task:bindPrompt pour donner à l'appelant une carte qu'il peut modifier :

local function applyLaserColour()
    local colour = task:getArg("Color")
    -- set the beam colours, eye colours, etc
end

applyLaserColour()
task:bindPrompt({
    args = {"Color"},
    onChange = applyLaserColour,
})

Tu peux aussi ajouter des buttons pour des actions ponctuelles :

task:bindPrompt({
    title = "Teleport",
    text = `Click to teleport to '{placeName}'`,
    deactivate = false,
    endOnClose = true, -- dismissing the card ends its task
    buttons = {
        {
            label = "Teleport",
            onActivate = onActivate,
        },
    },
})

Toutes les clés que la carte accepte, y compris les boutons confirm, les interrupteurs en plus et le bouton Re-run, sont listées dans task:bindPrompt. Pour les simples notifications et messages, vois prompt.

Tu peux en apprendre plus sur les tâches et leurs méthodes disponibles dans Task API.