Pular para conteúdo

Command API

Tudo o que um comando pode referenciar com segurança fica em CommandAPI:

local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)

Carregamento

loadCommands Server

CommandAPI.loadCommands(details): Commands

É o que os módulos de pacote em Config > Commands usam para carregar, marcar e modificar seus conjuntos de comandos. Abra qualquer um dos pacotes de lá para ver isso em ação.


Prompts

prompt Shared

-- In a server command module
CommandAPI.prompt(promptType: PromptType, player: Player, text: string, options: PromptOptions?): PromptHandle

-- In a client command module
CommandAPI.prompt(promptType: PromptType, text: string, options: PromptOptions?): PromptHandle

Mostra um aviso, uma mensagem ou um card. Para prompts de ação com botões, veja bindPrompt.

Tipo de prompt O que mostra
"info" "success" "warn" "error" Um aviso na lateral com efeito sonoro
"message" Uma mensagem no centro da tela, usada por exemplo em ;message
"hint" Uma barra pequena no topo da tela, usada por exemplo em ;hint
"privateMessage" Um aviso fixo na lateral que abre a mensagem completa ao ser clicado
"alert" Um aviso fixo na lateral que repete um som até ser silenciado e abre a mensagem completa ao ser clicado
"action" Um aviso na lateral com botões e controles. Crie esses com task:bindPrompt
CommandAPI.prompt("success", task.caller, "Quest complete!", {duration = 5})

Ele retorna uma conexão que você pode desconectar com connection:Disconnect() para encerrar o prompt. Você pode adicioná-las, por exemplo, ao janitor de uma tarefa para encerrar o prompt assim que o comando terminar:

task.janitor:add(CommandAPI.prompt("hint", task.target, "You're frozen until an admin releases you", {duration = 0})) -- 0 means "infinite"

Opções

Todas são opcionais e funcionam em todos os tipos de prompt, a menos que a linha diga o contrário:

Opção Tipo O que faz
title string O título acima do texto. privateMessage e alert definem o próprio
duration number Segundos até o prompt se dispensar sozinho. Se você omitir, o valor é calculado a partir do tamanho do texto. 0 mantém o prompt na tela até ser dispensado ou desconectado
subtext string Uma linha menor abaixo do texto
icon string Uma imagem rbxassetid:// que substitui o ícone do aviso
color Color3 Pinta o texto de um hint
dismissable boolean false esconde o botão de fechar, então só duration ou o handle podem removê-lo
openPage string Ao clicar no aviso, abre o painel nesta página, como "Commands", "Roles", "Settings" ou "About"
openProfile boolean Ao clicar no aviso, abre o perfil do próprio jogador
openImage table {image = "rbxassetid://...", title = "Map", ratio = 16/9}. Ao clicar no aviso, abre a imagem no centro da tela
linkButtons table Botões pequenos na parte de baixo do aviso. {label = "Roles", page = "Roles"} abre uma página e {label = "Profile", profile = true} abre o perfil. Adicione style = "Neutral" para um botão discreto e hideAfterPress = true para fechar o aviso depois de pressionado. Em um LocalScript, pela Client API, {label = "Shop", onActivate = function() ... end, icon = "rbxassetid://..."} executa a sua própria função
roleBadges table Selos de cargo abaixo do título, {{name = "Admin", color = Color3.fromRGB(255, 170, 0)}}
countdown number Faz uma contagem regressiva ao vivo, a partir desse número de segundos, onde quer que %TIME% apareça no texto
fromUserId number Mostra o avatar, o nome e o cargo mais alto desse usuário como remetente de uma message, privateMessage ou alert
userText boolean Mostra o texto exatamente como foi escrito, sem tags de rich text etc.
CommandAPI.prompt("info", task.caller, "You've unlocked the VIP role", {
    title = "New role",
    openPage = "Roles",
    roleBadges = {{name = "VIP", color = Color3.fromRGB(255, 170, 0)}},
})

Para prompts de ação com botões, veja bindPrompt.


Personagem

getHumanoid Shared

CommandAPI.getHumanoid(player: Player?): Humanoid?

O Humanoid do jogador, ou nil se o personagem dele não estiver presente.


getHRP Shared

CommandAPI.getHRP(player: Player?): BasePart?

O HumanoidRootPart do jogador, ou nil.


getHead Shared

CommandAPI.getHead(player: Player?): (BasePart?, Model?)

A Head do jogador e o personagem dele, ou nil.


getNeck Shared

CommandAPI.getNeck(player: Player?): Motor6D?

A junta do pescoço do jogador, ou nil. Funciona em rigs R6 e R15.


getTorso Shared

CommandAPI.getTorso(player: Player?): Instance?

O torso do jogador, ou nil. Funciona em rigs R6 e R15.


loadCharacter Server

CommandAPI.loadCharacter(player: Player?)

Faz o personagem do jogador renascer. Use sempre esta função no lugar de player:LoadCharacter(), para que as tarefas do HD Admin saibam que o respawn foi intencional.


Jogadores

getUserInfoAsync Shared

CommandAPI.getUserInfoAsync(userId: number | string): (boolean, UserInfo | string)

Retorna true e o UserInfo de qualquer usuário, mesmo offline, ou false e um motivo. Os resultados ficam em cache, então chamadas repetidas não custam nada.


getNameFromUserIdAsync Shared

CommandAPI.getNameFromUserIdAsync(userId: number | string): (boolean, string)

Retorna true e o nome do usuário, ou false e um motivo. Funciona para usuários offline.


teleportAsync Server

CommandAPI.teleportAsync(player: Player?, cframe: CFrame): (boolean, string)

Move o personagem do jogador para o CFrame indicado, tirando ele do assento antes para que não arraste o assento junto.


getAllowedTargets Server

CommandAPI.getAllowedTargets(task: Task, options: {players: {Player}?}?): ({Player}, {Player})

Os jogadores em quem um comando pode agir, que por padrão são todos no servidor menos quem ativou Block commands em You Settings.


unequipTools Server

CommandAPI.unequipTools(player: Player?): (boolean, string)

Devolve a ferramenta equipada do jogador para a mochila dele.


Tarefas

getTasks Shared

CommandAPI.getTasks(commandKey: string?, targetUserId: number?): {Task}

Retorna as tarefas em andamento, com filtro opcional por comando e alvo. São os mesmos objetos de tarefa descritos na Task API.


getTasksByCallerId Shared

CommandAPI.getTasksByCallerId(callerUserId: number): {Task}

Todas as tarefas em andamento iniciadas pelo executor indicado.


Chat

systemMessage Shared

-- In a server command module
CommandAPI.systemMessage(player: Player, text: string)

-- In a client command module
CommandAPI.systemMessage(text: string)

Envia uma mensagem no estilo do sistema para o chat do jogador.


checkTextLimit Server

CommandAPI.checkTextLimit(task: Task, textKind: "Message" | "SurfaceText" | "ChatText" | "Reason"): (boolean, number?)

O HD Admin limita o envio de recursos relacionados a mensagens por causa das políticas de segurança de idade da Roblox, então esta função permite ver esse tempo de espera.

Ela retorna true quando o texto pode ser mostrado, ou false com o tempo de espera restante.

args = {"Player", "Leaderstat", {arg = "String", textSurface = "None"}},
run = function(task)
    local stat = task:getArg("Leaderstat")
    local text = task:getArg("String")
    if stat:IsA("StringValue") then
        if not CommandAPI.checkTextLimit(task, "SurfaceText") then
            return
        end
    end
    stat.Value = text
end,
Tipo Compartilhado por
"Message" Mensagens, hints, avisos, alertas, mensagens privadas e votações
"SurfaceText" Nomes, títulos, nomes de times e estatísticas
"ChatText" Tags de chat e nomes de chat
"Reason" Motivos de expulsão e de banimento

forceBubbleChat Shared

CommandAPI.forceBubbleChat(target: Player | Model, text: string)

Mostra um balão de chat acima do personagem do jogador, ou acima de qualquer modelo ou parte que você passar no lugar.


Roupas

getDescription Server

CommandAPI.getDescription(humanoid: Humanoid): HumanoidDescription

A HumanoidDescription atual do humanoide.


applyDescription Server

CommandAPI.applyDescription(humanoid: Humanoid?, description: HumanoidDescription?, properties: {[string]: any}?): HumanoidDescription?

Aplica a HumanoidDescription com segurança, tentando de novo quando a Roblox rejeita a primeira tentativa. Passe properties para ajustar campos por cima da descrição base.


outfitBuff Server

CommandAPI.outfitBuff(target: Player, properties: {[string]: any})

Aplica propriedades da HumanoidDescription como um buff que se desfaz sozinho quando a tarefa termina, então comandos como ;wormify se limpam sozinhos.


setFakeBodyParts Server

CommandAPI.setFakeBodyParts(character: Model, info: {[string]: any}): (() -> ())?

Troca partes do corpo por substitutas criadas pelo comando e retorna uma função que restaura as originais.


clearFakeBodyParts Server

CommandAPI.clearFakeBodyParts(character: Model)

Remove essas substitutas de novo.


runBundleId Server

CommandAPI.runBundleId(task: Task, bundleId: number, properties: {[string]: any}?)

Veste o alvo da tarefa com um bundle do catálogo e restaura a roupa original dele quando a tarefa termina.


Assets

registerSound Shared

CommandAPI.registerSound(sound: Sound)

Obrigatório para qualquer Sound que o seu comando criar, para que as configurações de volume e de tom do jogo sejam aplicadas a ele.


setAnchored Shared

CommandAPI.setAnchored(instance: Instance, anchored: boolean)

Ancora ou desancora todas as partes dentro da instância.


setTransparency Shared

CommandAPI.setTransparency(instance: Instance, transparency: number)

Esmaece todas as partes dentro da instância.


promptPurchaseAsync Server

CommandAPI.promptPurchaseAsync(assetId: number, player: Player?, infoType: Enum.InfoType?)

Mostra ao jogador o prompt de compra do asset, usando o fluxo de compra certo para o tipo dele.


ownsAssetAsync Server

CommandAPI.ownsAssetAsync(assetId: number, player: Player?): boolean

Se o jogador possui o asset.


isTypeAsync Server

CommandAPI.isTypeAsync(assetId: number, assetType: Enum.AssetType | Enum.BundleType): (boolean, string?)

Verifica se o asset é do tipo indicado. Retorna true, ou false e o motivo.


loadAssetCommand Server

CommandAPI.loadAssetCommand(assetType: Enum.AssetType, task: Task, assetId: number, callback: (item: Instance) -> ())

Verifica se o asset é do tipo indicado e se é permitido, insere ele e depois o entrega ao seu callback para você posicionar. É isso que faz o ;gear funcionar.


getToolsInfoAsync Server

CommandAPI.getToolsInfoAsync(): (boolean, {ToolInfo} | string)

Retorna true e o ToolInfo de cada ferramenta disponível para ;give, ou false e um motivo.


Utilitários

getTargets Server

CommandAPI.getTargets(targetType: "All" | "Others" | "Nearby" | "OthersNearby", originPlayer: Player?, radius: number?): {Player}

Transforma um qualificador nos jogadores que ele cobre naquele momento. "Nearby" e "OthersNearby" medem a partir do jogador de origem, usando radius studs (50 por padrão).


setCameraSubject Client

CommandAPI.setCameraSubject(newSubject: Instance)

Aponta a câmera do jogador local para um novo alvo, como o Humanoid de outro jogador no ;view.


runPromptCommand Server

CommandAPI.runPromptCommand(promptType: PromptType, task: Task, targets: {Player}, text: string, options: PromptOptions?)

O motor por trás de ;message, ;hint e prompts parecidos. Ele filtra o texto, mostra o prompt para cada alvo e mantém a tarefa ativa até o prompt expirar.


runEmoteId Server

CommandAPI.runEmoteId(task: Task, emoteId: number, speed: number?, looped: boolean?)

Toca a animação do emote no alvo da tarefa e a encerra quando a tarefa termina.


createEmoteCommand Server

CommandAPI.createEmoteCommand(emoteName: string, emoteId: number, properties: {[string]: any}?): Command

Retorna um comando de emote completo, pronto para colocar no seu array de comandos. properties sobrescreve qualquer campo do comando gerado.


createBundleCommand Server

CommandAPI.createBundleCommand(commandName: string, bundleId: number, properties: {[string]: any}?): Command

O mesmo comportamento, para comandos de bundle como ;ratdance.


bindEmotePrompt Server

CommandAPI.bindEmotePrompt(task: Task, target: Player, emoteId: number, emoteName: string?, isLooped: boolean?)

Vincula o card de ação do emote à tarefa, para que o alvo possa favoritar o emote ou vê-lo no catálogo.


openProfile Server

CommandAPI.openProfile(player: Player?, userId: number)

Abre para o jogador o popup de perfil do usuário indicado.


openPage Server

CommandAPI.openPage(player: Player?, pageId: string, tabLabel: string?)

Abre o painel do jogador direto na página indicada, e opcionalmente em uma das abas dela.


openEmotes Server

CommandAPI.openEmotes(player: Player?)

Abre o popup de emotes para o jogador.


colourRoleName Shared

CommandAPI.colourRoleName(role): string

O nome do cargo envolto na cor dele, para rich text.


isTableEmpty Shared

CommandAPI.isTableEmpty(tbl: {[any]: any}): boolean

Se a tabela não tem nenhuma entrada, incluindo as com chave, que #tbl não conta.


round Shared

CommandAPI.round(number: number, decimalPlaces: number?): number

Arredonda um número para as casas decimais indicadas, ou para um número inteiro por padrão.


Tipos

Commands

type Commands = {Command}

O array que um módulo de comandos retorna.


Command

Uma tabela de comando dentro de Commands (name, args, run e assim por diante). Custom Commands cobre todos os campos.


Task

O objeto de tarefa passado para toda função run, coberto por completo na Task API.


ClientCommands

O equivalente de Commands para o lado do cliente, retornado pelo módulo Client.


ClientCommand

Uma tabela de comando do lado do cliente dentro de ClientCommands.


UserInfo

type UserInfo = {
    userId: number | string,
    userName: string,
    userImage: string,
    userDisplayName: string,
    userTopRole: {key: string, name: string, color: Color3}?,
}

userTopRole só existe para jogadores deste servidor.


ToolInfo

type ToolInfo = {
    name: string,
    textureId: string,
    tool: Tool?,
}

PromptType

type PromptType = "info" | "success" | "warn" | "error" | "message" | "hint" | "privateMessage" | "alert" | "vote" | "voteResults" | "action"

As strings dos tipos de prompt. Veja prompt para saber o que cada uma mostra.


PromptOptions

A tabela de opções que prompt aceita, listada por completo em prompt.


PromptHandle

O handle que prompt retorna, que dispensa o prompt antes da hora com handle:Disconnect().