Przejdź do treści

Własne komendy

Komendy

Komendy to po prostu tabele z informacjami o tym, czym są i jak mają działać. Zaprojektowaliśmy je w ten sposób z kilku ważnych powodów:

Pamięć Kiedy komenda zostaje uruchomiona, można ją przedstawić jako zadanie, które staff łatwo podejrzy i anuluje. Zadania same po sobie sprzątają, więc pamięć nigdy nie przecieka, a całość jest zrobiona tak, że nie musisz nawet pisać osobnej funkcji undo.
Zasięg Zadania nie zależą już od konkretnego gracza, który uruchomił komendę (czyli wywołującego), więc każda komenda działa z każdym modyfikatorem. Komendy, które napiszesz, od razu da się wysłać na wszystkie serwery.
Bezpieczeństwo Argumenty są sprawdzane, zanim run w ogóle zostanie wywołane, więc argument Player dociera jako prawdziwy Player, a Number zawsze mieści się w dozwolonym zakresie itd. Twój kod nigdy nie dostaje surowego tekstu, a wywołujący nie uruchomi komendy, do której jego role nie dają uprawnień.
Interfejs Strona Run, podpowiedzi paska komend i autouzupełnianie powstają automatycznie z twoich args, więc każda komenda, którą napiszesz, od razu nadaje się dla graczy, którzy nie mogą pisać na czacie.
Typowanie Komendy są w pełni typowane, więc oznaczenie ich jako CommandAPI.Commands daje ci autouzupełnianie i ostrzeżenia o typach podczas pisania.

Napisz własne

W ConfigCommands po prostu rozbuduj istniejący moduł Custom albo dodaj własny moduł z dowolną liczbą tabel komend:

obraz

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

Komendy klienckie

Kod komendy domyślnie jest dostępny i uruchamiany tylko na serwerze, a czasem potrzebujesz, żeby działał na kliencie. Żeby to obejść, możesz dodać pod modułem komend ModuleScript o nazwie Client z tabelami komend, w których wartości name pasują do komend na serwerze:

obraz

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

obraz

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

Zawiera migające obrazy. Kliknij, żeby zobaczyć

Info

Niczego nie replikujesz sam. Framework wykrywa każdy podrzędny moduł o nazwie Client i automatycznie przenosi go do graczy.


Pola komendy

Każde pole poza name jest opcjonalne:

Nazewnictwo
name Shared Tytuł komendy, który się wyświetla, i to, co gracze wpisują po swoim prefiksie. Służy też jako nazwa cofnięcia, więc ;speed kończy się przez ;unspeed
aliases Server Inne nazwy, które uruchamiają tę komendę``
undoAliases Server Nazwy, które cofają komendę zamiast ją uruchamiać (np. NoClip używa {"Clip"})
description Server Jedno zdanie wyświetlane pod komendą na jej stronie uruchamiania
credit Server Kogo wskazać jako autora komendy (np. {"GigsD4X"})
Uruchamianie
args Server Argumenty, które przyjmuje twoja komenda (np. "Player", "Text", "Number" itd. Pełną listę znajdziesz w MainModuleValueModulesParserArgs
run Shared Kod twojej komendy. Na serwerze dostaje zadanie i zwalidowane argumenty, a na kliencie dostaje zadanie, a potem to, co przekazał mu serwer w task.client:run
replication Client Funkcja, do której trafiają dane zwrócone z serwera. Twój klient wywołuje task.server:replicate, task.client.replicator na serwerze wybiera, kto je dostanie, a potem ta funkcja uruchamia się na ich kliencie
config Server Domyślne wartości, które twórcy gier mogą zmienić przez modify przy ładowaniu wbudowanych komend
cooldown Server Liczba sekund oczekiwania po zakończeniu komendy, zanim będzie można ją uruchomić ponownie
stackable Server Zwykle na jednym graczu lub serwerze może być aktywna tylko jedna taka komenda naraz, ale gdy jest ustawione true, może ich być kilka
groups Server Komendy z tej samej grupy cofają się nawzajem na tym samym graczu (np. Fly i NoClip są w grupie "Flight", więc uruchomienie jednej kończy drugą) i dzielą cooldown. Dwie grupy mają dodatkowe znaczenie: "Prompt" oznacza komendy w stylu wiadomości, które zużywają limit jednego tekstu na minutę nawet bez wpisanego tekstu i są filtrowane przez ustawienie Block prompts, a "Map" oznacza komendy, które edytują mapę, więc pierwsza uruchomiona po cichu zachowuje kopię dla ;clearmap
Zasięg
tags Server Tagi, które ta komenda odziedziczy. Role używają ich, żeby zdecydować, jakie komendy dziedziczą
disableModifiers Server Blokuje użycie modyfikatorów w tej komendzie
disableGlobalModifiers Server Blokuje użycie modyfikatorów globalnych (np. global, perm, join itd.) w tej komendzie
Interfejs
order Server Pozycja na stronie komend. Niższe liczby idą pierwsze
hide Server Ukrywa komendę na stronie Commands
autoPreview Server Gdy komenda jest uruchamiana przez czat albo przycisk szybkiego podglądu, otwiera stronę Run zamiast ją uruchamiać (np. Ban używa tego, żeby najpierw potwierdzić szczegóły)

Własne argumenty

Wbudowane argumenty (w MainModuleValueModulesParserArgs) pokrywają większość tego, czego potrzebujesz, ale jeśli chcesz stworzyć własny, zrobisz to w Config > Args:

obraz

return function(Args)
    return {

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

    }
end

Warning

Upewnij się, że wybrana nazwa nie pokrywa się z żadnym wbudowanym argumentem HD Admin. W przeciwnym razie przy starcie pojawi się ostrzeżenie, a jeden z argumentów wygra z drugim.

Jeśli chcesz zmienić argumenty tylko jednej komendy, możesz zamiast tego zamienić nazwę argumentu na tabelę argumentu:

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

Tip

Przydaje się, gdy chcesz zmienić ograniczenia argumentu bez zastępowania całego jego zachowania: obraz

Tekst, który widzą inni gracze

Zasady bezpieczeństwa wiekowego Roblox ograniczają tekst, który gracz pokazuje innym, do jednego na minutę. HD Admin filtruje każdy argument tekstowy i zużywa limit jednej minuty dla jego typu, wspólny dla wszystkich komend tego typu:

Arg Do czego go użyć
"Text" Wszystko, co jest pokazywane jako wiadomość, podpowiedź, powiadomienie, alert albo ankieta
"SurfaceText" Nazwy, tytuły i etykiety pokazywane nad graczem albo w świecie
"ChatText" Tagi czatu i nazwy na czacie
"Reason" Powody kicka i bana

Żeby samemu wybrać typ, dodaj textSurface do tabeli argumentu, np. {arg = "Text", textSurface = "SurfaceText"}. Użyj "None" dla tekstu, który tylko czasem jest pokazywany innym, i wywołaj checkTextLimit dokładnie w momencie, gdy tak się dzieje.


Argumenty

Żeby pobrać argument komendy, użyj task:getArg() i podaj jego nazwę albo indeks:

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

Pobieranie argumentu przez indeks jest konieczne, gdy komenda ma dwa lub więcej takich samych argumentów: {"Player", "Number", "Number"}

Gdy "Player" jest pierwszym argumentem, komenda jest uruchamiana osobno na każdym wskazanym graczu. W takim przypadku możesz użyć task.target, żeby odwołać się do tego "Player":

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

Trwałość

Zadanie jest niszczone w chwili, gdy run się kończy. To w porządku dla komend takich jak ;jump, które kończą się natychmiast, ale gorzej dla takich jak music, których efekty mają zostać. Dlatego każda komenda, którą chcemy utrzymać przy życiu, musi przejść przez task:keep:

task:keep("UntilTargetRespawns")
Trwałość Zadanie kończy się, gdy
"UntilTargetRespawns" cel odrodzi się lub wyjdzie
"UntilTargetLeaves" cel wyjdzie
"UntilCallerRespawns" osoba, która uruchomiła komendę, odrodzi się lub wyjdzie
"UntilCallerLeaves" osoba, która uruchomiła komendę, wyjdzie
"Indefinitely" ktoś zakończy je przez ;un albo gracz wyjdzie

Tip

Możesz łączyć kilka takich "keepów". Na przykład task:keep("UntilTargetLeaves") razem z task:keep("UntilCallerLeaves") zakończy komendę, gdy z serwera wyjdzie jej wywołujący albo jej cel.


Buffy

Zmiana właściwości, np. WalkSpeed w humanoidach, to zwykle prosta sprawa. Ustawiasz właściwość na wybraną wartość i gotowe. Robi się trudniej, gdy w grę wchodzi kilka komend naraz.

Załóżmy, że twoje zdrowie wynosi 100 i uruchamiasz ;health me 500, a potem ;god me. ;health najpierw ustawia zdrowie na 500, potem ;god zmienia je na 99999. Działa to dobrze, ale co, jeśli chcesz potem usunąć zadanie god i zostawić health? W wielu systemach admina cofnięcie god po prostu przywróciłoby zdrowie do 100, ignorując wciąż aktywne zadanie health. To niepożądane i właśnie tu przydają się buffy:

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)

Buff to po prostu twój kod plus grupa, do której należy (w tym przykładzie "WalkSpeed"). Za każdym razem, gdy zadanie z tej grupy startuje albo się kończy, wszystkie jej buffy są uruchamiane ponownie po kolei, więc twoja właściwość zawsze wyląduje na tym, czego chce ostateczna komenda.

Możesz też zwrócić wartość oryginalną, czyli wartość zapamiętywaną przez najwcześniejszy buff w grupie. Gdy ostatni buff zostanie usunięty, właściwość można ustawić z powrotem na tę wartość, więc twoje zdrowie wraca do 100, a nie do tego, co zostawiła po sobie poprzednia komenda.


Komunikacja sieciowa

Żeby z serwera dotrzeć do komend klienckich, używamy 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

Użycie task:expose jest konieczne dla nowo utworzonych na serwerze instancji i modeli, które chcemy udostępnić klientom. W przeciwnym razie mogą one do nich nie dotrzeć

Czasem klient też chce przekazać informacje serwerowi, a nawet innym klientom. Na przykład przy ;laserEyes chcemy, żeby inni klienci widzieli nasze promienie laserowe i to, gdzie nimi celujemy. Do tego używamy 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

Ważne, żebyś sprawdzał w replikatorze, czy wartości są takie, jakich się spodziewasz, bo klient zawsze może wysłać złośliwe albo inne wartości

Info

Nic nie trafia do innego gracza, jeśli twój replicator tego nie wyśle, więc klient nie może po cichu rozsyłać wszystkiego, co mu się podoba. Liczba żądań replikacji jest też ograniczona wewnętrznie, a potencjalne nadużycia ze strony klientów są uwzględnione


Monity

Uruchamianie komend to jedno, ale poprawianie ich w trakcie działania jest jeszcze fajniejsze. Do tego służy task:bindPrompt, które daje wywołującemu kartę do regulacji:

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

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

Możesz też dodać buttons do jednorazowych akcji:

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,
        },
    },
})

Wszystkie klucze, które karta przyjmuje, w tym przyciski confirm, dodatkowe przełączniki i przycisk Re-run, znajdziesz w task:bindPrompt. Zwykłe powiadomienia i wiadomości opisuje prompt.

Więcej szczegółów o zadaniach i ich metodach znajdziesz w Task API.