This guide will take you through creating your own live wallpapers with GameMaker. You can also follow the video version.
|Live Wallpapers are supported on Windows and GX.games.|
You will need this to get started:
- Download and install the latest GameMaker build.
- (For Windows) Download and install the latest Live Wallpaper Companion app.
Open GameMaker, click on New, and choose the Live Wallpaper project type.
Either select Blank Live Wallpaper, or choose any of the given templates to modify.
Blank Live Wallpaper contains a basic template for you to create a wallpaper with.
The obj_camera object contains three scaling modes you can choose from:
- NO_SCALE: The wallpaper only shows as much as the display allows.
- SCALE: The wallpaper is shown completely, with it scaling to the display.
- STRETCH: Same as before, but the aspect ratio is not maintained.
You can change the mode used in the Create event of the camera object, by changing the value of the scale_mode variable.
The wallpaper (i.e. the GameMaker runner) interacts with the companion app or Opera GX to (1) send and (2) receive settings:
- On launch, it sends the wallpaper’s settings configuration to the app, so the app can display the settings with their default values.
- Whenever a setting is changed in the app, the runner (wallpaper) is notified via an event. This event contains the updated values of the settings.
On launch, call the wallpaper_set_config() function to send your settings configuration to the companion app.
Use the Wallpaper Config Event in an object and write code to listen to settings updates and update your wallpaper properties accordingly.
Mouse input is disabled by default for live wallpapers. Call wallpaper_set_subscriptions(["desktop_mouse"]) to subscribe to enable mouse input, and optionally subscribe to various system metrics (the Companion app is required for metrics to work, and currently metrics are only supported on Windows).
Running A Live Wallpaper
On the GX.games target
You can quickly test your wallpaper on the GX.games target:
- Set GX.games as the platform:
- Run the project.
- Click the Toggle configurator option at the bottom of the page:
- You can now modify your wallpaper configuration:
On the Windows target
Here’s how you can run a Live Wallpaper on Windows:
- Start the companion app if it's not running already.
- In GameMaker, run your project once using the Windows/Test target, and close it.
- In the companion app menu (click its icon in the system tray), under Wallpapers, choose your wallpaper's project:
- To display the wallpaper's config and make changes to it, select Active wallpaper: <wallpaper_name> -> Configure parameters.
How to Publish a Live Wallpaper
In GameMaker, select the GX.games target and click on Create Executable.
When asked, choose "Upload as Live Wallpaper Mod".
Once it is uploaded, your wallpaper mod will be editable on GX.create, where you can provide all necessary details and publish it.
Important: Users who install your Live Wallpaper through Opera GX automatically get it on Windows, as long as they have the Companion app installed.
Here is an example:
var _config =
label: "Rotation speed",
label: "Clockwise rotation",
label: "Pause animation",
label: "Blend colour",
label: "Blend alpha",
This produces the following in the companion app:
Wallpaper Config Event
This event runs whenever a setting for the wallpaper is changed in the companion app.
You get the updated wallpaper settings in the wallpaper_config variable.
This variable is a struct containing your sections. Each section is a struct containing the options within that section.
To access an option from this struct, you would use this syntax:
Or, when using nested sections:
Here is an example using the same settings as defined in the previous section:
var _new_colour = wallpaper_config.colours.blendColor;
obj_clock.colour = _new_colour;
It’s recommended to make sure your wallpaper adapts to the resolution of the screen. Having a fixed size is not recommended, as it will not look good on most displays.
A cleaner way to get a dynamic view without modifying the room size is to use cameras. Ensure your camera changes its size to match the size of the display, using the aforementioned functions. If you use the Live Wallpaper Template project, it will take care of this for you.
Anything you draw in code should use percentages of the display size. For example, instead of drawing something at strictly 640px because your default width is 1280px, draw it at 0.5 times the display width. This will ensure that the item is centered no matter the size of the display.
// Not recommended
var _align = draw_get_halign();
draw_text(640, 360, "Wallpaper Text");
var _w = display_get_width();
var _h = display_get_height();
var _align = draw_get_halign();
draw_text(_w/2, _h/2, "Wallpaper Text");