商品摊位

MerchBooth 开发者模块 使您能够直接在体验中销售 头像资产、通行证 和 开发者产品。玩家可以浏览物品、在自己的头像上预览资产、购买物品并立即使用或装备它们 — 所有这些都无需离开您的体验。这可以帮助您 变现 您的体验，并通过销售其他创作者的物品获得与之相关的 40% 附属费收入。

模块使用

安装

要在体验中使用 MerchBooth 模块：

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

   

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

   

3. 找到并单击 包 瓷砖。

4. 找到 商品摊位 模块并单击它，或将其拖放到 3D 视图中。

   

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

配置

该模块已预配置为适用于大多数用例，但可以通过 configure 函数轻松自定义。例如，要创建更清淡的主题并禁用目录视图左上角的默认 筛选 按钮：

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

   

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

   LocalScript - ConfigureMerchBooth
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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. 在 ServerScriptService 中创建一个 Script，并将以下代码粘贴进去。

   Script - Add Avatar Assets
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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 自定义排序。

   Script - Add Avatar Assets
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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. 在 ServerScriptService 中创建一个 Script，并将以下代码粘贴进去。

   Script - Add Passes
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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 粘贴到 items 表中的以逗号分隔的列表中 并且 在 addItemAsync 中将 Enum.InfoType.GamePass 作为第二个参数以指示这些物品是通行证。默认情况下，物品将在目录视图中按字母顺序显示，但可以通过 setCatalogSort 自定义排序。

   Script - Add Passes
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
   	4343758, -- ColdFyre 装甲
   	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. 在 ServerScriptService 中创建一个 Script，并将以下代码粘贴进去。

   Script - Add Developer Products
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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 粘贴到 items 表中的以逗号分隔的列表中 并且 在 addItemAsync 中将 Enum.InfoType.Product 作为第二个参数以指示这些物品是开发者产品。默认情况下，物品按字母顺序出现在目录视图中，但您可以通过 setCatalogSort 自定义排序。

   Script - Add Developer Products
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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. 将以下代码粘贴到新脚本中。

   LocalScript - Custom Catalog Button
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.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. 在 StarterPlayerScripts 下插入一个新的 LocalScript。

   

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

   LocalScript
   local Players = game:GetService("Players")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   local CollectionService = game:GetService("CollectionService")
   
   local MerchBooth = require(ReplicatedStorage.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。

更改装备效果

默认情况下，商品摊位在玩家从中装备物品时显示通用的闪烁效果。要更改效果，请在 configure 调用中将 particleEmitterTemplate 设置为您自己的 ParticleEmitter 实例。

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

local MerchBooth = require(ReplicatedStorage.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
})

GUI 可见性

默认情况下，商品摊位在其 UI 出现时会隐藏所有 ScreenGuis 和 CoreGuis，包括聊天窗口、排行榜和 Roblox 包含的其他窗口。如果您希望禁用此行为，请在 configure 调用中将 hideOtherUis 设置为 false。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.configure({
	hideOtherUis = false
})

角色移动

在玩家位于商品摊位时阻止角色移动可能是有利的。可以通过在 configure 调用中将 disableCharacterMovement 设置为 true 来实现。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.configure({
	disableCharacterMovement = true
})

API 参考

类型

物品

商品摊位中的物品由包含以下键值对的字典表示。可以通过 getItems 函数或 itemAdded 事件收集物品。

枚举

MerchBooth.Controls

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

函数

configure

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

addItemAsync

异步地将物品添加到商品展位，使其能够在体验中进行购买。assetId是物品的资产 ID，productType是物品的Enum.InfoType枚举，hideFromCatalog可用于在目录视图中隐藏该物品。

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

Script - 添加头像资产
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local items = {
	4343758, -- ColdFyre 盔甲
	28521575, -- Slime Shield
}

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

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

local MerchBooth = require(ReplicatedStorage.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

getItems

返回一个字典，表示当前所有注册的物品。每个键都是物品的资产 ID（字符串），每个键的值是一个物品。此函数只能从Script调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

removeItem

取消注册之前通过addItemAsync添加的物品，移除其在目录视图中的标记以及任何分配给它的距离提示。此函数只能从Script调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

addProximityButton

在给定的adornee上添加一个距离提示，用于触发显示物品购买视图，给定其资产 ID。这可以作为2D目录视图的替代方案，鼓励玩家在3D环境中发现物品。

请注意，必须通过addItemAsync添加物品，才能分配距离按钮。另请参阅removeProximityButton以从对象中移除距离提示。

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

local MerchBooth = require(ReplicatedStorage.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

removeProximityButton

移除通过addProximityButton生成的距离提示。此函数只能从Script调用。

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

local MerchBooth = require(ReplicatedStorage.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

setCatalogSort

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

以下是一些对目录排序的示例：

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

setControlKeyCodes

配置与商品展位交互的键和按钮值。第一个参数必须是MerchBooth.Controls枚举，第二个参数是一个表，包含与键盘和/或游戏手柄相应的Enum.KeyCode枚举。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

openMerchBooth

打开商品展位窗口（如果关闭）并导航到目录视图。此函数只能从LocalScript调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

MerchBooth.openMerchBooth()

openItemView

导航到给定itemId的单个物品视图，在当前关闭时打开商品展位窗口。此函数只能从LocalScript调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

toggleCatalogButton

切换屏幕右侧的目录按钮的开/关。这在实现自定义按钮或限制商品展位的外观到区域或距离提示时非常有用。只能从LocalScript调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.toggleCatalogButton(false)

isMerchBoothOpen

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

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

local MerchBooth = require(ReplicatedStorage.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

closeMerchBooth

关闭商品展位窗口。此函数只能从LocalScript调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.closeMerchBooth()

isMerchBoothEnabled

此函数可以与setEnabled一起使用，以检查商品展位当前是否启用。只能从LocalScript调用。

setEnabled

设置整个商品展位是否启用。当禁用时，此函数将删除整个用户界面，包括距离提示，并断开所有事件连接。此函数只能从LocalScript调用。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

事件

itemAdded

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.itemAdded:Connect(function(assetId, itemInfo)
	print("以资产 ID 添加物品，ID 为", assetId)
	print(itemInfo)
end)

itemRemoved

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

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.itemRemoved:Connect(function(assetId)
	print("以资产 ID 移除物品，ID 为", assetId)
end)

merchBoothOpened

当目录 或 物品详细信息视图打开时触发。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.merchBoothOpened:Connect(function()
	print("展位视图已打开")
end)

merchBoothClosed

当目录 或 物品详细信息视图关闭时触发。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.merchBoothClosed:Connect(function()
	print("展位视图已关闭")
end)

catalogViewOpened

当目录视图打开时触发。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.catalogViewOpened:Connect(function()
	print("目录视图已打开")
end)

catalogViewClosed

当目录视图关闭时触发。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.catalogViewClosed:Connect(function()
	print("目录视图已关闭")
end)

itemViewOpened

当物品详细信息视图打开时触发。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.itemViewOpened:Connect(function()
	print("物品视图已打开")
end)

itemViewClosed

当物品详细信息视图关闭时触发。

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

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.itemViewClosed:Connect(function()
	print("物品视图已关闭")
end)