> 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/jiang-li-lun-zhuan.md).

# 🔄奖励轮转与抽奖动画

当前开发版支持在奖励数量超过展示槽位数量时，循环展示整个奖池。无需新增配置项，已有 UI 配置可以继续使用。相关选项见 [UI 配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi.md)，奖励物品和权重见 [奖励配置](https://spintowin.superiormc.cn/jian-ti-zhong-wen-2/zhuan-pan-ui/ui-pei-zhi/jiang-li-pei-zhi.md)。

## 启用条件

展示槽位由 UI 配置中的 `slots` 决定。默认 UI 有 14 个展示槽位，但程序并没有将数量固定为 14。

```yaml
slots: [9,10,11,12,13,22,31,40,39,38,37,36,27,18]
```

当奖励展示列表的数量大于 `slots` 的数量时，自动启用奖励轮转；否则奖励保持静止，沿用原来的指针抽奖动画。

奖励按数字编号排序。`rewards` 的编号需要从 `1` 开始连续递增，例如 `1` 到 `20`。

## 打开 UI 后的展示

以 20 个奖励、14 个展示槽位为例：

1. 刚打开 UI 时显示奖励 `1～14`。
2. 每隔 40 tick 移动一格，依次显示 `2～15`、`3～16`，直到奖池末尾后循环。
3. 跨过末尾时可以显示 `20、1～13`，因此玩家无需抽奖即可查看整个奖池。

在正常 20 TPS 下，40 tick 为 2 秒。待机时不播放抽奖移动音效。

指针沿 `slots` 的列表顺序前进，奖励沿相反方向轮转。在默认布局中，指针顺时针，奖励逆时针；自定义布局的实际方向取决于 `slots` 的排列顺序。

## 点击抽奖后的动画

抽奖开始时，停止待机轮转，并根据整个可抽奖池的权重确定中奖奖励。奖励是否正在展示，不影响它参与抽奖。

奖励与指针使用共同节拍反向旋转，动画分为三个阶段：

| 阶段 | 节奏                        |
| -- | ------------------------- |
| 起步 | 移动间隔从 6 tick 逐步缩短到 1 tick |
| 中段 | 保持每 1 tick 一个节拍           |
| 收尾 | 移动间隔逐步延长，最后达到 16 tick     |

正常 20 TPS 下，6 tick、1 tick、16 tick 分别约为 0.3 秒、0.05 秒、0.8 秒。这些时间表示指针移动节拍，奖励按照各自需要完成的步数分配到相同节拍中；双方总步数可以不同。

双方最后一步安排在同一个 tick，结束时中奖奖励正好位于指针对应的槽位。即使中奖奖励起初在展示区域之外，也会通过轮转进入展示区域，不需要先停住奖励，再让指针追过去。

上述节奏是当前程序内置的行为，没有新增动画速度配置项。

## 已领取奖励与重复抽奖

`reserve: false` 时，已领取奖励不再参与后续抽奖：

* 配置了 `replace`：已领取奖励会变为替代物品，替代物品仍占据展示列表位置，并参与展示轮转。例如原来有 20 个奖励，即使剩余可抽奖励不足 14 个，仍可能继续轮转。
* 未配置 `replace`：已领取奖励从展示列表移除。剩余展示数量不超过槽位数量后，奖励停止轮转。

`reserve: true` 时，奖励保留在奖池中，可以重复抽取；超过展示槽位数量的奖励也会保留并参与轮转。

抽奖结束后，UI 按现有流程重新生成，展示窗口从新的展示列表开头开始，不保留之前的轮转偏移。关闭 UI 或切换到历史界面时，停止当前界面的待机轮转任务。

## 抽奖次数与最后赏

超过展示槽位数量的奖池按完整可抽奖池计算剩余奖励，避免将隐藏奖励误当作已经抽完。

对于 `reserve: false` 的 20 奖励、14 槽位奖池，第一次抽奖为第 1 次。未显式配置最后赏次数时，默认次数取初始奖励数量与槽位数量中的较大值，因此此例默认在第 20 次触发最后赏。

可以继续显式指定最后赏次数；最后赏本身及其展示槽位也需要配置：

```yaml
last-reward-slot: 16
last-reward-times: 20
last-reward:
  material: NETHER_STAR
  amount: 1
  name: "&6最后赏"
```

## 测试方法

复制默认的 `ui/example.yml`，改名为 `rotation_test_20.yml`。保留原有的 14 个展示槽位，在 `rewards` 下保留 `1～14`，并增加连续编号的 `15～20`。给这些奖励使用不同的物品或名称，方便核对展示和落点。

为了连续免费测试，可以将该测试 UI 的整个 `prices` 节点替换为：

```yaml
prices:
  1:
    free: true
    amount: 0
    start-apply: 1
    placeholder: "&a免费"
```

将测试配置放在服务器的 `plugins/SpinToWin/ui/` 目录中，然后执行：

```
/s2w reload
/s2w open rotation_test_20
```

建议检查以下行为：

* 不点击抽奖，等待数次待机轮转，确认最初未展示的奖励也能看到。
* 在不同的待机轮转位置开始抽奖，观察中段加速与收尾减速，以及奖励和指针的同步停止。
* 核对指针停靠的奖励与实际发放的奖励是否一致。
* 连续抽取，检查替代物品或奖励移除行为，以及最后赏是否在设定次数触发。
* 关闭界面后重新打开，确认展示正常且没有叠加的待机轮转任务。

需要清除本轮领取记录并重新测试时，执行：

```
/s2w reset rotation_test_20
```

更新 UI 配置可以使用 `/s2w reload`。更新包含动画代码的插件 JAR 后，需要重启服务器，配置重载不会加载新的 Java 代码。
