State 变量、Frame 变量与媒体绑定

点击编辑器顶部“变量配置”，左侧显示 State 变量，右侧显示按模板归类的 Frame 变量。

State 与 Frame 的区别

例如，selected_route 记录玩家选择了哪条调查路线，两个 AI 页面都能读取。frame.portrait 只表示当前帧显示哪张立绘。

点击“+ 添加 State 变量”，填写：

对象和数组的默认值使用有效 JSON。变量名在作品中保持唯一。触发器规则、上下文条件和页面代码都会按名称引用它。

界面会显示由运行时提供的内置变量。内置变量不能编辑、删除或联动素材库，只能设置调试值检查预览状态。

点击变量卡片上的铅笔可以设置调试值。调试值只影响当前编辑器会话中的作品实时预览：

Frame 变量不能在变量配置中手动新建。模板的触发器规则只要写入 frame.background、frame.text 等目标，变量配置右侧就会在该模板下列出这些字段。删除或改名规则中的写入目标后，回到变量配置检查对应的 Frame 变量和媒体绑定。

上传文件后，点击变量卡片上的“联动素材库”。选择可能出现的素材，并配置：

素材库界面显示的“素材名称”在数据中就是可读的素材 ID。运行时，变量保存这个 ID，而不是文件 URL：

frame.portrait = 沈砚_认真

页面代码先直接读取这个字段，再用 media_url() 取得浏览器可以加载的地址：

const portraitUrl = frame.portrait ? media_url(frame.portrait) : ""

return portraitUrl ? <img src={portraitUrl} alt="" /> : null

State 媒体变量使用同一写法，例如 media_url(state.player_avatar)。media_url 的参数必须是直接的 frame.x 或 state.x 字段，不能另写一个素材 ID 字符串，也不能先拼接表达式。完整代码规则见页面代码：数据、素材与交互。

变量为空或没有精确匹配到素材 ID 时，编辑器使用配置的默认素材。某种状态不应显示素材时，可以让变量使用约定值“无”，并由页面代码在调用 media_url() 前判断这个值：

const portraitUrl = frame.portrait && frame.portrait !== "无"
  ? media_url(frame.portrait)
  : ""

“无”不是一张透明图片。页面代码应直接隐藏对应元素。

同名 Frame 变量出现在不同模板中时，需要分别配置。

新模板第一次保存前不能配置 Frame 媒体绑定。先保存模板，再回到“变量配置”联动素材库。

新增、编辑、重命名和删除 State 变量会进入变量标签草稿。媒体绑定的默认素材、条件和顺序也会进入草稿。点击顶部“保存作品”或关闭变量标签时选择“保存并关闭”，提交变量和媒体绑定。保存失败后，橙色圆点会保留。

MoMo：先看变量里的素材 ID，再看素材绑定，最后看 media_url()。三处必须使用同一个变量。