Comandos personalizados
Tip
Você pode procurar comandos bônus aqui.
Comandos¶
Comandos são simplesmente tabelas de informação que descrevem o que eles são e como devem rodar. Eles foram desenhados assim por alguns motivos principais:
| Memória | Quando um comando é executado, ele pode ser representado como uma 'tarefa' que a equipe consegue ver e cancelar facilmente. As tarefas se limpam sozinhas, então a memória nunca vaza, e foram pensadas para que você nem precise escrever uma função undo separada. |
| Alcance | Como as tarefas não dependem mais de um jogador específico executando o comando (ou seja, o chamador), qualquer comando funciona com qualquer modificador, o que significa que os comandos que você escreve podem ser transmitidos para todos os servidores na hora. |
| Segurança | Os argumentos são validados antes de run ser chamado, então um argumento Player chega como um Player de verdade, um Number sempre chega dentro do intervalo permitido, etc. Seu código nunca lida com texto bruto, e os chamadores nunca conseguem executar um comando que os cargos deles não podem usar. |
| Interface | O painel Run, as sugestões da barra de comandos e os autocompletes são gerados automaticamente a partir dos seus args, então todo comando que você escreve já pode ser usado por jogadores que não conseguem usar o chat. |
| Tipado | Os comandos são totalmente tipados, então anotar seus comandos com CommandAPI.Commands te dá autocompletes e avisos de tipo enquanto você escreve. |
Crie os seus¶
Em ConfigCommands, basta estender o módulo Custom existente, ou adicionar seu próprio módulo com quantas tabelas de comandos você quiser:

--!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
Comandos de cliente¶
Por padrão, o código de um comando só fica disponível e roda no servidor, mas às vezes você precisa que ele rode no cliente. Para resolver isso, você pode adicionar um ModuleScript chamado Client dentro do módulo de comandos, com tabelas de comandos cujos valores de name batam com os comandos do servidor:
--!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
--!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
Contém imagens piscantes. Clique para ver
Info
Você não replica nada por conta própria. O framework detecta qualquer módulo filho chamado Client e o move para os jogadores automaticamente.
Campos do comando¶
Todo campo, exceto name, é opcional:
| Nomes | |
|---|---|
name Shared |
O título do comando exibido e o que os jogadores digitam depois do prefixo. Ele também serve como nome para desfazer, então ;speed termina com ;unspeed |
aliases Server |
Outros nomes que ativam este comando`` |
undoAliases Server |
Nomes que desfazem o comando em vez de executá-lo (por exemplo, NoClip usa {"Clip"}) |
description Server |
Uma frase mostrada embaixo do comando na página Run dele |
credit Server |
Quem deve receber o crédito pelo comando (por exemplo, {"GigsD4X"}) |
| Execução | |
|---|---|
args Server |
Os argumentos que o seu comando recebe (por exemplo, "Player", "Text", "Number", etc. Você encontra a lista completa em MainModuleValueModulesParserArgs |
run Shared |
O código do seu comando. No servidor, ele recebe uma tarefa e os argumentos validados, e no cliente recebe uma tarefa e depois o que o servidor passou para ele em task.client:run |
replication Client |
Uma função onde chegam os dados retornados do servidor. Seu cliente chama task.server:replicate, o task.client.replicator do servidor escolhe quem recebe, e então isso roda no cliente deles |
config Server |
Valores padrão que os criadores do jogo podem mudar por meio de modify ao carregar comandos internos |
cooldown Server |
Segundos de espera depois que o comando termina até ele poder rodar de novo |
stackable Server |
Normalmente só um comando pode ficar ativo por jogador/servidor ao mesmo tempo, mas quando isto é true, vários podem ficar ativos juntos |
groups Server |
Comandos que compartilham um grupo se desfazem mutuamente no mesmo jogador (por exemplo, Fly e NoClip estão ambos no grupo "Flight", então iniciar um encerra o outro) e compartilham um cooldown. Dois grupos têm um significado extra: "Prompt" marca comandos no estilo de mensagem, que gastam o limite de texto de um por minuto mesmo sem nada digitado e são filtrados pela configuração Block prompts, e "Map" marca comandos que editam o mapa, então o primeiro a rodar guarda uma cópia em silêncio para o ;clearmap |
| Alcance | |
|---|---|
tags Server |
As tags que este comando vai herdar, que depois são usadas pelos cargos para decidir quais comandos herdar |
disableModifiers Server |
Impede que Modificadores sejam usados no comando |
disableGlobalModifiers Server |
Impede que os modificadores globais (por exemplo, global, perm, join, etc) sejam usados no comando |
| Interface | |
|---|---|
order Server |
Sua posição na página de comandos. Números menores vêm primeiro |
hide Server |
Esconde o comando da página Commands |
autoPreview Server |
Quando um comando é executado pelo chat ou pelo botão de pré-visualização rápida, ele abre a página Run em vez de executar o comando (por exemplo, Ban usa isso para confirmar os detalhes antes) |
Argumentos personalizados¶
Os argumentos nativos (em MainModuleValueModulesParserArgs) cobrem a maioria dos argumentos de que você vai precisar, mas se quiser criar os seus, você pode fazer isso em Config > Args:

return function(Args)
return {
["Radius"] = Args.createAliasOf("Number", {
display = "Radius",
min = 0,
max = 500,
step = 1,
default = 50,
}),
}
end
Warning
Confirme que o nome escolhido não é igual ao de nenhum argumento nativo do HD Admin, senão ele vai avisar na inicialização e um dos dois vai prevalecer sobre o outro.
Se quiser modificar o(s) argumento(s) de um único comando, você pode trocar o nome do argumento por uma tabela de argumento:
args = {
"Player",
{arg = "Number", display = "Speed", default = 50, min = 0, max = 1000, step = 1, logarithmic = true},
},
args = {
"Player",
"Number",
},
Tip
Isso é útil quando você quer atualizar as restrições de um argumento sem substituir todo o comportamento dele:

Texto que outros jogadores veem
As políticas de segurança por idade do Roblox limitam o texto que um jogador mostra para outros a um por minuto. O HD Admin filtra todo argumento de texto e gasta um limite de um minuto para o tipo dele, que todo comando desse tipo compartilha:
| Arg | Use para |
|---|---|
"Text" |
Qualquer coisa mostrada como mensagem, dica, aviso, alerta ou votação |
"SurfaceText" |
Nomes, títulos e rótulos mostrados sobre um jogador ou no mundo |
"ChatText" |
Tags de chat e nomes de chat |
"Reason" |
Motivos de expulsão e de banimento |
Para escolher o tipo você mesmo, adicione textSurface a uma tabela de argumento, como {arg = "Text", textSurface = "SurfaceText"}. Use "None" para texto que só às vezes aparece para outros, e então chame checkTextLimit no momento em que ele aparece.
Args¶
Para obter o argumento de um comando, use task:getArg() e informe o nome ou o índice dele:
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
Obter um argumento pelo índice é necessário quando um comando tem dois ou mais argumentos iguais: {"Player", "Number", "Number"}
Quando "Player" é usado como primeiro argumento, o comando é executado separadamente em cada jogador alvo. Nesse caso, você pode usar task.target para se referir ao "Player":
args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
local target = task.target
local number = task:getArg("Number")
-- ...
end
Persistência¶
Uma tarefa é destruída assim que run termina. Isso é ótimo para comandos como ;jump, que acabam na hora... mas não tanto para comandos como music, que querem que os efeitos continuem. Por isso, qualquer comando que a gente queira manter vivo precisa passar por task:keep:
task:keep("UntilTargetRespawns")
| Persistência | A tarefa termina quando |
|---|---|
"UntilTargetRespawns" |
o alvo renasce ou sai |
"UntilTargetLeaves" |
o alvo sai |
"UntilCallerRespawns" |
quem executou o comando renasce ou sai |
"UntilCallerLeaves" |
quem executou o comando sai |
"Indefinitely" |
alguém a encerra com ;un, ou o jogador sai |
Tip
Você pode combinar vários 'keeps'. Por exemplo, usar task:keep("UntilTargetLeaves") e task:keep("UntilCallerLeaves") vai encerrar o comando quando o chamador ou o alvo sair do servidor.
Buffs¶
Mudar propriedades, como WalkSpeed em humanoids, normalmente é simples. Você só define a propriedade com o valor que quer e pronto. Isso fica um pouco mais complicado quando há vários comandos envolvidos.
Imagine que sua vida é 100 e você executa ;health me 500 e depois ;god me. O ;health primeiro define sua vida como 500, e então o ;god muda para 99999. Até aqui funciona... mas e se você quiser remover a tarefa god mantendo a health? Em muitos sistemas de admin, desfazer o god simplesmente voltaria sua vida para 100, ignorando a tarefa health que ainda está ativa. Isso não é o ideal, e é aí que os buffs ajudam:
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)
Um buff é só o seu código mais o grupo ao qual ele pertence (como "WalkSpeed" neste exemplo). Toda vez que uma tarefa desse grupo começa ou termina, todos os buffs dela são executados de novo em ordem, então sua propriedade sempre termina no valor que o comando final quer.
Você também pode retornar um valor original, ou seja, o valor que é lembrado pelo primeiro buff do grupo. Quando o último buff é removido, sua propriedade pode voltar a esse valor original, então sua vida volta para 100 em vez de ficar com o que o comando anterior deixou.
Rede¶
Para alcançar nossos comandos de cliente a partir do servidor, usamos 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
Usar task:expose é essencial para instâncias/modelos recém-criados no servidor que queremos compartilhar com os clientes, senão existe a chance de eles não serem recebidos
Muitas vezes o cliente também quer compartilhar informações com o servidor, ou até com outros clientes. Por exemplo, ao usar ;laserEyes, queremos que os outros clientes vejam nossos raios laser e para onde estamos apontando. Para isso, usamos 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
É importante você conferir se os valores dentro do replicator são os esperados, pois o cliente sempre pode enviar valores maliciosos ou diferentes
Info
Nada chega a outro jogador a menos que o seu replicator envie, então um cliente não consegue transmitir o que quiser em silêncio. A quantidade de requisições de replicação também tem um limite interno, e possíveis abusos dos clientes já foram levados em conta
Prompts¶
Executar comandos é uma coisa... mas ajustá-los enquanto rodam é ainda melhor. É aí que você pode usar task:bindPrompt para dar ao chamador um card que ele pode ajustar:
local function applyLaserColour()
local colour = task:getArg("Color")
-- set the beam colours, eye colours, etc
end
applyLaserColour()
task:bindPrompt({
args = {"Color"},
onChange = applyLaserColour,
})
Você também pode adicionar buttons para ações pontuais:
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,
},
},
})
Todas as chaves que o card aceita, incluindo botões confirm, toggles extras e o botão Re-run, estão listadas em task:bindPrompt. Para avisos e mensagens simples, veja prompt.
Você pode saber mais detalhes sobre as tarefas e os métodos disponíveis em Task API.