> For the complete documentation index, see [llms.txt](https://spintowin.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi.md).

# 📝UI 配置

所有转盘配置位于 `plugins/SpinToWin/ui/`。指令中的 UI 名称就是文件名，不含 `.yml`；例如 `example.yml` 对应 `example`。

**免费版只能加载 1 个转盘 UI，高级版没有此限制。**

<figure><img src="https://content.gitbook.com/content/lZa8qg7GyuZPlsNnz1EO/blobs/frEZ7Ii8WtY9tqJsLtLb/2.png" alt="转盘界面示例"><figcaption></figcaption></figure>

## 配置示例

以下示例与英文版 UI Config 的结构一致，使用 `gui.title`、`gui.size`、`history-gui`、`auto-settings` 等节点：

```yaml
gui:
  title: ":offset_-8::s2w_ui:"
  size: 45
history-gui:
  title: ""
  dynamic-size: true
slots: [9,10,11,12,13,22,31,40,39,38,37,36,27,18]
last-reward-slot: 16

reserve: false
replace:
  material: gray_stained_glass_pane
  amount: 1
  name: "&3Acquired"
show-rate: true
frame: frame
# last-reward-times: 14

auto-settings:
  reset-timer-after-first-spin: -1
  reset-when-empty: true
  close-when-empty: true
  close-when-price-not-meet: false
  empty-amount: 1

limits:
  default: 100
  vip: 200
limits-conditions:
  vip:
    1:
      type: permission
      permission: 'group.vip'

buttons:
  spin:
    icons: [spin_1,spin_2,spin_3]
    slots: [33,34,35]
    name: "&aSpin!"
    lore:
      - "&fYou should cost %price%"
      - "&f"
      - "%click%"
  history:
    icons: [history_1,history_2,history_3]
    slots: [42,43,44]
    name: "&fHistory"
    lore:
      - "&fCheck the rewards you have drawn."
last_reward:
  material: DIAMOND_SWORD
  amount: 1
rewards:
  1:
    material: DIAMOND
    cmd: 0
    name: '&eA赏'
    lore:
      - '&fLine1'
      - '&fLine2'
    actions:
      1:
        type: console_command
        command: 'say %player% claimed A 赏!'
    amount: 10
    chance: 20
  2:
    material: IRON_INGOT
    amount: 10
    chance: 20
  3:
    material: GOLD_INGOT
    amount: 5
    chance: 10
  4:
    material: APPLE
    amount: 64
    chance: 10
  5:
    material: DIAMOND
    amount: 2
    chance: 5
  6:
    material: IRON_INGOT
    amount: 10
    chance: 20
  7:
    material: GOLD_INGOT
    amount: 5
    chance: 10
  8:
    material: APPLE
    amount: 64
    chance: 10
  9:
    material: DIAMOND
    amount: 2
    chance: 5
  10:
    material: IRON_INGOT
    amount: 10
    chance: 20
  11:
    material: GOLD_INGOT
    amount: 5
    chance: 10
  12:
    material: APPLE
    amount: 64
    chance: 10
  13:
    material: DIAMOND
    amount: 2
    chance: 5
  14:
    material: IRON_INGOT
    amount: 10
    chance: 20
prices:
  1:
    free: true
    placeholder: 'Free'
    apply: [1,2,3]
  2:
    economy-type: levels
    amount: 5
    placeholder: '5 Levels'
    apply: [1,2,3,4,5,6]
  3:
    economy-type: exp
    placeholders:
      7: '6 Exp'
      8: '7 Exp'
      9: '8 Exp'
      10: '9 Exp'
      11: '10 Exp'
    apply: [7,8,9,10,11]
    cost: [6,7,8,9,10]
  4:
    hook-plugin: EcoItems
    hook-item: super_sword
    amount: 3
    start-apply: 8

```

## 基础选项

| 选项                         | 说明                                         |
| -------------------------- | ------------------------------------------ |
| `gui.title`                | 转盘 UI 标题，可包含资源包字体字符或变量                     |
| `gui.size`                 | 转盘大小，取 `9`、`18`、`27`、`36`、`45`、`54` 之一     |
| `history-gui.title`        | 已领取奖励界面的标题                                 |
| `history-gui.dynamic-size` | 是否根据已领取奖励数量调整历史界面的大小；关闭后使用 `gui.size`      |
| `slots`                    | 奖励展示槽位及指针前进顺序，不能使用第一行 `0～8`                |
| `reserve`                  | `true` 允许重复抽取，`false` 表示本轮已领取奖励不再参与抽奖      |
| `replace`                  | `reserve: false` 时用于替换已领取奖励的物品；不配置则移除已领取奖励 |
| `frame`                    | 外框名称，来自 `config.yml` 的外框映射                 |
| `show-rate`                | 是否给奖励物品添加显示抽中概率的 Lore                      |

默认 UI 有 14 个展示槽位，但奖励数量可以超过槽位数量。超过后自动启用待机慢速轮转和抽奖时的反向旋转、同步减速，详见[奖励轮转与抽奖动画](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jiang-li-lun-zhuan.md)。

替代物品仍占据展示列表位置并参与轮转。不配置 `replace` 时，已领取奖励从列表移除，剩余展示数量不超过槽位数量后停止奖励轮转。

## 自动关闭与重置

| 选项                                           | 说明                                        |
| -------------------------------------------- | ----------------------------------------- |
| `auto-settings.empty-amount`                 | 判定奖池即将抽空时使用的剩余奖励数量；示例为 `1`                |
| `auto-settings.reset-timer-after-first-spin` | 第一次抽奖后自动重置的计时，`-1` 为禁用；当前实现按秒读取，再转换为 tick |
| `auto-settings.reset-when-empty`             | 奖池抽空时是否重置玩家数据                             |
| `auto-settings.close-when-empty`             | 奖池抽空时是否关闭 UI                              |
| `auto-settings.close-when-price-not-meet`    | 玩家无法满足后续抽奖价格时是否关闭 UI；请核对所用版本实际支持的键名       |

## 次数限制

* `limits`：转盘的抽奖次数上限，需要在 `config.yml` 启用 `check-permission-limit`。
* `limits.default`：默认次数上限。
* `limits.<条件ID>`：满足对应条件时采用的次数上限。
* `limits-conditions.<条件ID>`：对应的条件格式配置。

```yaml
limits:
  default: 10
  vip: 20
limits-conditions:
  vip:
    1:
      type: permission
      permission: 'test.permission'
```

此例中，拥有 `test.permission` 权限的玩家上限为 20 次，其他玩家为 10 次。条件语法见[配置格式](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/ji-ben-xin-xi/format.md)。

## 按钮、奖励与价格

* `buttons`：按钮配置。`buttons.<按钮ID>.icons` 引用 `config.yml` 中登记的图标名称。
* `last-reward`：最后赏的物品配置，兼容旧名 `last_reward`。物品与动作格式见[奖励配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jiang-li-pei-zhi.md)。
* `last-reward-slot`：最后赏展示槽位。
* `last-reward-times`：触发最后赏的抽奖次数，兼容旧名 `last_reward_times`。不设置时，取初始奖励数量与展示槽位数量中的较大值；20 个奖励、14 个槽位时默认第 20 抽触发。最后赏本身及槽位也需要配置。
* `rewards`：普通奖励列表，见[奖励配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jiang-li-pei-zhi.md)。
* `prices`：抽奖价格列表，见[价格配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jia-ge-pei-zhi.md)。

奖励和价格 ID 均从 `1` 开始连续递增，不要跳号。

## 自定义按钮

可以在 `buttons` 下增加按钮，并通过 `actions` 设置点击后的动作：

```yaml
buttons:
  spin:
    icons: [spin_1,spin_2,spin_3]
    slots: [33,34,35]
    display: "&aSpin!"
    lore:
      - "&fYou should cost %price%"
      - "&f"
      - "%click%"
  history:
    icons: [history_1,history_2,history_3]
    slots: [42,43,44]
    display: "History"
    lore:
      - "&fCheck the rewards you have drawn."
  test:
    icons: [test]
    slots: [18]
    display: "Buy Key"
    lore:
      - "&fCheck here to know where can buy key."
    actions:
      1:
        type: message
        message: 'Buy spin key at https://www.example.com!'
```

上例增加了 `test` 按钮。对应图标也需要在 `config.yml` 登记，例如：

```yaml
icon:
  history_3: 70000
  spin_1: 70001
  spin_2: 70002
  history_2: 70003
  spin_3: 70004
  history_1: 70005
  test: 10000
```

* `icons`：图标名称列表。
* `slots`：按钮所在槽位，不得使用第一行 `0～8`，且必须小于 `gui.size`。
* `actions`：点击后执行的动作，使用[动作格式](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/ji-ben-xin-xi/format.md)。
