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().