资源

注册后才能下载/购买插件！快来注册吧，注册即可免费下载精翻插件！【点我注册】
RustSB.COM向广大野生Rust插件作者发出入驻邀请！详情请见[原创作者条约]

新品【XMItemLibrary·物品库】 1.0.0

作者 pandaman
创建日期 2026-03-20
标签

核心插件

概述 API 历史讨论 (0)

API 方法列表

1. EnableTemporaryDrop - 启用临时物品掉落

功能描述：
启用指定容器的临时物品掉落配置。启用后，玩家可以在有效期内从该容器中获得临时物品。
方法签名：

C#:

bool EnableTemporaryDrop(string containerName, string itemName)

参数说明：

containerName (string): 容器名称，必须与配置文件中"临时物品掉落"的"容器名"匹配
itemName (string): 物品名称，必须与配置文件中"临时物品掉落"的"物品名"匹配

返回值：

true: 成功启用临时掉落
false: 启用失败（配置不存在或参数错误）

调用示例：

C#:

// 在其他插件中调用
[PluginReference]
private Plugin XMItemLibrary;

void SomeMethod()
{
    // 启用"垃圾堆箱"容器的"超级强化石"临时掉落
    bool success = (bool)XMItemLibrary?.Call("EnableTemporaryDrop", "垃圾堆箱", "超级强化石");
 
    if (success)
    {
        Puts("临时掉落已成功启用");
    }
    else
    {
        Puts("临时掉落启用失败，请检查配置");
    }
}

效果说明：

启用后，全服玩家会收到聊天通知：[物品库] 限时掉落已开启！现在有几率从{容器名}搜刮到{物品名}！
主UI中该物品会显示在容器物品列表的最左侧
物品标签显示倒计时：限时X天 / 限时X小时 / 限时X分钟
到期后自动禁用，物品从UI中移除

注意事项：

必须先在配置文件的"临时物品掉落"中添加对应的配置项
如果该临时掉落已经启用，重复调用会重置倒计时
临时物品的掉落仍受容器本身的"最少产出物品种类"和"最多产出物品种类"限制

2. API_GetContainerItems - 获取容器物品列表

功能描述：
获取指定容器中玩家可获得的物品列表，包括物品的详细信息和状态。此API主要用于其他插件集成物品库系统。
方法签名：

C#:

List<Dictionary<string, object>> API_GetContainerItems(string playerIdString, string containerName)

参数说明：

playerIdString (string): 玩家ID字符串（使用 player.UserIDString）
containerName (string): 容器名称，必须与配置文件中"容器设置"的"实体名"完全匹配

返回值：

成功：返回 List<Dictionary<string, object>>，包含物品信息列表
失败：返回 null（容器不存在或没有物品）

返回的物品信息字典包含以下键值：

ItemName (string) - 物品名称
ItemShortname (string) - 物品简称
ItemSkin (ulong) - 物品皮肤ID
MinAmount (int) - 最小数量
MaxAmount (int) - 最大数量
Probability (int) - 概率（1-100）
Status (string) - 物品状态：
- "unlocked" - 已解锁（玩家拥有权限或完成解锁任务）
- "locked" - 未解锁（玩家没有权限且未完成解锁任务）
- "unlocking" - 解锁中（玩家正在完成解锁任务）
- "temporary" - 临时掉落（管理员开启的限时掉落物品）
- "research" - 研发完成（玩家已完成研发的物品）

调用示例：

C#:

// 在其他插件中调用
[PluginReference]
private Plugin XMItemLibrary;

void GetPlayerItems(BasePlayer player)
{
    // 获取"XMRewardPool_基础奖池"容器的物品列表
    var libraryItems = XMItemLibrary?.Call("API_GetContainerItems", player.UserIDString, "XMRewardPool_基础奖池");
 
    if (libraryItems != null && libraryItems is List<Dictionary<string, object>>)
    {
        var itemList = (List<Dictionary<string, object>>)libraryItems;
     
        foreach (var itemData in itemList)
        {
            string status = itemData.ContainsKey("Status") ? itemData["Status"].ToString() : "locked";
         
            // 只处理已解锁、临时掉落或研发完成的物品
            if (status == "unlocked" || status == "temporary" || status == "research")
            {
                string itemName = itemData["ItemName"].ToString();
                string itemShortname = itemData["ItemShortname"].ToString();
                ulong itemSkin = Convert.ToUInt64(itemData["ItemSkin"]);
                int minAmount = Convert.ToInt32(itemData["MinAmount"]);
                int maxAmount = Convert.ToInt32(itemData["MaxAmount"]);
                int probability = Convert.ToInt32(itemData["Probability"]);
             
                // 使用物品数据...
                Puts($"物品: {itemName}, 状态: {status}, 概率: {probability}%");
            }
        }
    }
    else
    {
        Puts("未找到容器或容器没有物品");
    }
}

容器命名规范：

格式: {插件名}_{配置名}
示例:
- XMRewardPool_基础奖池 - 奖池插件的"基础奖池"
- XMBaiCaoYuan_灵草 - 百草园插件的"灵草"
建议: 直接使用中文名称进行精准匹配

效果说明：

API会根据玩家权限、解锁进度、临时掉落状态等返回物品列表
调用插件可以将这些物品动态添加到自己的奖励系统中
物品状态会实时更新，无需重启服务器
支持权限倍率和概率加成（已包含在返回的数据中）

注意事项：

容器名称必须与物品库配置中的"实体名"完全匹配
建议只使用状态为 unlocked、temporary 或 research 的物品
物品数量应该在 MinAmount 和 MaxAmount 之间随机
物品的概率可以与其他奖励的概率一起计算
如果容器不存在或玩家没有任何可用物品，返回 null

3. API_NotifyItemObtained - 通知物品获得

功能描述：
当其他插件通过 API_GetContainerItems 获取物品库物品并发放给玩家后，必须调用此API来同步以下功能：

通知UI - 玩家获得物品时显示个人和全服通知
本档掉落数量统计 - 记录每个物品的总产出数量
排行榜 - 记录玩家发现稀有物品的次数
解锁任务进度 - 自动增加对应容器的解锁任务进度

方法签名：

C#:

void API_NotifyItemObtained(string userid, string itemName, int amount, string containerName = "")

参数说明：

userid (string): 玩家ID字符串（使用 player.UserIDString）
itemName (string): 物品名称，必须与物品库配置中的"物品名称"完全匹配
amount (int): 获得的物品数量
containerName (string, 可选): 容器实体名（如 XMBaiCaoYuan_灵草、XMRewardPool_基础奖池）
- 传入此参数后会自动增加解锁任务进度！
- 不传或传空字符串则不处理解锁进度

返回值：

无返回值（void）

调用示例：

C#:

// 在其他插件中调用
[PluginReference]
private Plugin XMItemLibrary;

void GivePlayerItemFromLibrary(BasePlayer player, string itemName, int amount)
{
    // 1. 先通过 API_GetContainerItems 获取物品信息
    var libraryItems = XMItemLibrary?.Call("API_GetContainerItems", player.UserIDString, "XMRewardPool_基础奖池");
    
    if (libraryItems != null && libraryItems is List<Dictionary<string, object>>)
    {
        var itemList = (List<Dictionary<string, object>>)libraryItems;
        
        foreach (var itemData in itemList)
        {
            string status = itemData.ContainsKey("Status") ? itemData["Status"].ToString() : "locked";
            string name = itemData["ItemName"].ToString();
            
            if (status == "unlocked" && name == itemName)
            {
                // 2. 发放物品给玩家
                string shortname = itemData["ItemShortname"].ToString();
                ulong skin = Convert.ToUInt64(itemData["ItemSkin"]);
                
                var item = ItemManager.CreateByName(shortname, amount, skin);
                if (item != null)
                {
                    item.name = itemName;
                    player.GiveItem(item);
                    
                    // 3. 重要！调用通知API同步统计、通知和解锁进度
                    // 传入containerName参数后会自动增加解锁任务进度
                    XMItemLibrary?.Call("API_NotifyItemObtained", player.UserIDString, itemName, amount, containerName);
                }
                break;
            }
        }
    }
}

// 如果不需要解锁进度功能，可以不传containerName参数
XMItemLibrary?.Call("API_NotifyItemObtained", player.UserIDString, itemName, amount);

重要说明：

推荐传入 containerName 参数，这样玩家获得物品时会自动增加解锁任务进度
containerName 必须是物品库配置中的"实体名"（如 XMBaiCaoYuan_灵草）
系统会自动检查该物品是否在容器的物品列表中，只有匹配的物品才会增加解锁进度
每次调用会增加 1 次解锁进度，达到要求次数后自动授予权限

Markdown (GitHub flavored):

**效果说明：**
1. 记录物品掉落统计 - 在编辑页面的"本档掉落数量"中显示
2. 记录玩家稀有度发现次数 - 在排行榜中显示
3. 显示个人通知UI - 根据物品配置的"显示个人UI"设置
4. 显示全服通知UI - 根据物品配置的"显示全服UI"设置
5. 播放特效 - 玩家获得物品时的视觉效果
6. **增加解锁进度** - 如果传入了 `containerName`，会自动增加对应容器的解锁任务进度 ✅

**注意事项：**
- **必须在发放物品后立即调用此API**，否则会缺失统计和通知功能
- 物品名称必须与物品库配置中的"物品名称"完全匹配
- 如果物品不存在于物品库配置中，API会自动忽略

HOOK方法列表

1. OnXMItemLibraryUnlockCompleted

触发时机

当玩家完成解锁任务，成功解锁某个物品时触发。

参数

BasePlayer player - 完成解锁的玩家对象
string itemName - 解锁的物品名称
string containerName - 容器名称

使用示例

C#:

// 监听所有解锁完成事件
void OnXMItemLibraryUnlockCompleted(BasePlayer player, string itemName, string containerName)
{
    Puts($"玩家 {player.displayName} 解锁了 {containerName} 的 {itemName}");
    // 可以在这里添加奖励、通知等逻辑
}

// 监听特定物品的解锁
void OnXMItemLibraryUnlockCompleted(BasePlayer player, string itemName, string containerName)
{
    if (itemName == "传说武器")
    {
        // 给予额外奖励
        player.ChatMessage("恭喜解锁传说武器！额外奖励已发放！");
    }
}

2. OnXMItemLibraryItemDiscovered

触发时机

当玩家从容器中发现并获得物品时触发。

参数

BasePlayer player - 发现物品的玩家对象
string itemName - 发现的物品名称
string containerName - 容器名称
int amount - 获得的物品数量

使用示例

C#:

// 监听所有物品发现事件
void OnXMItemLibraryItemDiscovered(BasePlayer player, string itemName, string containerName, int amount)
{
    Puts($"玩家 {player.displayName} 从 {containerName} 发现了 {amount}个 {itemName}");
}

// 监听特定容器的物品发现
void OnXMItemLibraryItemDiscovered(BasePlayer player, string itemName, string containerName, int amount)
{
    if (containerName == "传说宝箱")
    {
        // 记录日志或触发特殊事件
        LogToFile("legendary_drops", $"{player.displayName} 获得 {itemName} x{amount}", this);
    }
}

// 监听特定物品的发现
void OnXMItemLibraryItemDiscovered(BasePlayer player, string itemName, string containerName, int amount)
{
    if (itemName == "神器碎片")
    {
        // 触发全服公告
        Server.Broadcast($"玩家 {player.displayName} 发现了神器碎片！");
    }
}

// 同时过滤容器和物品
void OnXMItemLibraryItemDiscovered(BasePlayer player, string itemName, string containerName, int amount)
{
    if (containerName == "BOSS宝箱" && itemName == "终极武器")
    {
        // 特殊处理
        player.ChatMessage("你发现了BOSS宝箱中的终极武器！");
    }
}

3. OnXMItemLibraryResearchCompleted

触发时机

当全服研发任务完成时触发。

参数

string itemName - 研发完成的物品名称
string containerName - 物品将加入的容器名称

使用示例

C#:

// 监听所有研发完成事件
void OnXMItemLibraryResearchCompleted(string itemName, string containerName)
{
    Puts($"全服研发完成: {itemName} 已加入 {containerName}");
    // 可以触发全服庆祝活动
}

// 监听特定物品的研发完成
void OnXMItemLibraryResearchCompleted(string itemName, string containerName)
{
    if (itemName == "时空武器")
    {
        // 触发特殊事件
        Server.Broadcast("时空武器研发成功！全服玩家获得特殊BUFF！");
        // 给所有在线玩家发放奖励
        foreach (var player in BasePlayer.activePlayerList)
        {
            // 发放奖励逻辑
        }
    }

顶部底部

新品 【XMItemLibrary·物品库】 1.0.0

API 方法列表​

1. EnableTemporaryDrop - 启用临时物品掉落​

2. API_GetContainerItems - 获取容器物品列表​

3. API_NotifyItemObtained - 通知物品获得​

HOOK方法列表​

1. OnXMItemLibraryUnlockCompleted​

触发时机​

参数​

使用示例​

2. OnXMItemLibraryItemDiscovered​

触发时机​

参数​

使用示例​

3. OnXMItemLibraryResearchCompleted​

触发时机​

参数​

使用示例​

新品【XMItemLibrary·物品库】 1.0.0

API 方法列表

1. EnableTemporaryDrop - 启用临时物品掉落

2. API_GetContainerItems - 获取容器物品列表

3. API_NotifyItemObtained - 通知物品获得

HOOK方法列表

1. OnXMItemLibraryUnlockCompleted

触发时机

参数

使用示例

2. OnXMItemLibraryItemDiscovered

触发时机

参数

使用示例

3. OnXMItemLibraryResearchCompleted

触发时机

参数

使用示例