Asynchronous Functions

Before dealing with the asynchronous functions (referred to from now on as async functions) in GameMaker Studio 2 it may be that you are wondering what the word "asynchronous" actually means! Well, the actual dictionary definition of asynchronous is:

"pertaining to a transmission technique that does not require a common clock between the communicating devices; timing signals are derived from special characters in the data stream itself."

In the context of GameMaker Studio 2, an async function is one that sends out to a web server, or asks for user input, or even streams data, while letting GameMaker Studio 2 continue to run without blocking. When the information callback is received a special Async Event is fired which, in turn, allows any instance with an Async Event assigned to it to execute further functions (although this does not have to be the case). So, basically, it's a way to communicate with some external resource (server, user or device) without the game or project blocking while waiting for a reply.

Why is this important? Well, since it allows GameMaker Studio 2 to continue functioning while sending or receiving data, and this means that you can do many things all without blocking the game loop like -

This all makes everything function in a much more fluid and unobtrusive way. It should be noted that the Async Events will be triggered for all instances that have them, so you can use an async function in one instance, and have the Asynchronous Event that deals with the reply in another one, or even various other ones. You can go here for more information on how the Asynchronous event works - Asynchronous Events.

The different type of asynchronous functions are listed in the sections below:

Below you can find a list of the Async http functions available in GameMaker Studio 2:

Please note that the above http_ functions may not function as expected due to cross domain security issues. This means that requests to your server or attempts to load resources from across domains are blocked and may appear to return blank results or 404 errors. One of the ways you can get around this is to have some server side PHP which allows certain domains to access your server (this is also a way to protect your resources and block servers that are not included in the PHP allow list).

The following is an example of the code you can use for this:

$http_origin = $_SERVER['HTTP_ORIGIN'];
if ($http_origin == "")
   header('Access-Control-Allow-Origin: *');

Previous versions of GameMaker had pop-up dialogues that blocked the runner while waiting for a response from the user. However most modern devices do not like this and will interpret the runner stopping as an error and close the app. To prevent this GameMaker Studio 2 has async equivalents of these functions that fulfil the same purpose as previous versions, but do not block the game runner at any time, meaning that when called the game will run as normal in the background while the user responds to the shown dialogue. Once the user has responded, a Dialogs Asynchronous Event will be called so that you can deal with the results.

Below is a list of all the available asynchronous dialogue functions:

When making games, it is often necessary to store information about the game state in a file of some type, but storing this information on the device is not always the best option as, if the player deleted the game and then re-installs, this information may be lost. To prevent this you can use various different cloud services, which offer data storage over the internet for retrieval and modification at any time. You should note that this function is limited to one single data "blob" per game, so every time you send a new save to the cloud service, whether it is a string or a file, it will overwrite any previously stored data.

GameMaker Studio 2 supports this with a few simple functions that work in conjunction with the Asynchronous Cloud Event. These functions are explained on the following pages:

NOTE: Currently only the Google Services extension on Android uses these functions, and this extension must be present before you can call them.

On mobile devices, normally only one application can be active in the foreground at any time, but many games and applications operate in a time-based or interconnected environment where events of interest to users can occur when the application is not in the foreground. In these cases, Local and Remote push notifications can allow these games to notify their users when events occur.

When the operating system delivers a local or remote push notification and the target application is not running in the foreground, it presents the notification to the user in the form of a banner. If there is a notification alert and the user taps on it, then the game is launched and an Asynchronous Push Event is called where you can check the callback string that you specify and resolve the push based on its value. If the application is running in the foreground when the notification is delivered, the application will still receive an Asynchronous Push Event, but the user will get no message displayed unless you create it yourself.

There are a few differences to note between supported platforms:

  • On Android, all notifications received when the app is not running/in background, will be stored, and the data delivered by the async event the next time the app runs and you will need to enable push notifications within the Android Game Options for them to work.

  • On iOS, data for a particular notification will only be delivered when the notification is selected (or if the app is running in foreground when the notification is received) and you will need to enable push notifications within the iOS Game Options for them to work.

A local push notification is local to the device that the game is installed on, and requires no backend server. You simply set the date and time for the notification and it will be displayed to the user if the game is not currently running. This type of notification is useful to set "reminders" for the user to play your game again, or to offer a daily reward for playing, etc... and when the user taps the notification it will launch the game and pass in a data string which can then be parsed by the game to give a reward or whatever.

The following functions are available for local notifications:

NOTE: This functionality is limited to the iOS and Android target modules. For Android you will need to have installed the Google Play Services Extension and have enabled push notifications in the Android Social Game Options.

Remote notification messages are sent by a server to a service provided by the device platform App Store, and this then forwards those messages onto all the devices on which your application is installed. This is supported by GameMaker Studio 2 on the iOS and Android target modules.

There are no functions in GameMaker Studio 2 to deal with remote notifications, as they must all be generated by your server and handled by the respective App Stores. However, once set up correctly, GameMaker Studio 2 games will receive these notifications, which can then be dealt with in the Asynchronous Push Event, as you would a local notification.

For all available platforms, once you have done the necessary set-up, when the game is run on a device it will register that device with the platforms push notification service. This will trigger an Asynchronous Push Notification Event, and the ds_map key "type" will have the value "register" as well as a new key, "reg_id", containing the registration id (or an error message in the "error" key, if "status" is 0). You must then send this registration id to your server, and every device that your game is installed on will have a different registration id. Your server must maintain a list of ids for registered devices, as when when you send a push notification message from your server, you use the registration ids to send the message to the registered devices.

Please note that there is no guarantee that remote push notifications will be delivered, and that the allowed data payload is fairly small. This varies between platforms, but iOS is particularly limited - the apple service only delivers the most recent notification, which must be selected by the recipient for the payload data to be delivered to your async event, and these notifications have a maximum payload size of 256bytes. Typically a remote push notification would just indicate that new data is available from your server for example.

NOTE: Android requires that you add the GCM Sender ID into the Android Game Options. This is the Project Number that is assigned when you create your Google Play API Project.

For further details on how to go about setting up a server, as well as information specific to the available platforms, please see the following pages on the YoYo Games Knowledge Base:

NOTE: Implementing the server-side is entirely up to the end user, and YoYo Games do not provide any support for that side of things, other than basic set-up information available from their Knowledge Base.

As the mobile platforms grow and take up more of the gaming market share, so to does the demand for social interaction and feedback from these games. To meet these demands GameMaker Studio 2 has certain 3rd party APIs integrated into it to permit you to communicate with different networks depending on the device you are targeting for your game.

The following sections contain information on the available social media integration:

  1. Facebook
  2. Achievements and Leaderboards

There is also an asynchronous function that will open a dialogue and permit you to request that a user of your game leaves a comment or rating on a specific web page: