YAML 注意事项

ItemMaster 的配置本质是 YAML，脚本块是 YAML 的多行字符串。写配置时，最常见的故障都出在 YAML 解析层面：冒号被误识别为映射分隔符、引号不配对、特殊字符没转义。本页总结配置时最容易踩坑的几类问题。

1. 脚本块必须用 | 多行字符串

variables、init、conditions、execute、onchange 的每一项等都是脚本语法，不是 YAML 键值对。请使用 | 多行字符串：

# ✓ 正确
variables: |
  最大等级 = 10
  当前等级 = @input.counter('强化等级')
  成功率 = max(10, 100 - 当前等级 * 5)

# ❌ 错误：把脚本写成 YAML 键值对
variables:
  最大等级: 10
  当前等级: "@input.counter('强化等级')"

脚本语法的特点：

• 用 = 赋值（不是 :）。
• 每行一个语句，不需要引号包围。
• 支持 // 注释。
• 支持 if、for、switch、chance、with 等流程控制。
• variables 中可以用 slot.set(...) 动态更新槽位，但不要用 effect.message(...)（会随每次刷新重复触发）。

2. 槽位定义带冒号时的引号嵌套

当槽位定义中的 lore、name、placeholder 等参数包含冒号 : 时，YAML 会误认为这是映射分隔符，抛出 mapping values are not allowed here。

slots:
  # ❌ 错误：lore 中的冒号导致 YAML 解析失败
  信: display(id=信息, material=BOOK, name="&e信息", lore="&7状态: 待机|&7等级: 1")

正确的引号嵌套规则：

外层引号	内层字符串	表达式内字符串	示例
单引号 '...'	双引号 "..."	两个单引号 ''	'input(id=x, match="lore.contains(''关键词'')")'
双引号 "..."	单引号 '...'	单引号 '...'	"button(id=x, name='&c按钮', lore='&7说明')"

slots:
  # ✓ 外层单引号，内层双引号
  '信': 'display(id=信息, material=BOOK, name="&e信息", lore="&7状态: 待机|&7等级: 1")'

  # ✓ 外层双引号，内层单引号
  '火': "button(id=开始, material=MAGMA_CREAM, name='&c&l点火', lore='&7点击开始|&7冷却: 10秒')"

  # ✓ match 表达式里需要字符串字面量时，用两个单引号 '' 转义
  'A': 'input(id=材料1, match="lore.contains(''丹材'')")'

TIP

中文字符键（如 信、火、丹）也建议统一用单引号包起来，避免某些 YAML 解析器的兼容问题。

3. 纯数字键必须加引号

布局字符如果是纯数字，slots 里的键会被 YAML 解析成整数：

layout: |
  .........
  .1.2.3...
  .........

slots:
  # ❌ 错误：键会被解析为 int 1，完全对不上布局里的 '1'
  1: toggle(id=锁1, toggleid=lock1, on=LIME_DYE, off=GRAY_DYE)

  # ✓ 正确
  "1": toggle(id=锁1, toggleid=lock1, on=LIME_DYE, off=GRAY_DYE)

4. 值包含 # 号时的陷阱

YAML 把 # 后的内容当作注释，如果你的显示名、Lore 里有 #（例如用 §#RRGGBB 十六进制颜色），必须用引号包住整个值：

slots:
  # ❌ 错误："等级 #1" 会被截断成 "等级 "
  D: display(id=info, name="等级 #1")

  # ✓ 正确
  D: "display(id=info, name=\"等级 #1\")"

5. 槽位定义中的参数必须用字符串

match、placeholder 等参数值是纯字符串，不要把脚本语法混进去：

slots:
  # ❌ 错误：match 没加引号
  I: input(id=input, match=lore.contains('可强化'))

  # ✓ 正确
  I: input(id=input, match="lore.contains('可强化')")

6. 流程控制必须多行写

IM 脚本引擎不支持单行 if：

execute: |
  # ❌ 错误：单行 if 会导致块内代码不执行，变量赋值静默失败
  if @input.filled { 数量 += 1 }

  # ✓ 正确：必须换行
  if @input.filled {
    数量 += 1
  }

  # ✓ else if / else 同样必须多行
  if a == 1 {
    x = 10
  } else if a == 2 {
    x = 20
  } else {
    x = 30
  }

同样适用于 for、chance、with、switch、try/catch。

7. 多行 Lore 在槽位定义里用 |

槽位定义的 lore 参数是单行字符串，但可以用 | 分隔多行：

slots:
  D: decoration(id=说明, material=PAPER, name="&e说明", lore="&7第一行|&7第二行|&7第三行")

如果想写成纯 YAML 多行，建议把说明写到 display/decoration 的 lore 里，并把整个槽位定义用外层引号包起来。

8. 颜色码的常见写法

• &0–&9、&a–&f：十六种标准颜色。
• &l 粗体、&o 斜体、&n 下划线、&m 删除线、&k 混淆、&r 重置。
• §#RRGGBB 或 &#RRGGBB：十六进制 RGB（1.16+ 服务端）。

注意 # 和前文提到的注释陷阱，包含十六进制颜色的值都应该用引号包起来。

9. Lore / 名称插值的引号

effect.message、name.set、lore.append 等动作的字符串参数里可以使用 {变量} 插值。插值语法和 YAML 引号是两回事：

execute: |
  effect.message("&a强化成功！等级: {当前等级}")        # ✓ 在 YAML 的 | 字符串内，双引号是脚本字符串
  装备.name.set("&6{原名} +{新等级}")

插值适用位置：所有接受字符串的动作参数。不要在匹配表达式里用 {}（匹配表达式直接写变量名即可）。

下一步：回到 顶级字段 或继续 匹配系统。