祈愿抽奖 ShiroGomaLottery

简介Copy Anchor Link

ShiroGomaLottery 是白芝麻服的祈愿大转盘（抽奖）插件。管理员可以创建多个独立池子、配置每期 UP 物品与概率权重，玩家消耗芝麻券（或十连抽奖券）进行单次 / 十连抽奖，有独立的抽奖历史与背包。

• 玩家侧：在祈愿转盘位置右键打开主界面，点击池子抽奖，查看历史，开启抽奖背包
• 管理侧：创建 / 管理池子，添加普通奖励、设置本期 UP，配置权重与消耗，发放十连抽奖券，查看任意玩家的抽奖记录

安装Copy Anchor Link

1. 将 ShiroGomaLottery-version.jar 放入服务端 plugins/ 文件夹
2. 确保前置插件已就位：Citizens（必需）、ShiroGomaVault（芝麻券）、ShiroGomaTitles（称号）
3. 重启服务器（或 /qiyuan reload）
4. 首次启动会生成 plugins/ShiroGomaLottery/config.yml 与 pools/ 目录（无子池子，需命令创建）

玩家使用Copy Anchor Link

抽奖机制（权重）Copy Anchor Link

插件使用权重体系决定每次抽奖各物品命中概率，总权重恒等于 qiyuan.total-weight（默认 10000）。

池子结构Copy Anchor Link

• 每个池子独立一份 UP（本期高光物品，绝对权重 up.weight）
• 普通奖励全池共享，存放在 qiyuan.common.items 下，并按稀有度等级分组

抽一次会发生什么Copy Anchor Link

1. 先按绝对权重判断是否命中该池 UP（up.weight / total-weight）
2. UP 未命中时，在剩余 (total-weight − up.weight) 内，按各普通物品的相对权重比例缩放后抽取一件
3. 因此，任何时候同一池的所有物品（UP + 普通）的概率之和都严格等于 100%

稀有度等级Copy Anchor Link

十连抽奖券Copy Anchor Link

玩家在主界面右键池子十连时，会弹出两种支付方式二选一：

1. 扣芝麻券：按池子原价 × 10 扣除
2. 用十连抽奖券：消耗 1 张券，不再扣芝麻券

十连抽奖券由管理员通过 /qiyuan tenpull give <玩家> [数量] 发放，玩家持券时右键池子十连才会看到这个选项。

券的材质、显示名、lore 在 config.yml 里的 ten-pull-ticket 下配置，识别只按 material 判断，改 display-name / lore 不影响已发放的旧券。

池子与配置文件Copy Anchor Link

每个池子对应一份 YAML，放在 plugins/ShiroGomaLottery/pools/<池子ID>.yml。

创建池子（推荐命令）Copy Anchor Link

/qiyuan pool create `id` `slot` [material]

创建后插件会自动生成对应 YAML 文件；后续可手动编辑或用 /qiyuan reload 重载。

pools/id.yml 模板Copy Anchor Link

display-name: "武器祈愿"
material: IRON_SWORD
lore:
  - "§7每抽消耗芝麻券 §6{cost} §7张"
  - "§7保底: §f{ pity } §7次"
slot: 11
cost: 100
glow: false

# 本期 UP（留空则本期无 UP）
up:
  tier: mythic
  weight: 300
  # 由控制台执行的命令，{player} 替换为中奖玩家名
  commands:
    - "say {player} 抽中了武器池 UP！"

# 抽中 UP 时自动发放的 ShiroGomaTitles 称号 ID（可选）
# 需要插件 soft-depend ShiroGomaTitles，留空或 none 表示不发
up-title: "lucky_draw_weapon"

管理员命令Copy Anchor Link

权限节点：shirogomalottery.admin（默认仅 OP 拥有）。

主命令Copy Anchor Link

奖励管理Copy Anchor Link

• tier 可选：common · rare · epic · legendary · mythic
• 池子 ID 支持 tab 补全

池子管理Copy Anchor Link

十连抽奖券Copy Anchor Link

配置（config.yml）Copy Anchor Link

qiyuan:
  # 总权重，所有池子必须一致，改后请检查现有 UP 权重是否需要同步调整
  total-weight: 10000
  # 正式服请改为 false
  only-op-draw: true

  ten-pull-ticket:
    material: PAPER
    display-name: "§6§l十连抽奖券"
    lore:
      - "§7在主界面右键池子十连时，可选择本券支付"
      - "§7消耗 1 张券进行一次十连抽奖"

  # 所有池子共享的普通奖励表
  common:
    items: {}

关于池子文件Copy Anchor Link

• display-name：主界面 GUI 显示名，支持 & 颜色代码
• material：GUI 格子用的物品（物品名须与 Minecraft 一致，如 IRON_SWORD）
• lore：物品下方描述行，支持占位符 {cost}（本池单抽花费）与 {pity}（保底次数，预留）
• slot：GUI 位置（0–53）；-1 表示不在主界面显示（可用于后台池子）
• cost：单抽消耗的芝麻券数量（由 ShiroGomaVault 扣减）
• glow：格子物品是否显示附魔光晕

称号联动（ShiroGomaTitles）Copy Anchor Link

当池子的 up-title（或命令 /qiyuan pool settitle 指定）填了一个合法的 ShiroGomaTitles 称号 ID，玩家抽中本池 UP 时会自动获得对应称号。

前置：

• 服务端安装并加载了 ShiroGomaTitles（插件的 softdepend）
• 目标称号 ID 已在 ShiroGomaTitles 的 config.yml titles 下定义

称号发放的时机是UP 实际被抽中，不是十连里任何其他结果。

数据存储Copy Anchor Link

• 玩家抽奖历史与抽奖背包存于 plugins/ShiroGomaLottery/<玩家UUID>.yml（每次抽奖 / 获得奖励时写入）
• 公共奖励表与池子配置分别存于 config.yml 与 pools/id.yml

常见问题Copy Anchor Link

Q：UP 概率算不明白？ UP 概率 = up.weight / total-weight（默认 total-weight=10000）。例如 UP 权重 500，即 500/10000 = 5% 命中 UP。

Q：为什么某池子几乎抽不到想要的普通物品？ 先查该池 UP 权重是否压得过大：UP 概率越高，留给普通物品的总权重越少；再看 qiyuan.common.items 下对应 tier 的权重总和，确认物品自身权重是否过低。

Q：抽中 UP 了但没拿到称号？ 检查三件事：① 服务端是否有 ShiroGomaTitles；② 池子文件或内存里是否真的配了 up-title（/qiyuan pool list 能看到）；③ 这个 titleId 是否在 ShiroGomaTitles 的 titles 里定义了。

Q：改了池子配置不生效？ 执行 /qiyuan reload（或重启服务器）。池子文件改动后必须 reload 才能重新读磁盘。

Q：只有 OP 能抽？ config.yml 的 qiyuan.only-op-draw 临时开关。正式服上线前改成 false 并重载即可。

Q：芝麻券扣不动？ 插件走 ShiroGomaVault 作为依赖；如果没装 Vault 或账户余额为 0，抽奖会提示余额不足。请先确认玩家账户芝麻券余额充足，或安装 Vault。

Q：玩家抽奖记录在哪看？ 管理员对在线玩家执行 /qiyuan history <玩家名> 打开 GUI；离线时可直接查看服务器 plugins/ShiroGomaLottery/<玩家UUID>.yml。