콘텐츠로 이동

Task API

명령어가 실행될 때마다 대상 하나하나에 작업이 만들어져요. 이 작업은 run에 그대로 전달되고, 명령어가 얼마나 오래 유지될지, 네트워킹, 정리 같은 일을 맡아요.

메서드

task:keep Server

task:keep(persistence: Persistence?)

run이 끝난 뒤에도 작업을 유지해요. 이걸 쓰지 않으면 작업은 바로 사라져요. 선택할 수 있는 값은 "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves", "Indefinitely"예요. 여러 번 호출하면 조건이 합쳐져서, 먼저 일어나는 쪽에서 작업이 끝나요. Persistence를 참고하세요.


task:getArg Server

task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any

주어진 인수 이름이나 위치의 검증된 값을 읽어요. 이 값은 인수의 default, 호출한 사람이 입력해서 검증된 값, 프롬프트가 바꾼 검증된 값, 또는 task:setArg()로 설정한 값 중 하나예요.

호출한 사람이 인수를 입력하지 않아서 값이 인수의 default에서만 왔다면, 두 번째 인수로 true를 넘겨 nil을 받을 수 있어요. 선택 인수에서 직접 만든 동작으로 대신하고 싶을 때 유용해요. ;message가 시간을 입력하지 않으면 글자 수로 지속 시간을 정하는 것처럼요.


task:setArg Server

task:setArg(nameOrPosition: string | number, value: any)

주어진 인수 이름이나 위치의 값을 바꿔요.


task:buff Server

task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)

속성을 바꾸고, 같은 그룹의 버프가 달라질 때마다 그 속성에 변경 사항을 다시 적용해요. 작업이 끝나면 속성을 원래 값으로 되돌려요. Buffs를 참고하세요.


task:updateBuffs Server

task:updateBuffs(player: Player?, group: string?)

해당 플레이어와 그룹의 버프를 다시 실행해요. 대부분의 상황에서는 자동으로 처리되니까, 그 그룹의 모든 걸 강제로 갱신하고 싶을 때만 쓰면 돼요.


task:redo Server

task:redo(player: Player?, callback: () -> ())

콜백을 바로 실행하고, 작업이 살아 있는 동안 플레이어가 리스폰할 때마다 다시 실행해요. 리스폰하면 사라지는 효과에 유용해요.


task:bindPrompt Server

task:bindPrompt(config)

명령어에 연결된 액션 프롬프트를 호출한 사람에게 보여줘요. ;speed의 슬라이더나 ;laserEyes의 눈 색상 선택이 그 예예요.

run = function(task: CommandAPI.Task)
    task:keep("UntilCallerLeaves")
    task:bindPrompt({
        title = "Dangerous Script",
        text = "This script uses HttpService, are you sure you want to load it?",
        audience = task.caller,
        duration = 20,
        deactivate = false,
        endOnClose = true,
        buttons = {
            {
                label = "Load",
                onActivate = function()
                    --loadScript()
                    task:destroy()
                end,
            },
            {
                label = "Cancel",
                style = "Neutral",
                onActivate = function()
                    task:destroy()
                end,
            },
        },
    })
end,

설정값

키 타입 하는 일
title string 프롬프트의 제목이에요. 기본값은 명령어 이름이에요
text string 본문 텍스트예요
subtext string 텍스트 아래에 나오는 작은 글줄이에요
audience Player 프롬프트를 볼 사람이에요. 기본값은 task.target이에요
duration number 프롬프트가 저절로 닫히기까지의 초예요. 기본값 0은 무한이라는 뜻이에요
args table 컨트롤로 보여줄 명령어 인수예요. 컨트롤을 참고하세요
onChange function function(argName, value)이고, 컨트롤이 인수를 바꾼 뒤에 실행돼요
toggle table 인수와 연결되지 않은 추가 켜기/끄기 스위치예요. {label = "Trails", value = true, onChange = function(isOn) end}
buttons table 한 번만 쓰는 액션 버튼이에요. 버튼을 참고하세요
deactivate boolean 기본값은 true이고, 명령어를 일시 정지하고 다시 시작하는 스위치와 명령어를 끝내는 정지 버튼이 프롬프트에 생겨요. 버튼만 있는 프롬프트를 원하면 false로 설정하세요
rerun boolean 정리하고 명령어를 다시 실행하는 재실행 버튼을 추가해요. deactivate가 false일 때만 보여요
endOnClose boolean 기본적으로 프롬프트를 닫으면 작업이 끝나요. false로 설정하면 클라이언트가 닫을 때까지 계속 실행돼요

컨트롤

액션 프롬프트로 인수를 조작할 수 있게 하려면 bindPrompt 안의 args에 인수 이름을 추가하세요. Number는 슬라이더, Color는 색상 선택기, Bool은 토글이 되는 식이에요. 클라이언트가 값을 바꾸면 인수가 갱신되고 onChange가 실행되니까, 새 값은 task:getArg를 다시 호출해서 읽으면 돼요. 따로 검증할 필요도 없어요. 모든 값은 채팅에 직접 입력한 것과 똑같이 검사돼요.

run = function(task: CommandAPI.Task)
    local function applySpinSpeed()
        local speed = task:getArg("Number")
        -- spin the character at this speed
    end
    applySpinSpeed()
    task:bindPrompt({
        args = {"Number"},
        onChange = applySpinSpeed,
    })
end,

버튼

버튼도 똑같이 쉬워요. 버튼마다 label과 onActivate 함수를 주면, 클라이언트가 버튼을 누를 때마다 그 함수가 서버에서 실행돼요. 여기서는 yield해도 괜찮아요(구매 프롬프트, 데이터스토어 호출 등). 끝날 때까지 버튼에 로딩 표시가 나올 뿐이에요.

키 타입 하는 일
label string 버튼에 보이는 텍스트예요
onActivate function 버튼을 눌렀을 때 일어나는 일이에요
style string 기본값은 "Primary"이고, 회색으로 보이게 하려면 "Neutral"을 쓰세요. 취소 버튼에 잘 어울려요
confirm boolean Confirm? 단계를 추가해서 두 번 눌러야만 실행돼요. 밴 확인처럼 강력한 동작에 편해요

버튼은 task:destroy()로 자기 작업을 끝낼 수 있어요. ;teleport 같은 일회용 명령어 프롬프트가 이렇게 해요.


task.client:run Server

task.client:run(player: Player?, ...)
task.client:runAll(...)
task.client:runOthers(originPlayer: Player, ...)
task.client:runNearby(originPlayer: Player?, radius: number, ...)

짝이 되는 클라이언트 명령어를 플레이어의 기기에서 실행하고, 추가로 넘긴 값은 그대로 전달해요. run은 한 플레이어, runAll은 모든 플레이어, runOthers는 originPlayer를 뺀 모든 플레이어, runNearby는 radius 스터드 안에 있는 플레이어가 대상이에요. Networking을 참고하세요.


task.client:expose Server

task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})

클라이언트 코드가 인스턴스를 찾기 전에, 그 인스턴스가 플레이어에게 실제로 도착했는지 확인해 줘요. 스트리밍 때문에 늦어질 수 있어서, 서버에서 만들어 클라이언트에서 쓰는 건 모두 먼저 여기를 거쳐야 해요.


task.server:replicate Client

task.server:replicate(...)

클라이언트 명령어의 값을 서버로 다시 보내고, 값은 같은 작업에 도착해요. 서버에서 task.client.replicator를 설정하면 그 값이 누구에게 이어질지 고를 수 있고, 값은 그 명령어의 replication 함수로 들어와요. Networking을 참고하세요.


task:tween Shared

task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween

작업과 함께 정리되는 트윈을 재생해요. 그래서 명령어보다 오래 남지 않아요.


task:createSound Shared

task:createSound(soundType: SoundType?): Sound

작업이 소유하고 정리하는 Sound를 만들어요. 이 사운드의 Volume과 Pitch는 모든 플레이어가 YouSettings에서 설정할 수 있어요. SoundType을 정하지 않으면 기본값은 "Command"예요.


task:onEnded Shared

task:onEnded(callback: () -> ())

작업이 끝날 때마다 콜백을 실행해요. task.janitor:add(callback)을 하는 것과 같아요.


task:onEndedForGood Shared

task:onEndedForGood(callback: () -> ())

작업이 끝났고, 곧바로 똑같은 작업이 새로 만들어지지 않을 때만 콜백을 실행해요. ;serverLock Admin 같은 명령어에 유용해요. 이 명령어는 실행될 때 공지("This server has been locked for Admins")를 띄우고, 끝날 때도 공지("This server has been unlocked")를 띄워요. 그런데 이어서 ;serverLock Mod를 실행하면 이전 명령어의 '끝' 공지는 띄우고 싶지 않고, 새 '실행' 공지만 띄우고 싶잖아요.


task:destroy Shared

task:destroy()

작업을 강제로 끝내고, 작업이 가진 모든 걸 정리해요. ;un이 내부적으로 호출하는 게 바로 이거예요.


스케줄링 Shared

task.spawn(callback: () -> ())
task.defer(callback: () -> ())
task.delay(seconds: number, callback: (() -> ())?)
task.wait(seconds: number?)
task.iterate(count: number, callback: (index: number) -> ())
task.loop(callback: (stop: () -> (), index: number) -> ())

Roblox 자체 task 스케줄링 함수를 작업에 맞게 감싼 거예요. 명령어가 활성 상태인 동안 유지되게 하거나, 작업이 정리될 때(예를 들어 작업이 끝나기 전에 누군가 undo를 실행할 때) 자동으로 취소되게 하려면 꼭 필요해요. Roblox의 task 메서드를 평소처럼 쓰기만 하면 나머지는 HD Admin이 내부에서 알아서 처리해요.

속성

task.target Server

task.target: Player

명령어가 실행되는 대상 플레이어예요. 첫 번째 인수가 Player라면 항상 하나가 있어요. HD Admin이 일치한 플레이어마다 실행을 별도의 작업으로 나누기 때문에, 확인 없이 바로 써도 돼요. Players 인수를 통째로 받는 명령어는 이렇게 나뉘지 않아서 비어 있어요. task.targetUserId에는 그 플레이어의 UserId가 들어 있고, 오프라인일 때도 쓸 수 있어요.


task.qualifiers Server

task.qualifiers: {[string]: {string}}

호출한 사람이 처음 입력한 명령어에서 누구를 대상으로 지정했는지 나타내요. ;clone others는 {others = {}}를 주고, 아무것도 붙이지 않은 ;clone은 빈 테이블을 줘요. 항상 테이블이라서 바로 읽어도 안전해요.


task.caller Server

task.caller: Player?

명령어를 실행한 사람이에요. 서버가 실행했거나, 호출한 사람이 내 서버에 없는 상태에서 전역 명령어를 받은 경우에는 nil이에요. task.callerUserId는 항상 있으니까, UserId가 필요하면 이걸 쓰세요.


task.janitor Shared

task.janitor:add(item): typeof(item)

인스턴스, 연결, 함수를 넘기면 자동으로 정리해 주는 Janitor 객체예요. 예를 들면 이렇게 써요.

local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart


task.config Server

task.config: {[string]: any}

명령어 자체의 config 테이블이에요. 팩이 Config > Commands의 modify로 바꾼 내용도 들어 있어요. 게임 소유자가 바꿀 수 있어야 하는 설정을 명령어가 읽는 방법이에요. ;insert의 허용 목록과 거부 목록이 그 예예요.


task.extra Shared

task.extra: {[string]: any}

추가 정보를 담을 수 있는 테이블이에요. 비활성화된 뒤에도, 작업이 완전히 끝날 때까지 남아 있어요.


task.isActive Shared

task.isActive: boolean

작업이 실행되는 동안은 true이고, 끝나기 시작하면 false가 돼요. 반복문 안에서 쓰면 작업이 강제로 끝났을 때 효과를 바로 멈출 수 있어요.


task.commandKey Shared

task.commandKey: string

이 작업이 실행하는 명령어 이름을 소문자로 나타낸 값이에요.


task.isReplay Server

task.isReplay: boolean

누군가 지금 명령어를 실행한 게 아니라, 서버가 시작될 때 저장된 영구 명령어가 다시 실행되는 중이면 true예요. 호출한 사람이 자동으로 또 보면 안 되는 프롬프트를 영구 명령어에서 제한할 때 유용해요(새 서버에 들어올 때마다 뜨는 ;music 프롬프트 같은 거예요).