> 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/wheel-ui.md).

# 🎡Wheel UI

Wheel UI 是可用鼠标操作的转盘抽奖界面。玩家可以查看奖励、点击按钮抽奖，并在历史页查看已获得的奖励。转盘支持等分扇区、按中奖权重分配扇区，以及转盘旋转或指针旋转两种动画。

## 使用前准备

服务器需要安装并启用 **ArcMenu**，玩家需要加载 ArcMenu 和 SpinToWin 的资源包。鼠标操作无需安装客户端模组。

SpinToWin 的转盘素材包含在默认资源包中，启动或重载插件后可在 `plugins/SpinToWin/pack/` 找到。将这些素材合并到服务器提供给玩家的资源包中即可。修改奖励、权重或扇区颜色不需要重新制作转盘纹理。

## 打开轮盘

轮盘配置保存在 `plugins/SpinToWin/wheels/`，内置以下示例：

| 文件                   | 样式与动画                |
| -------------------- | -------------------- |
| `example.yml`        | 彩色等分转盘，转盘旋转、指针固定     |
| `chance_pointer.yml` | 扇区按奖励权重分配，指针旋转、转盘固定  |
| `bedrock.yml`        | 基岩风格配色、绿色抽奖按钮和立体按钮边缘 |

```
/s2w open wheels/example
/s2w open wheels/chance_pointer
/s2w open wheels/bedrock
```

轮盘 ID 为 `wheels/文件名`，不包含 `.yml`。例如，`festival.yml` 对应 `wheels/festival`。配置也可以放在子目录中，但 ID 仍只取文件名，因此轮盘文件不能重名。普通背包 UI 与轮盘各自保存玩家记录。

修改配置后执行 `/s2w reload`；更换插件 JAR 后需要重启服务器。

| 操作        | 指令                              |
| --------- | ------------------------------- |
| 打开自己的轮盘   | `/s2w open wheels/example`      |
| 为指定玩家打开   | `/s2w open wheels/example 玩家名`  |
| 重置自己的轮盘记录 | `/s2w reset wheels/example`     |
| 重置指定玩家的记录 | `/s2w reset wheels/example 玩家名` |

打开轮盘需要 `spintowin.use.open` 和对应轮盘的权限，例如 `spintowin.use.open.wheels/example`。为其他玩家操作及重置记录的权限见[指令与权限](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/ji-ben-xin-xi/zhi-ling-quan-xian-jie-dian.md)。

## 创建轮盘

将以下内容保存为 `plugins/SpinToWin/wheels/my_wheel.yml`，执行 `/s2w reload`，再用 `/s2w open wheels/my_wheel` 打开。

这个轮盘每次消耗 4 个绿宝石，奖励可重复抽取，三种奖励的中奖概率分别为 60%、30% 和 10%。

```yaml
gui:
  title: '&6幸运转盘'
reserve: true
show-rate: true
wheel:
  sector-mode: chance
  rotation-mode: wheel
buttons:
  spin:
    name: '&a开始抽奖'
    lore:
      - '&7消耗：%price%'
      - '%click%'
  history:
    name: '&f抽奖记录'
  close:
    name: '&c关闭'
prices:
  1:
    material: EMERALD
    amount: 4
    start-apply: 1
    placeholder: '&a4 个绿宝石'
rewards:
  1:
    material: IRON_INGOT
    amount: 16
    chance: 60
  2:
    material: GOLD_INGOT
    amount: 8
    chance: 30
  3:
    material: DIAMOND
    amount: 2
    chance: 10
```

`rewards` 和 `prices` 的编号都必须从 `1` 开始连续递增。省略 `prices` 即为免费抽奖。奖励物品、指令奖励、动态权重和其他价格类型见[奖励配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jiang-li-pei-zhi.md)与[价格配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jia-ge-pei-zhi.md)。

### 扇区面积与中奖概率

| 配置                    | 可选值       | 效果                 |
| --------------------- | --------- | ------------------ |
| `wheel.sector-mode`   | `equal`   | 每个展示条目的扇区面积相同，默认值  |
| `wheel.sector-mode`   | `chance`  | 扇区面积按当前可抽奖励的权重比例分配 |
| `wheel.rotation-mode` | `wheel`   | 转盘与奖励旋转，指针固定，默认值   |
| `wheel.rotation-mode` | `pointer` | 指针旋转，转盘与奖励固定       |

**扇区面积不会改变中奖概率。** 例如，上方三个奖励即使改成 `equal`、各占三分之一盘面，中奖概率仍为 60%、30% 和 10%。动态权重会在每次抽奖开始时更新。

权重很小的奖励在 `chance` 模式下扇区和图标也很小；需要让所有奖励都容易看清时，可以选择 `equal`。

### 重复抽取与最后赏

`reserve: true` 允许重复获得奖励；`reserve: false` 时，已经获得的奖励在本轮内不能再次抽中。

在不可重复抽取的轮盘中，添加 `replace` 可以为已领取奖励保留替代图标。此显示方式仅适用于 `equal` 模式；`chance` 模式会移除已领取奖励的扇区。

以下配置可用于上方的三个奖励：每个奖励只抽取一次，第 3 次抽奖额外发放 1 个钻石块作为最后赏。

```yaml
reserve: false
replace:
  material: BARRIER
  name: '&7已获得'
last-reward-times: 3
last-reward:
  material: DIAMOND_BLOCK
  amount: 1
```

`last-reward` 设置实际发放的最后赏，`wheel.last-reward` 设置它在界面中的位置和外观。自动重置、自动关闭、抽奖次数限制等选项见[UI 配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi.md)。使用 `limits` 前，需要在 `config.yml` 中启用 `check-permission-limit`。

## 转盘布局与动画

```yaml
ui:
  layout:
    canvas:
      width: 640
      height: 400
  renderers:
    arcmenu:
      screen-scale: 1.5
  tooltip:
    font-size: 1.1
wheel:
  radius: 128
  hub-radius: 14
  item-size: 24
  pointer-angle: -90
  pointer-color: '#FFFFFF'
  colors:
    - '#C85A64'
    - '#D5A64B'
    - '#53A58E'
  idle:
    enabled: true
    degrees-per-second: 6
  spin:
    duration: 160
    turns: 5
```

| 配置                                  | 说明                                   |
| ----------------------------------- | ------------------------------------ |
| `ui.layout.canvas.width/height`     | 逻辑画布大小，默认 `640 × 400`                |
| `ui.renderers.arcmenu.screen-scale` | 整体显示比例，默认 `1.5`，范围 `0.75–2`          |
| `ui.tooltip.font-size`              | 悬停提示框字号，默认 `1.1`，范围 `0.5–2`          |
| `wheel.center.x/y`                  | 转盘圆心坐标；省略时自动布局                       |
| `wheel.radius`                      | 转盘半径，默认 `128`                        |
| `wheel.hub-radius`                  | 中心盖半径，默认 `14`                        |
| `wheel.item-size`                   | 奖励图标最大尺寸，默认 `24`                     |
| `wheel.pointer-angle`               | 初始指针角度，默认 `-90`，即顶部                  |
| `wheel.pointer-color`               | 指针颜色                                 |
| `wheel.colors`                      | 按奖励顺序循环使用的扇区颜色，省略时使用内置配色             |
| `wheel.idle.enabled`                | 是否在待机时缓慢旋转盘面，默认 `true`               |
| `wheel.idle.degrees-per-second`     | 待机转速，默认每秒 `6` 度；正数顺时针，负数逆时针，`0` 静止   |
| `wheel.spin.duration`               | 抽奖动画时长，默认 `160` tick，范围 `60–1200`    |
| `wheel.spin.turns`                  | 抽奖动画至少旋转的圈数，默认 `5`，范围 `2–30`         |
| `wheel.render.step`                 | 曲线绘制步长，默认 `5`，范围 `2–12`；越小越精细，渲染开销越高 |

正常 20 TPS 下，20 tick 为 1 秒。两种运动模式在待机时都旋转盘面，抽奖时才按 `rotation-mode` 切换运动对象。历史页暂停待机旋转。

### 悬停效果与扇区边框

```yaml
wheel:
  hover:
    enabled: true
    scale: 1.08
    color: '#FFFFFF'
    border:
      enabled: false
      color: '#FF66CC'
  pointer-border:
    enabled: false
    color: '#3399FF'
```

`hover` 控制鼠标悬停时的高亮和放大，`scale` 范围为 `1–1.3`。悬停提示框显示奖励名称和 Lore；`show-rate: true` 时还会显示概率。抽奖期间暂停悬停效果。

`hover.border` 控制悬停扇区的边框。`pointer-border` 仅在 `rotation-mode: pointer` 时显示指针当前指向扇区的边框。两种边框默认关闭，重叠时优先显示悬停边框。

### 按钮位置

按钮默认排列在转盘右侧，按钮组与转盘圆心垂直居中。可以为每个按钮设置位置和大小：

```yaml
buttons:
  spin:
    name: '&a开始抽奖'
    lore:
      - '&7消耗：%price%'
      - '%click%'
    wheel:
      x: 430
      y: 110
      width: 160
      height: 30
```

坐标以逻辑画布左上角为原点，`x/y` 为按钮左上角。转盘、最后赏和按钮会作为整体水平居中，因此手动坐标主要用于调整元素之间的相对位置。

`spin`、`history`、`close` 分别用于抽奖、查看记录、关闭界面。其他名称的按钮可通过 `actions` 设置点击动作，格式见[格式说明](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/ji-ben-xin-xi/format.md)。

## 背景与配色

外观颜色支持 `'#RRGGBB'` 和 `'#AARRGGBB'`，后者前两位为透明度，`00` 完全透明，`FF` 完全不透明。YAML 中需要给颜色加引号。

```yaml
ui:
  theme:
    background-enabled: false
    background: '#182332'
    border: '#D6AB42'
    text: '#FFFFFF'
    title:
      background-enabled: true
      background: '#182332'
      decoration-enabled: true
    decorations:
      enabled: true
      page-enabled: false
      style: both
      color: '#5B5338'
      corner-color: '#D6AB42'
      thickness: 1
      corner-thickness: 2
      corner-length: 20
      inset: 10
      dividers-enabled: true
    button:
      background: '#354861'
      hover: '#4D789C'
      border: '#D6AB42'
      text: '#FFFFFF'
      text-align: center
      font-size: 1
    bevel:
      enabled: false
    tooltip:
      background: '#182332'
      border: '#D6AB42'
```

主页面背景默认关闭。标题背景、标题装饰和最后赏面板有各自的开关，关闭主页面背景不会隐藏它们。历史页始终使用 `ui.theme.background`。

`decorations.style` 可选 `frame`（边框）、`corners`（四角）、`both`（两者）或 `none`。`page-enabled` 控制主页面外框，`dividers-enabled` 控制历史页分隔线；`decorations.enabled: false` 关闭全部装饰。线宽范围为 `0.5–6`，角线宽度为 `0.5–8`，角线长度为 `0–80`，内边距为 `0–30`。

按钮文字支持 `left`、`center`、`right` 对齐，字号范围为 `0.5–1.5`。`bevel.enabled: true` 开启立体边缘，可在 `bevel` 下设置 `shadow`、`top`、`left`、`right`、`bottom` 颜色。基岩风格配置可参考 `wheels/bedrock.yml`。

## 最后赏面板

配置了 `last-reward` 后，最后赏默认显示在转盘左侧。可以单独调整位置、标签、背景、边框和呼吸动画：

```yaml
wheel:
  last-reward:
    x: 32
    y: 208
    label:
      enabled: true
      text: '&6最后赏'
      font-size: 0.8
    background-enabled: true
    background: '#182332'
    border:
      enabled: true
      color: '#D6AB42'
    animation:
      enabled: true
      mode: always
      scale: 1.12
      period: 40
```

`x/y` 为物品图标中心坐标。标签字号范围为 `0.6–1.2`；省略面板背景颜色时沿用 `ui.theme.background`。

动画默认开启。`mode: always` 持续播放，`mode: spinning` 仅在抽奖时播放；`scale` 为最大放大倍数，范围 `1–1.5`，`period` 为一次完整缩放循环的 tick 数，范围 `10–1200`。关闭动画后，物品仍以原始大小显示。

## 历史记录与物品数量

点击历史按钮可查看当前轮盘的抽奖记录，每页显示 18 个奖励，通过上一页、下一页按钮翻页，再点击返回按钮回到转盘。

奖励、最后赏和历史页中的物品数量大于 1 时，图标右下角会显示数量。角标表示展示物品的堆叠数量，指令奖励的发放数量由奖励动作决定。

## 常见问题

### 从背包 UI 改成轮盘，需要修改什么？

将配置复制到 `wheels/`，使用 `wheels/文件名` 打开，标题改为普通文字，并使用本页的 `wheel` 设置调整布局。奖励、价格、次数限制和自动重置等配置可以继续使用。

`gui.size`、`slots`、`frame`、`last-reward-slot`、`buttons.*.icons` 和 `buttons.*.slots` 属于背包界面设置，不用于轮盘布局。历史页使用轮盘标题并固定每页 18 项，不使用 `history-gui.title` 或 `history-gui.dynamic-size`。

### 轮盘无法打开怎么办？

检查 ArcMenu 是否已启用、轮盘 ID 是否带有 `wheels/`，以及玩家是否有对应权限。配置修改后执行 `/s2w reload`，并检查控制台中的配置错误。`sector-mode`、`rotation-mode` 等选项需要使用本页列出的值。

### 界面缺少纹理怎么办？

确认服务器资源包包含 ArcMenu 和 SpinToWin 的素材，并让玩家重新下载资源包。SpinToWin 的转盘素材位于 `plugins/SpinToWin/pack/`。

### 抽奖过程中玩家退出会怎样？

已经开始的抽奖会按选中的结果结算，玩家退出或插件重载不会重新抽取结果。
