Synchronise the game with the cloud service.



Returns: Real


This function would normally be called at the start of a new game and is used to retrieve the current status of the cloud service at game start up. The function returns a unique id value which would then be used in the Asynchronous Cloud Event to retrieve the relevant information from the ds_map that is created.

This function will send off to the cloud for data, which will then trigger the appropriate asynchronous event. In this event, you can check the returned async_load ds_map for the following values:

  1. "status": This holds the status code, where a negative value denotes an error, a description of which will be contained in the “errorString”. A value of 0 (or a positive value) indicates a success(see below for exact values), and the “resultString” will contain the returned data or a success message.

  2. "id": The id which was returned from the called function. If you fire off a series of cloud_ requests then you need to know which one you are getting the reply to, and so you would use this value to compare to the value you stored when you originally sent the request to find the right one.

  3. "description": The description of the last uploaded file.

  4. "resultString": This holds a string which is the data blob returned from the cloud.

  5. "errorString": returns an Error String for any error.

The exact meaning of the returned "status" map entry is explained in the following table:

Status Value errorString / resultString Description
-1 errorString = "Not logged in to <SERVICE>" You have not successfully logged in to the given Cloud Service
0 resultString = recovered data New game data downloaded from the cloud (following a cloud_synchronise call)
1 resultString = "AlreadySynchronized" No new data since you last called cloud_synchronise
2 resultString = "ConflictDeferral" A conflict was encountered, but the gamer chose to ignore it
3 resultString = "GameUploadSuccess" data from cloud_string_save or cloud_file_save was successfully uploaded to the cloud
-n errorString = Description of error Any other negative number means a synchronisation failure

Extended Example:

This function would be called in an event like the Game Start Event or in an object that is placed in the first room of your game, with the idea being that you check the current data blob from the cloud server to see if it is up to date or not.

cloud_check = cloud_synchronise();

You would then want to check the returned ds_map in the asynchronous Cloud Event to get the status and the returned string, if there is one, with something like the following code:

if ds_map_find_value(async_load, "id") == cloud_check
   if ds_map_find_value(async_load, "status") < 0
      show_message_async("Cloud Services not available. Please check connectivity.");
      if ds_map_find_value(async_load, "status") == 0
         var file = file_text_open_write("Save.txt");
         file_text_write_string(file, ds_map_find_value(async_load, "resultString"));

The above code checks to make sure that the correct asynchronous function call is being revised, then goes on to get the status of the returned cloud ds_map. if the status is a negative number, something has gone wrong and the user is informed, otherwise the code will continue and retrieve the synchronised data and write it to a text file for later use.

Back: Cloud Services
Next: cloud_string_save
© Copyright YoYo Games Ltd. 2018 All Rights Reserved