보물찾기 | 설명서 - Roblox 크리에이터 허브

보물찾기 개발자 모듈은 플레이어에게 경험을 탐색할 수 있는 본질적으로 게임화된 방법을 제공하여 자연스럽게 전체 장소를 소개합니다. 플레이어의 진행 상황은 지속적이므로 보물찾기는 세션 간에 계속될 수 있습니다.

이 모듈은 데이터 저장소를 사용합니다. 스튜디오에서 테스트하려면 스튜디오의 파일 ⟩ 경험 설정 창의 보안 섹션에서 API 서비스에 대한 스튜디오 액세스 활성화가 활성화되어 있는지 확인하세요.

모듈 사용법

설치

경험에서 보물찾기 모듈을 사용하려면:

스튜디오의 창 메뉴 또는 홈 탭 도구 모음에서 도구상자를 열고 제작자 상점 탭을 선택합니다.
모델 정렬이 선택되어 있는지 확인한 후 카테고리의 모두 보기 버튼을 클릭합니다.
패키지 타일을 찾고 클릭합니다.
보물찾기 모듈을 찾아 클릭하거나 3D 뷰로 드래그 앤 드롭합니다.
탐색기 창에서 전체 보물찾기 모델을 ReplicatedStorage로 이동합니다. 경험을 실행하면 모듈이 실행되기 시작합니다.

아이템 사용

보물찾기 모듈은 플레이어가 검색하고 수집하는 아이템으로 아이템을 사용합니다. 이 모듈에는 3D 세계에서 배치할 수 있는 하나의 아이템 모델이 포함되어 있습니다.

모듈의 기본 폴더 내 작업공간 폴더에서 아이템1 메쉬를 찾습니다.
아이템1을 최상위 작업공간 계층으로 이동하고 원하는 곳에 배치합니다.
아이템에 고유 이름을 지정합니다. 이 이름은 모듈이 각 플레이어가 수집한 아이템을 추적하는 방법입니다.
더 많은 아이템을 추가하려면 기존 아이템을 복제하고 고유 이름을 부여합니다.

번들로 제공된 메쉬 아이템을 사용하고 싶지 않은 경우, Model 또는 BasePart는 다음 기준을 충족하는 한 사용할 수 있습니다:

객체에 CollectionService 태그가 ScavengerHuntPart이어야 합니다. 필요에 따라 모듈이 사용하는 태그 이름은 configureServer 호출에서 tokenTag에 다른 값을 설정하여 변경할 수 있습니다.
객체는 아이템이 수집될 때 표시할 "flavor text"에 설정된 자식 StringValue 인스턴스를 포함해야 합니다.

모델
메쉬파트

각 아이템은 플레이어 진행 상황을 추적하는 수단으로 고유 이름을 가져야 한다는 점을 기억하세요.

모듈은 런타임 중에 플레이어가 아이템에 물리적으로 충돌하지 않도록 아이템의 CanCollide 속성을 자동으로 비활성화합니다. 따라서 모든 아이템은 고정되어 있어 세계 기하학을 통과하지 않도록 해야 합니다.

지역 사용

지역은 아이템과 약간 다르며, 플레이어가 들어가면 "수집됨"으로 표시되는 큰 영역입니다. 또한 플레이어가 지역을 떠날 때, 맛 텍스트 모달이 자동으로 해제되고 지역 자체가 작업공간에서 제거됩니다.

블록 또는 구와 같은 지역 주위에 고정된 부품을 만듭니다. 모듈은 런타임 중에 플레이어가 물리적으로 지역에 충돌하지 않도록 CanCollide 속성을 자동으로 비활성화합니다.
고유 이름을 지정합니다. 이 이름은 모듈이 각 플레이어가 어떤 지역에 들어갔는지를 추적하는 방법입니다.
부품의 속성 태그 섹션을 사용하여 ScavengerHuntPart 태그를 부품에 적용하여 CollectionService가 이를 감지하도록 합니다. 필요에 따라 모듈이 사용하는 태그 이름은 configureServer 호출에서 tokenTag에 다른 값을 설정하여 변경할 수 있습니다.
지역에 들어갈 때 표시할 "flavor text"에 설정된 자식 StringValue 인스턴스를 포함합니다.

각 지역은 플레이어 진행 상황을 추적하는 수단으로 고유 이름을 가져야 한다는 점을 기억하세요.

구성

모듈은 대부분의 사용 사례를 처리할 수 있도록 미리 구성되어 있지만, 쉽게 사용자 정의할 수 있습니다. 예를 들어, 아이템 회전 속도를 변경하고 모달 정보 메시지를 사용자 정의하려면:

StarterPlayerScripts에서 새로운 LocalScript를 생성하고 ConfigureScavengerHunt로 이름을 바꿉니다.

새 스크립트에 다음 코드를 붙여넣습니다.

LocalScript - ConfigureScavengerHunt
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureClient({
	infoModalText = "내 보물찾기에 오신 것을 환영합니다!",
	completeModalText = "내 보물찾기에 참여해 주셔서 감사합니다!",
	tokenRotationSpeed = 60,
})

수집 이벤트

플레이어가 아이템을 수집하거나 지역에 들어갈 때마다 수집됨 이벤트가 발생합니다. 이 이벤트는 서버 측 Script에서 수신할 수 있으며, 연결된 함수는 아이템과 충돌한 또는 지역에 들어간 Player를 수신하고 해당 아이템이나 지역의 이름을 받습니다.

마찬가지로 플레이어가 모든 아이템을 수집하거나 모든 태그가 지정된 지역에 들어가면 모두 수집됨 이벤트가 발생하고 연결된 함수는 해당 Player를 수신합니다. 이 함수는 플레이어당 한 번만 발생하며, 해당 플레이어에게 뱃지, 새로운 지역에 대한 접근, 경험 내 화폐 등을 보상하는 데 사용할 수 있습니다.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.collected:Connect(function(player, itemName)
	print(player.DisplayName, itemName)
end)

ScavengerHunt.allCollected:Connect(function(player)
	print(player.DisplayName .. "가 보물찾기를 완료했습니다!")
end)

사용자 정의 GUI

이 모듈은 기본 GUI를 사용자 정의할 수 있는 여러 옵션을 제공합니다. 그러나 대신 사용자 정의 GUI 요소를 표시하도록 선택할 수 있습니다.

useCustomModals가 configureClient 함수에서 true로 설정되면, 플레이어가 아이템 추적기를 활성화할 때마다 showInfoModal 이벤트가 발생합니다. 또한, 플레이어가 보물찾기의 모든 아이템을 수집했을 때 showCompleteModal 이벤트가 발생합니다. 이 두 이벤트는 LocalScript에서 수신할 수 있습니다.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showInfoModal:Connect(function()
	-- 사용자 정의 정보 모달 표시
	local infoModal = Players.LocalPlayer.PlayerGui.ScavengerInfoModal
	infoModal.Enabled = true
end)

ScavengerHunt.showCompleteModal:Connect(function()
	-- 사용자 정의 완료 모달 표시
	local completeModal = Players.LocalPlayer.PlayerGui.ScavengerCompleteModal
	completeModal.Enabled = true
end)

사용자 정의 모달을 사용할 때는 플레이어가 이를 닫거나 숨길 수 있는 방법을 제공하거나 일정 시간 후 자동으로 해제되도록 해야 합니다.

GUI 가시성

기본적으로 보물찾기는 정보 모달 또는 완료 모달이 표시될 때 모든 ScreenGuis 및 CoreGuis(플레이어 목록 제외)를 숨깁니다. 이 자동 숨김 동작을 무시하고 어떤 GUI가 보이도록 할지를 프로그래밍적으로 결정하고 싶다면, hideOtherGuis 및 showOtherGuis 콜백을 포함하고 자신의 사용자 정의 논리로 응답하세요.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local StarterGui = game:GetService("StarterGui")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

local player = Players.LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")
local hiddenInstances = {}

-- 숨겨지지 않을 화면 GUI 생성
local specialGuiInstance = Instance.new("ScreenGui")
-- 보물찾기 GUI 위에 화면 GUI 그리기
specialGuiInstance.DisplayOrder = 1
specialGuiInstance.Parent = playerGui
-- GUI에 텍스트 레이블 추가
local specialLabel = Instance.new("TextLabel")
specialLabel.Size = UDim2.fromScale(1, 0.1)
specialLabel.Text = "모달을 표시할 때 보이는 상태 유지"
specialLabel.Font = Enum.Font.GothamMedium
specialLabel.TextSize = 24
specialLabel.Parent = specialGuiInstance

ScavengerHunt.hideOtherGuis(function()
	-- 모든 개발자가 정의한 화면 GUI 숨기기
	local instances = playerGui:GetChildren()
	for _, instance in instances do
		if instance:IsA("ScreenGui") and not instance.Name == "ScavengerHunt" and instance.Enabled then
			instance.Enabled = false
			table.insert(hiddenInstances, instance)
		end
	end
	-- 특정 코어 GUI 숨기기
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)

ScavengerHunt.showOtherGuis(function()
	-- 숨겨진 모든 개발자가 정의한 화면 GUI 표시
	for _, instance in hiddenInstances do
		instance.Enabled = true
	end
	hiddenInstances = {}
	-- 숨겨진 특정 코어 GUI 표시
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

API 참조

함수

configureClient

configureClient(config: table)

기본 클라이언트 측 구성 옵션을 config 테이블의 다음 키/값 쌍을 통해 재정의합니다. 이 함수는 LocalScript에서만 호출할 수 있습니다.

키	설명	기본값
autoDismissTime	모달이 자동으로 해제되기 전의 시간(초)값을 설정합니다. 0으로 설정하면 비활성화됩니다.	20
closeModalGamepad	모달을 닫는 데 사용되는 게임패드 버튼(Enum.KeyCode).	ButtonA
closeModalKeyboard	모달을 닫는 데 사용되는 키보드 키(Enum.KeyCode).	E
completeModalText	보물찾기가 완료된 후 아이템 추적기를 클릭했을 때 나타나는 모달의 텍스트입니다.	"참여해 주셔서 감사합니다!"
infoModalText	아이템 추적기를 클릭했을 때 나타나는 모달의 텍스트입니다.	"모든 아이템을 찾아 보물찾기를 완료하세요"
tokenRotationSpeed	아이템이 회전하는 속도로 초당 도 단위입니다. 회전을 방지하려면 0으로 설정합니다.	20
nextArrowImage	현재 모달 페이지 뒤에 보여질 모달 페이지가 더 있다는 것을 나타내는 데 사용되는 이미지입니다.	"rbxassetid://8167172095"
openTokenTrackerGamepad	아이템 추적기를 활성화한 후 나타나는 모달을 표시하는 데 사용되는 게임패드 버튼(Enum.KeyCode).	ButtonY
openTokenTrackerKeyboard	아이템 추적기를 활성화한 후 나타나는 모달을 표시하는 데 사용되는 키보드 키(Enum.KeyCode).	Y
openTokenTrackerGamepadButtonImage	아이템 추적기를 활성화하는 데 사용되는 게임패드 버튼의 이미지입니다.	"rbxassetid://8025860488"
regionIcon	지역에 들어갈 때 아이템 추적기 옆에 표시되는 아이콘입니다.	"rbxassetid://8073794624"
tokenIcon	아이템 수집 시 아이템 추적기 옆에 표시되는 아이콘입니다.	"rbxassetid://8073794477"
tokenTrackerPositionSmallDevice	스마트폰과 같은 작은 장치에서의 아이템 추적기 UI의 위치(UDim2).	(1, 0, 0, 84)
tokenTrackerPositionLargeDevice	태블릿 및 PC와 같은 큰 장치에서의 아이템 추적기 UI의 위치(UDim2).	(1, 0, 1, -16)
useRegions	아이템 대신 지역을 사용합니다.	false

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureClient({
	infoModalText = "내 보물찾기에 오신 것을 환영합니다!",
	completeModalText = "내 보물찾기에 참여해 주셔서 감사합니다!",
	tokenRotationSpeed = 60,
	navigationBeam = {
		lightEmission = 1
	},
	modal = {
		textSize = 14
	},
})

configureServer

configureServer(config: table)

기본 서버 측 구성 옵션을 config 테이블의 다음 키/값 쌍을 통해 재정의합니다. 이 함수는 Script에서만 호출할 수 있습니다.

키	설명	기본값
tokenTag	CollectionService가 보물찾기에서 사용되는 모든 아이템이나 지역을 찾는 데 사용하는 태그입니다.	"ScavengerHuntPart"
datastoreName	보물찾기가 각 플레이어의 수집 진행 상황을 저장하는 데 사용하는 DataStore의 이름입니다.	"ScavengerHuntTokens"
resetOnPlayerRemoving	참으로 설정하면 사용자가 경험을 떠날 때 진행 상황을 재설정합니다. 보물찾기를 테스트하는 동안 진행 상황이 저장되지 않도록 편리합니다.	false

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureServer({
	tokenTag = "GreenGem",
})

disable

disable()

모든 UI를 숨기고, 모든 입력 이벤트 리스너의 연결을 끊고, 플레이어가 아이템을 수집하거나 지역과 상호작용하지 못하도록 합니다. 이 함수는 Script에서만 호출할 수 있습니다.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.disable()

enable

enable()

모든 UI를 표시하고, 모든 입력 이벤트 리스너를 연결하고, 플레이어가 아이템을 수집하고 지역과 상호작용할 수 있도록 합니다. 이 함수는 Script에서만 호출할 수 있습니다.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.enable()

이벤트

collected

플레이어가 아이템과 충돌하거나 지역에 들어가면 발생합니다. 연결된 함수는 아이템과 충돌한 플레이어나 지역에 들어간 플레이어의 Player를 수신하고 충돌한 아이템의 이름 또는 들어간 지역의 이름을 수신합니다. 이 이벤트는 Script에서만 연결할 수 있습니다.

매개변수
player: Player	아이템과 충돌하거나 지역에 들어간 사용자입니다.
itemName: string	충돌한 아이템의 이름 또는 들어간 지역의 이름입니다.
totalCollected: number	사용자 player가 수집한 아이템의 총 수입니다.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.collected:Connect(function(player, itemName, totalCollected)
	print(player.DisplayName, itemName, totalCollected)
end)

allCollected

플레이어가 모든 아이템을 수집하거나 보물찾기에 있는 모든 지역에 들어가면 발생합니다. 연결된 함수는 모든 아이템을 수집한 Player를 수신하며, 한 플레이어당 한 번만 발생합니다. 이 이벤트는 Script에서만 연결할 수 있습니다.

매개변수
player: Player	모든 아이템을 수집했거나 모든 지역에 들어간 플레이어입니다.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.allCollected:Connect(function(player)
	print(player.DisplayName .. "가 보물찾기를 완료했습니다!")
end)

showInfoModal

플레이어가 useCustomModals 구성 옵션이 true로 설정된 상태에서 아이템 추적기를 클릭하면 발생합니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showInfoModal:Connect(function()
	local infoModal = Players.LocalPlayer.PlayerGui.InfoModal
	infoModal.Enabled = true
end)

showCompleteModal

플레이어가 useCustomModals 구성 옵션이 true로 설정되어 있고 보물찾기에서 모든 아이템을 수집했을 때 아이템 추적기를 클릭하면 발생합니다. 이 이벤트는 LocalScript에서만 연결할 수 있습니다.

LocalScript
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.showCompleteModal:Connect(function()
	local completeModal = Players.LocalPlayer.PlayerGui.CompleteModal
	completeModal.Enabled = true
end)