Using AWS Lambda functions in your Amazon GameSparks game

You can invoke AWS Lambda functions from Amazon GameSparks. With Lambda functions, you can:

• Leverage other resources, including AWS services and third-party services.

• Reuse your functions in multiple games across multiple AWS accounts.

• Implement your functions in multiple programming languages.

This topic shows you how to set up and call a sample Lambda function.

Note

If you are new to GameSparks, we recommend that you begin with Getting started using Amazon GameSparks and Using messages to implement game logic in Amazon GameSparks.

Deploy your game

If your game is new and you've never deployed it, follow these steps.

To deploy your game for the first time

1. In the GameSparks console, choose the name of your game.

2. In the navigation pane, choose Dev.

3. On the Dev page, under Snapshot, choose Deploy as new snapshot.

4. In the Deploy as new snapshot dialog box, optionally enter a description, and then choose Save.

Create a Lambda function

Get started calling a Lambda function from your cloud code by creating a sample function named NumberAddition with Python 3.9 syntax.

To create the NumberAddition Lambda function

1. Open the Functions page of the Lambda console.

2. Choose Create function.

3. On the Create function page, choose Author from scratch.

4. Under Basic information, do the following:

   1. For Function name, enter NumberAddition.

   2. For Runtime, choose Python 3.9.

5. Choose Create function.

6. On the Code tab, under Code source, replace the code in lambda_function with the following:

   import json
   
   def lambda_handler(event, context):
   
       num1 = event['num1']
       num2 = event['num2']
       return {
          "result": num1 + num2
       }

7. Choose Deploy.

8. On the Function overview pane, copy the Function ARN. You need this ARN in the next section.

An Amazon Resource Name (ARN) is a string that uniquely identifies a resource such as a game, a stage, a Lambda function, or a DynamoDB table. For more information, see Amazon Resource Names (ARNs) in the AWS General Reference.

Give your game permission to access your function

Before your GameSparks game can run your Lambda function, you must grant permission by using an AWS Identity and Access Management (IAM) policy. Create an IAM policy named RunNumberAdditionFunction policy and attach it to your Dev stage IAM role.

To create and attach an IAM policy

1. Open the IAM Create policy page.

2. Choose the JSON tab.

3. Replace the existing JSON policy with the following policy.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "RunNumberAdditionFunction",
               "Effect": "Allow",
               "Action": "lambda:InvokeFunction",
               "Resource": "arn:aws:lambda:us-east-1:111122223333:function:NumberAddition"
           }
       ]
   }

   Important

   Replace the value of Resource with the ARN that you copied in the previous section.

4. Choose Next: Tags, and then choose Next: Review.

5. On the Review policy page, do the following:

   1. For Name, enter RunNumberAdditionFunction.

   2. Choose Create policy.

6. In the GameSparks console, choose the name of your game.

7. In the navigation pane, choose Dev.

8. Under Dev stage configuration, choose View in IAM console.

   The IAM console opens to the IAM role for your Dev stage.

9. On the Permissions tab, choose Add permissions, Attach policies.

10. Under Other permissions policies, search for the RunNumberAdditionFunction policy.

11. In the search results, select the policy, and then choose Attach policies.

The Dev stage of your game now has permission to call the RunNumberAdditionFunction Lambda function.

Run your function synchronously using Lambda.Invoke

If your Lambda function runs quickly, and you need the data returned to your message, use the Lambda.Invoke cloud code function to run your Lambda function synchronously. Your message waits for a response from the Lambda function before proceeding to the next instruction.

Create the request

To run your Lambda function, create a request and use the Lambda.Invoke cloud code function.

To create the NumberAddition request

1. In the GameSparks console, choose the name of your game.

2. In the navigation pane, choose Dev. Then, under Configuration, choose Cloud code.

3. On the Cloud code page, choose Create message.

4. In the Create message dialog box, do the following:

   1. Choose Request.

   2. For Name, enter NumberAddition.

   3. (Optional) Enter a Description.

   4. Choose Create.

5. Select Enable client permission.

6. In the expanded Game-defined request fields pane, add the following fields:

   Request fields

   Field name	Shape	Required
   input1	Integer	Yes
   input2	Integer	Yes

   Response fields

   Field name	Shape	Required
   result	Integer	Yes

7. For Request handler, add the following code:

   GameSparks().Logging().Debug("In NumberAddition request handler");
   
   const response = GameSparks().Lambda("NumberAddition").Invoke(
       {
           "num1": message.input1,
           "num2": message.input2
       }
   );
   
   GameSparks().Logging().Debug("Result from Lambda is:");
   GameSparks().Logging().Debug(JSON.stringify(response.Payload));
   
   return GameSparks().Messaging().Response({"result": parseInt(response.Payload.result)});

8. Choose Save.

Deploy and test your request

Now that you've created your request, you're ready to deploy and test it using the test harness.

To deploy and test your custom request

1. In the GameSparks console, choose the name of your game.

2. In the navigation pane, choose Dev. Then, under Configuration, choose Test harness.

3. On the Test harness page, if you see the Deploy as new snapshot button, then choose it.

   1. In the Deploy as new snapshot dialog box, optionally enter a description, and then choose Save.

      GameSparks saves and deploys the snapshot. After this is done, you can proceed.

4. Choose your NumberAddition request.

5. Choose Populate example.

   {
   	"input2": 1,
   	"input1": 1
   }

6. Choose Send message.

In the Log inspector, you should see results like the following:

✓ Response received

Id: e2e5bfdc-abb1-4848-8bfe-fa06ad6e59ce
Type: Custom.Game.NumberAddition
Category: Response
ResponseTo: 20bd188d-7db4-49e1-a089-ca73433d10a6

{"result":2}

ⓘ Request sent

Id: 20bd188d-7db4-49e1-a089-ca73433d10a6
Type: Custom.Game.NumberAddition
Category: Request

{"input2":1,"input1":1}

Learn more about Lambda.Invoke

For more information about the Lambda.Invoke cloud code function, see Lambda.Invoke.

Run a function asynchronously using InvokeEvent

You can run your Lambda function asynchronously. This causes your cloud code message to continue to the next instruction without waiting for a response from the Lambda function. To run a Lambda function asynchronously, use the Lambda.InvokeEvent cloud code function.

GameSparks().Lambda("NumberAddition").InvokeEvent(
    {
        "num1": message.input1,
        "num2": message.input2
    }
);

Learn more about Lambda.InvokeEvent

For more information about this cloud code function, see Lambda.InvokeEvent.

Learn more about Lambda

For more information about what you can do with Lambda functions, see the AWS Lambda Developer Guide.