Saltar a contenido

Comandos personalizados

Tip

Puedes explorar comandos adicionales aquí.

Comandos

Los comandos son simplemente tablas de información que describen qué son y cómo deben ejecutarse. Se diseñaron así por unas cuantas razones clave:

Memoria Cuando se ejecuta un comando, ahora se puede representar como una "tarea" que el personal puede ver y cancelar fácilmente. Las tareas se limpian solas, así que nunca se filtra memoria, y están pensadas para que ni siquiera tengas que escribir una función undo aparte.
Alcance Como las tareas ya no dependen de un jugador concreto que ejecute el comando (es decir, quien lo llama), cualquier comando funciona con cualquier modificador, lo que significa que los comandos que escribas se pueden emitir al instante a todos los servidores.
Seguridad Los argumentos se validan antes de que se llame a run, así que un argumento Player llega como un Player real, un Number siempre llega dentro de su rango permitido, etc. Tu código nunca maneja texto sin procesar, y quienes ejecutan comandos nunca pueden usar uno que sus roles no permitan.
Interfaz La página Run, las sugerencias de la barra de comandos y los autocompletados se generan automáticamente a partir de tus args, así que cada comando que escribas se puede usar al instante por jugadores que no pueden usar el chat.
Tipado Los comandos están totalmente tipados, así que anotar tus comandos con CommandAPI.Commands te da autocompletados y advertencias de tipos mientras escribes.

Crea los tuyos

En ConfigCommands, simplemente amplía el módulo Custom existente, o agrega tu propio módulo con tantas tablas de comandos como quieras:

imagen

--!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 defecto, el código de los comandos solo está disponible y se ejecuta en el servidor, pero a veces necesitas que se ejecute en el cliente. Para lograrlo, puedes agregar un ModuleScript llamado Client dentro del módulo de comandos, con tablas de comandos cuyos valores name coincidan con los comandos del servidor:

imagen

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

imagen

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

Contiene imágenes parpadeantes. Haz clic para ver

Info

No tienes que replicar nada tú mismo. El framework detecta cualquier módulo hijo llamado Client y lo envía a los jugadores automáticamente.


Campos de comando

Todos los campos excepto name son opcionales:

Nombres
name Shared El título del comando que se muestra y lo que los jugadores escriben después de su prefijo. También funciona como nombre para deshacer, así que ;speed termina con ;unspeed
aliases Server Otros nombres que activan este comando``
undoAliases Server Nombres que deshacen el comando en lugar de ejecutarlo (por ejemplo, NoClip usa {"Clip"})
description Server Una frase que se muestra debajo del comando en su página Run
credit Server A quién dar crédito por el comando (por ejemplo, {"GigsD4X"})
Ejecución
args Server Los argumentos que recibe tu comando (por ejemplo, "Player", "Text", "Number", etc. Puedes encontrar la lista completa en MainModuleValueModulesParserArgs
run Shared El código de tu comando. En el servidor recibe una tarea y los argumentos validados, mientras que en el cliente recibe una tarea y luego lo que el servidor le pasó en task.client:run
replication Client Una función donde llegan los datos devueltos desde el servidor. Tu cliente llama a task.server:replicate, el task.client.replicator del servidor elige quién los recibe, y luego esto se ejecuta en el cliente de esos jugadores
config Server Valores por defecto que los creadores del juego pueden cambiar con modify cuando cargan comandos internos
cooldown Server Segundos de espera después de que el comando termina antes de que se pueda ejecutar de nuevo
stackable Server Normalmente solo un comando puede estar activo a la vez por jugador o servidor, pero cuando esto es true, permite varios a la vez
groups Server Los comandos que comparten un grupo se deshacen entre sí en el mismo jugador (por ejemplo, Fly y NoClip están en el grupo "Flight", así que iniciar uno termina el otro) y comparten un cooldown. Dos grupos tienen un significado extra: "Prompt" marca los comandos de estilo mensaje, que gastan el límite de texto de uno por minuto incluso sin escribir nada y que filtra el ajuste Block prompts, y "Map" marca los comandos que editan el mapa, así que el primero que se ejecuta guarda en silencio una copia para ;clearmap
Alcance
tags Server Las etiquetas que heredará este comando, que luego los roles usan para decidir qué comandos heredar
disableModifiers Server Impide que se usen modificadores en el comando
disableGlobalModifiers Server Impide que se usen los modificadores globales (por ejemplo, global, perm, join, etc.) en el comando
Interfaz
order Server Su posición en la página de comandos. Los números más bajos van primero
hide Server Oculta el comando de la página Commands
autoPreview Server Cuando un comando se ejecuta desde el chat o el botón de vista previa rápida, abre la página Run en lugar de ejecutar el comando (por ejemplo, Ban usa esto para confirmar primero los detalles)

Argumentos personalizados

Los argumentos integrados (en MainModuleValueModulesParserArgs) cubren la mayoría de los que vas a necesitar, pero si alguna vez quieres crear los tuyos, puedes hacerlo en Config > Args:

imagen

return function(Args)
    return {

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

    }
end

Warning

Asegúrate de que el nombre que elijas no coincida con ninguno de los argumentos integrados de HD Admin, porque si no, mostrará una advertencia al iniciar y uno de los dos se impondrá sobre el otro.

Si quieres modificar los argumentos de un solo comando, también puedes cambiar el nombre del argumento por una tabla de argumento:

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

Tip

Esto es útil cuando quieres actualizar las restricciones de un argumento sin reemplazar por completo su comportamiento: imagen

Texto que ven otros jugadores

Las políticas de seguridad por edad de Roblox limitan a uno por minuto el texto que un jugador muestra a otros. HD Admin filtra cada argumento de texto y gasta un límite de un minuto para su tipo, que comparten todos los comandos de ese tipo:

Argumento Úsalo para
"Text" Cualquier cosa que se muestre como mensaje, sugerencia, aviso, alerta o encuesta
"SurfaceText" Nombres, títulos y etiquetas que se muestran sobre un jugador o en el mundo
"ChatText" Etiquetas y nombres del chat
"Reason" Motivos de expulsión y de veto

Para elegir el tipo tú mismo, agrega textSurface a una tabla de argumento, así: {arg = "Text", textSurface = "SurfaceText"}. Usa "None" para texto que solo a veces se muestra a otros, y luego llama a checkTextLimit en el momento en que se muestre.


Argumentos

Para obtener un argumento de un comando, usa task:getArg() y especifica su nombre o su índice:

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

Obtener un argumento por su índice es necesario cuando un comando tiene dos o más argumentos iguales: {"Player", "Number", "Number"}

Cuando se usa "Player" como primer argumento, su comando se ejecuta por separado en cada jugador al que se apuntó. En este caso, puedes usar task.target para referirte al "Player":

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

Persistencia

Una tarea se destruye en el momento en que run termina. Esto está bien para comandos como ;jump, que terminan al instante... pero es menos deseable para comandos como music, cuyos efectos deben permanecer. Por eso, cualquier comando que queramos mantener activo debe pasar por task:keep:

task:keep("UntilTargetRespawns")
Persistencia La tarea termina cuando
"UntilTargetRespawns" el objetivo reaparece o se va
"UntilTargetLeaves" el objetivo se va
"UntilCallerRespawns" quien ejecutó el comando reaparece o se va
"UntilCallerLeaves" quien ejecutó el comando se va
"Indefinitely" alguien la termina con ;un, o el jugador se va

Tip

Puedes combinar varios "keeps". Por ejemplo, usar task:keep("UntilTargetLeaves") y task:keep("UntilCallerLeaves") terminará el comando cuando se vaya quien lo ejecutó o su objetivo del servidor.


Buffs

Cambiar propiedades, como WalkSpeed en los humanoides, normalmente es un trabajo sencillo. Solo asignas a la propiedad el valor que quieres y listo. Esto se complica un poco cuando hay varios comandos involucrados.

Imagina que tu salud es 100 y ejecutas ;health me 500 y luego ;god me. ;health primero pone tu salud en 500, y luego ;god la cambia a 99999. Esto funciona bien... pero ¿qué pasa si después quieres quitar la tarea god y conservar health? En muchos sistemas de administración, al deshacer god tu salud simplemente volvería a 100, ignorando la tarea health que sigue aplicada. Eso no es lo ideal, y aquí es donde los buffs son útiles:

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 es simplemente tu código más el grupo al que pertenece (como "WalkSpeed" en este ejemplo). Cada vez que una tarea de ese grupo empieza o termina, todos sus buffs se ejecutan de nuevo en orden, así que tu propiedad siempre termina en lo que quiera el último comando.

También puedes devolver un valor original, es decir, el valor que recuerda el buff más antiguo del grupo. Cuando se quita el último buff, tu propiedad puede volver a este valor original, así que tu salud regresa a 100 en lugar de lo que sea que dejó el comando anterior.


Red

Para llegar a nuestros comandos de cliente desde el 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 es esencial para las instancias o modelos recién creados en el servidor que queremos compartir con los clientes, porque si no, es posible que no lleguen

A veces el cliente también querrá compartir información con el servidor, o incluso con otros clientes. Por ejemplo, al usar ;laserEyes, queremos que otros clientes vean nuestros rayos láser y hacia dónde los apuntamos. Para lograrlo, 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

Es importante que compruebes que los valores dentro del replicator son los que esperas, ya que el cliente siempre puede enviar valores maliciosos o distintos

Info

Nada llega a otro jugador a menos que tu replicator lo envíe, así que un cliente no puede transmitir en silencio lo que quiera. Además, la cantidad de solicitudes de replicación tiene un tope interno, y los posibles abusos de los clientes están contemplados


Mensajes

Ejecutar comandos es una cosa... pero ajustarlos mientras se ejecutan es aún mejor. Aquí es donde puedes usar task:bindPrompt para darle a quien ejecuta el comando una tarjeta que puede ajustar:

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

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

También puedes agregar buttons para acciones de un solo uso:

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 las claves que acepta la tarjeta, incluidos los botones confirm, los interruptores adicionales y el botón Re-run, están en task:bindPrompt. Para avisos y mensajes simples, consulta prompt.

Puedes conocer más detalles sobre las tareas y sus métodos disponibles en Task API.