商品展位

The MerchBooth 开发者模块 让你在体验中直接提供 虚拟形象资产 , 通行证 和 开发者产品 出售。玩家可以浏览物品，预览自己的虚拟形象上的资产，购买物品，并立即使用或装备它们—无需离开体验。这可以帮助你 货币化 你的经验，通过与出售其他创作者物品相关的 40% 佣金获得收入。

模块使用

安装

要在体验中使用 MerchBooth 模块：

1. 从视图选项卡打开工具箱并选择 创建者商店 选项卡。

   

2. 确保 模型 排序已选择，然后单击 查看全部 按钮以获取 类别 。

   

3. 找到并单击 开发模块 瓦片。

   

4. 找到 商品展位 模块并单击它，或拖放到 3D 视查看中。

   

5. 在 浏览器 窗口中，将整个 MerchBooth 模型移至 ServerScriptService 。在运行体验时，模块将分配到各种服务并开始运行。

   

配置

模块已预配置为处理大多数使用案例，但它可以通过 配置 函数轻松自定义。例如，要创建更轻的主题并禁用目录查看图的左上角默认 过滤器 按钮：

1. 在 新手玩家脚本 中，创建一个新的 LocalScript 并将其重命名为 配置商店展位 。

   

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

   本地脚本 - 配置商店摊位
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   MerchBooth.configure({
   	backgroundColor = Color3.fromRGB(220, 210, 200),
   	textSize = 17,
   	textFont = Enum.Font.Fondamento,
   	textColor = Color3.fromRGB(20, 20, 20),
   	useFilters = false
   })

   

添加物品

没有商品的商品摊是什么？以下部分概述了如何将虚拟形象资产、通行证和开发者产品添加到你的商品摊。

虚拟形象资产

例如 服装和配件 必须通过其 资产ID 位于虚拟形象商店的物品详情页面添加。

1. 在 Script 中创建一个 **** 并粘贴以下代验证码。

   脚本 - 添加虚拟形象资产
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   local items = {
   
   }
   
   for _, assetId in items do
   	local success, errorMessage = pcall(function()
   		MerchBooth.addItemAsync(assetId)
   	end)
   	if not success then
   		warn(errorMessage)
   	end
   end

2. 从他们的虚拟形象商店网站URL复制物品资产ID。例如，Roblox棒球帽的ID是 607702162 。

   

3. 将每个复制的ID粘贴到 items 表中的逗号分隔列表中。默认情况下，项目在目录视图中按字母顺序显示，但您可以使用 setCatalogSort 来自定义排序。

   脚本 - 添加虚拟形象资产
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   local items = {
   	607702162, -- Roblox棒球帽
   	4819740796, -- Robox
   	1374269, -- 猫耳
   	11884330, -- 书呆子眼镜
   	10476359, -- 纸帽
   }
   
   for _, assetId in items do
   	local success, errorMessage = pcall(function()
   		MerchBooth.addItemAsync(assetId)
   	end)
   	if not success then
   		warn(errorMessage)
   	end
   end

   这个例子使用 Roblox 帐户拥有的资产，但一个繁荣的社区制作资产市场可以在这里 获得。

通行证

添加通行证需要位于创建者仪表板中的通行证ID。

1. 在 Script 中创建一个 **** 并粘贴以下代验证码。

   脚本 - 添加通行证
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   local items = {
   
   }
   
   for _, assetId in items do
   	local success, errorMessage = pcall(function()
   		MerchBooth.addItemAsync(assetId)
   	end)
   	if not success then
   		warn(errorMessage)
   	end
   end

2. 导航到 创建者仪表板 并选择体验。

3. 在左栏中，在 货币化 下，选择 通行证 。

4. 将鼠标悬停在游戏通行证行证缩略图上，单击 ⋯ 按钮，然后从上下文菜单中选择 复制资产ID 。

   

5. 将每个复制的ID粘贴到 表中的逗号分隔列表中，包括 作为第二个参数，用于指示项目是传递。默认情况下，项目会按字母顺序出现在目录视图中，但排序可以通过 setCatalogSort 进行自定义。

   脚本 - 添加通行证
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   local items = {
   	4343758, -- 冷火焰护甲
   	28521575, -- 史莱姆盾牌
   }
   
   for _, assetId in items do
   	local success, errorMessage = pcall(function()
   		MerchBooth.addItemAsync(assetId, Enum.InfoType.GamePass)
   	end)
   	if not success then
   		warn(errorMessage)
   	end
   end

开发者产品

添加 开发者产品 需要在 创建者仪表板 中找到的产品 ID。

1. 在 Script 中创建一个 **** 并粘贴以下代验证码。

   脚本 - 添加开发者产品
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   local items = {
   
   }
   
   for _, assetId in items do
   	local success, errorMessage = pcall(function()
   		MerchBooth.addItemAsync(assetId)
   	end)
   	if not success then
   		warn(errorMessage)
   	end
   end

2. 导航到 创建者仪表板 并选择体验。

3. 在左栏中，在 货币化 下，选择 开发者产品 。

4. 将鼠标悬停在产品缩略图上，单击 ⋯ 按钮，然后从上下文菜单中选择 复制资产 ID 。

   

5. 将每个复制的ID粘贴到 表中的逗号分隔列表中，包括 作为第二个参数，用于指示项目是开发者产品。默认情况下，项目在目录视图中按字母顺序显示，但您可以使用 setCatalogSort 来自定义排序。

   脚本 - 添加开发者产品
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   local items = {
   	1236602053, -- 魔力补充
   	1257880672, -- 治疗药水
   }
   
   for _, assetId in items do
   	local success, errorMessage = pcall(function()
   		MerchBooth.addItemAsync(assetId, Enum.InfoType.Product)
   	end)
   	if not success then
   		warn(errorMessage)
   	end
   end

自定义目录按钮

默认情况下，右侧的 目录按钮 允许玩家随时打开展位。

在某些情况下，可能有用于 移除 此按钮并连接自拥有：

1. 按照 按钮 中的说明创建一个新按钮。

2. 创建一个 LocalScript 作为按钮对象的子。

   

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

   本地脚本 - 自定义目录按钮
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   -- 移除默认目录按钮
   MerchBooth.toggleCatalogButton(false)
   
   -- 连接自定义按钮
   script.Parent.Activated:Connect(function()
   	MerchBooth.openMerchBooth()
   end)

可购买区域

在体验中驱动购买的有用方法之一是当玩家进入区域时自动显示商品摊位。

要创建可购买区域：

1. 创建一个Anchored块，包含检测区域。确保块足够高，以便与角色模型的 PrimaryPart (默认为 HumanoidRootPart ) 碰撞。

   

2. 使用砖块的属性 标签 部分或 Studio 的 标签编辑器 将标签 ShopRegion 应用到块上，以便 CollectionService 检测到它。

3. 将零件的 Transparency 设置为最大值，以便将其从体验中的玩家隐藏。还禁用其 CanCollide 和 CanQuery 属性，以便对象不会物理碰撞它，射线投射也不会检测到它。

   

   

4. 在 LocalScript 下插入一个新的 **** 。

   

5. 在新脚本中，粘贴以下代码，该代码使用 Touched 和 TouchEnded 事件检测角色是否进入或离开区域，并调用 openMerchBooth 和 closeMerchBooth 打开/关闭展位 GUI。

   本地脚本
   local Players = game:GetService("Players")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   local CollectionService = game:GetService("CollectionService")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))
   
   -- 移除默认目录按钮
   MerchBooth.toggleCatalogButton(false)
   
   local function setupRegion(region: BasePart)
   	region.Touched:Connect(function(otherPart)
   		local character = Players.LocalPlayer.Character
   		if character and otherPart == character.PrimaryPart then
   			MerchBooth.openMerchBooth()
   		end
   	end)
   
   	region.TouchEnded:Connect(function(otherPart)
   		local character = Players.LocalPlayer.Character
   		if character and otherPart == character.PrimaryPart then
   			MerchBooth.closeMerchBooth()
   		end
   	end)
   end
   
   -- 通过现有标记的商店区域循环
   for _, region in CollectionService:GetTagged("ShopRegion") do
   	setupRegion(region)
   end
   -- 检测非流式商店区域在何时流入
   CollectionService:GetInstanceAddedSignal("ShopRegion"):Connect(setupRegion)

靠近提示

作为 2D 目录查看图的替代，您可以在体验中添加 靠近提示 。这鼓励玩家在 3D 环境中发现物品，预览它们在自己的虚拟形象上，购买它们，并立即装备它们。请参阅addProximityButton获取详细信息。

更改装备效果

默认情况下，商家展位在玩家装备其中一个物品时显示通用闪光效果。要更改效果，在 particleEmitterTemplate 调用中将 ParticleEmitter 设置为自己的实例的 配置 调用。

本地脚本 - 配置商店摊位
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local myParticleEmitter = Instance.new("ParticleEmitter")
myParticleEmitter.SpreadAngle = Vector2.new(22, 22)
myParticleEmitter.Lifetime = NumberRange.new(0.5, 1.5)
myParticleEmitter.Shape = Enum.ParticleEmitterShape.Sphere
myParticleEmitter.Transparency = NumberSequence.new(0, 1)
myParticleEmitter.RotSpeed = NumberRange.new(200, 200)

MerchBooth.configure({
	particleEmitterTemplate = myParticleEmitter
})

图形用户界面可见性

默认情况下，商家展位在其 UI 出现时隐藏所有的 ScreenGuis 和 CoreGuis ，包括聊天、排行榜和由 Roblox 包含的其他内容。如果您想禁用此行为，请在 配置 调用中将 设置为 。

本地脚本 - 配置商店摊位
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.configure({
	hideOtherUis = false
})

角色移动

当角色在商店摊位上时，防止其移动可能是有利的。这可以通过在 配置 调用中设置 来完成。

本地脚本 - 配置商店摊位
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.configure({
	disableCharacterMovement = true
})

API 参考

类型

项目

商店展位中的物品由以下键值对表示的词典。项目可以通过 getItems 函数或 itemadded 事件收集。

枚数

商店展位.控件

与 setControlKeyCodes 一起使用来自定义与商店摊位互动的键和游戏手柄按钮。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.setControlKeyCodes(MerchBooth.Controls.ProximityPrompts, {
	keyboard = Enum.KeyCode.Q,
	gamepad = Enum.KeyCode.ButtonL1
})

功能

配置

通过以下键/值在 config 表中覆盖默认客户端配置选项，来实现以下功能：此函数只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.configure({
	backgroundColor = Color3.fromRGB(255, 255, 255),
	textSize = 16,
	textFont = Enum.Font.Roboto,
	textColor = Color3.fromRGB(20, 20, 20),
	hideOtherUis = false,
})

添加物品异步

异步地将一件物品添加到商店展位，以便在体验中购买。 assetId 是物品的资产ID，productType 是物品的Enum.InfoType枚列，而hideFromCatalog可用于在目录查看图中隐藏物品。

请参阅添加物品获取详细信息，因为使用情况略有不同，即 资产 对比 游戏通行证 或 开发者产品 。

脚本 - 添加虚拟形象资产
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local items = {
	607702162, -- Roblox棒球帽
	4819740796, -- Robox
	1374269, -- 猫耳
	11884330, -- 书呆子眼镜
	10476359, -- 纸帽
}

for _, assetId in items do
	local success, errorMessage = pcall(function()
		MerchBooth.addItemAsync(assetId)
	end)
	if not success then
		warn(errorMessage)
	end
end

脚本 - 添加通行证
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local items = {
	4343758, -- 冷火焰护甲
	28521575, -- 史莱姆盾牌
}

for _, assetId in items do
	local success, errorMessage = pcall(function()
		MerchBooth.addItemAsync(assetId, Enum.InfoType.GamePass)
	end)
	if not success then
		warn(errorMessage)
	end
end

脚本 - 添加开发者产品
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local items = {
	1236602053, -- 魔力补充
	1257880672, -- 治疗药水
}

for _, assetId in items do
	local success, errorMessage = pcall(function()
		MerchBooth.addItemAsync(assetId, Enum.InfoType.Product)
	end)
	if not success then
		warn(errorMessage)
	end
end

获取物品

返回代表所有已注册项目的词典。每个键是作为字符串的物品资产ID，每个键的值是一个 物品 。此函数只能从 Script 中调用。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	local items = MerchBooth.getItems()
	print(items)
end

移除项目

取消注册以前使用 addItemAsync 添加的物品，在目录视图中移除其地砖，并移除为它分配的任何 靠近提示。此函数只能从 Script 中调用。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	-- 一段时间后，移除项物品
	task.wait(5)
	MerchBooth.removeItem(4819740796)
end

添加近距离按钮

添加一个 靠近提示 到指定的 adornee 上，该提示会触发显示物品的购买视查看，因为它具有其资产 ID。这可以用作 2D 目录视查看的替代，鼓励玩家在 3D 环境中发现物品。

请注意，必须通过 addItemAsync 添加物品，才能将感应按钮分配到它。还请参阅removeProximityButton以从对象中移除靠近提示。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	local item = Workspace:FindFirstChild("Robox")
	if item then
		MerchBooth.addProximityButton(item, 4819740796)
	end
end

移除近距离按钮

移除通过 addProximityButton 生成的靠近提示。此函数只能从 中调用。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	local item = Workspace:FindFirstChild("Robox")
	if item then
		MerchBooth.addProximityButton(item, 4819740796)
	end

	-- 一段时间后，移除提示
	task.wait(5)
	MerchBooth.removeProximityButton(item)
end

设置目录排序

将排序函数 sortFunction 设置为在目录视查看中使用。提供的排序函数可以使用基于物品信息的逻辑，例如price或title。此函数只能从 LocalScript 中调用。

以下是分类目录的一些例子：

价格从低到高
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.setCatalogSort(function(a, b)
	return a.price < b.price
end)

价格从高到低
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.setCatalogSort(function(a, b)
	return a.price > b.price
end)

价格从低到高和按字母顺序
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.setCatalogSort(function(a, b)
	return if a.price == b.price then a.title < b.title else a.price < b.price
end)

设置控制键代码

配置与商店摊位互动的键和按钮值。第一个参数必须是一个 MerchBooth.Controls 枚列，第二个参数是包含相应键 和/或 的表。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.setControlKeyCodes(MerchBooth.Controls.ProximityPrompts, {
	keyboard = Enum.KeyCode.Q,
	gamepad = Enum.KeyCode.ButtonL1,
})

打开商店展位

打开商店展位窗口(如果关闭)并导航到目录视查看。此功能只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(assetId)
end)
if not success then
	warn(errorMessage)
end

MerchBooth.openMerchBooth()

打开物品视图

导航到给定的 itemId 单个项目视图，如果目前已关闭，打开商店展位窗口。此函数只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	MerchBooth.openItemView(4819740796)
end

切换目录按钮

在屏幕右侧切换目录按钮的开启/关闭。当实现一个 自定义按钮 或将商店展位的外观限制为 区域 或 靠近提示 时，这很有用。只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.toggleCatalogButton(false)

是否打开商店展位

返回 true 如果目录或项目视图打开。如果项目视图打开，项物品的资产 ID 作为第二值返回。此函数只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	MerchBooth.openItemView(4819740796)

	local isOpen, itemId = MerchBooth.isMerchBoothOpen()
	print(isOpen, itemId)
end

关闭商店展位

关闭商店展位窗口。此功能只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.closeMerchBooth()

是否启用商店展位

此函数可以与 setEnabled 一起使用，以检查商店是否已启用或未启用。只能从 LocalScript 中调用。

设置启用

设置整个商店展位是否启用或不启用。禁用时，该函数移除整个用户界面，包括靠近提示，并断开所有事件。此函数只能从 LocalScript 中调用。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

local isEnabled = MerchBooth.isMerchBoothEnabled()
if isEnabled then
	MerchBooth.setEnabled(false)
end

事件

添加了物品

当通过 addItemAsync 添加物品时，发生火焰。此事件只能在 Script 中连接。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemAdded:Connect(function(assetId, itemInfo)
	print("Item added with asset ID of", assetId)
	print(itemInfo)
end)

物品已移除

当通过 removeItem 移除物品时，发生火灾。此事件只能在 Script 中连接。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemRemoved:Connect(function(assetId)
	print("Item removed with asset ID of", assetId)
end)

商店打开

当目录 或 项目详情视图打开时发生火灾。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.merchBoothOpened:Connect(function()
	print("Booth view opened")
end)

商店关闭

当目录 或 项目详情视图关闭时发生火焰。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.merchBoothClosed:Connect(function()
	print("Booth view closed")
end)

目录查看已打开

当目录视图打开时发生火灾。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.catalogViewOpened:Connect(function()
	print("Catalog view opened")
end)

目录视图已关闭

当目录视图关闭时发生火灾。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.catalogViewClosed:Connect(function()
	print("Catalog view closed")
end)

打开的项目视图

当物品详情视图打开时发生火灾。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemViewOpened:Connect(function()
	print("Item view opened")
end)

关闭的项目视图

当物品详情视图关闭时发生火灾。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemViewClosed:Connect(function()
	print("Item view closed")
end)