Aller au contenu

API du serveur

Tout ce qui est ici se trouve dans CoreServerAPI et s'exécute depuis un Script serveur :

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

Commandes

requestCommand Serveur

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

Exécute un message de commande exactement comme s'il avait été écrit dans le chat. Si tu ne donnes pas de joueur, un utilisateur serveur prend la place de l'appelant, donc tu peux lancer des commandes depuis n'importe où dans le code de ton jeu, sans vérification de permission. Si tu donnes un joueur, ses rôles, ses permissions et ses limites de fréquence s'appliquent, et les notifications destinées à l'appelant lui sont envoyées. Renvoie si la commande a été approuvée, les notifications produites, et les tâches créées.

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

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

getTasks Serveur

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

Renvoie les tâches en cours. Les deux filtres sont facultatifs. ServerAPI.getTasks() renvoie toutes les tâches, ServerAPI.getTasks("fly") toutes les tâches fly, et ServerAPI.getTasks("fly", player) uniquement les tâches fly de ce joueur.


endTasks Serveur

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

Termine les tâches correspondantes et renvoie combien ont été terminées. C'est ;unCommand sous forme de code, avec les mêmes filtres facultatifs que getTasks.

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

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

canUseCommandAsync Serveur

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

Indique si les rôles de la cible lui permettent d'exécuter la commande donnée. Renvoie true, ou false et la raison.


disableCommands Serveur

ServerAPI.disableCommands(player: Player)

Empêche le joueur d'exécuter de nouvelles commandes jusqu'à l'appel de enableCommands ou jusqu'à ce qu'il se reconnecte. Pratique pendant une manche de mini-jeu ou une cinématique. Ses tâches déjà en cours continuent, donc associe-le à endTasks si tu veux aussi les arrêter. Tu peux l'appeler directement depuis PlayerAdded sans souci.


enableCommands Serveur

ServerAPI.enableCommands(player: Player)

Permet de nouveau au joueur d'exécuter des commandes.


Rôles

Les noms de rôles ne tiennent pas compte de la casse, donc "VIP" et "vip" désignent le même rôle.

giveRoleAsync Serveur

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

Donne le rôle à la cible et renvoie true, ou false et la raison de l'échec. Les attributions permanentes sont sauvegardées, se propagent entre les serveurs et fonctionnent aussi pour les cibles hors ligne.

Option Ce que ça fait
scope "perm" sauvegarde pour toujours (par défaut), "server" dure uniquement pour ce serveur, "expire" se retire tout seul après duration
duration En secondes, obligatoire pour le scope "expire"
reason La raison de l'attribution
callerUserId Le UserId de la personne qui l'a donné, utilisé aussi pour la vérification de rang
-- 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 Serveur

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

Retire le rôle à la cible, y compris les attributions permanentes faites sur d'autres serveurs ou pendant qu'elle était hors ligne. options accepte scope ("perm" ou "server") et callerUserId, comme giveRoleAsync.


getRolesAsync Serveur

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

Renvoie true et les rôles de la cible, classés du rang le plus haut au plus bas, ou false et une raison. La cible doit être dans ce serveur.

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

getTopRoleAsync Serveur

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

Renvoie true et le rôle le plus élevé de la cible (nil si elle n'en a aucun), ou false et une raison. La cible doit être dans ce serveur.


hasRoleAsync Serveur

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

Indique si la cible possède actuellement le rôle. La cible doit être dans ce serveur.


getRole Serveur

ServerAPI.getRole(roleName: string): Role?

Renvoie le Role correspondant au nom donné, ou nil si aucun rôle ne correspond.


getAllRoles Serveur

ServerAPI.getAllRoles(): {Role}

Renvoie tous les rôles de la configuration du jeu.


Modération

banAsync Serveur

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

Bannit la cible de ton jeu, et l'expulse si elle est actuellement dans un serveur. Renvoie true et le nouveau banId, ou false et la raison de l'échec. Ça marche aussi pour les cibles hors ligne.

Option Ce que ça fait
reason Obligatoire, affichée au joueur quand il essaie de rejoindre
scope "perm" (par défaut), "server" pour ce serveur uniquement, ou "expire"
duration En secondes, pour le scope "expire"
expiresAt Une date absolue en epoch qui remplace duration
banAlts true par défaut, bannit les comptes alternatifs via le BanService de Roblox
callerUserId Un UserId à qui attribuer le bannissement, utilisé aussi pour la vérification de rang. Ne le mets pas pour un bannissement système sans restrictions
-- A 7 day ban issued by your own anti-cheat
ServerAPI.banAsync(player, {
    reason = "Exploiting",
    scope = "expire",
    duration = 7 * 24 * 3600,
})

unbanAsync Serveur

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

Supprime les bannissements de la cible et renvoie (success, failReason, totalBansCleared). Donne un banId pour supprimer un bannissement précis, ou nil pour tous les supprimer. options accepte scope et callerUserId.


getBanAsync Serveur

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

Renvoie le BanRecord actif de la cible et son banId, en regardant aussi les enregistrements hors ligne, ou nil si elle n'est pas bannie.

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

Invites

prompt Partagé

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

Affiche une notification, un message ou une carte au joueur avec l'interface de HD Admin, depuis n'importe quel Script serveur. C'est la même fonction que le prompt de la Command API, qui détaille tous les types d'invite, la liste complète des options, et les cartes d'action avec boutons et curseurs.

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

Texte

filterTextAsync Serveur

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

Passe le texte dans le filtre de Roblox et renvoie true et le texte filtré, ou false et la raison. Laisse viewer vide pour filtrer pour tout le monde, ce qui convient à tout ce que chaque joueur peut voir et au texte que tu sauvegardes. Donne un viewer pour filtrer uniquement pour ce joueur. L'auteur doit être dans ce serveur, car le filtre de Roblox refuse de s'exécuter pour quelqu'un qui n'y est pas. Un texte qui revient composé uniquement de hashtags compte comme un échec, donc tu n'affiches jamais un résultat vide.

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

Infos

getSetting Partagé

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

Renvoie la valeur d'un paramètre du jeu, comme ServerAPI.getSetting("Prefix"). Donne un joueur pour appliquer aussi ses propres paramètres personnels (You Settings), et obtenir ainsi la valeur exacte que ce joueur voit.


getVersion Partagé

ServerAPI.getVersion(): string

La version de HD Admin en cours d'exécution, comme "v2.0.0".


Isolation

isolateServer Serveur

ServerAPI.isolateServer()

Coupe ce serveur de la sauvegarde des données et de l'envoi de quoi que ce soit aux autres serveurs. Tout continue de sembler fonctionner normalement, comme les bannissements permanents, les modifications de rôles, les paramètres du jeu, les commandes globales et les votes globaux, sauf que rien n'est réellement sauvegardé ni transmis aux autres serveurs, donc tout disparaît à la fin du serveur. Les données sauvegardées sont quand même lues normalement, donc le serveur démarre avec tes vrais rôles, bannissements, paramètres, etc. Les préférences propres à chaque joueur, comme ses paramètres personnels (You settings) et ses emotes favorites, sont quand même sauvegardées parce qu'elles n'affectent que ce joueur.

C'est utile pour les serveurs privés ou réservés où tu veux donner "Owner" à quelqu'un sans aucun impact sur le reste de ton univers.

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

isServerIsolated Serveur

ServerAPI.isServerIsolated(): boolean

Renvoie true dès que isolateServer a été appelé dans ce serveur.


Restriction

restrictServer Serveur

ServerAPI.restrictServer(options: RestrictOptions?)

Restreint toutes les fonctionnalités qui touchent l'ensemble du jeu, dont les paramètres du jeu, les modifications de rôles, les rôles permanents, les bannissements et débannissements permanents, la vérification, les tâches sauvegardées, et les modificateurs perm, global et join. Les commandes des rôles de commandsInRoles ou citées dans commands sont aussi restreintes. Tout apparaît quand même normalement dans le panneau, jusqu'à ce que la fonctionnalité ou la commande soit utilisée, et là une notification d'erreur s'affiche à la place. Toute personne qui a un rôle dans bypassRoles échappe à toutes les restrictions.

Contrairement à isolateServer, les données sont quand même sauvegardées et atteignent les autres serveurs. Le HD Admin Hub l'utilise par exemple pour donner "Dev" à chaque joueur et présenter le panneau d'administration, tout en restreignant beaucoup de commandes et de fonctionnalités abusives pour éviter que les serveurs soient détruits.

Option Ce que ça fait
commandsInRoles Noms ou clés de rôles dont les commandes sont refusées
commands Noms ou clés de commandes refusées en plus de celles-là
bypassRoles Noms ou clés de rôles qui échappent à toutes les restrictions
warning Remplace "This is restricted in this game", la notification affichée chaque fois que quelque chose est refusé
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 Serveur

ServerAPI.isServerRestricted(): boolean

Renvoie true dès que restrictServer a été appelé dans ce serveur.


Emotes

getEmoteById Serveur

ServerAPI.getEmoteById(emoteId: number): Emote?

Renvoie l'Emote enregistrée avec l'id donné, ou nil.


getEmoteByName Serveur

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

Renvoie l'Emote enregistrée qui correspond au nom donné, ou nil.


getRandomEmote Serveur

ServerAPI.getRandomEmote(): Emote?

addEmoteAsync Serveur

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

Enregistre une nouvelle emote à partir d'un asset d'animation d'emote, pour qu'elle puisse être jouée avec ;emote et apparaître dans le menu des emotes. Seul emoteId est obligatoire, les autres détails sont récupérés pour toi. Renvoie true et l'Emote complète, ou false et la raison de l'échec.


Types

Role

La table de configuration complète d'un rôle, exactement comme elle est définie dans ConfigRoles. Voir Rôles.


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

Le banId ne fait pas partie de l'enregistrement lui-même, donc getBanAsync te le donne comme deuxième valeur de retour.


Task

Voir API des tâches.


Emote

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