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