工坊手册

主题

CommodityService ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • [CommodityService]（17 函数 / 5 事件）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

商业化服务，提供玩家商品与权益查询、商品面板交互、免费商品请求、消耗操作以及相关状态事件。

适用场景 ​

适合服务端校验玩家商品、粉丝团或会员权益，以及客户端展示商品详情、购买面板并监听商业化状态变化。

使用要点 ​

先通过 game:GetService("CommodityService") 获取服务。商品、权益与数量等可信查询应在服务端执行；面板展示和交互请求按方法运行端约束调用，商品 ID 必须来自项目实际配置。

注意事项 ​

CommodityService 同时包含客户端 UI/请求方法与服务端查询方法。HasCommodity/GetCommodityCount/IsAuthorFans/GetFanClubLevel/IsFansRightsActive/IsVip/IsVipRightsActive/GetGoods/GetGoodsInfo 等查询在客户端会返回默认值或无法获得真实业务数据，应在服务端脚本中调用；ShowGoodsDetailPanel/ShowGoodsPurchasePanel/SetGoodsPanelVisible/SetGoodsVisible/RequestFreeGoods/ConsumeCommodity 可按具体交互从客户端或服务端触发。

代码示例 ​

监听道具消耗事件 ​

lua
-- @runtime client
local commodityService = game:GetService('CommodityService')
commodityService.CommodityConsumed:Once(function(commodityId, consumeNum, consumePlayer)
    print('消耗道具:', commodityId, '数量:', consumeNum, '玩家:', consumePlayer)
end)

关联类型 ​

事件 (5) ​

CommodityConsumed ​

签名：CommodityConsumed(commodityId: Int, consumeNum: Int, consumePlayer: Player) 触发：local

CommodityConsumed 是 CommodityService 上的本地事件，在道具被消耗时触发。回调依次给出道具 ID（commodityId，Int）、本次消耗数量（consumeNum，Int）以及发生消耗的玩家（consumePlayer，Player）。

回调参数类型说明
commodityIdInt道具Id
consumeNumInt数量
consumePlayerPlayer玩家

示例代码

监听一次道具消耗事件

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")
commodityService.CommodityConsumed:Once(function(commodityId, consumeNum, consumePlayer)
    print("道具消耗:", commodityId, "数量:", consumeNum)
    if consumePlayer ~= nil then
        print("消耗玩家:", consumePlayer:GetName())
    end
end)

CommodityObtain ​

签名：CommodityObtain(commodityId: Int, consumeNum: Int, consumePlayer: Player, isBringInto: Bool) 触发：local

CommodityObtain 是 CommodityService 上的本地事件，在道具被获取时触发。回调依次给出道具 ID（commodityId，Int）、获取数量（consumeNum，Int）、相关玩家（consumePlayer，Player）以及是否为带入（isBringInto，Bool）。

回调参数类型说明
commodityIdInt道具Id
consumeNumInt数量
consumePlayerPlayer玩家
isBringIntoBool是否为跨局携带道具

示例代码

监听商品获得事件

lua
-- @runtime client
local commodityService = game:GetService('CommodityService')
commodityService.CommodityObtain:Once(function(commodityId, consumeNum, consumePlayer, isBringInto)
    print('获得商品:', commodityId, '数量:', consumeNum)
    print('玩家:', consumePlayer, '是否带入:', isBringInto)
end)

GoodsPurchaseCompleted ​

签名：GoodsPurchaseCompleted(goodsId: String, goodsNum: Int, player: Player) 触发：local

GoodsPurchaseCompleted 是 CommodityService 上的本地事件，在商品购买完成时触发。回调依次给出商品 ID（goodsId，String）、购买数量（goodsNum，Int）与购买玩家（player，Player）。

回调参数类型说明
goodsIdString商品Id
goodsNumInt数量
playerPlayer玩家

示例代码

监听商品购买完成

lua
-- @runtime client
local commodityService = game:GetService('CommodityService')
commodityService.GoodsPurchaseCompleted:Once(function(goodsId, goodsNum, player)
    print('购买完成:', goodsId, '数量:', goodsNum, '玩家:', player)
end)

FanClubStatusChanged ​

签名：FanClubStatusChanged(player: Player, oldLevel: Int, newLevel: Int) 触发：local

FanClubStatusChanged 是 CommodityService 上的本地事件，在玩家的粉丝团等级发生变化时触发。回调依次给出玩家（player，Player）、变化前的等级（oldLevel，Int）与变化后的等级（newLevel，Int）。

回调参数类型说明
playerPlayer玩家
oldLevelInt变更前等级（0=未加入）
newLevelInt变更后等级（0=已退出）

示例代码

监听一次粉丝团等级变化

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")
commodityService.FanClubStatusChanged:Once(function(player, oldLevel, newLevel)
    local playerName = player ~= nil and player:GetName() or "未知玩家"
    print(string.format("粉丝团等级变化：%s 从 %d 级变为 %d 级", playerName, oldLevel, newLevel))
end)

VipStatusChanged ​

签名：VipStatusChanged(player: Player, isVip: Bool) 触发：local

VipStatusChanged 是 CommodityService 上的本地事件，在玩家的乐园会员状态发生变化时触发。回调依次给出玩家（player，Player）与变化后的会员状态（isVip，Bool）。

回调参数类型说明
playerPlayer玩家
isVipBool变更后的会员状态

示例代码

监听乐园会员状态变化

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")
-- 监听乐园会员状态变化，根据 isVip 分别输出提示
commodityService.VipStatusChanged:Once(function(player, isVip)
    if isVip then
        print("玩家已成为乐园会员", player)
    else
        print("玩家已不是乐园会员", player)
    end
end)

函数 (17) ​

HasCommodity ​

签名：HasCommodity(player: Player, commodityId: Int) -> Bool (是否拥有道具)

HasCommodity 用于判断玩家是否拥有指定道具，入参为玩家（player，Player）与道具 ID（commodityId，Int），返回布尔值表示是否拥有。

参数类型说明
playerPlayer玩家对象
commodityIdInt道具Id

返回值 Bool (是否拥有道具)

示例代码

在服务端检查玩家是否拥有道具

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil then
    local hasCommodity = commodityService:HasCommodity(player, 10001)
    print("玩家是否拥有道具:", hasCommodity)
end

GetCommodityCount ​

签名：GetCommodityCount(player: Player, commodityId: Int) -> Int (拥有道具数量)

GetCommodityCount 用于查询指定玩家拥有的指定道具数量，入参为玩家（player，Player）与道具 ID（commodityId，Int），返回整型的持有道具数量。

参数类型说明
playerPlayer玩家对象
commodityIdInt道具Id

返回值 Int (拥有道具数量)

示例代码

在服务端查询玩家道具数量

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil then
    local count = commodityService:GetCommodityCount(player, 10001)
    print("玩家拥有道具数量:", count)
end

ConsumeCommodity ​

签名：ConsumeCommodity(player: Player, commodityId: Int, num: Int) -> void

ConsumeCommodity 用于消耗指定玩家指定数量的道具，入参依次为玩家（player，Player）、道具 ID（commodityId，Int）与消耗数量（num，Int）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象
commodityIdInt道具Id
numInt消耗数量

返回值 void

示例代码

消耗项目配置中的道具

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")

local function consumeConfiguredCommodity(player, commodityId, amount)
    if player == nil or commodityId == nil or amount == nil or amount <= 0 then return end
    commodityService:ConsumeCommodity(player, commodityId, amount)
end

-- 调用方应传入项目商业化配置中的真实 commodityId 和消耗数量

SetGoodsPanelVisible ​

签名：SetGoodsPanelVisible(player: Player, visible: Bool) -> void

SetGoodsPanelVisible 用于设置指定玩家付费道具商店面板的可见性，入参为玩家（player，Player）与可见性（visible，Bool）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象
visibleBool可见性

返回值 void

示例代码

设置付费道具商店可见性

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
-- 使用本地玩家作为设置目标
local player = players.LocalPlayer
if player == nil then return end
-- 目标可见性：true 表示显示付费道具商店
local visible = true
-- 设置付费道具商店对该玩家的可见性
commodityService:SetGoodsPanelVisible(player, visible)
print("已设置付费道具商店可见性:", visible)

ShowGoodsDetailPanel ​

签名：ShowGoodsDetailPanel(player: Player, rawGoodsId: String) -> void

ShowGoodsDetailPanel 用于让指定玩家显示指定商品的详情界面，入参为玩家（player，Player）与商品原始标识（rawGoodsId，String）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象
rawGoodsIdString商品Id

返回值 void

示例代码

用项目配置的商品 ID 打开详情

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")

local function showGoodsDetail(player, rawGoodsId)
    if player == nil or rawGoodsId == nil or rawGoodsId == "" then return end
    commodityService:ShowGoodsDetailPanel(player, rawGoodsId)
end

-- 调用方应把商业化后台配置的真实 rawGoodsId 传给 showGoodsDetail

ShowGoodsPurchasePanel ​

签名：ShowGoodsPurchasePanel(player: Player, rawGoodsId: String, showTime: Float) -> void

ShowGoodsPurchasePanel 用于让指定玩家显示指定商品的购买界面，入参为玩家（player，Player）、商品原始标识（rawGoodsId，String）与展示时长（showTime，Float）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象
rawGoodsIdString商品Id
showTimeFloat展示时间

返回值 void

示例代码

用项目配置的商品 ID 打开购买面板

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")

local function showGoodsPurchase(player, rawGoodsId, displaySeconds)
    if player == nil or rawGoodsId == nil or rawGoodsId == "" then return end
    commodityService:ShowGoodsPurchasePanel(player, rawGoodsId, displaySeconds)
end

-- 调用方应传入商业化后台配置的真实 rawGoodsId 与展示时长

SetGoodsVisible ​

签名：SetGoodsVisible(player: Player, rawGoodsId: String, visible: Bool) -> void

SetGoodsVisible 用于设置指定玩家某个付费商品的可见性，入参为玩家（player，Player）、商品原始标识（rawGoodsId，String）与可见性（visible，Bool）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象
rawGoodsIdString商品Id
visibleBool可见性

返回值 void

示例代码

按项目配置切换商品可见性

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")

local function setConfiguredGoodsVisible(player, rawGoodsId, visible)
    if player == nil or rawGoodsId == nil or rawGoodsId == "" then return end
    commodityService:SetGoodsVisible(player, rawGoodsId, visible)
end

-- 调用方应把商业化后台配置的真实 rawGoodsId 传入该函数

RequestFreeGoods ​

签名：RequestFreeGoods(player: Player, rawGoodsId: String) -> void

RequestFreeGoods 用于为指定玩家获取免费商品，入参为玩家（player，Player）与商品原始标识（rawGoodsId，String）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象
rawGoodsIdString商品Id

返回值 void

示例代码

请求项目中已配置的免费商品

lua
-- @runtime client
local commodityService = game:GetService("CommodityService")

local function requestConfiguredFreeGoods(player, rawGoodsId)
    if player == nil or rawGoodsId == nil or rawGoodsId == "" then return end
    commodityService:RequestFreeGoods(player, rawGoodsId)
end

-- 仅传入商业化后台中已配置为免费商品的真实 rawGoodsId

IsAuthorFans ​

签名：IsAuthorFans(player: Player) -> Bool (是否为粉丝)

IsAuthorFans 用于查询玩家是否为当前地图作者的粉丝，入参为玩家（player，Player），返回布尔值表示是否为粉丝。

参数类型说明
playerPlayer玩家对象

返回值 Bool (是否为粉丝)

示例代码

在服务端检查作者粉丝状态

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil then
    local isFans = commodityService:IsAuthorFans(player)
    print("玩家是否为作者粉丝:", isFans)
end

GetFanClubLevel ​

签名：GetFanClubLevel(player: Player) -> Int (粉丝团等级（0=未加入，1/2/3=各级粉丝团）)

GetFanClubLevel 用于获取玩家对当前地图创作者的粉丝团等级，入参为玩家（player，Player），返回整型等级，其中 0 表示未加入，1、2、3 分别对应各级粉丝团。

参数类型说明
playerPlayer玩家对象

返回值 Int (粉丝团等级（0=未加入，1/2/3=各级粉丝团）)

示例代码

在服务端获取粉丝团等级

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil then
    local level = commodityService:GetFanClubLevel(player)
    print("玩家粉丝团等级:", level)
end

IsFansRightsActive ​

签名：IsFansRightsActive() -> Bool (是否开启)

查询当前地图是否开启了粉丝团权益功能。

返回值 Bool (是否开启)

示例代码

在服务端检查粉丝团权益开关

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local isActive = commodityService:IsFansRightsActive()
print("粉丝团权益是否开启:", isActive)

IsVip ​

签名：IsVip(player: Player) -> Bool (是否为乐园会员)

IsVip 用于查询玩家是否为乐园会员，入参为玩家（player，Player），返回布尔值表示是否为乐园会员。

参数类型说明
playerPlayer玩家对象

返回值 Bool (是否为乐园会员)

示例代码

在服务端检查乐园会员状态

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil then
    local isVip = commodityService:IsVip(player)
    print("玩家是否为乐园会员:", isVip)
end

IsVipRightsActive ​

签名：IsVipRightsActive() -> Bool (是否开启)

查询当前地图是否开启了乐园会员权益功能。

返回值 Bool (是否开启)

示例代码

在服务端检查乐园会员权益开关

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local isActive = commodityService:IsVipRightsActive()
print("乐园会员权益是否开启:", isActive)

PromptFanClubPurchase ​

签名：PromptFanClubPurchase(player: Player) -> void

PromptFanClubPurchase 用于向指定玩家提示加入或升级粉丝团，入参为玩家（player，Player）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象

返回值 void

示例代码

在服务端提示玩家加入粉丝团

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil and commodityService:IsFansRightsActive() then
    commodityService:PromptFanClubPurchase(player)
    print("已向玩家弹出粉丝团购买界面")
end

PromptVipPurchase ​

签名：PromptVipPurchase(player: Player) -> void

PromptVipPurchase 用于向指定玩家提示开通乐园会员，入参为玩家（player，Player）。该函数没有返回值。

参数类型说明
playerPlayer玩家对象

返回值 void

示例代码

在服务端提示玩家开通乐园会员

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local players = game:GetService("Players")
local player = players:GetPlayers()[1]

if player ~= nil and commodityService:IsVipRightsActive() then
    commodityService:PromptVipPurchase(player)
    print("已向玩家弹出乐园会员购买界面")
end

GetGoods ​

签名：GetGoods() -> Array<Any> (商品信息列表)

获取当前地图所有商品信息的列表。

返回值 Array<Any> (商品信息列表)

示例代码

在服务端获取商品列表

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local goodsList = commodityService:GetGoods()

for index, goodsInfo in ipairs(goodsList) do
    print("商品", index, tostring(goodsInfo))
end

GetGoodsInfo ​

签名：GetGoodsInfo(goodsId: String) -> Map (商品信息，不存在时返回nil)

获取指定商品的详细信息。

参数类型说明
goodsIdString商品Id

返回值 Map (商品信息，不存在时返回nil)

示例代码

在服务端获取指定商品信息

lua
-- @runtime server
local commodityService = game:GetService("CommodityService")
local goodsId = "10001"
local goodsInfo = commodityService:GetGoodsInfo(goodsId)

if goodsInfo ~= nil then
    print("商品信息:", tostring(goodsInfo))
else
    print("未找到该商品")
end