koishi-plugin-dice-draw

一个用于 Koishi 的牌堆抽取插件，支持加权抽取、不放回抽取、云端牌组等功能。

功能特性

• 🎯 双抽取模式: 支持放回抽取和不放回抽取
• ⚖️ 加权抽取: 使用 ::权重:: 语法设置卡牌权重
• 🎲 掷骰表达式: 支持 [XdY+Z] 格式的掷骰表达式
• 🔄 嵌套抽取: 支持 {牌堆.牌组} 和 {%牌堆.牌组} 语法
• ☁️ 云端牌组: 支持从远程URL加载牌组内容
• 🔍 牌堆管理: 支持按名称或标题查找牌堆
• 📊 状态跟踪: 实时显示剩余卡牌数量

基本命令

抽取命令

• draw <牌堆.牌组> [数量] - 放回抽取（可重复抽到相同卡牌）
• drawn <牌堆.牌组> [数量] - 不放回抽取（抽一张少一张）

管理命令

• deck-list - 列出所有可用的牌堆
• deck-keys <牌堆> - 查看指定牌堆的所有牌组
• deck-info <牌堆> - 查看牌堆详细信息
• deck-search <关键词> - 搜索牌堆和牌组
• reset <牌堆[.牌组]> - 重置抽取状态
• deck-status [牌堆.牌组] - 查看剩余状态

维护命令

• deck-reload [牌堆] - 重新加载牌堆文件
• deck-update <牌堆> - 从远程更新牌堆

使用示例

# 放回抽取3张卡牌
draw 测试牌堆.基础牌组 3

# 不放回抽取1张卡牌
drawn 冒险牌堆.道具 1

# 查看牌堆信息
deck-info 测试牌堆

# 重置牌组状态
reset 测试牌堆.基础牌组

# 查看状态
deck-status

牌堆格式

{
  "meta": {
    "title": "测试牌堆",
    "author": "作者名",
    "version": "1.0.0",
    "desc": "牌堆描述"
  },
  "decks": {
    "基础牌组": [
      "普通卡牌",
      "::2::双倍权重卡牌",
      "包含掷骰的卡牌: [1d6]",
      "嵌套抽取: {其他牌堆.牌组}"
    ]
  }
}

配置选项

• dataPath: 牌堆文件存储路径 (默认: data/dice-draw)
• enableDiceRoll: 启用掷骰表达式 (默认: true)
• enableCloudDecks: 启用云端牌组 (默认: true)
• enableNesting: 启用嵌套抽取 (默认: true)
• defaultDrawCount: 默认抽取数量 (默认: 1)
• maxDrawCount: 最大抽取数量 (默认: 10)
• cloudTimeout: 云端牌组获取超时时间 (默认: 5000ms)

版本信息

当前版本: 1.0.0

• [1d20-3] - 掷一个20面骰子减3

嵌套抽取

• {牌堆名.牌组名} - 不放回抽取（每次结果唯一）
• {%牌堆名.牌组名} - 放回抽取（可能重复）

隐藏牌组

• 以 _ 开头的牌组不在列表中显示，但可以直接抽取
• 以 __ 开头的牌组完全无法外部访问，只能内部调用

牌堆文件格式

牌堆文件存储在 data/dice-draw/ 目录下，使用 JSON 格式：

{
  "meta": {
    "title": "牌堆标题",
    "author": "作者名",
    "version": "1.0.0",
    "desc": "牌堆描述",
    "license": "MIT"
  },
  "decks": {
    "牌组名": [
      "普通卡牌",
      "::5::高权重卡牌",
      "包含掷骰的卡牌：[1d6]",
      "嵌套抽取：{其他牌堆.其他牌组}"
    ]
  }
}

示例

1. 基础抽取：

   # 放回抽取（默认）
   .draw test.基础物品
   .draw adventure.武器 2
   
   # 不放回抽取
   .drawn test.基础物品
   .drawn adventure.武器 3
   
   # 使用牌堆标题
   .draw "冒险者物品库".武器 2
   .drawn "魔法学院生活".课程 3

2. 查看可用牌堆：

   .draw list
   .draw keys test
   .draw keys "冒险者物品库"

3. 搜索功能：

   .draw search 物品
   .draw search 事件

4. 状态管理：

   .draw status
   .draw status test.基础物品
   .draw reset test
   .draw reset test.基础物品

核心机制

不放回抽取

默认情况下，从牌组抽取是不放回的：

• 每张卡牌在一个会话中只能被抽取一次
• 当牌组中的卡牌全部抽完时，需要手动重置才能继续抽取
• 权重系统影响初始分布，权重越高的卡牌在牌组中出现的次数越多

会话管理

• 每个用户都有独立的抽取会话
• 会话记录每个牌组的剩余卡牌和已抽取卡牌
• 重置命令可以恢复牌组到初始状态

文本处理

• 支持递归的嵌套抽取和掷骰表达式
• 处理顺序：先处理掷骰，再处理嵌套抽取
• 嵌套抽取可以跨牌堆引用

配置

• dataPath: 牌堆文件存储路径（默认：data/dice-draw）
• enableDiceRoll: 启用掷骰表达式（默认：true）
• enableNesting: 启用嵌套抽取（默认：true）
• enableCloudDecks: 启用云端牌组（默认：true）
• defaultDrawCount: 默认抽取数量（默认：1）
• maxDrawCount: 最大抽取数量（默认：10）
• defaultWithReplacement: 默认是否为放回抽取（默认：false）
• cloudTimeout: 云端牌组获取超时时间（默认：5000ms）

注意事项

1. 牌堆文件必须是有效的 UTF-8 编码 JSON 格式
2. 牌组名称不能包含 . 字符，因为它用作分隔符
3. 权重值必须是正整数
4. 嵌套抽取有循环引用检测，避免无限递归
5. 以 __ 开头的牌组只能在牌堆内部使用，无法直接访问