How to Schedule Cloud Code Scripts Using the Game Data Service

You can schedule Cloud Code scripts on the GameSparks platform in two ways:

• Schedule a Module script via the SparkScheduler Cloud Code object.
• Use one of the predefined system schedulers.

Game Data Service? This tutorial assumes an understanding of the Game Data Service. We strongly recommend that you review the Game Data and the Data Explorer topics before you attempt to follow this tutorial.

Scheduling a Script via the SparkScheduler Object

Suppose you want to allow your players to plant virtual seeds within the game world and for the seed to grow into a plant after a given amount of time has passed.

To do this, let's first create an Event that the game code can trigger to indicate that the player has planted the seed.

1. Log in to the GameSparks Portal and navigate to Configurator > Events.

2. Click to Add a new Event and set up the Event as follows:

3. Save the Event and navigate to Configurator > Cloud Code > Scripts > Events and select PLANT_SEED to open up the Cloud Code editor for this Event.

4. Copy the following script to the Editor:

// Get the Event's coord data
var x = Spark.getData().X;
var y = Spark.getData().Y;

// Schedule the GROW_SEED module to run in 60s time,
// passing in the x,y coords where the seed was planted
var theScheduler = Spark.getScheduler();
theScheduler.inSeconds("GROW_SEED", 60, {"x" : x, "y" : y});

This script schedules the GROW_SEED module script to run after 60 seconds.

5. Click to Save the Cloud Code script you've added to the Event and navigate to Configurator > Cloud Code > Scripts > Modules > Create New Module.

6. Enter GROW_SEED as the Module name and click Save. GROW_SEED will now be listed under your Cloud Code > Scripts > Modules.

7. Click to open the Cloud Code Editor for the GROW_SEED Module.

8. Copy the following script into the Editor and click the Save button.

// Get the x,y coords of the seed
var x = Spark.getData().x;
var y = Spark.getData().y;

//Get playerId and timestamp to create entry name
var playerId = Spark.getPlayer().getPlayerId();
var time = new Date().toISOString();
var entryName = playerId + time;


//Create entry and get its data object
var API = Spark.getGameDataService();
var entry = API.createItem("field", entryName);
var data = entry.getData();

//Add new data to entry
data.x = x;
data.y = y;
data.item = "plant"
data.playerId = playerId;

//Persist entry
var status = entry.persistor().persist().error();

if(status){
    Spark.setScriptError("Error", status);
}

Testing the Configuration

Let’s test out this configuration in the Test Harness.

1. Navigate to the GameSparks developer portal Test Harness.

2. Copy the JSON request below into the JSON field and click to Send Request.

{
 "@class": ".RegistrationRequest",
 "displayName": "displayName",
 "password": "password",
 "userName": "gardener"
}

The GameSparks platform will return a response similar to this.

{
  "@class": ".RegistrationResponse",
  "authToken": "59035171-bc9d-46bc-8dca-1d8598df1553",
  "displayName": "displayName",
  "newPlayer": true,
  "userId": "581a0e543a32df72c7b30675"
}

This player is now authenticated and could sign into later sessions using these credentials with an AuthenticationRequest.

3. Now make the PLANT_SEED Event call. Copy the JSON request below into the JSON field and click to Send Request.

 {

 "@class": ".LogEventRequest",
 "eventKey": "PLANT_SEED",
 "X": 10,
 "Y": 12

}

The GameSparks platform will return a response similar to this:

{

 "@class": ".LogEventResponse"

}

Execution of the scripts:

• The 'Plant a Seed' Cloud Code script will execute when GameSparks receives this Event. The script schedules the GROW_SEED script to run after 60 seconds, passing in the X and Y coordinates from the Event.
• 60 seconds later, the GROW_SEED script will execute, which will result in a document being created in the field Data Type.

4. Lastly, to see the results navigate to the Data Explorer and select the field Data Type.

5. Either query for the entry or find it via ID, then click the Find button and expand the results returned:

• To set up this query, you'll first have to add indexed fields for the field Data Type on the Game Data page:

Scheduling a Script via a System Scheduler

The Cloud Code > System section contains three time-based triggers:

• Every Day.
• Every Hour.
• Every Minute.

These scripts execute at the top of every day, every hour, and every minute respectively. Continuing our "plant a seed" example from above, let's schedule a script that clears all the plants from the virtual field every hour.

1. Navigate to Configurator > Cloud Code, under Scripts expand System, and select Every Hour.

2. Copy the following script into the Cloud Code editor and click the Save button:

//Load Data Service
var API = Spark.getGameDataService();

//Create condition
var query = API.S("item").eq("plant");

//Use condition for query
var resultsOBJ = API.queryItems("field", query);

//Are there errors
if(resultsOBJ.error()){
    Spark.setScriptError("ERROR", resultsOBJ.error());
}else{

    //Get results
    var results = resultsOBJ.cursor();

    //Loop through cursor and remove entries
    while(results.hasNext()){
        results.next().delete();
    }
}

Note that the query results only return 100 entries. So iterate a few times until all plants are removed.