# 最常见能做什么

• 飘字
• 移入高亮
• 受击抖动
• 按钮发光
• 跟手提示
• 局部遮罩

# 1. 最常用的 3 个方法

方法	用途
tools.runClientEffect(script, options?)	启动一个画面特效
tools.disposeClientEffect(label)	按 label 结束一个特效
tools.clearClientEffects()	清空当前页面全部特效

# 2. 最重要的理解：有外层脚本和内层脚本

你平时在编辑器里写的，是外层脚本：

tools.runClientEffect("...");

真正负责演出的，是传进去的那段字符串脚本：

tools.runClientEffect(`
  const current = api.getTarget();
  if (!current) return;
`);

这两层不是一回事。

# 外层脚本里常用什么

• player
• objects
• tools

# 内层特效脚本里常用什么

• api
• payload
• target
• targets
• session
• pointer

# 3. 最简单的启动方式

tools.runClientEffect(`
  const current = api.getTarget();
  if (!current) return;

  current.setStyle({
    outline: "2px solid rgba(255,255,255,0.65)"
  });
`, {
  target: "攻击按钮",
  label: "attack-highlight"
});

# 4. options 里最常用的字段

字段	用途
payload	传数据给特效脚本
target	指定一个目标控件
targets	指定多个目标控件
waitMs	特效结束后额外保留多久
label	给这个特效起一个稳定名字

# 5. target 可以怎么写

# 直接传控件 ID

tools.runClientEffect(script, {
  target: "攻击按钮"
});

# 传对象控件目标

tools.runClientEffect(script, {
  target: { itemId: "装备按钮", objectId: "对象ID" }
});

# 传多个目标

tools.runClientEffect(script, {
  targets: ["主按钮", "副按钮"]
});

# 6. 最常见的几种效果

# 飘字

tools.runClientEffect(`
  api.createText(payload.text || "-10", {
    style: {
      color: "#fff",
      fontSize: "18px",
      textShadow: "0 2px 8px rgba(0,0,0,0.45)"
    }
  }).place({
    target: api.getTarget(),
    offsetY: -20
  });
`, {
  payload: { text: "-10" },
  target: "攻击按钮",
  label: "damage-float"
});

# 高亮

tools.runClientEffect(`
  const current = api.getTarget();
  if (!current) return;

  current.setStyle({
    filter: "brightness(1.15)"
  });
`, {
  target: "主按钮",
  label: "btn-highlight"
});

# 清掉效果

tools.disposeClientEffect("btn-highlight");

# 7. label 为什么重要

如果没有稳定的 label：

• 同类效果容易越叠越多
• hover、move 一类高频效果会越来越乱
• 很难在离开时准确清掉

所以只要是会重复出现的效果，通常都会给一个稳定的 label。

# 8. pointer 只在特效脚本内部可用

如果你要做跟手提示、鼠标附近提示，坐标要在内层特效脚本里拿：

tools.runClientEffect(`
  api.createText("查看详情").place({
    x: pointer?.clientX || 0,
    y: pointer?.clientY || 0,
    offsetX: 12,
    offsetY: 12
  });
`, {
  label: "pointer-tip"
});

pointer 这个变量会在内层特效脚本里使用。

# 9. 这类内容通常不放在特效系统里

下面这些内容更常写在普通脚本、事件或 AI 联动里：

• 扣金币
• 改属性
• 创建对象
• 推进主线
• 决定 AI 能不能输入

一个简单判断方法是：

如果把这段效果删掉，真实状态还是对的，只是看起来没那么明显，那它就很适合放在特效系统里。

# 使用时要注意的几件事

• runClientEffect 的第一个参数必须是一段字符串脚本。
• 第二个参数如果传，必须是对象。
• 内层特效脚本只能使用注入的 api、payload、target、targets、runtime、session、pointer；运行时会遮蔽 window、document、localStorage、fetch、postMessage 等浏览器能力，但不额外拦截普通 JavaScript 写法。
• 跟手、hover 这类高频效果一定要重视 label。
• 特效系统更适合做视觉反馈，核心状态仍然放在属性、事件或别的脚本里。

# 下一步

如果你准备把声音也做成前端脚本，可以继续看 客户端音效系统。
如果你准备把特效挂到控件移入、移出、移动上，可以继续看 交互特效脚本。