效果动作（effect.*）

effect.* 负责对玩家/世界产生副作用：消息、音效、标题、粒子、药水、命令、GUI 跳转。它们不修改物品，也不走链式调用。

消息类

effect.message

向当前玩家发送聊天消息，支持颜色码和 {} 插值。

effect.message("&a强化成功！等级提升至 {新等级}")
effect.message("&c强化失败，装备已损坏")

调试物品

effect.message("{物品变量}") 对 ItemStack 显示的是物品描述摘要，不包含完整 Lore。要逐行打印 Lore：

for i in 0..list_size(装备.lore)-1 {
  effect.message("Lore[{i}]: " + list_get(装备.lore, i))
}

effect.actionbar

在玩家屏幕下方显示动作栏消息（不进入聊天记录）。

effect.actionbar("&e正在强化中...")

effect.title

显示标题。

effect.title("&6强化成功", "&7等级: {等级}")
effect.title("主标题", "副标题", 10, 70, 20)   # fadeIn, stay, fadeOut（ticks）

参数	默认值	说明
title	—	主标题
subtitle	—	副标题
fadeIn	10	淡入时间（ticks）
stay	70	停留时间
fadeOut	20	淡出时间

感官类

effect.sound

播放音效。

effect.sound("ENTITY_PLAYER_LEVELUP")
effect.sound("BLOCK_ANVIL_USE", 1.0, 1.0)              # volume, pitch
effect.sound("ENTITY_EXPERIENCE_ORB_PICKUP", 0.5, 1.5) # 小音量、高音调

effect.sound(sound, volume, pitch)。volume 默认 1.0，pitch 默认 1.0。

effect.particle

播放粒子。

effect.particle("VILLAGER_HAPPY")
effect.particle("FLAME", 20, 0.5, 0.5, 0.5)  # count, offsetX, offsetY, offsetZ

参数	默认	说明
particle	VILLAGER_HAPPY	粒子类型
count	10	数量
offsetX/Y/Z	0.3	偏移范围

effect.potion

给玩家施加药水效果。

effect.potion("SPEED", 200, 1)                    # 效果, 时长(tick), 等级
effect.potion("REGENERATION", 100, 2)
effect.potion("STRENGTH", 400, 0, false, true)    # ambient, particles

参数	默认	说明
effect	—	效果 ID
duration	200	持续时间（ticks，20 ticks = 1 秒）
amplifier	0	等级（0=I 级，1=II 级）
ambient	false	是否为环境效果
particles	true	是否显示粒子

命令类

effect.command

以玩家身份执行命令。

effect.command("spawn")
effect.command("pay {target} 100")

effect.console

以控制台身份执行命令。

effect.console("give {player.name} diamond 1")
effect.console("broadcast &a{player.name} 强化成功!")

玩家离线时静默失败

effect.command 在玩家离线时不会报错，但也不会执行。要保证离线也能执行，用 effect.console 并在命令里指定目标。

GUI 控制类

effect.close

关闭当前 GUI。

effect.close()

effect.refresh

刷新当前 GUI（重新执行 variables 并渲染）。

effect.refresh()

slot.set 会自动刷新显示，一般不需要手动调用 effect.refresh。

effect.open

打开另一个 GUI，支持物品传递。GUI 会在下一 tick 打开（避免事件冲突），打开前会自动关闭当前 GUI。

effect.open("guiId")
effect.open("guiId", "物品来源")
effect.open("guiId", "物品来源", "目标槽位")
effect.open("guiId", "物品来源", "", "目标变量")
effect.open("guiId", "物品来源", "目标槽位", "目标变量")

参数	说明
gui	要打开的 GUI ID（必填）
item	物品来源："@input"（从槽位）或变量名
targetSlot	物品放入新 GUI 的槽位 ID
targetVar	物品存入新 GUI 的变量名

# 基本
effect.open("enhance_gui")

# 把 @input 传到新 GUI 的 match="@this" 槽位
effect.open("confirm_gui", "@input")

# 指定槽位
effect.open("confirm_gui", "@input", "weapon")

# 传到变量（第 3 参数留空）
effect.open("confirm_gui", "@input", "", "passedItem")

# 同时指定槽位和变量
effect.open("confirm_gui", "@input", "weapon", "backupItem")

# 从变量传递
myItem = @input
effect.open("confirm_gui", "myItem", "material")

玩家离线时的行为

以下 effect.* 动作在玩家离线后静默失败（后台会话仍会运行，但这些操作不生效）：

• effect.message / effect.actionbar / effect.title
• effect.sound / effect.particle / effect.potion
• effect.command（以玩家身份执行）
• effect.open / effect.close

继续正常执行的只有 effect.console（控制台命令）。

如果逻辑需要在玩家离线后也可靠执行（例如定时完成的制造系统），把关键命令放到 effect.console 里，并通过时间戳判断完成状态。详见 会话与物品安全。