> ## Documentation Index
> Fetch the complete documentation index at: https://guide.moyostory.com/llms.txt
> Use this file to discover all available pages before exploring further.
# State 变量、Frame 变量与媒体绑定
> 区分跨页面状态与当前帧数据，并把背景、立绘和音频绑定到变量值。
点击编辑器顶部“变量配置”，左侧显示 State 变量，右侧显示按模板归类的 Frame 变量。
## State 与 Frame 的区别
| | State 变量 | Frame 变量 |
| ------ | ------------------- | --------------------------- |
| 保存时间 | 随作品运行状态在页面节点之间保留 | 记录当前帧需要显示或处理的数据 |
| 适合内容 | 好感度、玩家姓名、已获得线索、选择路线 | 当前台词、说话人、背景、立绘、这一帧的选项 |
| 在哪里创建 | 变量配置左侧手动添加 | 模板中的触发器规则写入 `frame.x` 后自动汇总 |
| 媒体绑定范围 | 整个作品共用 | 只属于产生该变量的模板 |
例如，`selected_route` 记录玩家选择了哪条调查路线，两个 AI 页面都能读取。`frame.portrait` 只表示当前帧显示哪张立绘。
## 添加 State 变量
点击“+ 添加 State 变量”，填写：
* 变量名；
* 类型：字符串、数字、布尔值、对象或数组；
* 默认值；
* 描述。
对象和数组的默认值使用有效 JSON。变量名在作品中保持唯一。触发器规则、上下文条件和页面代码都会按名称引用它。
### 内置变量
界面会显示由运行时提供的内置变量。内置变量不能编辑、删除或联动素材库，只能设置调试值检查预览状态。
### 调试值
点击变量卡片上的铅笔可以设置调试值。调试值只影响当前编辑器会话中的作品实时预览：
* 不进入“保存作品”；
* 不写入玩家存档；
* 刷新页面或切换作品后清空。
## Frame 变量从哪里出现
Frame 变量不能在变量配置中手动新建。模板的触发器规则只要写入 `frame.background`、`frame.text` 等目标，变量配置右侧就会在该模板下列出这些字段。
```mermaid theme={null}
flowchart LR
A[模板触发器规则
写入 frame.portrait] --> B[变量配置
出现 frame.portrait]
B --> C[绑定立绘素材]
C --> D[模板页面代码
显示当前立绘]
```
删除或改名规则中的写入目标后，回到变量配置检查对应的 Frame 变量和媒体绑定。
## 把变量联动素材库
上传文件后，点击变量卡片上的“联动素材库”。选择可能出现的素材，并配置：
* 默认素材；
* 每个素材对应的变量值或生效条件；
* 多个素材的匹配顺序。
运行时，页面代码读取变量：
```text theme={null}
frame.portrait = 沈砚_认真
```
媒体绑定找到条件值“沈砚\_认真”，把对应立绘地址交给页面代码。
### 默认素材
变量为空或没有命中具体条件时，编辑器使用默认素材。角色暂时不显示时，可以把取值“无”加入指令约束；运行时会把它作为透明素材处理。
### State 和 Frame 的绑定位置
* State 变量的媒体绑定位于 State 变量卡片，整个作品共用。
* Frame 变量的媒体绑定位于右侧对应模板下，只影响使用该模板的页面。
同名 Frame 变量出现在不同模板中时，需要分别配置。
新模板第一次保存前不能配置 Frame 媒体绑定。先保存模板，再回到“变量配置”联动素材库。
## 保存
新增、编辑、重命名和删除 State 变量会进入变量标签草稿。媒体绑定的默认素材、条件和顺序也会进入草稿。
点击顶部“保存作品”或关闭变量标签时选择“保存并关闭”，提交变量和媒体绑定。保存失败后，橙色圆点会保留。
## 素材没有显示时
1. 在素材库确认文件仍存在。
2. 在变量配置确认变量显示“已联动素材库”。
3. 检查指令填写值与媒体条件完全一致。
4. 检查触发器规则是否把参数写入正确的 State 或 Frame 变量。
5. 检查页面代码读取的变量名。
MoMo：上传文件、写入变量、联动素材库、页面代码读取变量，四个位置缺一处，媒体都不会出现。