SceneScript——为壁纸元素编写自定义逻辑

什么时候需要 SceneScript

场景编辑器的可视化轨道动画能覆盖大部分效果，但以下场景需要 SceneScript：

让元素响应音频分析数据（可视化频谱驱动元素参数）
让元素跟踪鼠标光标（高级交互）
基于时间或外部事件触发复杂状态切换
多个元素之间的联动逻辑

SceneScript 是什么

SceneScript 是 Wallpaper Engine 编辑器内置的类 C# 脚本语言。它直接嵌入在场景的元素属性里，通过回调函数驱动元素参数变化。

// SceneScript 示例：让物体 Y 轴随时间循环移动
void UpdateTime(float time) {
    _Surface.Binding = "Material";
    _Surface.InputName = "OffsetY";
    _Surface.Value = sin(time * 2) * 0.5;
}

脚本挂载方式

在编辑器中选中要绑定的元素（通常是一个带材质的贴图）
在属性面板找到材质参数（如 OffsetY）
点击参数右侧的 SceneScript 按钮，进入脚本编辑器
写入回调函数，保存即可生效

常用回调函数

函数	触发时机	典型用途
`UpdateTime(float time)`	每帧渲染	基于时间的持续动画
`UpdateAudio(float[] bands)`	每帧音频分析完成	让元素响应音乐
`Initialize()`	场景加载时	初始化变量、一次性设置
`Vector2 OnMouseMove(Vector2 pos)`	鼠标移动	让元素跟随鼠标

访问用户属性

如果壁纸暴露了用户可调的自定义属性（如颜色、速度开关），SceneScript 可以读取它们：

float speed = properties.MyCustomSlider; // 读取用户滑块值

这样就能让创作者写的逻辑由最终用户控制——比如「开/关粒子效果」「调运动速度」。

官方文档位置

完整的 SceneScript API 参考在官方创作文档 docs.wallpaperengine.io 的 Scene 板块。编辑器内置了 API 自动补全提示，不用担心记不住所有参数名。