> 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/ji-ben-xin-xi/format.md).

# 📋配置格式

SpinToWin 的**物品格式（Item Format）**、**动作格式（Action Format）**、\*\*条件格式（Condition Format）**和**数学表达式格式（Math Calculation Format）\*\*与 UltimateShop 基本一致。

通用语法详见 [UltimateShop 格式文档](https://ultimateshop.superiormc.cn/format)。以下列出 SpinToWin 的差异。

## 动作

SpinToWin 不提供下列 UltimateShop 专属动作：

* `buy`
* `sell`
* `open-menu`
* `shop-menu`
* `connect`

## 动作与条件的通用选项

SpinToWin 不提供 UltimateShop 中 ActionFormat 和 ConditionFormat 的额外通用选项。不要将商品或菜单专用配置直接套用到转盘中。

## 动作与条件中的变量

| 变量               | 含义        |
| ---------------- | --------- |
| `{display}`      | 奖励物品显示名称  |
| `{price}`        | 抽奖价格      |
| `{times}`        | 指令奖励的执行次数 |
| `{player_x}`     | 玩家 X 坐标   |
| `{player_y}`     | 玩家 Y 坐标   |
| `{player_z}`     | 玩家 Z 坐标   |
| `{player_pitch}` | 玩家俯仰角     |
| `{player_yaw}`   | 玩家朝向角     |
| `{player}`       | 玩家名称      |

抽奖按钮和奖励 Lore 中的百分号变量见下文，与动作和条件中的花括号变量区分使用。

## 按钮、奖励与提示变量

| 变量          | 用途                        |
| ----------- | ------------------------- |
| `%price%`   | 抽奖价格显示文本，在抽奖按钮中使用         |
| `%click%`   | 抽奖按钮状态文本，如价格不足或可以抽奖       |
| `%uses%`    | 玩家已记录的当前 UI 使用次数，在抽奖按钮中使用 |
| `%times%`   | 当前 UI 对玩家的抽奖次数上限，在抽奖按钮中使用 |
| `%rate%`    | 奖励实际抽中概率，用于奖励附加 Lore      |
| `%display%` | 对应上下文中的物品显示名称             |
| `%amount%`  | 对应上下文中的物品或价格数量            |

`%click%`、默认价格格式等文本在[语言文件](https://spintowin.superiormc.cn/pages/ht8BFaH2hDDZXT0rIn9j#%E8%AF%AD%E8%A8%80%E6%96%87%E4%BB%B6)中设置。动作与条件中的花括号变量见上文。

## PlaceholderAPI

安装 PlaceholderAPI 及对应扩展后，可以使用其变量。例如：

```
/papi ecloud download Player
```

随后可在支持 PlaceholderAPI 的配置位置使用 `%player_name%` 表示玩家名称。

## 条件示例

### 世界

```yaml
1:
  type: world
  world: 'world'
```

玩家位于指定世界时满足。需要多个世界或组合判断时，请按通用条件格式组织条件，不再使用旧版 `world: World1;;World2` 字符串。

### 权限

```yaml
1:
  type: permission
  permission: 'group.vip'
```

玩家拥有指定权限时满足。多个权限应使用多个条件节点。

### PlaceholderAPI 变量

```yaml
1:
  type: placeholder
  placeholder: '%player_points%'
  rule: '>='
  value: '200'
```

`placeholder` 是比较左值，`rule` 是比较规则，`value` 是比较右值。

| 规则                    | 含义           |
| --------------------- | ------------ |
| `>=`、`>`、`=`、`<`、`<=` | 数值比较         |
| `==`、`!=`             | 字符串相等或不相等    |
| `*=`                  | 左侧字符串包含右侧字符串 |
| `=*`                  | 右侧字符串包含左侧字符串 |
| `!*=`、`!=*`           | 对应包含关系的否定    |

在价格中的放置方式见[价格配置](https://spintowin.superiormc.cn/pages/LKNeJuwsjksUvC14can0#%E4%BB%B7%E6%A0%BC%E6%9D%A1%E4%BB%B6)，动态权重中的放置方式见[奖励配置](https://spintowin.superiormc.cn/pages/mZ8ZCkRRb7HUOb0mcTRA#%E5%8A%A8%E6%80%81%E6%9D%83%E9%87%8D)。
