Zum Inhalt

Server API

Alles hier befindet sich in CoreServerAPI und läuft in einem Server-Script:

local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd.Core.ServerAPI)

Befehle

requestCommand Server

ServerAPI.requestCommand(message: string, fromPlayer: Player?): (boolean, {any}, {Task})

Führt eine Befehlsnachricht genau so aus, als wäre sie im Chat geschrieben worden. Wenn kein Spieler angegeben ist, übernimmt ein Server User die Rolle des Aufrufers. So kannst du Befehle von überall in deinem Spielcode auslösen, ohne dass Berechtigungen geprüft werden. Wenn du einen Spieler übergibst, gelten seine Rollen, Berechtigungen und Ratenbegrenzungen, und alle Hinweise an den Aufrufer werden an ihn gesendet. Gibt zurück, ob der Befehl genehmigt wurde, die erzeugten Hinweise und die Aufgaben, die er erstellt hat.

-- Run as the server
ServerAPI.requestCommand(";fly all")

-- Or on behalf of a player
ServerAPI.requestCommand(";fly me", player)

getTasks Server

ServerAPI.getTasks(commandName: string?, target: Target?): {Task}

Gibt die laufenden Aufgaben zurück. Beide Filter sind optional. ServerAPI.getTasks() liefert jede Aufgabe, ServerAPI.getTasks("fly") jede fly-Aufgabe und ServerAPI.getTasks("fly", player) nur die fly-Aufgaben dieses Spielers.


endTasks Server

ServerAPI.endTasks(commandName: string?, target: Target?): number

Beendet die passenden Aufgaben und gibt zurück, wie viele beendet wurden. Das ist ;unCommand als Code, mit denselben optionalen Filtern wie getTasks.

-- End every fly in the server
ServerAPI.endTasks("fly")

-- Clear everything running on one player
ServerAPI.endTasks(nil, player)

canUseCommandAsync Server

ServerAPI.canUseCommandAsync(target: Target, commandName: string): (boolean, string?)

Gibt an, ob die Rollen des Ziels es erlauben, den angegebenen Befehl auszuführen. Gibt true zurück, oder false und den Grund.


disableCommands Server

ServerAPI.disableCommands(player: Player)

Sperrt dem Spieler alle neuen Befehle, bis enableCommands aufgerufen wird oder er neu beitritt. Praktisch, solange er in einer Minispielrunde oder einer Cutscene steckt. Seine bereits laufenden Aufgaben laufen weiter, kombiniere das also mit endTasks, wenn sie auch beendet werden sollen. Du kannst es bedenkenlos direkt aus PlayerAdded aufrufen.


enableCommands Server

ServerAPI.enableCommands(player: Player)

Erlaubt dem Spieler wieder, Befehle auszuführen.


Rollen

Rollennamen werden ohne Beachtung der Groß- und Kleinschreibung abgeglichen, "VIP" und "vip" treffen also dieselbe Rolle.

giveRoleAsync Server

ServerAPI.giveRoleAsync(target: Target, roleName: string, options: ActionOptions?): (boolean, string?)

Gibt dem Ziel die Rolle und gibt true zurück, oder false und den Grund, warum es nicht geklappt hat. Dauerhafte Vergaben werden gespeichert, gelten serverübergreifend und funktionieren auch bei Zielen, die offline sind.

Option Was sie macht
scope "perm" speichert für immer (der Standard), "server" gilt nur für diesen Server, "expire" entfernt sich nach duration von selbst
duration Sekunden, für den Scope "expire" erforderlich
reason Der Grund für die Vergabe
callerUserId Die UserId der Person, die die Rolle vergeben hat und gegen deren Rang geprüft wird
-- Reward a purchase forever
ServerAPI.giveRoleAsync(player, "VIP")

-- A 24 hour trial, granted by an offline head admin
ServerAPI.giveRoleAsync(player, "Mod", {
    scope = "expire",
    duration = 24 * 3600,
    callerUserId = 1234567,
})

takeRoleAsync Server

ServerAPI.takeRoleAsync(target: Target, roleName: string, options: ActionOptions?): (boolean, string?)

Nimmt dem Ziel die Rolle weg, auch dauerhafte Vergaben, die auf anderen Servern oder im Offline-Zustand gemacht wurden. options akzeptiert scope ("perm" oder "server") und callerUserId, genau wie bei giveRoleAsync.


getRolesAsync Server

ServerAPI.getRolesAsync(target: Target): (boolean, {Role} | string)

Gibt true und die Rollen des Ziels zurück, sortiert mit dem höchsten Rang zuerst, oder false und einen Grund. Das Ziel muss sich auf diesem Server befinden.

local success, roles = ServerAPI.getRolesAsync(player)
if success then
    for _, role in roles do
        print(role.name, role.rank)
    end
end

getTopRoleAsync Server

ServerAPI.getTopRoleAsync(target: Target): (boolean, (Role | string)?)

Gibt true und die ranghöchste Rolle des Ziels zurück (nil, wenn es keine hat), oder false und einen Grund. Das Ziel muss sich auf diesem Server befinden.


hasRoleAsync Server

ServerAPI.hasRoleAsync(target: Target, roleName: string): boolean

Gibt an, ob das Ziel die Rolle aktuell hat. Das Ziel muss sich auf diesem Server befinden.


getRole Server

ServerAPI.getRole(roleName: string): Role?

Gibt die Rolle mit dem angegebenen Namen zurück, oder nil, wenn keine Rolle passt.


getAllRoles Server

ServerAPI.getAllRoles(): {Role}

Gibt jede Rolle aus der Konfiguration deines Spiels zurück.


Moderation

banAsync Server

ServerAPI.banAsync(target: Target, options: BanOptions): (boolean, string?)

Sperrt das Ziel für den Zutritt zu deinem Spiel und kickt es, falls es gerade auf irgendeinem Server ist. Gibt true und die neue banId zurück, oder false und den Grund, warum es nicht geklappt hat. Funktioniert auch bei Offline-Zielen.

Option Was sie macht
reason Erforderlich, wird dem Spieler beim Beitrittsversuch angezeigt
scope "perm" (der Standard), "server" nur für diesen Server, oder "expire"
duration Sekunden, für den Scope "expire"
expiresAt Ein absoluter Epoch-Zeitstempel, der duration überschreibt
banAlts Standardmäßig true, sperrt Zweitkonten über den BanService von Roblox
callerUserId Eine UserId, der der Bann zugeschrieben wird und gegen deren Rang geprüft wird. Lässt du sie weg, ist es ein Systembann ohne Einschränkungen
-- A 7 day ban issued by your own anti-cheat
ServerAPI.banAsync(player, {
    reason = "Exploiting",
    scope = "expire",
    duration = 7 * 24 * 3600,
})

unbanAsync Server

ServerAPI.unbanAsync(target: Target, banId: string?, options: UnbanOptions?): (boolean, string?, number?)

Hebt die Banne des Ziels auf und gibt (success, failReason, totalBansCleared) zurück. Übergib eine banId, um einen bestimmten Bann aufzuheben, oder nil, um alle aufzuheben. options akzeptiert scope und callerUserId.


getBanAsync Server

ServerAPI.getBanAsync(target: Target): (BanRecord?, string?)

Gibt den aktiven BanRecord des Ziels und seine banId zurück, wobei auch Offline-Einträge geprüft werden, oder nil, wenn es nicht gebannt ist.

local ban, banId = ServerAPI.getBanAsync(userId)
if ban then
    print(`Banned for '{ban.reason}' by {ban.bannedBy}`)
end

Eingabeaufforderungen

prompt Shared

ServerAPI.prompt(promptType: PromptType, player: Player, text: string, options: PromptOptions?): PromptHandle

Zeigt dem Spieler mit der eigenen Oberfläche von HD Admin einen Hinweis, eine Nachricht oder eine Karte an, aus jedem Server-Script. Das ist dieselbe Funktion wie das prompt der Command API. Dort findest du alle Typen von Eingabeaufforderungen, die vollständige Liste der Optionen und die Aktionskarten mit Schaltflächen und Reglern.

ServerAPI.prompt("success", player, "Quest complete!", {duration = 5})

Text

filterTextAsync Server

ServerAPI.filterTextAsync(text: string, author: Target, viewer: Target?): (boolean, string)

Schickt den Text durch den Filter von Roblox und gibt true und den gefilterten Text zurück, oder false und den Grund. Lass viewer weg, um für alle zu filtern. Das ist richtig für alles, was jeder Spieler sehen kann, und für Text, den du speicherst. Übergib einen viewer, um stattdessen nur für diesen einen Spieler zu filtern. Der Autor muss sich auf diesem Server befinden, weil der Filter von Roblox sonst nicht läuft. Text, der nur als Hashtags zurückkommt, zählt als Fehlschlag, damit du nie ein leeres Ergebnis anzeigst.

local success, result = ServerAPI.filterTextAsync(petName, player)
if success then
    nameLabel.Text = result
else
    ServerAPI.prompt("warn", player, "That name can't be used")
end

Info

getSetting Shared

ServerAPI.getSetting(settingName: string, player: Player?): any

Gibt den Wert einer Spieleinstellung zurück, zum Beispiel ServerAPI.getSetting("Prefix"). Übergib einen Spieler, damit auch seine eigenen You Settings angewendet werden. So bekommst du genau den Wert, den dieser Spieler erlebt.


getVersion Shared

ServerAPI.getVersion(): string

Die laufende HD-Admin-Version, zum Beispiel "v2.0.0".


Isolation

isolateServer Server

ServerAPI.isolateServer()

Trennt diesen Server vom Speichern von Daten und vom Senden an andere Server. Alles scheint weiterhin normal zu funktionieren, etwa permanente Banne, Rollenänderungen, Spieleinstellungen, globale Befehle und globale Abstimmungen. Nichts davon wird aber wirklich gespeichert oder erreicht andere Server, deshalb ist alles weg, sobald der Server endet. Gespeicherte Daten werden weiterhin normal gelesen, der Server startet also mit deinen echten Rollen, Bannen, Einstellungen usw. Die persönlichen Präferenzen jedes Spielers, etwa seine You Settings und Lieblings-Emotes, werden weiterhin gespeichert, weil sie nur diesen Spieler betreffen.

Das ist nützlich für private oder reservierte Server, auf denen du jemandem "Owner" geben willst, ohne dass das Auswirkungen auf den Rest deines Universums hat.

local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd:WaitForChild("Core"):WaitForChild("ServerAPI"))
ServerAPI.isolateServer()

isServerIsolated Server

ServerAPI.isServerIsolated(): boolean

Gibt true zurück, sobald isolateServer auf diesem Server aufgerufen wurde.


Einschränkung

restrictServer Server

ServerAPI.restrictServer(options: RestrictOptions?)

Das schränkt alle spielweiten Funktionen ein, darunter Spieleinstellungen, Rollenänderungen, permanente Rollen, permanente Banne und Entbannungen, Vetting, gespeicherte Aufgaben sowie die Modifikatoren perm, global und join. Befehle, die zu den Rollen in commandsInRoles gehören oder in commands genannt sind, werden ebenfalls eingeschränkt. Im Panel erscheint weiterhin alles normal. Erst wenn die Funktion oder der Befehl tatsächlich benutzt wird, wird stattdessen ein Fehlerhinweis angezeigt. Wer eine Rolle aus bypassRoles hat, umgeht jede Einschränkung.

Anders als bei isolateServer werden Daten weiterhin gespeichert und erreichen weiterhin andere Server. Der HD Admin Hub nutzt das zum Beispiel, um jedem Spieler "Dev" zu geben und das Admin-Panel vorzuführen. Viele missbrauchsanfällige Befehle und Funktionen sind aber eingeschränkt, damit niemand die Server zerstören kann.

Option Was sie macht
commandsInRoles Rollennamen oder Schlüssel, deren Befehle abgelehnt werden
commands Befehlsnamen oder Schlüssel, die zusätzlich abgelehnt werden
bypassRoles Rollennamen oder Schlüssel, die jede Einschränkung umgehen
warning Ersetzt "This is restricted in this game", den Hinweis, der erscheint, wenn etwas abgelehnt wird
local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd:WaitForChild("Core"):WaitForChild("ServerAPI"))
ServerAPI.restrictServer({
    commandsInRoles = {"Dev", "Owner"},
    commands = {"BuildingTools", "Music"},
    bypassRoles = {"Owner"},
    warning = "This is restricted in this demo",
})

isServerRestricted Server

ServerAPI.isServerRestricted(): boolean

Gibt true zurück, sobald restrictServer auf diesem Server aufgerufen wurde.


Emotes

getEmoteById Server

ServerAPI.getEmoteById(emoteId: number): Emote?

Gibt das registrierte Emote mit der angegebenen ID zurück, oder nil.


getEmoteByName Server

ServerAPI.getEmoteByName(emoteName: string, matchLength: boolean?): Emote?

Gibt das registrierte Emote zurück, das zum angegebenen Namen passt, oder nil.


getRandomEmote Server

ServerAPI.getRandomEmote(): Emote?

addEmoteAsync Server

ServerAPI.addEmoteAsync(emote: IncompleteEmote, dontRegister: boolean?): (boolean, Emote | string)

Registriert ein neues Emote aus einem Emote-Animations-Asset, damit es mit ;emote abgespielt werden kann und im Emote-Menü erscheint. Nur emoteId ist erforderlich, die fehlenden Angaben werden für dich geholt. Gibt true und das fertige Emote zurück, oder false und den Grund, warum es nicht geklappt hat.


Typen

Role

Die vollständige Konfigurationstabelle einer Rolle, genau wie unter ConfigRoles definiert. Siehe Rollen.


BanRecord

type BanRecord = {
    type: "perm" | "expire" | "server",
    source: "admin" | "loader",
    bannedBy: number | string,
    bannedAt: number,
    expiresAt: number?,
    grantedOnJobId: string?, -- only present on server-scope bans
    reason: string,
    banAlts: boolean,
}

Die banId ist nicht Teil des Eintrags selbst, deshalb liefert getBanAsync sie dir als zweiten Rückgabewert.


Task

Siehe Task API.


Emote

type Emote = {
    name: string,
    originalName: string?,
    order: number,
    animationId: number,
    emoteId: number,
}