Connecting your Unity game client to Amazon GameSparks

Now that you've deployed your Amazon GameSparks backend, you're ready to connect your game client.

Note

This topic builds on Part 1: Hello World. You must complete that tutorial before you begin this one.

Create a GameSparks connection object

Set up the GameSparks client SDK in your Unity project. If you've already done this, skip to the next procedure.

To set up the client SDK

1. Make sure you've installed Unity 2021.3.

2. Download the GameSparks SDK tarball package.

3. Start Unity Hub and do one of the following:

   1. Open a 3D project that is built with Unity 2021.3.

   2. Create a new 3D project that is built with Unity 2021.3.

4. In the Unity editor window, from the Window menu, choose Package Manager.

5. In Package Manager, add the GameSparks package from the tarball you downloaded.

   

In Unity, create a connection asset that enables your game client to communicate with the backend.

To create a GameSparks connection object

1. In your Unity project, from the GameSparks menu, choose Set up scene, Create connection.

   An Assets/Amazon/GameSparks/Connection.asset appears in your Project pane.

   

2. Copy and paste the game key from GameSparks into Unity.

   1. In the GameSparks console navigation panel, select Dev.

      In the Dev stage configuration card, copy the Key value to your clipboard.

   2. In Unity, select the Connection object.

   3. In the Inspector panel, paste the key value into the Game Key field.

   

Generate and import code

We highly recommend that you use generated code to connect your game client to GameSparks. The generated code gives you intermediary classes to write strongly-typed client code (instead of using JSON literals). This approach improves development efficiency and reduces bugs.

To generate and download client code

1. In the GameSparks console navigation pane,choose Dev.

2. On the Dev page, in the Snapshot card, choose Actions, and then choose Generate SDK message template.

3. In the Generate Code for Dev Stage dialog box, make sure that Game client platform is set to Unity.

4. Choose Generate Code.

5. After the code has been generated, choose Download.

To begin using the code you you'll import it into your Unity project.

To import the generated code into your Unity project

1. Open the .ZIP file you downloaded.

2. Extract the HelloWorldOperations.cs file.

   Important

   If you created your GameSparks game with a different name (for example, HelloMoon), then the .cs file name will be different (for example, HelloMoonOperations.cs).

3. In Unity

   1. In the Project pane, choose the GameSparks folder.

   2. Open the Assets menu or right-click inside the folder, and then choose Import New Asset.

   

4. In the dialog box that appears, select HelloWorldOperations.cs, and then choose Import.

Create a Unity script

You're ready to implement a Unity script in your game client to communicate with the GameSparks backend. The script makes the GetGreeting request and then look for a response from GameSparks.

Note

The following client code depends on the GameSparks game you created. Specifically, the code depends on the name of the game (HelloWorld), the request (GetGreeting), and its field names and types (greeting, a String and count, Integer).

If you used different names, then modify the client code. For example, if you named your request SayHello, then change instances of GetGreeting to SayHelloOperations.

To create your game client script

1. In Unity

   1. In the Project pane, choose the GameSparks folder.

   2. Open the Assets menu or right-click inside the folder, and then choose Create.

   3. Choose C# Script.

   

2. Name the script Player.

3. Open Player script in your IDE.

4. Replace the contents of the script with the following code, and then save your changes.

using System;
using Amazon.GameSparks.Unity.DotNet;
using Amazon.GameSparks.Unity.Generated;
using Amazon.GameSparks.Unity.Editor.Assets;
using UnityEngine;

namespace Amazon.GameSparks.Unity.Samples.UsingScriptableObjects.Scripts
{
public sealed class Player : MonoBehaviour
{
  [SerializeField]
  private ConnectionScriptableObject connectionScriptableObject = default;

  private void OnMouseUp()
  {
    var greetingRequest = new HelloWorldOperations.GetGreetingRequest("World");

    try {
      Debug.Log("Sending GetGreeting request");
      connectionScriptableObject.Connection.EnqueueGetGreetingRequest(
        greetingRequest,
        HandleGetGreetingResponse,
        error => { Debug.Log("Request failed: " + error); },
        () => { Debug.Log("Request timed out."); },
        TimeSpan.FromMinutes(2));
    } catch (Exception e) {
      Debug.LogException(e);
    }
  }

  private void HandleGetGreetingResponse(
    Message<HelloWorldOperations.GetGreetingResponse> response)
  {
    string gameSparksGreeting = "'greeting' " + 
    response.Payload.greeting.GetType() +
    " from GameSparks: " + response.Payload.greeting;
    string gameSparksCount = "'count' " + response.Payload.count.GetType() +
      " from GameSparks: " + response.Payload.count;

    Debug.Log(gameSparksGreeting);
    Debug.Log(gameSparksCount);
  }
}
}

Set up your game client to connect to the backend

To connect to GameSparks, you'll:

• Attach your Player.cs script to a 3D object. This 3D object will associate with your script's ConnectionScriptableObject property.

• Add the Assets/Amazon/GameSparks/Connection asset to ConnectionScriptableObject property of your 3D object.

The result will be that your Player.cs script can communicate with the backend through its ConnectionScriptableObject property. The client will be able to raise events, make requests, and receive notifications.

To enable your ConnectionScriptableObject

1. In Unity, create a 3D object. For example, from the GameObject menu, choose 3D Object, Cylinder.

2. Make sure that you have selected the Scene tab near the top of the Unity window.

3. Select the 3D object.

4. 1. Drag Assets/Amazon/GameSparks/Player from the Project pane onto the 3D object.

   2. With the 3D object selected, drag Assets/Amazon/GameSparks/Connection from the Project pane into the Connection Scriptable Object field.

   

Run the game

To run the game

1. In Unity, if the console is not already displayed, from the Window menu, choose General, Console.

2. From the Edit menu, choose Play.

3. Choose the 3D object.

4. In the Unity Console, observe how the game connects and makes the request.

5. After some time, the backend responds.

The log in the Unity console looks something like this:

Sending GetGreeting request
[INFO]: Building message: 
   ID: 3, 
   timeout: 120000, 
   type: Custom.Game.GetGreeting, 
   payload: {"word":"World"}

[INFO]: adding a message of type [Custom.Game. GetGreeting] to the queue
[INFO]: draining a message of size [94] from the queue
[INFO]: enqueuing text message of length: 94
[INFO]: message received of 148 bytes, op: text frame

[INFO ] : response message received: Id: 0bafdd8b-2f70-4a58-a320-8b536d8c31bd
Category: Response
Type: Custom.Game.GetGreeting
ContentType: JSON
ResponseTo: 3
{"greeting":"Hello World!","count":1}

'greeting' System.String from GameSparks: Hello World!
'count' System.Int32 from GameSparks: 1

Recap

You just created a game client and connected it with the GameSparks backend that you created in Part 1: Hello World. You generated and imported code from GameSparks so that you could implement type safe code on the client side.

private void OnMouseUp()
{
  var greetingRequest = new HelloWorldOperations.GetGreetingRequest("World")
// ...

Finally, you ran the game and saw how the game client raised a request to GameSparks, and then received a response.

Next steps

In Part 3: Messages, you'll learn how to create events, requests, and notifications. You can then implement your game logic in those messages to provide a connected game experience for your players.