사용자 지정 명령어
Tip
여기에서 보너스 명령어를 둘러볼 수 있어요.
명령어¶
명령어는 무엇인지, 어떻게 실행해야 하는지를 설명하는 정보 테이블일 뿐이에요. 이렇게 설계한 데에는 몇 가지 이유가 있어요.
| 메모리 | 명령어를 실행하면 스태프가 쉽게 확인하고 취소할 수 있는 '작업'으로 나타낼 수 있어요. 작업은 스스로 정리되어 메모리가 새지 않고, 별도의 undo 함수를 따로 쓸 필요도 없게 설계했어요. |
| 도달 범위 | 작업은 명령어를 실행한 특정 플레이어(즉 호출자)에 더 이상 의존하지 않아서, 어떤 명령어든 어떤 수식어와도 함께 쓸 수 있어요. 직접 만든 명령어도 바로 모든 서버에 전달할 수 있어요. |
| 안전 | 인수는 run이 호출되기 전에 먼저 검증돼요. 그래서 Player 인수는 진짜 Player로 들어오고, Number는 항상 허용 범위 안의 값으로 들어와요. 코드가 원본 텍스트를 다룰 일이 없고, 호출자는 자기 역할로 쓸 수 없는 명령어를 실행할 수 없어요. |
| 인터페이스 | 실행 페이지, 명령어 입력창 추천, 자동 완성은 args를 바탕으로 자동 생성돼요. 그래서 직접 만든 모든 명령어를 채팅을 못 하는 플레이어도 바로 쓸 수 있어요. |
| 타입 | 명령어는 완전한 타입을 갖추고 있어서, 명령어에 CommandAPI.Commands를 지정하면 코드를 쓰는 동안 자동 완성과 타입 경고를 받을 수 있어요. |
직접 만들기¶
ConfigCommands 아래에서 기존 Custom 모듈을 확장하거나, 원하는 만큼 명령어 테이블을 담은 모듈을 새로 추가하면 돼요.

--!strict
-- LOCAL
local TAGS = {"CoolCommands"}
local StarterPlayer = game:GetService("StarterPlayer")
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
local getHumanoid = CommandAPI.getHumanoid
local getHRP = CommandAPI.getHRP
-- COMMANDS
local commands: CommandAPI.Commands = {
--------------------
{
name = "Jump",
args = {"Player"},
tags = TAGS,
run = function(task: CommandAPI.Task)
local target = task.target
local humanoid = getHumanoid(target)
if not humanoid then return end
humanoid.Jump = true
end,
},
--------------------
{
name = "Fire",
args = {"Player"},
tags = TAGS,
run = function(task: CommandAPI.Task)
local target = task.target
local hrp = getHRP(target)
if not hrp then return end
task:keep("UntilTargetRespawns")
local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = hrp
end,
},
--------------------
}
return commands
클라이언트 명령어¶
명령어 코드는 기본적으로 서버에서만 사용하고 실행할 수 있는데, 클라이언트에서 실행해야 할 때도 있어요. 이럴 때는 명령어 모듈 아래에 Client라는 이름의 ModuleScript를 추가하고, 서버 명령어와 name 값이 같은 명령어 테이블을 넣으면 돼요.
--!strict
-- LOCAL
local TAGS = {script.Name}
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
-- COMMANDS
local commands: CommandAPI.Commands = {
--------------------
{
name = "Flash",
args = {"Player"},
tags = TAGS,
run = function(task: CommandAPI.Task)
local target = task.target
task.client:run(target)
end,
},
--------------------
}
return commands
--!strict
-- LOCAL
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
local Players = game:GetService("Players")
local TweenService = game:GetService("TweenService")
-- COMMANDS
local clientCommands: CommandAPI.ClientCommands = {
--------------------
{
name = "Flash",
run = function(task: CommandAPI.Task)
local localPlayer = Players.LocalPlayer
local playerGui = localPlayer:FindFirstChildOfClass("PlayerGui")
if not playerGui then
return
end
local screenGui = Instance.new("ScreenGui")
screenGui.Name = "HDCustomFlash"
screenGui.IgnoreGuiInset = true
screenGui.DisplayOrder = 999
local frame = Instance.new("Frame")
frame.BackgroundColor3 = Color3.new(1, 1, 1)
frame.Size = UDim2.fromScale(1, 1)
frame.Parent = screenGui
screenGui.Parent = playerGui
local tween = TweenService:Create(frame, TweenInfo.new(1), {BackgroundTransparency = 1})
tween.Completed:Once(function()
screenGui:Destroy()
end)
tween:Play()
end,
},
--------------------
}
return clientCommands
깜빡이는 이미지가 포함되어 있어요. 눌러서 보기
Info
복제 작업은 직접 할 필요가 없어요. 프레임워크가 Client라는 이름의 하위 모듈을 찾아서 플레이어에게 자동으로 옮겨 줘요.
명령어 필드¶
name을 제외한 모든 필드는 선택이에요.
| 이름 | |
|---|---|
name Shared |
표시되는 명령어 제목이자, 플레이어가 접두사 뒤에 입력하는 이름이에요. 되돌리기 이름도 겸해서, ;speed는 ;unspeed로 끝낼 수 있어요 |
aliases Server |
이 명령어를 실행하는 다른 이름이에요`` |
undoAliases Server |
명령어를 실행하는 대신 되돌리는 이름이에요 (예: NoClip은 {"Clip"}을 써요) |
description Server |
실행 페이지에서 명령어 아래에 보여 주는 한 문장이에요 |
credit Server |
명령어 제작에 기여한 사람이에요 (예: {"GigsD4X"}) |
| 실행 | |
|---|---|
args Server |
명령어가 받는 인수예요 (예: "Player", "Text", "Number" 등). 전체 목록은 MainModuleValueModulesParserArgs에서 확인할 수 있어요 |
run Shared |
명령어의 코드예요. 서버에서는 작업과 검증된 인수를 받고, 클라이언트에서는 작업과 서버가 task.client:run으로 넘겨준 값을 받아요 |
replication Client |
서버에서 반환한 데이터가 도착하는 함수예요. 클라이언트가 task.server:replicate를 호출하면 서버의 task.client.replicator가 받을 대상을 고르고, 그 대상의 클라이언트에서 이 함수가 실행돼요 |
config Server |
내장 명령어를 불러올 때 게임 제작자가 modify로 바꿀 수 있는 기본값이에요 |
cooldown Server |
명령어가 끝난 뒤 다시 실행할 수 있을 때까지 기다리는 시간(초)이에요 |
stackable Server |
보통 한 플레이어나 서버에서는 명령어가 하나만 활성화될 수 있어요. 이 값이 true이면 여러 개를 동시에 활성화할 수 있어요 |
groups Server |
같은 그룹에 속한 명령어는 같은 플레이어에게서 서로를 되돌리고, cooldown도 함께 써요 (예: Fly와 NoClip은 둘 다 "Flight" 그룹이라서 하나를 시작하면 다른 하나가 끝나요). 두 그룹은 특별한 의미가 있어요. "Prompt"는 메시지 형태의 명령어를 뜻해요. 이 명령어는 아무것도 입력하지 않아도 1분에 한 번이라는 텍스트 제한을 쓰고, Block prompts 설정으로 걸러져요. "Map"은 맵을 수정하는 명령어를 뜻해요. 가장 먼저 실행된 명령어가 조용히 사본을 보관해 두고, ;clearmap이 그 사본을 써요 |
| 도달 범위 | |
|---|---|
tags Server |
이 명령어가 상속받는 태그예요. 역할이 어떤 명령어를 상속받을지 정할 때 이 태그를 써요 |
disableModifiers Server |
명령어에 수식어를 쓰지 못하게 해요 |
disableGlobalModifiers Server |
전역 수식어(예: global, perm, join 등)를 명령어에 쓰지 못하게 해요 |
| 인터페이스 | |
|---|---|
order Server |
명령어 페이지에서의 위치예요. 숫자가 낮을수록 먼저 나와요 |
hide Server |
명령어 페이지에서 이 명령어를 숨겨요 |
autoPreview Server |
채팅이나 빠른 미리보기 버튼으로 명령어를 실행하면, 명령어를 바로 실행하지 않고 실행 페이지를 열어요 (예: Ban은 이 값으로 세부 내용을 먼저 확인해요) |
사용자 지정 인수¶
내장 인수(MainModuleValueModulesParserArgs 아래)로 필요한 인수 대부분을 해결할 수 있어요. 그래도 직접 만들고 싶다면 Config > Args 아래에서 만들 수 있어요.

return function(Args)
return {
["Radius"] = Args.createAliasOf("Number", {
display = "Radius",
min = 0,
max = 500,
step = 1,
default = 50,
}),
}
end
Warning
고른 이름이 HD Admin의 내장 인수 이름과 겹치지 않게 해 주세요. 겹치면 시작할 때 경고가 뜨고, 둘 중 하나만 적용돼요.
명령어 하나의 인수만 바꾸고 싶다면, 인수 이름 대신 인수 테이블을 쓸 수도 있어요.
args = {
"Player",
{arg = "Number", display = "Speed", default = 50, min = 0, max = 1000, step = 1, logarithmic = true},
},
args = {
"Player",
"Number",
},
Tip
인수의 동작을 통째로 바꾸지 않고 제약 조건만 수정하고 싶을 때 유용해요.

다른 플레이어에게 보이는 텍스트
Roblox의 연령 안전 정책은 플레이어가 다른 사람에게 보여 주는 텍스트를 1분에 한 번으로 제한해요. HD Admin은 모든 텍스트 인수를 필터링하고, 유형별로 1분 제한을 소모해요. 같은 유형의 모든 명령어가 이 제한을 함께 써요.
| 인수 | 쓰는 곳 |
|---|---|
"Text" |
메시지, 힌트, 공지, 경고, 투표로 보여 주는 모든 것 |
"SurfaceText" |
플레이어 위나 월드에 표시되는 이름, 제목, 라벨 |
"ChatText" |
채팅 태그와 채팅 이름 |
"Reason" |
킥과 밴 사유 |
유형을 직접 고르려면 {arg = "Text", textSurface = "SurfaceText"}처럼 인수 테이블에 textSurface를 추가하세요. 가끔만 다른 사람에게 보이는 텍스트라면 "None"을 쓰고, 실제로 보이는 시점에 checkTextLimit를 호출하세요.
인수¶
명령어의 인수를 가져오려면 task:getArg()를 쓰고, 이름이나 인덱스를 지정하세요.
args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
local target = task:getArg("Player")
local number = task:getArg("Number")
-- ...
end
args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
local target = task:getArg(1)
local number = task:getArg(2)
-- ...
end
Note
같은 인수가 두 개 이상 있는 명령어({"Player", "Number", "Number"})에서는 인덱스로 인수를 가져와야 해요.
"Player"가 첫 번째 인수이면, 명령어는 대상이 된 모든 플레이어에게 각각 따로 실행돼요. 이때는 task.target으로 "Player"를 가리킬 수 있어요.
args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
local target = task.target
local number = task:getArg("Number")
-- ...
end
지속¶
작업은 run이 끝나는 순간 없어져요. ;jump처럼 바로 끝나는 명령어에는 괜찮지만, music처럼 효과가 계속 남아야 하는 명령어에는 맞지 않아요. 그래서 계속 유지하고 싶은 명령어는 task:keep을 거쳐야 해요.
task:keep("UntilTargetRespawns")
| 지속 | 작업이 끝나는 때 |
|---|---|
"UntilTargetRespawns" |
대상이 리스폰하거나 나갈 때 |
"UntilTargetLeaves" |
대상이 나갈 때 |
"UntilCallerRespawns" |
명령어를 실행한 사람이 리스폰하거나 나갈 때 |
"UntilCallerLeaves" |
명령어를 실행한 사람이 나갈 때 |
"Indefinitely" |
누군가 ;un으로 끝내거나, 플레이어가 나갈 때 |
Tip
여러 'keep'을 함께 쓸 수도 있어요. 예를 들어 task:keep("UntilTargetLeaves")와 task:keep("UntilCallerLeaves")를 같이 쓰면, 호출자나 대상 중 한 명이 서버를 나갈 때 명령어가 끝나요.
버프¶
WalkSpeed 같은 Humanoid의 속성을 바꾸는 일은 보통 간단해요. 속성을 원하는 값으로 설정하면 끝이에요. 하지만 여러 명령어가 얽히면 조금 복잡해져요.
체력이 100인데 ;health me 500을 실행하고 이어서 ;god me를 실행했다고 해 볼게요. ;health가 먼저 체력을 500으로 설정하고, ;god이 99999로 바꿔요. 여기까지는 문제없어요. 그런데 health는 그대로 두고 god 작업만 없애고 싶다면 어떨까요? 많은 관리 시스템에서는 god을 되돌리면 아직 적용 중인 health 작업은 무시하고 체력을 100으로 되돌려요. 이건 원하는 동작이 아니고, 이럴 때 버프가 필요해요.
task:buff(target, "WalkSpeed", function(hasEnded: boolean, original: any)
local humanoid = getHumanoid(target)
local before = if humanoid then humanoid.WalkSpeed else StarterPlayer.CharacterWalkSpeed
if humanoid then
humanoid.WalkSpeed = if hasEnded then original else task:getArg("Number")
end
return before
end)
버프는 코드와 그 코드가 속한 그룹(이 예시에서는 "WalkSpeed")으로 이루어져 있어요. 그 그룹의 작업이 시작되거나 끝날 때마다 모든 버프가 순서대로 다시 실행돼요. 그래서 속성은 항상 마지막 명령어가 원하는 값으로 정해져요.
원래 값을 반환할 수도 있어요. 그룹에서 가장 먼저 실행된 버프가 기억해 두는 값이에요. 마지막 버프가 제거되면 속성을 이 원래 값으로 되돌릴 수 있어서, 이전 명령어가 어떤 값을 남겼든 상관없이 체력이 100으로 돌아와요.
네트워킹¶
서버에서 클라이언트 명령어에 접근하려면 task.client를 써요.
local part = Instance.new("Part")
task.client:expose(target, part)
task.client:run(target, part , "Hello this is a part from the server")
run = function(task: CommandAPI.Task, part, message)
print("part, message =", part, message)
end
Important
서버에서 새로 만든 인스턴스나 모델을 클라이언트와 공유하려면 task:expose를 꼭 써야 해요. 쓰지 않으면 클라이언트가 받지 못할 수도 있어요.
클라이언트가 서버나 다른 클라이언트와 정보를 공유하고 싶을 때도 많아요. 예를 들어 ;laserEyes를 쓰면 다른 클라이언트가 내 레이저 빔과 조준하는 위치를 볼 수 있어야 해요. 이럴 때는 task.server를 써요.
-- The client's device knows something that others don't
task.server:replicate(targetCFrame, lookCFrame)
-- Your chance to pick who sees it, and to throw out anything dodgy
task.client.replicator = function(replicateTo, targetCFrame, lookCFrame)
if typeof(targetCFrame) ~= "CFrame" or typeof(lookCFrame) ~= "CFrame" then
return
end
for _, player in getTargets("OthersNearby", target, 100) do
replicateTo(player, target, targetCFrame, lookCFrame)
end
end
-- Runs on every client the server chose in the same client module
replication = function(target: Player, targetCFrame: CFrame, lookCFrame: CFrame)
-- Show it happening on their screen
end,
Important
클라이언트는 악의적이거나 예상과 다른 값을 보낼 수 있으니, replicator 안의 값이 예상과 같은지 꼭 확인하세요.
Info
replicator가 보내지 않으면 다른 플레이어에게는 아무것도 전달되지 않아요. 그래서 클라이언트가 마음대로 아무 데이터나 몰래 뿌릴 수 없어요. 복제 요청의 양도 내부적으로 제한되어 있고, 클라이언트의 악용 가능성도 고려해 두었어요.
프롬프트¶
명령어를 실행하는 것도 좋지만, 실행 중에 조정할 수 있으면 더 좋아요. 이럴 때 task:bindPrompt를 쓰면 호출자에게 조정할 수 있는 카드를 보여 줄 수 있어요.
local function applyLaserColour()
local colour = task:getArg("Color")
-- set the beam colours, eye colours, etc
end
applyLaserColour()
task:bindPrompt({
args = {"Color"},
onChange = applyLaserColour,
})
한 번만 실행하는 동작에는 buttons를 추가할 수도 있어요.
task:bindPrompt({
title = "Teleport",
text = `Click to teleport to '{placeName}'`,
deactivate = false,
endOnClose = true, -- dismissing the card ends its task
buttons = {
{
label = "Teleport",
onActivate = onActivate,
},
},
})
confirm 버튼, 추가 토글, 다시 실행 버튼을 포함해 카드가 받는 모든 키는 task:bindPrompt에 정리되어 있어요. 일반 공지와 메시지는 프롬프트를 참고하세요.
작업과 사용할 수 있는 메서드에 대한 자세한 내용은 작업 API에서 확인할 수 있어요.