奖池文件

每个奖池是 plugins/StarCrate/crates/ 里的一个 YAML 文件，文件名（不含 .yml）就是奖池 ID。

大多数时候你不需要碰这个文件：编辑器 里的每个按钮都对应这里的一个键，改了立即保存。 这一页适合想手写奖池、批量修改，或想弄清楚某个设定到底做什么的人。

手改文件之后

直接修改文件后执行 /sc reload 才会生效。请不要在编辑器开着同一个奖池时手改文件：编辑器下一次保存会用游戏里的内容覆盖整个文件（注释也不会保留）。

奖池 ID

• 只能使用字母、数字、中文、- 与 _，最多 48 个字，例如 xinghui、新春礼包、vip-box。
• 不分大小写：/sc open XingHui 与 /sc open xinghui 是同一个奖池。
• 玩家的保底、抽奖记录等数据都用 ID 记录，所以改 ID 请用 /sc rename（数据会一起转移），不要直接改文件名。

完整范例

插件第一次启动生成的 crates/example.yml（手写格式）：

plugins/StarCrate/crates/example.yml

display-name: '<gradient:#FFD86F:#FC6262>星辉宝箱</gradient>'
type: normal
animation: roulette
ten-animation: cards
ten-pull: true
show-chance: true
permission: ''
daily-limit: 0
cost:
  type: none
  single: 0
  ten: 0
  key-name: ''
consume-crate-item: true
pity:
  hard: 50
  soft-start: 35
  soft-step: 5
  ten-guarantee: rare
effects:
  hologram: true
  particle: spiral
  broadcast: true
prizes:
  - id: p1
    item: {material: BREAD, amount: 16, name: '<white>星辉面包'}
    weight: 40
    rarity: common
  - id: p5
    item: {material: DIAMOND, amount: 3, name: '<aqua>星辉钻石', lore: ['<gray>闪着微光']}
    weight: 5
    rarity: epic
  - id: p7
    item: {material: NETHER_STAR, amount: 1, name: '<gradient:#FF4D6D:#FFB627>神话 · 星核</gradient>'}
    weight: 0.5
    rarity: mythic
    grand: true
    broadcast: true

（范例中省略了 p2、p3、p4、p6。）在游戏里编辑过之后，文件会改写成编辑器的格式：每个奖品的物品变成 item-data（完整物品数据），所有键都会写出来。

基本设定

键	类型	默认	作用
display-name	文字	奖池 ID	奖池显示名称，用在界面标题、公告、邮件、宝箱物品与方块全息上。支持 MiniMessage、& 颜色与 &#RRGGBB。
type	normal / instant / select	normal	奖池类型，见 三种奖池类型。写错时当成 normal 并在控制台警告。
select-count	整数 ≥ 1	1	自选奖池要选几个奖品。只有 type: select 时有用（也只在这时写进文件）。
animation	动画名称	roulette	单抽动画。名称见 抽奖动画；写错时使用 roulette。
ten-animation	动画名称	cards	十连动画。只能单抽的动画（roulette、slots、carousel）或写错时使用 cards。
ten-pull	true / false	true	是否允许十连。false 时预览界面不显示十连按钮，用指令十连会提示「这个奖池不能十连抽」。
show-chance	true / false	true	玩家预览时是否看得到每个奖品的概率；也决定宝箱物品的奖励列表要不要带概率。
permission	权限节点	''	抽这个奖池需要的权限，空白 = 所有人。没有权限仍然可以打开预览看奖品，但点抽奖会提示「你没有权限开启」。免费代抽（/sc draw … free、API 的免费抽奖）不检查。
daily-limit	整数	0	每位玩家每天最多抽几次，0 = 不限。十连算 10 次；剩下的次数不够这一次时整次不抽、也不扣费。以服务器时区的 0 点为一天的开始；使用 MySQL 时所有子服合计。见下方说明。

daily-limit 怎么计数

每日次数是从抽奖记录里数「今天这位玩家在这个奖池抽到了几个奖品」，所以免费代抽（/sc draw … free）本身不受上限限制，但抽到的奖品会算进当天的次数。

花费（cost）

cost:
  type: key        # none 免费 / money 金币 / points 点券 / key 钥匙
  single: 0        # 单抽花费
  ten: 0           # 十连花费
  key-name: ''     # 钥匙名称（只用于提示文字）
  key-item:        # 钥匙物品模板（在编辑器设定，自动写入 item-data）
    item-data: '…'

键	类型	默认	作用
cost.type	none / money / points / key	none	花费方式。money 需要 Vault + 经济插件，points 需要 PlayerPoints；没装时玩家抽奖会被提示服务器没有对应的插件。
cost.single	数字 ≥ 0	0	单抽花费。金币可以有小数；点券取整数；钥匙是把数。
cost.ten	数字 ≥ 0	0	十连花费，可以设得比 10 次单抽便宜，做「十连折扣」。
cost.key-name	文字	''	钥匙在提示文字里的名称（例如「钥匙不足：需要 1 把 ✦星辉钥匙」）。空白时使用 messages.yml 的 default-key-name（{crate} 钥匙）。
cost.key-item	物品	无	钥匙物品的模板。没设定时钥匙是一个发光的绊线钩。见 宝箱物品与钥匙。

花费的细节：

• 金币 / 点券填 0 = 免费（type: money 但 single: 0 时单抽不扣钱）。
• 钥匙填 0 = 单抽 1 把、十连 10 把；填了数字就用那个数字（四舍五入成整数）。
• 背包（含副手）里的钥匙会被计算与扣除。
• 所有花费都先检查后扣除：钥匙、金币、点券、宝箱物品全部足够才一起扣，扣失败会退回已扣的部分。
• 扣费前还会检查玩家还能抽到几个奖品（奖品有每人上限时）：不够这次的抽数就整次不抽、不扣费，见 概率与保底 · 十连。
• 免费代抽（/sc draw … free）不扣任何东西。

宝箱物品（consume-crate-item / crate-item）

键	类型	默认	作用
consume-crate-item	true / false	true	右键宝箱物品打开预览后抽奖，是否用掉宝箱（单抽 1 个、十连 10 个，自选时按 1 个或 10 个）。用抽奖方块或 /sc open 打开时不会用到宝箱。
crate-item	物品	无	宝箱物品的外观模板（在编辑器设定，写成 crate-item.item-data）。没设定时使用 config.yml 的 crate-item.material（默认末影箱）。

宝箱物品的完整说明见 宝箱物品与钥匙。

保底（pity）

pity:
  hard: 50          # 硬保底：连续 49 抽没出终极大奖，第 50 抽必出（0 = 关闭）
  soft-start: 35    # 软保底起点（0 = 关闭）
  soft-step: 5      # 软保底每抽提高几个百分点
  ten-guarantee: rare   # 十连保底稀有度（'' = 使用 config.yml 的 defaults.ten-guarantee）

键	类型	默认	作用
pity.hard	整数	0	硬保底。距离上一次终极大奖的第 N 抽必定是终极大奖。0 = 关闭。
pity.soft-start	整数	0	软保底起点。连续这么多抽没出终极大奖之后，下一抽开始终极大奖的总概率逐抽提高。0 = 关闭。
pity.soft-step	数字	0	软保底每抽提高几个百分点（例如 5 = 每抽 +5%）。0 = 关闭软保底。
pity.ten-guarantee	稀有度 ID	''	十连保底：十连至少有一个这个稀有度以上的奖品。空白时使用 config.yml 的 defaults.ten-guarantee（默认也是空白 = 不保底）；写了不存在的稀有度 = 不保底。

保底只和「终极大奖」（grand: true 的奖品）有关。怎么计算、附数字范例，见 概率与保底。

效果（effects）

键	类型	默认	作用
effects.hologram	true / false	true	抽奖方块上方是否显示标题与旋转的奖品展示，见 抽奖方块。
effects.particle	粒子样式	none	抽奖方块的待机粒子：none、halo、spiral、orbit、fountain、stars、flame、magic。
effects.broadcast	true / false	true	false = 这个奖池的所有奖品都不公告（不论奖品或稀有度怎么设定）。

奖品（prizes）

prizes 是一个列表，列表顺序就是预览界面的顺序。每个奖品：

键	类型	默认	作用
id	文字	自动	奖品编号，在这个奖池内不能重复。没写或重复时自动编成 p1、p2…。保底、每人上限、统计都用它记录，改了编号等于换了一个奖品。
item-data	物品数据	—	游戏里放进来的完整物品（附魔、自定义名称、其他插件的物品数据都会保留）。请勿手动修改。
item	物品	—	手写物品，见 手写物品。item-data 与 item 至少要有一个，都没有的奖品会被跳过并在控制台警告。
weight	数字 ≥ 0	10	权重，越大越容易抽中。概率 = 权重 ÷ 所有奖品权重总和。0 = 只展示、永远抽不到。也可以写成 chance。
rarity	稀有度 ID	common	稀有度，决定颜色、音效、烟花、默认公告等，见 稀有度。写了不存在的稀有度时当成最普通的那一个。
grand	true / false	false	终极大奖。计入保底：抽到它保底次数归零，保底到了必出它这一类奖品。
broadcast	default / true / false	default	全服公告。default = 跟随稀有度（稀有度设定公告，或这个奖品是终极大奖时公告）；true = 一定公告；false = 一定不公告。
give-item	true / false	true	抽中时是否发放这个物品。false = 物品只用来展示，奖励靠 commands 发放（例如称号、权限、金币）。
commands	文字列表	无	抽中时执行的指令，见 奖励指令。
display-name	文字	''	奖品在公告、邮件、聊天结果与抽奖记录里显示的名称。空白 = 使用物品名称（没有自定义名称时显示物品的原版名称，会随玩家的语言显示）。
limit	整数	0	每位玩家最多获得几次，0 = 不限。达到后这个玩家就抽不到它了（也不能在自选奖池选它），预览显示「已达获得上限」。
permission	权限节点	''	只有拥有这个权限的玩家抽得到它（自选时也选不了）。没有权限的玩家，这个奖品不参与他的概率计算。

手写物品

prizes:
  # 完整写法
  - id: sword
    item:
      material: DIAMOND_SWORD
      amount: 1
      name: '<gradient:#5EC8FF:#C77DFF>星陨之刃</gradient>'
      lore: ['<gray>斩开夜空的剑']
      custom-model-data: 10001
    weight: 2
    rarity: epic
  # 只写材质
  - id: apple
    item: GOLDEN_APPLE
    weight: 30

material 用 Bukkit 材质名称（大小写都可以），amount 默认 1，name 与 lore 支持 MiniMessage 与 & 颜色。 附魔、其他插件的自定义物品等复杂物品，请在游戏里用编辑器放进来。

奖励指令

commands:
  - 'lp user {player} permission set title.star true'   # 控制台执行
  - '[console] eco give {player} 1000'                  # 同上，明确写出控制台
  - '[player] spawn'                                     # 玩家自己执行
  - '[message] <gold>恭喜获得星辰称号！'                  # 发一条消息给玩家

• 开头的 / 可以写也可以不写。
• 变量：{player}、%player%、%player_name% = 玩家名称，{uuid} = 玩家 UUID。
• 什么时候执行：动画结束、奖励发放时。奖励寄到星月邮箱时，默认在玩家领取邮件时才执行（config.yml 的 delivery.mail-commands 可以改成抽中立刻执行），见 奖励发放。
• 在编辑器输入时，一次可以输入多条，用 || 分隔。

三种奖池类型

normal（抽奖）

默认类型。点单抽 / 十连会播放奖池设定的动画（玩家关掉动画或 config.yml 关闭动画时直接显示结果），动画结束后打开「抽奖结果」界面。

instant（立即抽取）

和 normal 完全相同，只是一律不播放动画，结果直接写在聊天栏，也不打开结果界面。适合低价、大量开启的奖池。

select（自选）

玩家不是抽奖，而是自己选：打开奖池时显示的是选择界面（标题默认「选择 N 个」），点奖品选择 / 取消，选满 select-count 个后按「确认选择」领取。

• select-count: 1 时，点另一个奖品会直接换选。
• 花费按单抽花费计算；select-count 为 10 以上时按十连花费计算。从宝箱物品打开时按同样的规则消耗 1 个或 10 个宝箱。
• 奖池的 permission：没有权限的玩家可以打开选择界面看奖品，按「确认选择」时会提示「你没有权限开启 …」（用 /sc draw 或 API 替他开启时，在打开选择界面前就会检查）。
• daily-limit：确认时今天至少要还剩 1 次；领取的每个奖品都会记入当天的次数。
• weight 不起作用，所有奖品都能选；但 limit（达到上限的选不了）与奖品的 permission（没有权限的选不了）照常有效。
• 自选不影响保底次数，但会计入抽奖次数与抽奖记录；确认时同样会触发 开发者事件。
• 动画、十连、保底等设定对自选奖池没有作用。

适合「三选一礼包」「新手自选武器箱」这类玩法：

display-name: '<green>新手自选武器箱'
type: select
select-count: 1
cost: {type: none, single: 0, ten: 0}
consume-crate-item: true
prizes:
  - {id: sword, item: DIAMOND_SWORD}
  - {id: bow,   item: BOW}
  - {id: axe,   item: DIAMOND_AXE}

然后 /sc give <奖池> 1 <玩家> 发一个宝箱给新手，右键打开选一把。

删除与改名

指令	会发生什么
/sc delete <奖池>	文件移到 plugins/StarCrate/deleted-crates/<奖池>-<时间>.yml，可以搬回 crates/ 后 /sc reload 复原。玩家数据不会删除。绑定这个奖池的抽奖方块会一起解除（方块上方的全息也会移除）；复原奖池后需要重新 /sc setblock。
/sc rename <旧> <新>	换成新 ID 的文件；玩家的保底、获得次数、抽奖记录、待补发记录一起转移；抽奖方块跟着改；之前发出的宝箱物品与钥匙照常可用（见下方）。

renamed-crates.yml

/sc rename 会把「旧 ID → 新 ID」记在 plugins/StarCrate/renamed-crates.yml：

plugins/StarCrate/renamed-crates.yml

xinghui: starlight

• 玩家手上旧 ID 的宝箱物品与带标记的钥匙，会通过这个文件找到新奖池，改名前发出的照样能用。
• 旧 ID 之后会一直指向新奖池：/sc open xinghui 打开的就是 starlight，也因此不能再用旧 ID 建立新的奖池。
• 改名多次也没关系（a → b → c，a 会找到 c）。这个文件由插件维护，请勿手动修改。