寻宝游戏

*此内容使用人工智能（Beta）翻译，可能包含错误。若要查看英文页面，请点按 此处。

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

模块使用

安装

要在游戏中使用 ScavengerHunt 模块：

  1. 从 Studio 的 窗口 菜单或 主页 选项卡工具栏中，打开 工具箱 并选择 创作者商店 选项卡。

  2. 确保选择了 模型 排序，然后单击 查看所有 按钮以查看 类别。

  3. 找到并单击 包 瓦片。

  4. 找到 寻宝游戏 模块并单击它，或将其拖放到 3D 视图中。

  5. 在 资源管理器 窗口中，将整个 ScavengerHunt 模型移动到 ReplicatedStorage 中。运行游戏时，模块将开始运行。

使用令牌

寻宝游戏模块使用 令牌 作为玩家搜索和收集的物品。该模块附带一个令牌模型，您可以将其放置在 3D 世界中。

  1. 在模块主文件夹的 Workspace 文件夹中找到 Token1 网格。

  2. 将 Token1 移动到顶层 Workspace 层次结构中，并将其放置在所需位置。

  3. 给令牌一个 唯一名称；这个名称是模块跟踪每个玩家收集了哪些令牌的方式。

  4. 要添加更多令牌，请复制现有令牌并给它一个唯一名称。

如果您不想使用捆绑的网格令牌，任何 Model 或 BasePart 都可以使用，只要它满足以下标准：

  • 对象具有 CollectionService 标签 ScavengerHuntPart。如果需要，可以通过在 configureServer 调用中为 tokenTag 设置不同的值来更改模块使用的 CollectionService 标签名称。

  • 对象包含一个子 StringValue 实例，设置为收集令牌时显示的“风味文本”。

    模型
    MeshPart

使用区域

区域与令牌略有不同，因为它们是标记为“已收集”的大区域，一旦玩家进入它们。此外，当玩家离开该区域时，风味文本模态会自动消失，该区域本身也会从工作区中移除。

  1. 在区域周围创建一个固定的部件，例如一个块或球体。该模块将在运行时自动禁用区域的 CanCollide 属性，以便玩家不会与该区域物理碰撞。

  2. 给它一个 唯一名称。这个名称是模块跟踪每个玩家进入了哪些区域的方式。

  3. 使用部件属性的 标签 部分，将标签 ScavengerHuntPart 应用到该部件，以便 CollectionService 能够检测到它。如果需要，可以通过在 configureServer 调用中为 tokenTag 设置不同的值来更改模块使用的标签名称。

  4. 包含一个子 StringValue 实例，设置为进入区域时显示的“风味文本”。

配置

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

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

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

    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()

	-- 隐藏所有开发者定义的屏幕 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如果为 true，则在用户离开游戏时重置其进度；在测试寻宝游戏时方便不保存进度。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)

回调

hideOtherGuis

hideOtherGuis(callback: function)

此回调在模态显示之前立即运行，让您在模态显示之前禁用整个 ScreenGuis 或其中的元素。有关详细信息和示例代码，请参见 GUI 可见性。

showOtherGuis

showOtherGuis(callback: function)

此回调在模态被关闭后立即运行，让您启用整个 ScreenGuis 或其中的元素。有关详细信息和示例代码，请参见 GUI 可见性。

©2026 Roblox Corporation、Roblox、Roblox 标志及 Powering Imagination 是我们在美国及其他国家或地区的注册与未注册商标。
条款·隐私政策·辅助功能·支持
中文(简体)