콘텐츠로 이동

Command API

명령어가 안전하게 참조할 수 있는 기능은 모두 CommandAPI에 있어요.

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

불러오기

loadCommands 서버

CommandAPI.loadCommands(details): Commands

Config > Commands 아래의 팩 모듈이 명령어 세트를 불러오고, 태그를 달고, 수정할 때 쓰는 함수예요. 그곳의 팩을 아무거나 열어 보면 어떻게 쓰는지 볼 수 있어요.


프롬프트

prompt 공용

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

공지, 메시지, 카드를 보여줘요. 버튼이 있는 액션 프롬프트는 bindPrompt를 참고하세요.

프롬프트 종류 보여주는 것
"info" "success" "warn" "error" 효과음이 나는 사이드바 공지
"message" 화면 중앙에 뜨는 메시지예요. 예를 들어 ;message에서 써요
"hint" 화면 위쪽에 뜨는 작은 바예요. 예를 들어 ;hint에서 써요
"privateMessage" 클릭하면 전체 메시지가 열리는, 사라지지 않는 사이드바 공지
"alert" 음소거할 때까지 효과음이 반복되고, 클릭하면 전체 메시지가 열리는 사이드바 공지
"action" 버튼과 컨트롤이 있는 사이드바 공지예요. task:bindPrompt로 만들어요
CommandAPI.prompt("success", task.caller, "Quest complete!", {duration = 5})

프롬프트를 끝내려면 connection:Disconnect()로 연결을 끊을 수 있는 연결 객체를 돌려줘요. 예를 들어 작업의 janitor에 추가해 두면 명령어가 끝나는 즉시 프롬프트도 끝나요.

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

옵션

모두 선택 사항이고, 행에 따로 적혀 있지 않으면 모든 프롬프트 종류에서 쓸 수 있어요.

옵션 타입 하는 일
title string 텍스트 위에 붙는 제목이에요. privateMessage와 alert는 자체 제목을 써요
duration number 프롬프트가 저절로 사라지기까지의 초예요. 생략하면 텍스트 길이에 맞춰 정해져요. 0이면 닫거나 연결을 끊을 때까지 화면에 남아요
subtext string 텍스트 아래에 들어가는 더 작은 줄
icon string 공지 아이콘을 대체하는 rbxassetid:// 이미지
color Color3 hint의 텍스트 색을 바꿔요
dismissable boolean false면 닫기 버튼이 사라져서 duration이나 핸들로만 없앨 수 있어요
openPage string 공지를 클릭하면 패널에서 이 페이지가 열려요. "Commands", "Roles", "Settings", "About" 같은 값을 써요
openProfile boolean 공지를 클릭하면 플레이어 본인의 프로필이 열려요
openImage table {image = "rbxassetid://...", title = "Map", ratio = 16/9} 형태예요. 공지를 클릭하면 이미지가 화면 중앙에 열려요
linkButtons table 공지 아래쪽에 붙는 작은 버튼이에요. {label = "Roles", page = "Roles"}는 페이지를 열고, {label = "Profile", profile = true}는 프로필을 열어요. style = "Neutral"을 넣으면 차분한 색의 버튼이 되고, hideAfterPress = true를 넣으면 누른 뒤 공지가 닫혀요. LocalScript에서 클라이언트 API로 쓸 때는 {label = "Shop", onActivate = function() ... end, icon = "rbxassetid://..."}로 직접 만든 함수를 실행할 수 있어요
roleBadges table 제목 아래에 붙는 역할 배지예요. {{name = "Admin", color = Color3.fromRGB(255, 170, 0)}} 형태로 써요
countdown number 텍스트에 %TIME%이 있는 자리에서 이 초부터 실시간으로 카운트다운해요
fromUserId number 해당 유저의 아바타, 이름, 최상위 역할을 message, privateMessage, alert의 보낸 사람으로 보여줘요
userText boolean 리치 텍스트 태그 등을 적용하지 않고 텍스트를 쓴 그대로 보여줘요
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)}},
})

버튼이 있는 액션 프롬프트는 bindPrompt를 참고하세요.


캐릭터

getHumanoid 공용

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

플레이어의 Humanoid를 돌려줘요. 캐릭터가 없으면 nil이에요.


getHRP 공용

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

플레이어의 HumanoidRootPart를 돌려줘요. 없으면 nil이에요.


getHead 공용

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

플레이어의 Head와 캐릭터를 돌려줘요. 없으면 nil이에요.


getNeck 공용

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

플레이어의 목 관절을 돌려줘요. 없으면 nil이에요. R6와 R15 리그 모두에서 동작해요.


getTorso 공용

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

플레이어의 몸통을 돌려줘요. 없으면 nil이에요. R6와 R15 리그 모두에서 동작해요.


loadCharacter 서버

CommandAPI.loadCharacter(player: Player?)

플레이어의 캐릭터를 리스폰해요. HD Admin의 작업이 의도한 리스폰이라는 걸 알 수 있도록, player:LoadCharacter() 대신 항상 이 함수를 쓰세요.


플레이어

getUserInfoAsync 공용

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

오프라인 유저를 포함한 모든 유저에 대해 true와 UserInfo를 돌려줘요. 실패하면 false와 이유를 돌려줘요. 결과는 캐시되니까 다시 호출해도 부담이 없어요.


getNameFromUserIdAsync 공용

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

true와 유저 이름을 돌려줘요. 실패하면 false와 이유를 돌려줘요. 오프라인 유저에게도 쓸 수 있어요.


teleportAsync 서버

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

플레이어의 캐릭터를 주어진 CFrame으로 옮겨요. 의자를 끌고 가지 않도록 먼저 자리에서 일으켜 세워요.


getAllowedTargets 서버

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

명령어가 영향을 줄 수 있는 플레이어 목록이에요. 기본값은 서버의 모든 플레이어에서 You Settings의 Block commands를 켠 플레이어를 뺀 목록이에요.


unequipTools 서버

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

플레이어가 들고 있는 도구를 가방으로 되돌려요.


작업

getTasks 공용

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

실행 중인 작업을 돌려줘요. 명령어와 대상으로 걸러낼 수도 있어요. Task API에서 설명하는 것과 같은 작업 객체예요.


getTasksByCallerId 공용

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

주어진 호출자가 시작한 실행 중인 작업을 모두 돌려줘요.


채팅

systemMessage 공용

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

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

플레이어의 채팅에 시스템 스타일 메시지를 보내요.


checkTextLimit 서버

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

HD Admin은 Roblox의 연령 안전 정책 때문에 메시지와 관련된 기능의 전송 횟수를 제한해요. 이 함수로 그 대기 시간을 확인할 수 있어요.

텍스트를 보여줄 수 있으면 true를, 아니면 false와 남은 대기 시간을 돌려줘요.

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,
종류 함께 제한되는 것
"Message" 메시지, 힌트, 공지, 알림, 비공개 메시지, 투표
"SurfaceText" 이름, 칭호, 팀 이름, 스탯
"ChatText" 채팅 태그, 채팅 이름
"Reason" 킥과 밴 사유

forceBubbleChat 공용

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

플레이어의 캐릭터 위에 말풍선을 띄워요. 플레이어 대신 모델이나 파트를 넘기면 그 위에 띄워요.


의상

getDescription 서버

CommandAPI.getDescription(humanoid: Humanoid): HumanoidDescription

Humanoid의 현재 HumanoidDescription을 돌려줘요.


applyDescription 서버

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

HumanoidDescription을 안전하게 적용해요. Roblox가 첫 시도를 거부하면 다시 시도해요. properties를 넘기면 기본 description 위에 필드를 덧씌울 수 있어요.


outfitBuff 서버

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

HumanoidDescription 속성을 버프로 적용해요. 작업이 끝나면 저절로 원래대로 돌아가서, ;wormify 같은 명령어가 알아서 정리돼요.


setFakeBodyParts 서버

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

신체 파트를 명령어가 만든 대체 파트로 바꾸고, 원래 파트를 복원하는 함수를 돌려줘요.


clearFakeBodyParts 서버

CommandAPI.clearFakeBodyParts(character: Model)

그 대체 파트를 다시 제거해요.


runBundleId 서버

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

작업의 대상에게 카탈로그 번들을 입혀요. 작업이 끝나면 원래 의상으로 돌려놓아요.


에셋

registerSound 공용

CommandAPI.registerSound(sound: Sound)

명령어가 만드는 모든 Sound에 필요해요. 게임의 볼륨과 피치 설정이 그 Sound에도 적용돼요.


setAnchored 공용

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

인스턴스 아래의 모든 파트를 고정하거나 고정 해제해요.


setTransparency 공용

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

인스턴스 아래의 모든 파트를 투명하게 만들어요.


promptPurchaseAsync 서버

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

플레이어에게 에셋 구매 창을 띄워요. 에셋 종류에 맞는 구매 흐름으로 알아서 연결해 줘요.


ownsAssetAsync 服务器

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

플레이어가 해당 에셋을 가지고 있는지 알려줘요.


isTypeAsync 서버

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

에셋이 주어진 종류가 맞는지 확인해요. 맞으면 true를, 아니면 false와 이유를 돌려줘요.


loadAssetCommand 서버

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

에셋이 주어진 종류가 맞고 허용된 것인지 확인한 뒤 삽입하고, 배치는 콜백에 맡겨요. ;gear가 이 함수로 동작해요.


getToolsInfoAsync 서버

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

;give로 줄 수 있는 모든 도구의 ToolInfo와 함께 true를 돌려줘요. 실패하면 false와 이유를 돌려줘요.


유틸리티

getTargets 서버

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

한정자를 지금 해당되는 플레이어 목록으로 바꿔 줘요. "Nearby"와 "OthersNearby"는 기준 플레이어로부터 radius 스터드(기본 50) 안을 잡아요.


setCameraSubject 클라이언트

CommandAPI.setCameraSubject(newSubject: Instance)

로컬 플레이어의 카메라를 새 대상에 맞춰요. ;view에서 다른 플레이어의 Humanoid를 보는 게 그 예예요.


runPromptCommand 서버

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

;message, ;hint 같은 프롬프트 명령어의 핵심 로직이에요. 텍스트를 필터링하고, 모든 대상에게 프롬프트를 보여주고, 프롬프트가 사라질 때까지 작업을 유지해요.


runEmoteId 서버

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

작업의 대상에게 이모트 애니메이션을 재생하고, 작업이 끝나면 함께 끝내요.


createEmoteCommand 서버

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

완성된 이모트 명령어를 돌려줘요. 명령어 배열에 그대로 넣으면 돼요. properties로 생성된 명령어의 어떤 필드든 덮어쓸 수 있어요.


createBundleCommand 서버

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

;ratdance 같은 번들 명령어를 같은 방식으로 만들어 줘요.


bindEmotePrompt 서버

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

이모트 액션 카드를 작업에 연결해서, 대상이 이모트를 즐겨찾기에 넣거나 카탈로그에서 볼 수 있게 해요.


openProfile 서버

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

플레이어 화면에 주어진 유저의 프로필 팝업을 열어요.


openPage 서버

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

플레이어의 패널을 주어진 페이지로 바로 열어요. 원하면 그 페이지의 탭 하나까지 지정할 수 있어요.


openEmotes 서버

CommandAPI.openEmotes(player: Player?)

플레이어에게 이모트 팝업을 열어요.


colourRoleName 공용

CommandAPI.colourRoleName(role): string

리치 텍스트에 쓸 수 있도록, 역할 이름을 그 역할의 색으로 감싸서 돌려줘요.


isTableEmpty 공용

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

테이블에 항목이 하나도 없는지 확인해요. #tbl이 놓치는 키 기반 항목도 포함해서 봐요.


round 공용

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

숫자를 주어진 소수 자릿수로 반올림해요. 생략하면 정수로 반올림해요.


타입

Commands

type Commands = {Command}

명령어 모듈이 돌려주는 배열이에요.


Command

Commands 안에 들어가는 명령어 테이블 하나예요(name, args, run 등). 모든 필드는 사용자 지정 명령어에서 다뤄요.


Task

모든 run 함수에 전달되는 작업 객체예요. 자세한 내용은 Task API에서 다뤄요.


ClientCommands

Commands의 클라이언트 쪽 짝이에요. Client 모듈이 돌려줘요.


ClientCommand

ClientCommands 안에 들어가는 클라이언트 쪽 명령어 테이블 하나예요.


UserInfo

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

userTopRole은 이 서버에 있는 플레이어에게만 들어 있어요.


ToolInfo

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

PromptType

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

프롬프트 종류를 나타내는 문자열이에요. 각각이 무엇을 보여주는지는 prompt를 참고하세요.


PromptOptions

prompt가 받는 옵션 테이블이에요. 전체 목록은 prompt에 있어요.


PromptHandle

prompt가 돌려주는 핸들이에요. handle:Disconnect()로 프롬프트를 일찍 닫을 수 있어요.