Pular para conteúdo

Server API

Tudo aqui está em CoreServerAPI e roda a partir de um Script do servidor:

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

Comandos

requestCommand Servidor

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

Executa uma mensagem de comando exatamente como se ela tivesse sido enviada no chat. Quando nenhum jogador é informado, um Server User assume o lugar de quem chamou, então os comandos podem ser disparados de qualquer ponto do código do seu jogo, sem verificação de permissão. Quando você informa um jogador, os cargos, as permissões e os limites de uso dele valem normalmente, e os avisos para quem chamou são enviados a ele. Retorna se foi aprovado, os avisos gerados e as tarefas criadas.

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

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

getTasks Servidor

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

Retorna as tarefas em execução. Os dois filtros são opcionais. ServerAPI.getTasks() retorna todas as tarefas, ServerAPI.getTasks("fly") todas as tarefas de fly, e ServerAPI.getTasks("fly", player) apenas as tarefas de fly desse jogador.


endTasks Servidor

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

Encerra as tarefas correspondentes e retorna quantas foram encerradas. É o ;unCommand em forma de código, com os mesmos filtros opcionais de getTasks.

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

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

canUseCommandAsync Servidor

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

Diz se os cargos do alvo permitem que ele execute o comando indicado. Retorna true, ou false e o motivo.


disableCommands Servidor

ServerAPI.disableCommands(player: Player)

Impede o jogador de executar novos comandos até que enableCommands seja chamado ou ele entre de novo. Útil enquanto ele está numa rodada de minigame ou numa cutscene. As tarefas que ele já tem em execução continuam, então combine com endTasks se quiser encerrá-las também. Pode chamar direto de PlayerAdded sem problema.


enableCommands Servidor

ServerAPI.enableCommands(player: Player)

Deixa o jogador executar comandos de novo.


Cargos

Os nomes de cargo não diferenciam maiúsculas de minúsculas, então "VIP" e "vip" chegam ao mesmo cargo.

giveRoleAsync Servidor

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

Dá o cargo ao alvo e retorna true, ou false e o motivo da falha. Concessões permanentes são salvas, valem entre servidores e funcionam também para alvos offline.

Opção O que faz
scope "perm" salva para sempre (o padrão), "server" dura só neste servidor, "expire" se remove sozinho depois de duration
duration Segundos, obrigatório para o scope "expire"
reason O motivo da concessão
callerUserId O UserId de quem concedeu, usado também para checar o rank
-- 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 Servidor

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

Tira o cargo do alvo, incluindo concessões permanentes feitas em outros servidores ou enquanto ele estava offline. options aceita scope ("perm" ou "server") e callerUserId, igual a giveRoleAsync.


getRolesAsync Servidor

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

Retorna true e os cargos do alvo ordenados do maior rank para o menor, ou false e o motivo. O alvo precisa estar neste servidor.

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

getTopRoleAsync Servidor

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

Retorna true e o cargo mais alto do alvo (nil se ele não tiver nenhum), ou false e o motivo. O alvo precisa estar neste servidor.


hasRoleAsync Servidor

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

Diz se o alvo tem o cargo no momento. O alvo precisa estar neste servidor.


getRole Servidor

ServerAPI.getRole(roleName: string): Role?

Retorna o Role com o nome informado, ou nil se nenhum cargo corresponder.


getAllRoles Servidor

ServerAPI.getAllRoles(): {Role}

Retorna todos os cargos da configuração do jogo.


Moderação

banAsync Servidor

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

Bane o alvo de entrar no seu jogo e o expulsa se ele estiver em qualquer servidor no momento. Retorna true e o novo banId, ou false e o motivo da falha. Funciona também para alvos offline.

Opção O que faz
reason Obrigatório, mostrado ao jogador quando ele tenta entrar
scope "perm" (o padrão), "server" só para este servidor, ou "expire"
duration Segundos, para o scope "expire"
expiresAt Uma época absoluta que substitui duration
banAlts O padrão é true, banindo contas alternativas pelo BanService do Roblox
callerUserId Um UserId a quem atribuir o banimento e para checar o rank. Deixe de fora para um banimento do sistema, sem restrições
-- A 7 day ban issued by your own anti-cheat
ServerAPI.banAsync(player, {
    reason = "Exploiting",
    scope = "expire",
    duration = 7 * 24 * 3600,
})

unbanAsync Servidor

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

Remove os banimentos do alvo e retorna (success, failReason, totalBansCleared). Passe um banId para remover um banimento específico, ou nil para remover todos. options aceita scope e callerUserId.


getBanAsync Servidor

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

Retorna o BanRecord ativo do alvo e o banId dele, checando também os registros offline, ou nil se ele não estiver banido.

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

Prompts

prompt Compartilhado

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

Mostra um aviso, uma mensagem ou um card ao jogador usando a própria interface do HD Admin, a partir de qualquer Script do servidor. É a mesma função do prompt da API de comandos, que cobre todos os tipos de prompt, a lista completa de opções e os cards de ação com botões e controles deslizantes.

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

Texto

filterTextAsync Servidor

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

Passa o texto pelo filtro do Roblox e retorna true e o texto filtrado, ou false e o motivo. Deixe viewer de fora para filtrar para todos, o que é o certo para qualquer coisa que todo jogador pode ver e para texto que você vai salvar. Passe um viewer para filtrar só para aquele jogador. O autor precisa estar neste servidor, porque o filtro do Roblox se recusa a rodar para quem não está. Texto que volta só com hashtags conta como falha, então você nunca exibe um resultado vazio.

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

Informações

getSetting Compartilhado

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

Retorna o valor de uma configuração do jogo, como ServerAPI.getSetting("Prefix"). Passe um jogador para aplicar também as You Settings dele, assim você recebe exatamente o valor que aquele jogador vê.


getVersion Compartilhado

ServerAPI.getVersion(): string

A versão do HD Admin em execução, como "v2.0.0".


Isolamento

isolateServer Servidor

ServerAPI.isolateServer()

Corta este servidor de salvar dados e de enviar qualquer coisa para outros servidores. Tudo continua parecendo funcionar normalmente, como banimentos permanentes, edições de cargo, configurações do jogo, comandos globais e votações globais, mas nada disso é salvo nem chega a outros servidores, então tudo some quando o servidor fecha. Os dados salvos ainda são lidos normalmente, então o servidor começa com seus cargos, banimentos, configurações etc. reais. As preferências de cada jogador, como as You Settings e os emotes favoritos, ainda são salvas, porque afetam só aquele jogador.

Isso é útil em servidores privados ou servidores reservados onde você quer dar "Owner" a alguém sem afetar o resto do seu universo.

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

isServerIsolated Servidor

ServerAPI.isServerIsolated(): boolean

Retorna true depois que isolateServer foi chamado neste servidor.


Restrição

restrictServer Servidor

ServerAPI.restrictServer(options: RestrictOptions?)

Restringe todos os recursos que valem para o jogo inteiro, incluindo as configurações do jogo, edições de cargo, cargos permanentes, banimentos e desbanimentos permanentes, vetting, tarefas salvas e os modificadores perm, global e join. Os comandos dos cargos em commandsInRoles ou citados em commands também ficam restritos. Tudo continua aparecendo normalmente no painel, até que o recurso ou o comando seja usado e um aviso de erro seja exibido no lugar. Quem tem um cargo em bypassRoles ignora todas as restrições.

Diferente de isolateServer, os dados ainda são salvos e ainda chegam a outros servidores. O HD Admin Hub usa isso, por exemplo, para dar "Dev" a todos os jogadores e mostrar o painel de administração, mas restringe vários comandos e recursos abusivos para evitar que os servidores sejam destruídos.

Opção O que faz
commandsInRoles Nomes ou chaves de cargos cujos comandos são recusados
commands Nomes ou chaves de comandos recusados além desses
bypassRoles Nomes ou chaves de cargos que ignoram todas as restrições
warning Substitui "This is restricted in this game", o aviso mostrado sempre que algo é recusado
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 Servidor

ServerAPI.isServerRestricted(): boolean

Retorna true depois que restrictServer foi chamado neste servidor.


Emotes

getEmoteById Servidor

ServerAPI.getEmoteById(emoteId: number): Emote?

Retorna o Emote registrado com o id informado, ou nil.


getEmoteByName Servidor

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

Retorna o Emote registrado que corresponde ao nome informado, ou nil.


getRandomEmote Servidor

ServerAPI.getRandomEmote(): Emote?

addEmoteAsync Servidor

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

Registra um novo emote a partir de um asset de animação de emote, para que ele possa ser tocado por ;emote e apareça no menu de emotes. Só emoteId é obrigatório, e os detalhes que faltam são buscados para você. Retorna true e o Emote completo, ou false e o motivo da falha.


Tipos

Role

A tabela completa de configuração de cargo, exatamente como definida em ConfigRoles. Veja Cargos.


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

O banId não faz parte do registro em si, então getBanAsync entrega ele a você como segundo valor de retorno.


Task

Veja API de tarefas.


Emote

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