SceneScript Event update

The update event function is will be called every frame for all scripts that export it. This makes it an incredibly useful tool for adjusting wallpaper elements in real-time.

However, this also means it must be used with caution. Since it is executed every frame, always try to avoid placing logic in this function unless there is no better place for it, look for more fitting events first.

For example, if you want to change something about your wallpaper when a user resizes their window, you should put this logic into the resizeScreen event instead so that your code is only executed when it is really needed.

export function update(value) {
    // The initial value of the property this script is assigned to.
    return value;
}

The function parameter value is the current value of the property that you have assigned this script to. The type of value also depends on the property of the script.

Wallpaper Engine will attempt to convert any numeric return values to Vec2 and Vec3 if you are working on a property that expects these return types. For example, if you return 2 on the Scale property, Wallpaper Engine will first convert the value to Vec3(2, 2, 2) so that it matches the return type the Scale property expects.

You can choose to not return any value, then the property will not be modified.

Note on Frametime

Since the update() function gets called each frame, it gets called more often for users with a high FPS limit in the Wallpaper Engine settings. If you animate anything in the update() function, make sure to use engine.frametime to normalize the speed of your animation across all FPS settings. If you do not use engine.frametime, the speed of your animation will increase with higher FPS settings in Wallpaper Engine.

For example, if you want to move an object upwards, use engine.frametime as a reference and multiply it with a factor to increase the speed of the animation. In the following example, we hard-coded 100 as a factor but you would change this to match the desired animation speed:

export function update(value) {
    value.y += engine.frametime * 100;
    return value;
}