Zum Inhalt

Eigene Befehle

Tip

Hier kannst du nach Bonus-Befehlen stöbern.

Befehle

Befehle sind einfach Tabellen mit Infos darüber, was sie sind und wie sie laufen sollen. Dass sie so aufgebaut sind, hat ein paar wichtige Gründe:

Speicher Wenn ein Befehl ausgeführt wird, wird er als 'Aufgabe' dargestellt, die Teammitglieder einfach ansehen und abbrechen können. Aufgaben räumen automatisch hinter sich auf, damit nie Speicherlecks entstehen, und du musst nicht mal eine eigene undo-Funktion schreiben.
Reichweite Weil Aufgaben nicht mehr davon abhängen, dass ein bestimmter Spieler den Befehl ausführt (also der Aufrufer), funktioniert jeder Befehl mit jedem Modifikator. Deine Befehle lassen sich also sofort auf allen Servern ausführen.
Sicherheit Argumente werden geprüft, bevor run überhaupt aufgerufen wird. Ein Player-Argument kommt also als echter Player an, eine Number liegt immer in ihrem erlaubten Bereich usw. Dein Code hat nie mit rohem Text zu tun, und niemand kann einen Befehl ausführen, den seine Rollen nicht erlauben.
Oberfläche Die Run-Seite, die Vorschläge in der Befehlsleiste und die Autovervollständigung werden automatisch aus deinen args erzeugt. So kann jeder Befehl, den du schreibst, sofort auch von Spielern genutzt werden, die nicht chatten können.
Typisiert Befehle sind vollständig typisiert. Wenn du deine Befehle mit CommandAPI.Commands annotierst, bekommst du schon beim Schreiben Autovervollständigung und Typwarnungen.

Eigene Befehle erstellen

Unter ConfigCommands kannst du einfach das vorhandene Custom-Modul erweitern oder ein eigenes Modul mit beliebig vielen Befehlstabellen hinzufügen:

Bild

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

Client-Befehle

Befehlscode ist standardmäßig nur auf dem Server verfügbar und läuft auch nur dort, manchmal muss er aber auf dem Client laufen. Dafür kannst du unter dem Befehlsmodul ein ModuleScript namens Client hinzufügen. Darin stehen Befehlstabellen, deren name-Werte zu den Befehlen auf dem Server passen:

Bild

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

Bild

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

Enthält blinkende Bilder. Zum Ansehen klicken

Info

Du musst nichts selbst replizieren. Das Framework erkennt jedes Kindmodul namens Client und verschiebt es automatisch zu den Spielern.


Befehlsfelder

Alle Felder außer name sind optional:

Benennung
name Shared Der angezeigte Befehlsname und das, was Spieler nach ihrem Präfix eintippen. Er dient gleichzeitig als Undo-Name, ;speed wird also mit ;unspeed beendet
aliases Server Andere Namen, die diesen Befehl auslösen``
undoAliases Server Namen, die den Befehl rückgängig machen, statt ihn auszuführen (z. B. nutzt NoClip {"Clip"})
description Server Ein Satz, der auf der Run-Seite unter dem Befehl steht
credit Server Wer für den Befehl genannt werden soll (z. B. {"GigsD4X"})
Ausführung
args Server Die Argumente, die dein Befehl erwartet (z. B. "Player", "Text", "Number" usw. Die vollständige Liste findest du unter MainModuleValueModulesParserArgs
run Shared Der Code deines Befehls. Auf dem Server bekommt er eine Aufgabe und die geprüften Argumente, auf dem Client eine Aufgabe und das, was der Server ihm in task.client:run übergeben hat
replication Client Eine Funktion, in der vom Server zurückgeschickte Daten landen. Dein Client ruft task.server:replicate auf, task.client.replicator auf dem Server entscheidet, wer die Daten bekommt, und dann läuft diese Funktion auf deren Client
config Server Standardwerte, die Spieleentwickler über modify ändern können, wenn sie interne Befehle laden
cooldown Server Wie viele Sekunden nach dem Ende des Befehls vergehen müssen, bevor er wieder laufen kann
stackable Server Normalerweise kann ein Befehl auf einem Spieler oder Server nur einmal gleichzeitig aktiv sein. Ist das hier true, kann er mehrfach gleichzeitig laufen
groups Server Befehle in derselben Gruppe heben sich auf demselben Spieler gegenseitig auf (z. B. sind Fly und NoClip beide in der Gruppe "Flight", startest du den einen, endet der andere) und teilen sich einen cooldown. Zwei Gruppen haben eine besondere Bedeutung: "Prompt" kennzeichnet Nachrichtenbefehle. Die verbrauchen das Textlimit von einmal pro Minute, auch wenn nichts eingetippt wurde, und werden von der Einstellung Block prompts gefiltert. "Map" kennzeichnet Befehle, die die Map verändern. Der erste davon, der läuft, legt still eine Kopie für ;clearmap an
Reichweite
tags Server Die Tags, die dieser Befehl übernimmt. Über sie entscheiden Rollen, welche Befehle sie übernehmen
disableModifiers Server Verhindert, dass Modifikatoren bei diesem Befehl genutzt werden
disableGlobalModifiers Server Verhindert, dass die globalen Modifikatoren (z. B. global, perm, join usw.) bei diesem Befehl genutzt werden
Oberfläche
order Server Seine Position auf der Befehlsseite. Niedrigere Zahlen kommen zuerst
hide Server Blendet den Befehl auf der Commands-Seite aus
autoPreview Server Wird der Befehl über den Chat oder den Schnellvorschau-Button ausgeführt, öffnet sich stattdessen die Run-Seite (z. B. nutzt Ban das, damit die Details erst bestätigt werden)

Eigene Argumente

Die eingebauten Argumente (unter MainModuleValueModulesParserArgs) decken das meiste ab, was du brauchst. Wenn du trotzdem eigene erstellen willst, geht das unter Config > Args:

Bild

return function(Args)
    return {

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

    }
end

Warning

Achte darauf, dass dein Name nicht mit einem der eingebauten Argumente von HD Admin übereinstimmt. Sonst gibt es beim Start eine Warnung und eins von beiden setzt sich gegen das andere durch.

Wenn du nur die Argumente eines einzelnen Befehls anpassen willst, kannst du stattdessen seinen Arg-Namen durch eine Arg-Tabelle ersetzen:

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

Tip

Das ist praktisch, wenn du die Grenzen eines Args ändern willst, ohne sein Verhalten komplett zu ersetzen: Bild

Text, den andere Spieler sehen

Die Richtlinien von Roblox zum Altersschutz erlauben nur einen Text pro Minute, den ein Spieler anderen zeigt. HD Admin filtert jedes Text-Arg und verbraucht dafür das Minutenlimit seines Typs, das sich alle Befehle dieses Typs teilen:

Arg Wofür
"Text" Alles, was als Nachricht, Hint, Hinweis, Alert oder Umfrage angezeigt wird
"SurfaceText" Namen, Titel und Beschriftungen über einem Spieler oder in der Welt
"ChatText" Chat-Tags und Chat-Namen
"Reason" Gründe für Kicks und Banns

Um den Typ selbst festzulegen, füg einer Arg-Tabelle textSurface hinzu, z. B. {arg = "Text", textSurface = "SurfaceText"}. Nimm "None" für Text, der nur manchmal für andere sichtbar ist, und ruf dann genau in dem Moment checkTextLimit auf.


Argumente

Um ein Arg eines Befehls abzurufen, nutzt du task:getArg() und gibst entweder seinen Namen oder seinen Index an:

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

Den Index brauchst du, wenn ein Befehl dasselbe Arg zwei- oder mehrmals hat: {"Player", "Number", "Number"}

Wenn "Player" das erste Arg ist, wird der Befehl für jeden anvisierten Spieler einzeln ausgeführt. Dann kommst du mit task.target an den "Player":

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

Persistenz

Eine Aufgabe wird zerstört, sobald run fertig ist. Bei Befehlen wie ;jump, die sofort vorbei sind, passt das... bei Befehlen wie music, deren Wirkung bleiben soll, eher nicht. Jeder Befehl, der weiterlaufen soll, muss deshalb task:keep aufrufen:

task:keep("UntilTargetRespawns")
Persistenz Die Aufgabe endet, wenn
"UntilTargetRespawns" das Ziel respawnt oder den Server verlässt
"UntilTargetLeaves" das Ziel den Server verlässt
"UntilCallerRespawns" derjenige, der den Befehl ausgeführt hat, respawnt oder den Server verlässt
"UntilCallerLeaves" derjenige, der den Befehl ausgeführt hat, den Server verlässt
"Indefinitely" jemand sie mit ;un beendet oder der Spieler den Server verlässt

Tip

Du kannst mehrere 'keeps' kombinieren. Mit task:keep("UntilTargetLeaves") und task:keep("UntilCallerLeaves") endet der Befehl zum Beispiel, sobald entweder der Aufrufer oder das Ziel den Server verlässt.


Buffs

Eigenschaften zu ändern, etwa WalkSpeed bei Humanoids, ist meistens einfach. Du setzt die Eigenschaft auf den gewünschten Wert und fertig. Etwas kniffliger wird es, wenn mehrere Befehle beteiligt sind.

Sagen wir, deine Gesundheit liegt bei 100 und du führst ;health me 500 und dann ;god me aus. ;health setzt deine Gesundheit zuerst auf 500, dann ändert ;god sie auf 99999. Das klappt... aber was, wenn du danach die god-Aufgabe entfernen und health behalten willst? In vielen Admin-Systemen setzt das Rückgängigmachen von god deine Gesundheit einfach zurück auf 100 und ignoriert die noch aktive health-Aufgabe. Das will man nicht, und genau dafür gibt es Buffs:

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)

Ein Buff ist einfach dein Code plus die Gruppe, zu der er gehört (in diesem Beispiel "WalkSpeed"). Jedes Mal, wenn eine Aufgabe in dieser Gruppe startet oder endet, laufen alle ihre Buffs der Reihe nach neu. So landet deine Eigenschaft immer bei dem Wert, den der letzte Befehl haben will.

Du kannst auch einen Originalwert zurückgeben, also den Wert, den sich der früheste Buff der Gruppe merkt. Wird der letzte Buff entfernt, kann deine Eigenschaft auf diesen Originalwert zurückgesetzt werden. Deine Gesundheit geht dann wieder auf 100 und nicht auf das, was der vorherige Befehl zufällig hinterlassen hat.


Netzwerk

Um vom Server aus unsere Client-Befehle zu erreichen, nutzen wir 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

task:expose brauchst du unbedingt für neu erstellte Instanzen oder Modelle auf dem Server, die du mit Clients teilen willst. Sonst kann es passieren, dass sie nicht ankommen

Oft will auch der Client Infos mit dem Server oder sogar mit anderen Clients teilen. Bei ;laserEyes sollen zum Beispiel andere Clients unsere Laserstrahlen sehen und wohin wir damit zielen. Dafür nutzen wir 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

Prüf im Replicator unbedingt, ob die Werte so aussehen, wie du sie erwartest. Ein Client kann jederzeit manipulierte oder ganz andere Werte schicken

Info

Nichts erreicht einen anderen Spieler, wenn dein replicator es nicht weiterschickt. Ein Client kann also nicht heimlich an alle senden, was er will. Die Zahl der Replikationsanfragen ist intern außerdem begrenzt, und möglicher Missbrauch durch Clients ist berücksichtigt


Eingabeaufforderungen

Befehle auszuführen ist das eine... sie anzupassen, während sie laufen, ist noch besser. Dafür gibt es task:bindPrompt, damit bekommt der Aufrufer eine Karte, an der er Dinge einstellen kann:

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

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

Für einmalige Aktionen kannst du auch buttons hinzufügen:

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

Alle Schlüssel, die die Karte akzeptiert, darunter confirm-Buttons, zusätzliche Schalter und der Re-run-Button, findest du unter task:bindPrompt. Für einfache Hinweise und Nachrichten schau unter prompt.

Mehr über Aufgaben und ihre Methoden erfährst du unter Task-API.