Server API
여기에 나오는 함수는 모두 CoreServerAPI에 있고, 서버 Script에서 실행해요.
local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd.Core.ServerAPI)
명령어¶
requestCommand Server¶
ServerAPI.requestCommand(message: string, fromPlayer: Player?): (boolean, {any}, {Task})
명령어 메시지를 채팅으로 입력한 것과 똑같이 실행해요. 플레이어를 넘기지 않으면 호출한 사람 자리에 Server User가 들어가서, 권한 확인 없이 게임 코드 어디에서든 명령어를 실행할 수 있어요. 플레이어를 넘기면 그 플레이어의 역할, 권한, 사용 횟수 제한이 모두 적용되고, 호출자에게 가는 공지도 그 플레이어에게 전달돼요. 승인 여부, 만들어진 공지, 생성된 작업을 반환해요.
-- Run as the server
ServerAPI.requestCommand(";fly all")
-- Or on behalf of a player
ServerAPI.requestCommand(";fly me", player)
getTasks Server¶
ServerAPI.getTasks(commandName: string?, target: Target?): {Task}
실행 중인 작업을 반환해요. 두 필터는 모두 선택이에요. ServerAPI.getTasks()는 모든 작업을, ServerAPI.getTasks("fly")는 모든 fly 작업을, ServerAPI.getTasks("fly", player)는 해당 플레이어의 fly 작업만 반환해요.
endTasks Server¶
ServerAPI.endTasks(commandName: string?, target: Target?): number
조건에 맞는 작업을 끝내고, 끝낸 개수를 반환해요. ;unCommand를 코드로 쓴 것과 같고, 선택 필터도 getTasks와 같아요.
-- End every fly in the server
ServerAPI.endTasks("fly")
-- Clear everything running on one player
ServerAPI.endTasks(nil, player)
canUseCommandAsync Server¶
ServerAPI.canUseCommandAsync(target: Target, commandName: string): (boolean, string?)
대상의 역할로 해당 명령어를 실행할 수 있는지 알려줘요. 가능하면 true를, 아니면 false와 그 이유를 반환해요.
disableCommands Server¶
ServerAPI.disableCommands(player: Player)
enableCommands를 호출하거나 플레이어가 다시 접속하기 전까지 새 명령어를 실행하지 못하게 막아요. 미니게임 라운드나 컷신 중에 쓰면 좋아요. 이미 실행 중인 작업은 그대로 계속되니, 그것도 없애고 싶다면 endTasks와 함께 쓰세요. PlayerAdded에서 바로 호출해도 안전해요.
enableCommands Server¶
ServerAPI.enableCommands(player: Player)
플레이어가 다시 명령어를 실행할 수 있게 해요.
역할¶
역할 이름은 대소문자를 구분하지 않아서, "VIP"와 "vip"는 같은 역할이에요.
giveRoleAsync Server¶
ServerAPI.giveRoleAsync(target: Target, roleName: string, options: ActionOptions?): (boolean, string?)
대상에게 역할을 주고 true를 반환해요. 줄 수 없으면 false와 그 이유를 반환해요. 영구 부여는 저장되고, 서버 간에 전달되고, 오프라인인 대상에게도 적용돼요.
| 옵션 | 하는 일 |
|---|---|
scope |
"perm"은 영구 저장(기본값), "server"는 이 서버에서만 유지, "expire"는 duration이 지나면 저절로 사라져요 |
duration |
초 단위이고, scope가 "expire"일 때 필수예요 |
reason |
역할을 주는 이유 |
callerUserId |
역할을 준 사람의 UserId이고, 이 사람의 랭크를 기준으로 확인해요 |
-- 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 Server¶
ServerAPI.takeRoleAsync(target: Target, roleName: string, options: ActionOptions?): (boolean, string?)
대상에게서 역할을 회수해요. 다른 서버에서 했거나 오프라인일 때 한 영구 부여도 포함돼요. options에는 giveRoleAsync와 똑같이 scope("perm" 또는 "server")와 callerUserId를 쓸 수 있어요.
getRolesAsync Server¶
ServerAPI.getRolesAsync(target: Target): (boolean, {Role} | string)
true와 함께 대상의 역할을 랭크가 높은 순으로 반환해요. 실패하면 false와 그 이유를 반환해요. 대상은 이 서버에 있어야 해요.
local success, roles = ServerAPI.getRolesAsync(player)
if success then
for _, role in roles do
print(role.name, role.rank)
end
end
getTopRoleAsync Server¶
ServerAPI.getTopRoleAsync(target: Target): (boolean, (Role | string)?)
true와 함께 대상의 가장 높은 역할을 반환해요. 역할이 하나도 없으면 nil이에요. 실패하면 false와 그 이유를 반환해요. 대상은 이 서버에 있어야 해요.
hasRoleAsync Server¶
ServerAPI.hasRoleAsync(target: Target, roleName: string): boolean
대상이 지금 그 역할을 갖고 있는지 알려줘요. 대상은 이 서버에 있어야 해요.
getRole Server¶
ServerAPI.getRole(roleName: string): Role?
해당 이름의 Role을 반환해요. 맞는 역할이 없으면 nil이에요.
getAllRoles Server¶
ServerAPI.getAllRoles(): {Role}
게임 설정에 있는 모든 역할을 반환해요.
관리¶
banAsync Server¶
ServerAPI.banAsync(target: Target, options: BanOptions): (boolean, string?)
대상이 게임에 들어오지 못하게 밴하고, 어느 서버에든 접속 중이면 킥해요. 성공하면 true와 새 banId를, 실패하면 false와 그 이유를 반환해요. 오프라인인 대상에게도 쓸 수 있어요.
| 옵션 | 하는 일 |
|---|---|
reason |
필수이고, 플레이어가 접속을 시도할 때 보여줘요 |
scope |
"perm"(기본값), 이 서버에서만 밴하는 "server", 또는 "expire" |
duration |
초 단위이고, scope가 "expire"일 때 써요 |
expiresAt |
절대 시각(epoch)이고, duration보다 우선해요 |
banAlts |
기본값은 true이고, Roblox의 BanService로 부계정도 밴해요 |
callerUserId |
밴을 한 사람으로 기록하고 랭크를 기준으로 확인할 UserId예요. 빼면 제한 없는 시스템 밴이 돼요 |
-- A 7 day ban issued by your own anti-cheat
ServerAPI.banAsync(player, {
reason = "Exploiting",
scope = "expire",
duration = 7 * 24 * 3600,
})
unbanAsync Server¶
ServerAPI.unbanAsync(target: Target, banId: string?, options: UnbanOptions?): (boolean, string?, number?)
대상의 밴을 해제하고 (success, failReason, totalBansCleared)를 반환해요. banId를 넘기면 그 밴 하나만 해제하고, nil을 넘기면 모두 해제해요. options에는 scope와 callerUserId를 쓸 수 있어요.
getBanAsync Server¶
ServerAPI.getBanAsync(target: Target): (BanRecord?, string?)
대상에게 적용 중인 BanRecord와 그 banId를 반환해요. 오프라인 기록도 확인하고, 밴 상태가 아니면 nil이에요.
local ban, banId = ServerAPI.getBanAsync(userId)
if ban then
print(`Banned for '{ban.reason}' by {ban.bannedBy}`)
end
프롬프트¶
prompt Shared¶
ServerAPI.prompt(promptType: PromptType, player: Player, text: string, options: PromptOptions?): PromptHandle
HD Admin의 UI로 플레이어에게 공지, 메시지, 카드를 보여줘요. 서버 Script라면 어디서든 쓸 수 있어요. Command API의 프롬프트와 같은 함수이고, 그쪽에서 모든 프롬프트 종류, 옵션 전체 목록, 버튼과 슬라이더가 있는 액션 카드를 자세히 다뤄요.
ServerAPI.prompt("success", player, "Quest complete!", {duration = 5})
텍스트¶
filterTextAsync Server¶
ServerAPI.filterTextAsync(text: string, author: Target, viewer: Target?): (boolean, string)
텍스트를 Roblox 필터에 통과시켜서, 성공하면 true와 필터링된 텍스트를, 실패하면 false와 그 이유를 반환해요. viewer를 빼면 모두를 기준으로 필터링해요. 모든 플레이어에게 보이는 텍스트나 저장할 텍스트에는 이 방식이 맞아요. viewer를 넘기면 그 플레이어 한 명을 기준으로 필터링해요. Roblox 필터는 서버에 없는 사람에게는 실행되지 않기 때문에, 작성자는 이 서버에 있어야 해요. 결과가 해시태그뿐이면 실패로 처리해서, 빈 결과를 화면에 보여주는 일이 없게 해요.
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
정보¶
getSetting Shared¶
ServerAPI.getSetting(settingName: string, player: Player?): any
ServerAPI.getSetting("Prefix")처럼 게임 설정 값을 반환해요. 플레이어를 넘기면 그 플레이어의 You Settings까지 적용해서, 그 플레이어가 실제로 겪는 값을 얻을 수 있어요.
getVersion Shared¶
ServerAPI.getVersion(): string
실행 중인 HD Admin 버전을 "v2.0.0" 같은 형태로 반환해요.
격리¶
isolateServer Server¶
ServerAPI.isolateServer()
이 서버가 데이터를 저장하거나 다른 서버로 무언가를 보내지 못하게 끊어요. 영구 밴, 역할 수정, 게임 설정, 전역 명령어, 전역 투표 같은 것들은 겉으로는 전부 평소처럼 작동하는 것처럼 보여요. 하지만 실제로는 아무것도 저장되지 않고 다른 서버에도 전달되지 않아서, 서버가 끝나면 모두 사라져요. 저장된 데이터는 평소처럼 읽기 때문에, 서버는 실제 역할, 밴, 설정 등을 가지고 시작해요. 각 플레이어 개인의 환경설정(You settings, 즐겨찾는 이모트 등)은 그 플레이어에게만 영향을 주니 그대로 저장돼요.
비공개 서버나 예약 서버에서 전체 체험에 영향을 주지 않고 누군가에게 "Owner"를 주고 싶을 때 유용해요.
local hd = game:GetService("ReplicatedStorage"):WaitForChild("HD Admin")
local ServerAPI = require(hd:WaitForChild("Core"):WaitForChild("ServerAPI"))
ServerAPI.isolateServer()
isServerIsolated Server¶
ServerAPI.isServerIsolated(): boolean
이 서버에서 isolateServer가 호출됐다면 true를 반환해요.
제한¶
restrictServer Server¶
ServerAPI.restrictServer(options: RestrictOptions?)
게임 전체에 걸친 기능을 제한해요. 게임 설정, 역할 수정, 영구 역할, 영구 밴과 밴 해제, 심사, 저장된 작업, 영구, 전역, 접속 수식어가 여기에 해당해요. commandsInRoles에 있는 역할의 명령어와 commands에 적은 명령어도 제한돼요. 패널에는 모든 것이 평소처럼 보이지만, 실제로 그 기능이나 명령어를 쓰면 오류 공지가 대신 나와요. bypassRoles에 있는 역할을 가진 사람은 모든 제한을 건너뛰어요.
isolateServer와 달리 데이터는 그대로 저장되고 다른 서버에도 전달돼요. 예를 들어 HD Admin Hub는 관리자 패널을 보여주려고 모든 플레이어에게 "Dev"를 주면서, 서버를 망가뜨릴 수 있는 명령어와 기능은 많이 제한해요.
| 옵션 | 하는 일 |
|---|---|
commandsInRoles |
명령어를 막을 역할의 이름이나 키 |
commands |
위에 더해서 막을 명령어의 이름이나 키 |
bypassRoles |
모든 제한을 건너뛸 역할의 이름이나 키 |
warning |
무언가 막혔을 때 보여주는 공지인 "This is restricted in this game"를 바꿔요 |
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 Server¶
ServerAPI.isServerRestricted(): boolean
이 서버에서 restrictServer가 호출됐다면 true를 반환해요.
이모트¶
getEmoteById Server¶
ServerAPI.getEmoteById(emoteId: number): Emote?
해당 id로 등록된 Emote를 반환해요. 없으면 nil이에요.
getEmoteByName Server¶
ServerAPI.getEmoteByName(emoteName: string, matchLength: boolean?): Emote?
해당 이름과 맞는 등록된 Emote를 반환해요. 없으면 nil이에요.
getRandomEmote Server¶
ServerAPI.getRandomEmote(): Emote?
addEmoteAsync Server¶
ServerAPI.addEmoteAsync(emote: IncompleteEmote, dontRegister: boolean?): (boolean, Emote | string)
이모트 애니메이션 에셋으로 새 이모트를 등록해요. 등록하면 ;emote로 재생할 수 있고 이모트 메뉴에도 나타나요. 꼭 필요한 건 emoteId 하나뿐이고, 나머지 정보는 알아서 가져와요. 성공하면 true와 완성된 Emote를, 실패하면 false와 그 이유를 반환해요.
타입¶
Role¶
ConfigRoles에 정의된 그대로의 전체 역할 설정 테이블이에요. 역할을 참고하세요.
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,
}
banId는 기록 자체에 들어 있지 않아서, getBanAsync가 두 번째 반환값으로 넘겨줘요.
Task¶
작업 API를 참고하세요.
Emote¶
type Emote = {
name: string,
originalName: string?,
order: number,
animationId: number,
emoteId: number,
}