미션 패키지 | 설명서 - Roblox 크리에이터 허브

이 기능 패키지는 베타 버전입니다.

미션 기능 패키지는 플레이어가 보상을 얻고 게임에서 진행할 수 있는 미션을 생성하는 즉시 사용 가능한 기능을 제공합니다. 모든 미션은 ID, 카테고리 및 플레이어가 미션을 완료하기 위해 수행해야 하는 작업 목록을 가져야 합니다. 그러나 작업 목록은 비워둘 수 있으며, 이 경우 미션의 보상을 즉시 청구할 수 있습니다.

패키지의 사용자 정의 옵션을 사용하여 모든 미션을 개인화하여 고유한 게임 플레이 요구 사항을 충족할 수 있습니다. 예를 들어:

온보딩 미션을 생성하여 새로운 플레이어를 게임에 유도하고 D1 유지율을 개선합니다.
중장기 목표와 진행 감각을 추가하여 D7 및 D30 유지율을 목표로 합니다.
게임의 다양한 시스템을 드러내고 플레이어가 상호작용할 때 보상을 제공하여 참여도를 높입니다.

플레이어에게 신선한 목표와 인센티브를 제공하여 더 오랫동안 플레이하고 참여도를 높이도록 하는 방법에 대한 정보는 퀘스트 디자인 소개를 참조하세요.

패키지 가져오기

크리에이터 스토어는 툴박스의 탭으로, Roblox 및 Roblox 커뮤니티에서 프로젝트 내에서 사용할 수 있도록 만든 모든 자산을 찾는 데 사용할 수 있습니다. 여기에는 모델, 이미지, 메시, 오디오, 플러그인, 비디오 및 글꼴 자산이 포함됩니다. 크리에이터 스토어를 사용하여 기능 패키지를 포함하여 하나 이상의 자산을 열린 게임에 직접 추가할 수 있습니다!

모든 기능 패키지는 제대로 작동하기 위해 코어 기능 패키지가 필요합니다. 코어 및 미션 기능 패키지 자산이 귀하의 인벤토리에 있으면 플랫폼의 모든 프로젝트에서 재사용할 수 있습니다.

인벤토리에서 패키지를 게임으로 가져오려면:

다음 구성 요소 세트에서 인벤토리에 추가 링크를 클릭하여 Studio 내에서 코어 및 미션을 인벤토리에 추가합니다.

코어 기능 패키지
코어 기능 패키지는 모든 기능 패키지에 대한 공유 데이터 저장소 논리를 제공합니다.
미션 기능 패키지
미션 기능 패키지는 플레이어가 보상을 얻고 게임에서 진행할 수 있는 미션을 생성하는 기능을 제공합니다.
Studio의 창 메뉴 또는 홈 탭 도구 모음에서 툴박스를 엽니다.
툴박스 창에서 인벤토리 탭을 클릭합니다. 내 모델 정렬이 표시됩니다.
기능 패키지 코어 타일을 클릭한 다음 미션 기능 패키지 타일을 클릭합니다. 두 패키지 폴더가 탐색기 창에 표시됩니다.
패키지 폴더를 ReplicatedStorage로 드래그합니다.

미션 정의

각 완료 가능한 미션에는 미션을 완료하기 위해 완료해야 하는 작업 세트, 구성 옵션 및 선택적 표시 메타데이터가 포함되어 있으며, 이는 모두 ReplicatedStorage.Missions.Configs.Missions 내에서 정의할 수 있으며, 같은 폴더의 Types 스크립트에서 내보낸 유형을 사용합니다.

필수 필드

각 미션에 대해 다음 필드가 필요합니다.

이름	유형	설명
missionId	string	주요 미션 테이블 키입니다. 모든 미션은 고유한 문자열로 식별됩니다.
categoryId	string	미션은 카테고리에 속해야 하며, UI에서 카테고리별로 그룹화됩니다.
tasks	table	플레이어가 미션을 완료하기 위해 완료해야 하는 작업 목록입니다.

잠금 조건

기본적으로 미션은 플레이어에게 자동으로 잠금 해제되며 정확히 한 번 완료할 수 있습니다. 그러나 다음 선택적 구성 옵션을 사용하여 이 동작을 변경할 수 있습니다.

이름	유형	설명
prerequisites	table	미션이 잠금 해제되기 전에 완료해야 하는 다른 missionIds 목록입니다.
manualOnly	bool	미션의 자동 잠금 해제를 비활성화합니다. 대신, 미션을 잠금 해제하기 위해 함수를 호출해야 합니다. 다른 잠금 조건도 여전히 충족되어야 합니다.
availableAfterUtc	bool	지정된 UTC 시간 이전에는 미션을 잠금 해제할 수 없습니다.
availableBeforeUtc	bool	지정된 UTC 시간 이후에는 미션을 잠금 해제할 수 없습니다. 이 시간 이전에 잠금 해제되었지만 완료되지 않은 경우, 미션은 실패합니다.
repeatable	bool	미션이 완료된 후 다시 잠금 해제됩니다.
repeatLimit	number	미션이 반복 가능할 경우, 이 횟수 이상 반복할 수 없습니다.
repeatCooldownSeconds	number	미션이 반복 가능할 경우, 잠금 해제되기 전에 지연 시간이 있습니다.
expireSeconds	number	미션이 잠금 해제되고 지정된 초 수 내에 완료되지 않으면 실패합니다.
expireCountOffline	bool	미션에 expireSeconds가 설정되어 있고 expireCountOffline이 true로 설정된 경우, 플레이어가 실제로 게임에 없을 때의 시간도 미션 만료에 포함됩니다.

메타데이터

미션에는 미션 사용자 인터페이스에서 어떻게 표시될지를 지정하는 메타데이터가 있습니다. 다음 선택적 필드를 사용하여 메타데이터를 사용자 정의할 수 있습니다.

이름	유형	설명
displayName	string	미션의 missionId 대신 사용자 인터페이스에 표시할 이름입니다.
description	string	미션에 대한 추가 정보나 맥락을 제공하는 긴 텍스트 블록입니다.
visibleAfterComplete	bool	true로 설정하면, 미션이 완료된 후에도 완료된 것으로 표시되며 미션 목록에 나타납니다.
visibleAfterFailed	bool	true로 설정하면, 미션이 실패한 후에도 실패한 것으로 표시되며 미션 목록에 나타납니다.
visibleBeforeUnlocked	bool	true로 설정하면, 미션이 완료 가능하기 전에 잠금 상태로 미션 목록에 표시됩니다.
invisibleWhileActive	bool	true로 설정하면, 미션이 진행 중일 때도 보이지 않습니다.
rewards	table	보상 표시 정보 목록입니다. assetID (number) - 미션 UI에서 퀘스트의 보상 아래에 표시되는 이미지 ID입니다. 보상이 있는 경우 필수입니다. displayName (string) - 아이콘 아래에 미션 UI에 표시되는 이름입니다.

작업 정의

각 미션은 0개 이상의 작업을 가질 수 있습니다. 미션에 작업이 0개인 경우 잠금 해제된 직후 청구할 수 있으며, 작업이 1개 이상인 경우 작업이 완료되면 플레이어는 미션과 관련된 보상을 수집할 수 있습니다. 각 작업에는 해당 미션에 대한 작업과 연결된 taskId가 있습니다.

작업은 두 가지 유형이 있습니다:

타이머 작업 - 작업을 서로 다른 시점에서 시작하고 중지할 수 있습니다. 작업의 타이머가 실행되는 동안 일정 시간이 지나야 작업이 완료됩니다.
카운트 작업 - 작업의 진행 상황을 추가하거나 설정할 수 있습니다. 진행 상황이 설정된 값에 도달하면 작업이 완료됩니다.

두 작업 유형은 다음 필드를 공유합니다:

이름	유형	설명
taskType	string	작업 유형이 카운트인지 타이머인지 지정합니다.
counter	object	(선택 사항) 이 작업이 추적하는 카운터입니다. 카운터는 숫자 또는 타이머에 대한 플레이어별 지속적인 저장소입니다. 여러 작업이 단일 카운터를 추적할 수 있습니다. 예를 들어, 여러 작업이 플레이어가 수집한 동전의 수를 추적하는 경우, 모두 동일한 "동전" 카운터를 공유할 수 있습니다. 이러한 작업은 새로 수집된 동전을 독립적으로 추적하거나 카운터 값(이미 수집된 모든 동전)에서 계속 카운팅할 수 있습니다. counterId (string) - 추적할 카운터의 ID입니다. 이 ID를 사용하여 카운터의 값을 가져오거나 설정합니다. continueFromCounter (선택적 bool) - true로 설정하면, 작업 진행 상황이 증가한 양이 아니라 카운터의 값과 직접 일치합니다.
metadata	object	(선택 사항) UI에서 작업이 표시되는 방식에 대한 정보입니다. displayName (string) - UI에 표시될 때 사용되는 작업의 이름입니다. numericType (선택적 string) - 작업의 진행 숫자가 표시되는 방식입니다. 분수, 예: 5/10 또는 5k/50k 백분율, 예: 50% 또는 10% 긴 분수, 예: 5/10 또는 5000/50000 부울, 예: 미완료
callToAction	object	(선택 사항) 콜백 함수를 트리거하는 버튼입니다. callback (function) - callToAction 버튼에 의해 트리거되는 함수입니다. buttonText (string) - 버튼 UI에 표시되는 텍스트입니다.

카운트 작업 필드

카운트 작업에는 필수 값이 있습니다. 작업 진행 상황이 이 양에 도달하면 작업이 완료됩니다.

이름	유형	설명
goalCount	number	(선택 사항) 작업을 완료하는 데 필요한 진행 상황입니다.

타이머 작업 필드

타이머 작업에는 소요된 목표 시간이 있으며, 시작 및 중지됩니다. 목표 시간이 충족되면 작업이 완료됩니다.

이름	유형	설명
goalSeconds	number	작업을 완료하기 위해 지나야 하는 초 수입니다.
startImmediately	bool	작업이 잠금 해제되자마자 시간을 계산해야 하는지 여부입니다. 시작된 후에만 시작할 수 있습니다.
includesOfflineTime	bool	플레이어가 게임에 적극적으로 참여하지 않을 때 소요된 시간을 포함해야 하는지 여부입니다.

카테고리 구성

카테고리는 사용하기 위해 명시적으로 정의할 필요가 없으며, 미션의 카테고리는 기본값이 사용됩니다. 그러나 ReplicatedStorage.Missions.Configs.Categories에서 이러한 값을 구성하여 카테고리에 추가 효과를 추가할 수 있습니다. 카테고리는 미션 구성에서 참조된 것과 동일한 고유 CategoryIds로 식별됩니다.

이름	유형	설명
repeatDelaySeconds	number	(선택 사항) 설정된 경우, 지정된 시간이 경과할 때마다 카테고리의 모든 미션이 재설정되며, 다시 잠금 해제되고 완료되며 보상을 청구할 수 있습니다. 이는 주어진 카테고리 반복 내에서 반복 가능한 미션과는 별개입니다.

서버 논리 통합

ReplicatedStorage.Missions.Server.Examples.MissionsExample을 살펴보세요. 이 예제는 서버가 미션 기능 패키지와 어떻게 상호작용하는지를 보여줍니다.

미션 기능 패키지를 게임에 드래그한 후에는 주로 네 가지를 연결해야 합니다:

미션 구성에서 미션을 정의합니다.

작업 진행 상황이나 진행 상황이 연결된 카운터를 업데이트하는 게임 로직을 추가합니다.

README

-- 점프 작업이 있는 미션 Jumping의 진행 상황을 증가시킵니다.
Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

-- BattlingTime 미션의 TimeInBattle 작업에서 타이머를 시작합니다.
Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

-- BattlingTime 미션의 TimeInBattle 작업에서 타이머를 중지합니다.
Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

-- Jumps 카운터에 연결된 모든 작업의 진행 상황을 증가시킵니다.
CounterSystem.addCounter(player, "Jumps", 1)

-- TimeInBattle 타이머 카운터에 연결된 모든 타이머 작업에서 타이머를 시작합니다.
CounterSystem.startTimer(player, "TimeInBattle")

-- TimeInBattle 타이머 카운터에 연결된 모든 타이머 작업에서 타이머를 중지합니다.
CounterSystem.stopTimer(player, "TimeInBattle")

미션 완료 핸들러를 설정하고, 선택적으로 잠금 해제 또는 실패 핸들러를 설정합니다. 완료 핸들러를 사용하여 게임에서 미션의 보상을 수여합니다.

README

local function completeHandler(player: Player, missionId: Types.MissionId)
     print(`{player}가 미션 {missionId}를 완료했습니다.`)
     -- 플레이어에게 보상을 수여합니다.
 end

Missions.setCompletionHandler(missionId, completeHandler)

자동으로 잠금 해제되지 않는 미션을 잠금 해제합니다. 미션 기능 패키지 로직은 미션이 완료되기 전에 모든 미션 요구 사항이 충족되도록 보장하며, 보상을 수집할 수 있습니다.
README
Missions.unlockMission(player, "Manual")

상수 구성

코어 기능 패키지의 상수는 두 곳에 있습니다:

공유 상수는 ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants에 있습니다.
패키지별 상수, 이 경우 미션 기능 패키지는 ReplicatedStorage.Missions.Configs.Constants에 있습니다.

또한, 번역을 위한 문자열은 하나의 위치에 나누어져 있습니다: ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

UI 구성 요소 사용자 정의

패키지 객체의 색상, 글꼴 및 투명도를 수정하여 미션 UI의 시각적 표현을 조정할 수 있습니다. 예를 들어, ReplicatedStorage.Missions.Configs.Constants에서 SingleTaskMode를 활성화하여 단일 작업만 있는 미션에 대해 미션 자체에 진행률 표시줄을 표시할 수 있습니다.

객체를 계층적으로 이동하면 코드가 이를 찾을 수 없게 되며, MissionsUI에서 조정해야 합니다.

또한, 게임에 이미 존재하는 UI가 있고 이를 미션 기능 패키지와 통합하고 싶다면, 클라이언트 ModuleScript MissionsClient에는 서버에서 플레이어의 미션에 대한 정보를 전송하는 데 필요한 모든 함수가 포함되어 있습니다.