Pular para conteúdo

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:

imagem

--!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:

imagem

--!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

imagem

--!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:

imagem

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: imagem

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.