This guide will take you through creating your own live wallpapers with GameMaker.
| Live Wallpapers are supported on Windows and GX.games. |
Basic Setup
You will need this to get started:
- Download and install the latest GameMaker build.
- Create a GameMaker project, or try this sample project.
- (For Windows) Download and install the latest Live Wallpaper Companion app.
On creating a new project, you can choose the Live Wallpaper template project, which contains code for scaling your wallpaper on different displays.
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.
Overview
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.
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 (Create Executable).
- Click the Toggle config 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 create.gx.games, where you can provide all necessary details and publish it.
Users who install your Live Wallpaper through Opera GX automatically get it on Windows inside the companion app.
wallpaper_set_config(settings_array)
This function sends the settings for your wallpaper to the companion app. It takes an array containing your options/sections, where each option/section is a struct.
Here is an example:
var _config =
[
{
type: "section",
name: "animation",
label: "Animation",
children:
[
{
type: "range",
name: "speed",
label: "Rotation speed",
value: 50,
min: 0,
max: 200,
step: 25
},
{
type: "boolean",
name: "clockwiseRotation",
label: "Clockwise rotation",
value: false
},
{
type: "boolean",
name: "pause",
label: "Pause animation",
value: true
}
]
},
{
type: "section",
name: "colours",
label: "Colours",
children:
[
{
type: "colour",
name: "blendColor",
label: "Blend colour",
value: c_white
},
{
type: "range",
name: "blendAlpha",
label: "Blend alpha",
value: 100
}
]
}
];
wallpaper_set_config(_config);
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:
wallpaper_config.section_name.option_name
Or, when using nested sections:
wallpaper_config.section1_name.section2_name.option_name
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;
Resolution Management
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.
Instead of using a fixed room size, you can change it depending on the result of display_get_width() and display_get_height().
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_set_halign(fa_center);
draw_text(640, 360, "Wallpaper Text");
draw_set_halign(_align);
// Recommended
var _w = display_get_width();
var _h = display_get_height();
var _align = draw_get_halign();
draw_set_halign(fa_center);
draw_text(_w/2, _h/2, "Wallpaper Text");
draw_set_halign(_align);