scavenger hunt | 文档 - Roblox 创作者中心

ScavengerHunt 开发者模块为玩家提供了一种内在游戏化的方式来探索您的体验，自然地将他们引入整个地方。玩家的进度是持久的，因此寻物活动可以在不同的游戏会话之间继续进行。

此模块使用了数据存储。要在Studio中进行测试，请确保在Studio的文件 ⟩ 体验设置窗口的安全部分中启用启用Studio对API服务的访问。

模块使用

安装

要在体验中使用ScavengerHunt模块：

从Studio的窗口菜单或主页选项卡工具栏，打开工具箱并选择创作者商店选项卡。
确保选择了模型排序，然后单击查看全部按钮以显示类别。
找到并点击Packages模块。
找到Scavenger Hunt模块并点击，或者将其拖放到3D视图中。
在资源管理器窗口中，将整个ScavengerHunt模型移动到ReplicatedStorage。在运行该体验时，该模块将开始运行。

使用令牌

寻物模块使用令牌作为玩家搜索和收集的物品。该模块带有一个令牌模型，您可以在3D世界中进行定位。

找到模块主文件夹中的Workspace文件夹内的Token1网格。
将Token1移动到顶级Workspace层次结构中，并将其放置在所需位置。
给令牌一个唯一名称；该名称是模块跟踪每个玩家收集了哪些令牌的方式。
若要添加更多令牌，请复制现有令牌并给它一个唯一名称。

如果您不想使用捆绑的网格令牌，任何Model或BasePart都可以正常工作，只要它满足以下条件：

对象具有CollectionService标签ScavengerHuntPart。如有需要，可以通过在configureServer调用中设置不同的tokenTag值来更改该模块使用的CollectionService标签名称。
对象包含一个设置为"flavor text"的子StringValue实例，以便在收集令牌时显示。

模型
MeshPart

请记住，每个令牌必须具有唯一名称作为跟踪玩家进度的手段。

该模块将在运行时自动禁用令牌的CanCollide属性，以便玩家不会与它们发生物理碰撞。因此，所有令牌应固定以防止它们掉落到世界几何体中。

使用区域

区域与令牌略有不同，作为大型区域，一旦玩家进入它们，就会标记为“已收集”。此外，当玩家离开区域时，风味文本模态会自动关闭，并且区域本身会从工作区中移除。

在区域周围创建一个固定的部分，例如一个块或球体。模块将在运行时自动禁用该区域的CanCollide属性，以便玩家不会与区域发生物理碰撞。
给它一个唯一名称。该名称是模块跟踪每个玩家进入了哪些区域的方式。
使用该部分属性的标签部分，将标签ScavengerHuntPart应用于该部分，以便CollectionService检测到它。如有需要，可以通过在configureServer调用中设置不同的值来更改模块使用的标签名称。
包含一个设置为"flavor text"的子StringValue实例，以便在进入区域时显示。

请记住，每个区域必须具有唯一名称作为跟踪玩家进度的手段。

配置

该模块已预先配置以适应大多数用例，但可以轻松自定义。例如，要更改令牌旋转速度和自定义模态信息消息：

在StarterPlayerScripts中，创建一个新的LocalScript并将其重命名为ConfigureScavengerHunt。

将以下代码粘贴到新脚本中。

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureClient({
	infoModalText = "欢迎参加我的寻物活动！",
	completeModalText = "感谢你参与我的寻物活动！",
	tokenRotationSpeed = 60,
})

收集事件

每当玩家收集令牌或进入区域时，collected事件就会触发。您可以在服务器端的Script中侦听此事件并做出相应的响应。连接的函数接收与令牌碰撞或进入区域的Player以及该令牌或区域的名称。

同样，当玩家收集所有令牌或进入所有标记区域时，allCollected事件会触发，并且连接的函数接收关联的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元素。

当在configureClient函数中将useCustomModals设置为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()
	-- 隐藏所有开发者定义的屏幕GUIs
	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
	-- 隐藏特定核心GUIs
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)
end)

ScavengerHunt.showOtherGuis(function()
	-- 显示所有开发者定义的被隐藏的屏幕GUIs
	for _, instance in hiddenInstances do
		instance.Enabled = true
	end
	hiddenInstances = {}
	-- 显示被隐藏的特定核心GUIs
	StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, true)
end)

键	描述	默认值
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	如果为true，当用户退出体验时重置用户的进度；便于在测试寻物活动时不保存进度。	false

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

local ScavengerHunt = require(ReplicatedStorage.ScavengerHunt)

ScavengerHunt.configureServer({
	tokenTag = "绿色宝石",
})

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)