Task API
Jedes Mal, wenn ein Befehl läuft, erstellt er für jedes Ziel eine Aufgabe. Diese Aufgabe wird an run übergeben und bestimmt, wie lange der Befehl lebt, wie das Networking läuft, wie aufgeräumt wird und vieles mehr.
Methoden¶
task:keep Server¶
task:keep(persistence: Persistence?)
Hält die Aufgabe am Leben, nachdem run zurückgekehrt ist. Sonst wird sie sofort zerstört. Zur Wahl stehen "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" und "Indefinitely". Rufst du die Methode mehrmals auf, werden die Bedingungen kombiniert, und die Aufgabe endet, sobald die erste davon eintritt. Siehe Persistenz.
task:getArg Server¶
task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any
Liest den validierten Wert des Arguments mit dem angegebenen Namen oder an der angegebenen Position. Dieser Wert kann aus dem default des Arguments stammen, aus dem validierten Wert des Aufrufers, aus einem validierten Wert, auf den eine Eingabeaufforderung ihn geändert hat, oder aus einem Wert, der mit task:setArg() gesetzt wurde.
Übergib true als zweites Argument, um nil zu erhalten, wenn der Aufrufer das Argument nie angegeben hat und der Wert nur aus dem default des Arguments kam. Das ist praktisch bei optionalen Argumenten, bei denen du auf dein eigenes Verhalten zurückfallen willst, so wie ;message die Dauer aus der Textlänge berechnet, solange keine eingetippt wurde.
task:setArg Server¶
task:setArg(nameOrPosition: string | number, value: any)
Ändert den Wert des Arguments mit dem angegebenen Namen oder an der angegebenen Position.
task:buff Server¶
task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)
Ändert eine Eigenschaft, wendet die Änderungen auf diese Eigenschaft erneut an, wenn sich Buffs in derselben Gruppe ändern, und setzt die Eigenschaft auf ihren ursprünglichen Wert zurück, sobald die Aufgabe endet. Siehe Buffs.
task:updateBuffs Server¶
task:updateBuffs(player: Player?, group: string?)
Führt die Buffs für diesen Spieler und diese Gruppe erneut aus. Das passiert in den meisten Fällen automatisch und ist nur nützlich, wenn du gezielt alles in dieser Gruppe aktualisieren willst.
task:redo Server¶
task:redo(player: Player?, callback: () -> ())
Führt deinen Callback sofort aus und danach jedes Mal erneut, wenn der Spieler respawnt, solange die Aufgabe aktiv ist. Nützlich für Effekte, die beim Respawn sonst verschwinden würden.
task:bindPrompt Server¶
task:bindPrompt(config)
Gibt dem Aufrufer eine Aktions-Eingabeaufforderung, die an den Befehl gebunden ist, etwa den Slider bei ;speed oder die Augenfarbe bei ;laserEyes:
run = function(task: CommandAPI.Task)
task:keep("UntilCallerLeaves")
task:bindPrompt({
title = "Dangerous Script",
text = "This script uses HttpService, are you sure you want to load it?",
audience = task.caller,
duration = 20,
deactivate = false,
endOnClose = true,
buttons = {
{
label = "Load",
onActivate = function()
--loadScript()
task:destroy()
end,
},
{
label = "Cancel",
style = "Neutral",
onActivate = function()
task:destroy()
end,
},
},
})
end,
Config
| Key | Type | What it does |
|---|---|---|
title |
string | Die Überschrift der Eingabeaufforderung, standardmäßig der Name des Befehls |
text |
string | Der Haupttext |
subtext |
string | Eine kleinere Zeile unter dem Text |
audience |
Player | Wer die Eingabeaufforderung sieht, standardmäßig task.target |
duration |
number | Sekunden, bis sich die Eingabeaufforderung selbst schließt. Standardmäßig 0, was eine unendliche Dauer bedeutet |
args |
table | Die Befehlsargumente, die als Bedienelemente angezeigt werden, siehe Bedienelemente |
onChange |
function | function(argName, value), läuft, nachdem ein Bedienelement ein Argument geändert hat |
toggle |
table | Ein zusätzlicher An/Aus-Schalter, der nicht an ein Argument gebunden ist, {label = "Trails", value = true, onChange = function(isOn) end} |
buttons |
table | Einmalige Aktionsbuttons, siehe Buttons |
deactivate |
boolean | Standardmäßig true, wodurch die Eingabeaufforderung einen Schalter zum Pausieren und Fortsetzen des Befehls und einen Stopp-Button zum Beenden bekommt. Setze false für eine Eingabeaufforderung, die nur aus Buttons besteht |
rerun |
boolean | Fügt einen Button zum erneuten Ausführen hinzu, der aufräumt und den Befehl noch einmal startet. Wird nur angezeigt, wenn deactivate false ist |
endOnClose |
boolean | Schließt man die Eingabeaufforderung, endet die Aufgabe standardmäßig. Mit false läuft sie weiter, bis der Client sie wegklickt |
Bedienelemente
Damit die Aktions-Eingabeaufforderung ein Argument steuern kann, trägst du seinen Namen in args innerhalb von bindPrompt ein. Aus einem Number wird ein Slider, aus einer Color eine Farbauswahl, aus einem Bool ein Schalter usw. Sobald der Client eines davon ändert, wird das Argument aktualisiert und dein onChange ausgelöst. Rufe also einfach task:getArg erneut auf, um den neuen Wert zu lesen. Du musst auch nichts validieren, denn jeder Wert wird genauso geprüft, als wäre er im Chat eingetippt worden:
run = function(task: CommandAPI.Task)
local function applySpinSpeed()
local speed = task:getArg("Number")
-- spin the character at this speed
end
applySpinSpeed()
task:bindPrompt({
args = {"Number"},
onChange = applySpinSpeed,
})
end,
Buttons sind genauso einfach. Gib jedem ein label und eine onActivate-Funktion, und diese Funktion läuft auf dem Server, sobald der Client den Button drückt. Hier darfst du auch yielden (Kaufaufforderung, DataStore-Aufruf usw.), denn der Button zeigt einfach einen Spinner an, bis du fertig bist:
| Key | Type | What it does |
|---|---|---|
label |
string | Der Text auf dem Button |
onActivate |
function | Was passiert, wenn er gedrückt wird |
style |
string | Standardmäßig "Primary", oder "Neutral" für eine ausgegraute Optik, ideal für Abbrechen |
confirm |
boolean | Fügt einen Confirm?-Schritt hinzu, sodass der Button erst beim zweiten Drücken auslöst, praktisch für alles Mächtige wie eine Bann-Bestätigung |
Ein Button kann seine eigene Aufgabe mit task:destroy() beenden. So machen es einmalige Befehls-Eingabeaufforderungen wie ;teleport.
task.client:run Server¶
task.client:run(player: Player?, ...)
task.client:runAll(...)
task.client:runOthers(originPlayer: Player, ...)
task.client:runNearby(originPlayer: Player?, radius: number, ...)
Führt deinen passenden Client-Befehl auf den Geräten der Spieler aus und reicht zusätzliche Werte direkt durch. run zielt auf einen Spieler, runAll auf alle, runOthers auf alle außer dem originPlayer und runNearby auf alle innerhalb von radius Studs. Siehe Networking.
task.client:expose Server¶
task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})
Stellt sicher, dass die Instanzen den Spieler tatsächlich erreicht haben, bevor dein Client-Code nach ihnen sucht. Streaming kann Dinge zurückhalten, deshalb sollte alles, was du auf dem Server erstellst und auf dem Client verwendest, zuerst hier durchlaufen.
task.server:replicate Client¶
task.server:replicate(...)
Sendet Werte von einem Client-Befehl zurück an den Server, wo sie bei derselben Aufgabe ankommen. Setze task.client.replicator auf dem Server, um zu wählen, an wen sie weitergegeben werden. Dann kommen sie in der replication-Funktion dieses Befehls an. Siehe Networking.
task:tween Shared¶
task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween
Spielt einen Tween ab, der mit der Aufgabe aufgeräumt wird und deshalb nie länger lebt als der Befehl.
task:createSound Shared¶
task:createSound(soundType: SoundType?): Sound
Erstellt einen Sound, der der Aufgabe gehört und von ihr aufgeräumt wird. Lautstärke und Tonhöhe dieses Sounds kann dann jeder Spieler unter YouSettings einstellen. Der SoundType ist standardmäßig "Command", wenn er nicht gesetzt wird.
task:onEnded Shared¶
task:onEnded(callback: () -> ())
Führt deinen Callback jedes Mal aus, wenn die Aufgabe endet. Das ist gleichbedeutend mit task.janitor:add(callback).
task:onEndedForGood Shared¶
task:onEndedForGood(callback: () -> ())
Führt deinen Callback nur aus, wenn die Aufgabe beendet ist UND direkt danach keine identische Aufgabe erstellt wird. Das ist nützlich für Befehle wie ;serverLock Admin, der beim Ausführen einen Hinweis anzeigt ("This server has been locked for Admins") und beim Beenden ebenfalls ("This server has been unlocked"). Führen wir danach aber ;serverLock Mod aus, soll der vorherige Befehl seinen Abschlusshinweis nicht anzeigen, sondern nur der neue Hinweis beim Start erscheinen.
task:destroy Shared¶
task:destroy()
Beendet die Aufgabe sofort und räumt alles auf, was ihr gehört. Das ruft ;un im Hintergrund auf.
Scheduling Shared¶
task.spawn(callback: () -> ())
task.defer(callback: () -> ())
task.delay(seconds: number, callback: (() -> ())?)
task.wait(seconds: number?)
task.iterate(count: number, callback: (index: number) -> ())
task.loop(callback: (stop: () -> (), index: number) -> ())
Das sind aufgabenbewusste Wrapper um Roblox' eigenes task-Scheduling. Sie sind wichtig, damit der Befehl am Leben bleibt, solange er aktiv ist, und damit sie automatisch abgebrochen werden, wenn ihre Aufgabe aufgeräumt wird (zum Beispiel wenn jemand undo ausführt, bevor die Aufgabe endet). Benutze sie einfach so, wie du Roblox' Task-Methoden sonst auch benutzt, und HD Admin erledigt den Rest intern.
Eigenschaften¶
task.target Server¶
task.target: Player
Der Spieler, auf dem der Befehl läuft. Wenn dein erstes Argument Player ist, gibt es immer einen, weil HD Admin den Lauf für jeden gefundenen Spieler in eine eigene Aufgabe aufteilt. Du kannst ihn also ohne Prüfung verwenden. Befehle mit einem Sammelargument Players werden so nicht aufgeteilt, deshalb ist er dort leer. task.targetUserId enthält seine UserId und ist auch dann vorhanden, wenn er offline ist.
task.qualifiers Server¶
task.qualifiers: {[string]: {string}}
Wen der Aufrufer in seinem ursprünglichen Befehlstext angesprochen hat. ;clone others ergibt {others = {}}, ein einfaches ;clone ergibt eine leere Tabelle. Es ist immer eine Tabelle, du kannst sie also gefahrlos direkt lesen.
task.caller Server¶
task.caller: Player?
Wer den Befehl ausgeführt hat, oder nil, wenn es der Server war (oder wenn ein globaler Befehl auf einem Server ankommt, auf dem der Aufrufer nicht ist). task.callerUserId ist immer vorhanden, nimm also diese, wenn du die UserId brauchst.
task.janitor Shared¶
task.janitor:add(item): typeof(item)
Ein Janitor-Objekt, dem du Instanzen, Verbindungen und Funktionen übergeben kannst, damit sie automatisch aufgeräumt werden. Zum Beispiel:
local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart
task.config Server¶
task.config: {[string]: any}
Die eigene config-Tabelle des Befehls, einschließlich allem, was ein Paket über modify in Config > Commands geändert hat. So liest ein Befehl eine Einstellung, die der Besitzer des Spiels ändern können soll, etwa die Erlaubnis- und Sperrlisten von ;insert.
task.extra Shared¶
task.extra: {[string]: any}
Eine Tabelle für zusätzliche Informationen, die du ergänzen kannst und die eine Deaktivierung überdauert, bis die Aufgabe vollständig beendet ist.
task.isActive Shared¶
task.isActive: boolean
true, solange die Aufgabe läuft, und false, sobald sie zu enden beginnt. Nutze das in Schleifen, damit dein Effekt sofort aufhören kann, wenn die Aufgabe zum Beispiel zwangsweise beendet wurde.
task.commandKey Shared¶
task.commandKey: string
Der kleingeschriebene Name des Befehls, den diese Aufgabe ausführt.
task.isReplay Server¶
task.isReplay: boolean
true, wenn ein gespeicherter permanenter Befehl beim Start eines Servers erneut abgespielt wird, statt dass ihn jemand gerade ausführt. Nützlich, um Eingabeaufforderungen in Perm-Befehlen einzuschränken, die der Aufrufer nicht automatisch noch einmal sehen soll (etwa eine ;music-Eingabeaufforderung beim Beitritt zu jedem neuen Server).