槽位 / GUI / 延迟动作

槽位动作 slot.*

slot.set

把物品写入槽位。

slot.set("output", @input)                   # 把 @input 物品放到输出槽
slot.set("preview", "@input", "modified")    # 第 3 参数 "modified" = 使用修改后的物品

• 第 1 参数：目标槽位 ID（不是布局字符，也不是类型名）。
• 第 2 参数：来源物品（槽位引用、变量、item(...)）。
• 第 3 参数（可选）："modified" 等特殊标记，用于在预览场景中显式使用修改后的副本。

slot.clear

清空槽位内容。

slot.clear("input")
slot.clear("material")
slot.clear("food")                # 槽位组全部清空

slot.take

从槽位取出指定数量。

slot.take("material", 1)
slot.take("input", 5)

slot.lock / slot.unlock

锁定 / 解锁槽位。锁定后：

• 玩家不能点击拿取。
• 关闭 GUI 时不归还锁定槽位的物品（会随会话保存/销毁而处理）。

slot.lock("s1,s2,s3,confirm")       # 批量锁定（逗号分隔）
slot.unlock("s3,confirm")           # 批量解锁
slot.lock("confirm")                # 单个

GUI 动作 gui.*

gui.lock / gui.unlock

锁定整个 GUI，玩家按 ESC 无法关闭（会被拦截后 1 tick 自动重开）。

gui.lock()
// ... 动画代码 ...
gui.unlock()

配置 closeable: false vs gui.lock()

方式	何时锁定
closeable: false	整个生命周期默认锁定，脚本调 gui.unlock() 解锁
gui.lock()	按需动态锁定（动画开始前）

必须解锁

gui.lock() 后一定要在适当时机 gui.unlock()，否则玩家永远无法关闭 GUI。

delay 延迟动作

用于在脚本中创建延迟，实现动画等跨 tick 流程。

execute: |
  effect.message("&e准备中...")
  delay(20)                # 延迟 20 tick = 1 秒
  effect.message("&a执行!")

时间单位：1 秒 = 20 ticks。

delay(n)	实际时间
delay(1)	0.05 秒
delay(20)	1 秒
delay(40)	2 秒

delay 的执行模型

• delay 之后的代码异步执行，不阻塞服务端主线程。
• slot.set 会立即刷新 GUI 显示，不用额外 effect.refresh()。
• 玩家离线后 delay 仍然正常倒计时（后台模式）。

delay 在 if 块内的行为

# ✓ if 块内：delay 链式执行
if 条件 {
  slot.set("s1", 绿)
  delay(10)
  slot.set("s1", 灰)
  slot.set("s2", 绿)
}

# ⚠️ if 块"之后"的代码：立即执行，不等块内 delay
if 条件 {
  delay(20)
  // 块内这行会在 20 tick 后执行
}
// 这行会立即执行，不会等上面的 delay

结论：动画停止后的奖品发放应放在 if 块内部。

转盘动画模式

环形槽位用 output 类型，每个独立 ID；中间用 O 放结果。

# 布局
layout: |
  XXXXXXXXX
  X..123..X
  X..8O4..X
  X..765..X
  XXXXBXXXX

slots:
  '1': "output(id=s1, placeholder=STAINED_GLASS_PANE: )"
  '2': "output(id=s2, placeholder=STAINED_GLASS_PANE: )"
  # ... s3-s8 类似
  'O': "output(id=result, placeholder=NETHER_STAR:&e&l?)"
  'B': "button(id=spin, material=LIME_WOOL, name='&a开始')"

动画脚本（精简版）：

execute: |
  # 颜色标记
  灰 = item("mc:STAINED_GLASS_PANE:7")
  绿 = item("mc:STAINED_GLASS_PANE:5")
  黄 = item("mc:STAINED_GLASS_PANE:4")
  红 = item("mc:STAINED_GLASS_PANE:14")

  # 锁定所有环形槽位 + 按钮
  slot.lock("s1,s2,s3,s4,s5,s6,s7,s8,result,spin")
  gui.lock()       # 动画期间禁止玩家关闭

  # 初始化为灰
  slot.set("s1", 灰); slot.set("s2", 灰); // ... s3-s8

  # 快速阶段
  slot.set("s1", 绿)
  effect.sound("BLOCK_NOTE_BLOCK_HAT", 0.5, 1.5)
  delay(2)
  slot.set("s1", 灰); slot.set("s2", 绿)
  delay(2)
  # ... 转一圈回到 s1

  # 减速阶段：换黄，delay 越来越大
  slot.set("s1", 黄); delay(5)
  slot.set("s1", 灰); slot.set("s2", 黄); delay(7)
  # delay(10), delay(14) ...

  # 停下：变红 + 展示结果
  slot.set("s4", 红)
  delay(5)
  slot.set("result", 最终奖品)
  slot.set("s4", 最终奖品)
  effect.title("&6&l恭喜!", "&e获得奖品", 5, 60, 20)

  # 解锁：只解中奖槽位（关闭 GUI 时只归还解锁槽位）
  slot.unlock("result,spin")
  gui.unlock()

锁定与物品安全

锁定的展示槽物品不会在关闭 GUI 时归还玩家。这对转盘非常关键——不会因为关闭 GUI 把所有奖品一口气给玩家。 详见 会话与物品安全。

mc: 前缀的原版物品

item("mc:DIAMOND_SWORD")              # 原版物品
item("mc:STAINED_GLASS_PANE:5")       # 带数据值（1.12 染色玻璃板）
item("mc:WOOL:14")                    # 红色羊毛

动画最佳实践

• 动画总时长 3–5 秒左右，别让玩家等太久。
• 所有展示槽位都要 slot.lock，防止玩家点击。
• 颜色标记变量可复用（灰 = item(...) 后重复用）。
• 动画结束后再 slot.unlock 需要归还的槽位 + gui.unlock。
• 随机停止位置：用独立的 if 目标 == N { ... } 块，每块内部完成"剩余步数 + 奖品发放 + 解锁"的完整链路，详见 实战案例 - 转盘抽奖。