Suite

配置

Lottery 配置文件详解

配置文件总览

Lottery 模块涉及以下配置文件：

文件路径说明
主配置config.yml模块顶层配置（存储、UI、奖池目录、共享保底组）
消息配置messages.yml本地化消息文本
奖池配置lottery/pools/*.yml每个文件定义一个奖池（GACHA 或 CASE）
兑换商店lottery/exchange/*.yml积分兑换商店商品
UI 配置ui/lottery_gacha.yml 等祈愿/开箱界面（详见 UI 文档）
迁移脚本migrations/1-2.yml、2-3.yml配置版本迁移规则

主配置（ArcartXLottery.yml）

config-version: 3  # 配置文件版本号
 
# ─── UI 配置 ────────────────────────────────────────
ui:
  overwrite-ui-files: false         # 是否强制覆盖用户已修改的 UI 文件
  gacha-ui-id: "AXS:lottery_gacha"  # 祈愿（GACHA）界面 UI ID
  case-ui-id: "AXS:lottery_case"    # 开箱（CASE）界面 UI ID
  # wish-ui-id: "AXS:lottery_wish"  # 祈愿（WISH 全屏版）界面 UI ID（可选）
 
# 奖池文件所在目录（相对模块数据目录）
pools-directory: "lottery/pools"
exchange-directory: "lottery/exchange"
 
# ─── 数据存储 ────────────────────────────────────────
storage:
  shared: true  # true=共享本体数据源（推荐），false=自建连接池
 
  # —— shared: false 时配置以下字段 ——
  # mode: "sqlite"
  # sqlite:
  #   file: "lottery.db"
  # pool-size: 1
  # mysql:
  #   host: "127.0.0.1"
  #   port: 3306
  #   database: "arcartxsuite"
  #   username: "root"
  #   password: ""
  #   table-prefix: "axs_lottery_"
 
# ─── 原神跨池共享保底组 ────────────────────────────────────────
shared-pity-groups:
  character_events: "character_event_*"
  weapon_events: "weapon_event_*"

主配置字段表

字段类型默认值说明
config-versionint3配置文件版本号，用于触发自动迁移
ui.overwrite-ui-filesbooleanfalse是否在模块启动时强制覆盖用户已修改的 UI 文件
ui.gacha-ui-idStringAXS:lottery_gacha祈愿界面绑定的 UI ID
ui.case-ui-idStringAXS:lottery_case开箱界面绑定的 UI ID
ui.wish-ui-idStringAXS:lottery_wish祈愿全屏版界面绑定的 UI ID（可选）
pools-directoryStringlottery/pools奖池文件目录（相对模块数据目录）
exchange-directoryStringlottery/exchange兑换商店文件目录
storage.sharedbooleantrue是否使用共享存储模式
storage.modeStringsqlite存储模式（sqlite 或 mysql），仅 shared: false 时生效
storage.sqlite.fileStringlottery.dbSQLite 文件名，仅 shared: false 时生效
storage.mysql.hostString127.0.0.1MySQL 主机地址
storage.mysql.portint3306MySQL 端口
storage.mysql.databaseStringarcartxsuiteMySQL 数据库名
storage.mysql.usernameStringrootMySQL 用户名
storage.mysql.passwordString空MySQL 密码
storage.mysql.table-prefixStringaxs_lottery_表名前缀
storage.pool-sizeint1连接池大小（SQLite 建议 1）
shared-pity-groupsMap<String, String>见示例共享保底组：key 为分组 ID，value 为匹配奖池 ID 的通配符

存储模式说明

  • shared: true（推荐）：模块使用本体统一数据源，连接由本体 config.yml 的 storage 节管控，性能较好。模块仅提供表前缀 axs_lottery_。
  • shared: false：模块自建独立 HikariCP 连接池，不复用本体连接。需配置 mode / sqlite / mysql 等字段。向后兼容：若 shared 字段不存在但 mode=mysql 存在，视为 shared: false。

配置版本迁移

模块支持配置版本自动迁移，迁移脚本位于 migrations/ 目录：

迁移说明
1-2.ymlstorage.sqlite-file-name → storage.sqlite.file，扁平 mysql-* 字段 → mysql 子节
2-3.ymlstorage.mode 重命名为 storage.shared，值 mysql → false、sqlite → true

奖池配置

奖池文件放在 pools-directory 目录下，每个 .yml / .yaml 文件对应一个奖池。模块启动时按文件名排序加载，id 重复时后加载的覆盖先加载的（记录警告）。

通用字段

字段类型默认值说明
idString必填奖池唯一标识
typeStringGACHA奖池类型：GACHA（原神祈愿）或 CASE（CS 开箱）
enabledbooleantrue是否启用
display-nameStringid显示名称
descriptionString空描述文本（支持 \n 换行）
up-item-iconIconDefinition无UP 物品图标，未配置时自动使用 UP 5 星奖品（CASE 为最高稀有度奖品）
up-item-descString空UP 物品描述文本
costCostConfig无消耗配置
pointsMap<String, PointDefinition>无积分产出规则

图标配置写法详见 图标，物品匹配器写法详见 条件系统。

消耗配置（cost）

cost 分为 single（单抽）与 ten（十连）两组条目列表。十连不做倍数换算，未配置 ten 则该奖池不提供十连。每个条目通过 type 区分资源类型：

type说明必填字段
CURRENCY货币，按 id 扣除对应货币id、amount
ITEM物品，用 matcher 匹配背包物品，禁止填 idmatcher、amount
POINT积分，id 对应奖池 points 块定义的积分点 IDid、amount

公共字段：amount（正整数）、display-name（UI 显示名）、icon（消耗图标）。同一抽下可列多个条目，玩家需同时满足全部条目才能抽奖。

cost:
  single:
    - type: CURRENCY
      id: "gold"
      amount: 160
      display-name: "金币"
      icon:
        material: DIAMOND
        name: "金币"
    - type: ITEM
      amount: 1
      display-name: "纠缠之缘"
      icon:
        material: AMETHYST_SHARD
        name: "纠缠之缘"
      matcher:
        material-ids:
          - AMETHYST_SHARD
        lore-contains:
          - "纠缠之缘"
        nbt-values:
          lottery: "intertwined_fate"
  ten:
    - type: CURRENCY
      id: "gold"
      amount: 1600
      display-name: "金币"
      icon:
        material: DIAMOND
        name: "金币"

积分配置（points）

积分按 id 在所有奖池间共享余额。每次抽奖按 per-pull（固定产出）与 rarity（按稀有度产出）累积积分。GACHA 的 rarity key 使用星级（3/4/5），CASE 使用奖池中定义的稀有度名称（如 COMMON/RARE）。

points:
  stardust:
    display-name: "星尘"
    icon:
      material: AMETHYST_SHARD
      name: "星尘"
    per-pull: 1
    rarity:
      "4": 2
      "5": 10
字段类型默认值说明
idString配置节键名积分 ID，余额按该 ID 在所有奖池间共享
display-nameStringid展示名称
iconIconDefinition无展示图标
per-pullint0每次抽取固定产出的积分
rarityMap<String, Integer>无按稀有度产出的积分映射

GACHA 奖池配置（gacha 节）

gacha:
  pool-type: CHARACTER
  pity-5star: 90
  pity-4star: 10
  soft-pity-start: 73
  soft-pity-increment: 0.06
  base-5star-rate: 0.006
  base-4star-rate: 0.051
  up-rate: 0.5
  fate-point-cap: 0
  shared-pity-group: "character_events"
 
  up-5star-items:
    star_character:
      name: "星辰"
      item:
        source: minecraft
        id: "minecraft:nether_star"
      icon:
        material: NETHER_STAR
        name: "星辰"
      delivery: DIRECT
      weight: 1
 
  standard-5star-items:
    moon_character:
      name: "月影"
      item: { source: minecraft, id: "minecraft:ender_eye" }
      delivery: DIRECT
      weight: 1
 
  up-4star-items: { ... }
  standard-4star-items: { ... }
  star3-items: { ... }
字段类型默认值说明
pool-typeStringCHARACTERCHARACTER / WEAPON / STANDARD
pity-5starint905 星硬保底抽数
pity-4starint104 星硬保底抽数
soft-pity-startint73软保底起始抽数
soft-pity-incrementdouble0.06软保底每抽概率增量
base-5star-ratedouble0.0065 星基础概率
base-4star-ratedouble0.0514 星基础概率
up-ratedouble0.5UP 物品在对应星级中的概率
fate-point-capint0命运点上限（武器池定轨），0 不启用
shared-pity-groupString无共享保底组名
up-5star-itemsList<PoolItem>无UP 5 星奖品列表
standard-5star-itemsList<PoolItem>无常驻 5 星奖品列表
up-4star-itemsList<PoolItem>无UP 4 星奖品列表
standard-4star-itemsList<PoolItem>无常驻 4 星奖品列表
star3-itemsList<PoolItem>无3 星奖品列表（必填）

CASE 奖池配置（case 节）

case:
  rarity-settings:
    COMMON:
      color: "&f"
      base-weight: 15625
    RARE:
      color: "&9"
      base-weight: 625
    SPECIAL:
      color: "&6"
      base-weight: 2
 
  items:
    stone_sword:
      name: "石纹短剑"
      rarity: COMMON
      item:
        source: minecraft
        id: "STONE_SWORD"
      delivery: DIRECT
      icon:
        material: STONE_SWORD
        name: "石纹短剑"
字段类型说明
rarity-settingsMap<String, RaritySetting>稀有度名称到权重设定的映射
rarity-settings.<name>.colorString显示颜色代码（如 &f）
rarity-settings.<name>.base-weightint基础权重，必须为正数
itemsList<PoolItem>奖池中全部可用奖品列表

CASE 箱子物品配置（case-item 与 requires-key）

case-item:
  matcher:
    material-ids:
      - CHEST
    nbt-values:
      lottery: "case_box"
  amount: 1
  display-name: "战术武器箱"
  icon:
    material: CHEST
    name: "战术武器箱"
 
requires-key: true
字段类型默认值说明
case-item.matcherItemMatcher必填识别玩家手持箱子物品的匹配器
case-item.amountint1单次开箱消耗的箱子数量（十连按倍数扣除）
case-item.display-nameString箱子UI 显示名称
case-item.iconIconDefinition无UI 图标
requires-keybooleanfalse是否需要钥匙开启；true 时消耗 = 箱子 + cost 配置的钥匙

奖品配置（PoolItem）

每个奖品由 PoolItem 定义，适用于 GACHA 各星级列表与 CASE 物品列表：

star_character:
  name: "星辰"
  item:
    source: minecraft
    id: "minecraft:nether_star"
    # nbt: "{CustomTag:'value'}"  # 仅 minecraft 源有效
  icon:
    material: NETHER_STAR
    name: "星辰"
  delivery: DIRECT
  amount: 1
  weight: 1
  rarity: COMMON  # 仅 CASE 奖池使用
  commands: []  # 仅 COMMAND 投递使用
  extra-commands: []  # 投递成功后执行的附加命令
  mail:
    presets: []  # 仅 MAIL 投递使用
字段类型默认值说明
idString配置节键名奖品标识
nameStringid奖品显示名称
deliveryStringDIRECT投递方式：DIRECT / COMMAND / MAIL
item.sourceString必填物品来源（minecraft / mythicmobs / neigeitems / overture / mmoitems）
item.idString必填物品标识；MMOItems 使用 TYPE;ID 格式
item.nbtString无自定义 NBT（SNBT 字符串，仅 minecraft 源有效）
iconIconDefinition无奖品图标，未配置时用 item 生成的物品
amountint1发放数量（正整数）
weightint1奖池内相对权重（正整数）
rarityString无CASE 奖池中的稀有度名称
commandsList<String>无COMMAND 投递执行的命令列表
extra-commandsList<String>无投递成功后执行的附加命令
mail.presetsList<String>无MAIL 投递使用的邮件预设 ID 列表

物品来源（item.source）支持的来源详见 物品来源，图标写法详见 图标。

兑换商店配置

兑换商店文件放在 exchange-directory 目录下，每个 .yml 文件的 items 块下每个键为一个商品：

items:
  dust_ticket:
    id: dust_ticket
    display-name: "祈愿凭证"
    icon:
      material: AMETHYST_SHARD
      name: "祈愿凭证"
    pool-id: "genshin_vanilla_event"  # 可选，日志归类用
    cost:
      single:
        - type: POINT
          id: "stardust"
          amount: 10
          display-name: "星尘"
          icon:
            material: AMETHYST_SHARD
            name: "星尘"
    limit: 0  # 0=无限制，>0=每人最多可兑换次数
    reward:
      name: "祈愿凭证"
      item:
        source: minecraft
        id: "minecraft:amethyst_shard"
字段类型默认值说明
idString配置节键名商品唯一标识
display-nameStringid商品显示名称
iconIconDefinition无商品图标，未配置时用 reward.item 生成
pool-idString无兑换记录归属的奖池 ID（日志归类用），未配置时记为 exchange
costList<CostEntry>必填兑换消耗条目（支持配置节写法或直接列表写法）
limitint0限购次数：0=无限制，>0=每人最多可兑换次数
rewardPoolItem必填兑换奖励（结构同奖池奖品）

完整配置示例

GACHA 角色池示例

id: "character_event_1"
type: GACHA
enabled: true
display-name: "角色活动祈愿"
description: |-
  角色活动祈愿
  在本祈愿中，5星角色「星辰」的获取概率将大幅提升！
up-item-icon:
  material: NETHER_STAR
  name: "星辰"
up-item-desc: "五星角色「星辰」获取概率大幅提升"
cost:
  single:
    - type: CURRENCY
      id: "gold"
      amount: 160
      display-name: "金币"
      icon: { material: DIAMOND, name: "金币" }
  ten:
    - type: CURRENCY
      id: "gold"
      amount: 1600
      display-name: "金币"
      icon: { material: DIAMOND, name: "金币" }
points:
  stardust:
    display-name: "星尘"
    per-pull: 1
    rarity: { "4": 2, "5": 10 }
gacha:
  pool-type: CHARACTER
  pity-5star: 90
  pity-4star: 10
  soft-pity-start: 73
  soft-pity-increment: 0.06
  base-5star-rate: 0.006
  base-4star-rate: 0.051
  up-rate: 0.5
  shared-pity-group: "character_events"
  up-5star-items:
    star_character:
      name: "星辰"
      item: { source: minecraft, id: "minecraft:nether_star" }
      delivery: DIRECT
      weight: 1
  standard-5star-items:
    moon_character:
      name: "月影"
      item: { source: minecraft, id: "minecraft:ender_eye" }
      delivery: DIRECT
      weight: 1
  up-4star-items: { ... }
  standard-4star-items: { ... }
  star3-items: { ... }

CASE 开箱池示例

id: "default_weapon_case"
type: CASE
enabled: true
display-name: "常规武器箱"
case-item:
  matcher:
    neige-item-ids:
      - lottery_case_box
  amount: 1
  display-name: "常规武器箱"
requires-key: true
cost:
  single:
    - type: ITEM
      amount: 1
      display-name: "CaseKey"
      matcher:
        neige-item-ids:
          - lottery_case_key
  ten:
    - type: ITEM
      amount: 10
      display-name: "CaseKey"
      matcher:
        neige-item-ids:
          - lottery_case_key
points:
  dust:
    display-name: "尘辉"
    per-pull: 1
    rarity: { COMMON: 1, RARE: 2, EPIC: 4 }
case:
  rarity-settings:
    COMMON: { color: "&f", base-weight: 15625 }
    UNCOMMON: { color: "&b", base-weight: 3125 }
    RARE: { color: "&9", base-weight: 625 }
    EPIC: { color: "&5", base-weight: 125 }
    LEGENDARY: { color: "&d", base-weight: 25 }
    MYTHIC: { color: "&c", base-weight: 5 }
    SPECIAL: { color: "&6", base-weight: 2 }
  items:
    skin_p250_sand:
      name: "P250 | 沙漠风暴"
      rarity: COMMON
      item: { source: minecraft, id: "minecraft:stone" }
      delivery: DIRECT

本页目录