Your Alexa Consoles
Sign In
?
Sign In
Support

GameEngine Interface Reference

The Game Engine interface enables your skill to receive input from Echo Buttons. This interface works with compatible Amazon Echo devices only.

Your skill uses the Game Engine Interface by sending directives that start and stop the Input Handler, which is the component within Alexa that sends your skill Echo Button events when conditions that you define are met (for example, the user pressed a certain sequence of buttons).

Configuring Your Skill to Use the Game Engine Interface

To use Game Engine directives, you must specify the Game Engine interface in your skill metadata.

Game Engine Directives

The Game Engine interface provides the following directives:

Directive Description
GameEngine.StartInputHandler Sends Alexa a command to configure Echo Button events and start the Input Handler, which translates button presses into Echo Button events.
GameEngine.StopInputHandler Sends Alexa a command to stop sending Echo Button press events to your skill.

When including a directive in your response, set the type property to the directive that you want to send. Include directives in the directives array in your response. The following is the format of a request with a GameEngine.StartInputHandler directive in it.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {},
    "card": {},
    "reprompt": {},
    "directives": [
    {
      "type": "GameEngine.StartInputHandler",
      "timeout": 5000,
      "proxies": [],
      "recognizers": {},
      "events": {}
    }
    ],
    "shouldEndSession": true
  }
}

For the full response format, see Response Format in the JSON Interface Reference for Custom Skills.

StartInputHandler Directive

Configures and starts the Input Handler to send Echo Button events to your skill.

The following is the basic form of the StartInputHandler directive. For examples, see Receive Echo Button Events and Define Echo Button Events.

{
  "type": "GameEngine.StartInputHandler",
  "timeout": 5000,
  "proxies": [],
  "recognizers": {},
  "events": {}
}
Parameter Description Type Required
type Must be set to GameEngine.StartInputHandler. string yes
timeout The maximum run time for this Input Handler, in milliseconds. Although this parameter is required, you can specify events with conditions on which to end the Input Handler earlier. Minimum value: 0. Maximum value: 90,000 ms (90 seconds). number yes
proxies Names for unknown gadget IDs to use in recognizers, allocated on a first-come, first-served basis. array no
recognizers Conditions that, at any moment, are either true or false. You use recognizers when you specify the conditions under which your skill is notified of Echo Button input. Minimum number of recognizers: 0 (leave the object empty). Maximum number of recognizers: 20. object yes
events The logic that determines when your skill is notified of Echo Button input. Minimum number of events: 1. Maximum number of events: 32. object yes

recognizers object

The recognizers object contains one or more objects that represent different types of recognizers: the patternRecognizer, deviationRecognizer, or progressRecognizer. In addition to these recognizers, there is a predefined timed out recognizer. All of these recognizers are described next.

For more information about how to use recognizers, see Define Echo Button Events.

The following example is a recognizers object that contains two recognizers. Both recognizers are of type patternRecognizer. The first recognizer detects button presses and the second recognizer detects button releases.

"recognizers": 
{  
   "button_down_recognizer": 
    {
        "type": "match",
        "fuzzy": false,
        "anchor": "end",
        "pattern": [
         {
           "action": "down"
         }
        ]
     },
    "button_up_recognizer": {
        "type": "match",
        "fuzzy": false,
        "anchor": "end",
        "pattern": [
         {
           "action": "up"
         }
        ]
    }
}
patternRecognizer object

This recognizer is true when all of the specified events have occurred in the specified order.

Parameter Description Type Required

type

Must be set to match.

string

yes

anchor

Where the pattern must appear in the history of this input handler. Possible values:

  • start: (Default) The first event in the pattern must be the first event in the history of raw Echo Button events.
  • end: The last event in the pattern must be the last event in the history of raw Echo Button events.
  • anywhere: The pattern may appear anywhere in the history of raw Echo Button events.

enum

no

fuzzy

When true, the recognizer will ignore additional events that occur between the events specified in the pattern.

boolean

no

gadgetIds

The gadget IDs of the Echo Buttons to consider in this pattern recognizer.

array

no

actions

The actions to consider in this pattern recognizer. All other actions will be ignored.

array

no

pattern

An object that provides all of the events that need to occur, in a specific order, for this recognizer to be true. Omitting any parameters in this object means "match anything".

array

yes

pattern.gadgetIds

A whitelist of gadgetIds that are eligible for this match.

array

no

pattern.colors

A whitelist of colors that are eligible for this match.

array

no

pattern.action

The specific action name that must match. Possible values:

  • down: A button is pressed down.
  • up: A button is released.
  • silence: There is no action on the buttons.

enum

no
deviationRecognizer object

The deviation recognizer returns true when another specified recognizer reports that the player has deviated from its expected pattern.

Parameter Description Type Required
type Must be set to deviation. string yes
recognizer The name of the recognizer that defines a pattern that must not be deviated from. string yes
progressRecognizer object

This recognizer consults another recognizer for the degree of completion, and is true if that degree is above the specified threshold. The completion parameter is specified as a decimal percentage.

Parameter Description Type Required
type Must be set to progress. string yes
recognizer The name of a recognizer for which to track the progress. string yes
completion The completion threshold, as a decimal percentage, of the specified recognizer before which this recognizer becomes true. number yes
timed out recognizer object

This recognizer is true when the Input Handler has reached the end of the timeout period specified using StartInputHandler. This recognizer is predefined and cannot be overridden.

events object

The events object is where you define the conditions that must be met for your skill to be notified of Echo Button input. You must define at least one event.

The following is an example of an event defined within an events object. For examples, see Define Echo Button Events.

{
  "myEventName": {
    "meets": [ "a recognizer", "a different recognizer" ],
    "fails": [ "some other recognizer" ],
    "reports": "history",
    "shouldEndInputHandler": true,
    "maximumInvocations": 1,
    "triggerTimeMilliseconds": 1000    
  }
}

The fields are as follows.

Parameter Description Type Required

meets

Specifies that this event will be sent when all of the recognizers are true.

array

yes

fails

Specifies that this event will not be sent if any of these recognizers are true.

array

no

reports

Specifies what raw button presses to put in the inputEvents field of the event. Possible values:

  • history: All button presses since this Input Handler was started.
  • matches: Just the button presses that contributed to this event (that is, were in the recognizers). To receive no raw button presses, leave this array empty or do not specify it at all.

enum

no

shouldEndInputHandler

Whether the Input Handler should end after this event fires. If true, the Input Handler will stop and no further events will be sent to your skill unless you call StartInputHandler again.

boolean

yes

maximumInvocations

Enables you to limit the number of times that the skill is notified about the same event during the course of the Input Handler. The default value is 1. This property is mutually exclusive with triggerTimeMilliseconds. Minimum: 1. Maximum: 2,048.

number

no

triggerTimeMilliseconds

Adds a time constraint to the event. Instead of being considered whenever a raw button event occurs, an event that has this parameter will only be considered once at triggerTimeMilliseconds after the Input Handler has started. Because a time-triggered event can only fire once, the maximumInvocations value is ignored. Omit this property entirely if you do not want to time-constrain the event. Minimum: 0. Maximum: 300,000.

number

no

StopInputHandler Directive

Stops Echo Button events from being sent to your skill.

{
  "type": "GameEngine.StopInputHandler",
  "originatingRequestId": "amzn1.echo-api.request.406fbc75-8bf8-4077-a73d-519f53d172a4"
}
Parameter Description Type Required
type Set to GameEngine.StopInputHandler string yes
originatingRequestId Provides the requestId of the request to which you responded with a StartInputHandler directive. string yes

Game Engine Requests

This section contains the types of requests that Alexa might send your skill when you use the Game Engine interface.

InputHandlerEvent Request

GameEngine sends the following requests to notify your skill about Echo Button events:

Request Type Description
GameEngine.InputHandlerEvent Sent when the conditions of an Echo Button event that your skill defined were met.

The form of a GameEngine.InputHandlerEvent request is as follows.

{
  "version": "1.0",
  "session": {
    "application": {},
    "user": {},
    "request": {
      "type": "GameEngine.InputHandlerEvent",  
      "requestId": "amzn1.echo-api.request.406fbc75-8bf8-4077-a73d-519f53d172a4",
      "timestamp": "2017-08-18T01:29:40.027Z",
      "locale": "en-US",
      "originatingRequestId": "amzn1.echo-api.request.406fbc75-8bf8-4077-a73d-519f53d172d6",
      "events": [
        {       
          "name": "myEventName",
          "inputEvents": [
            {
              "gadgetId": "someGadgetId1",
              "timestamp": "2017-08-18T01:32:40.027Z",
              "action": "down",
              "color": "FF0000"
            }
          ]
        }
      ]
    }
  }
}

For the full request format, see Request Format in the JSON Interface Reference for Custom Skills.

Parameters
Parameter Description Type
type GameEngine.InputHandlerEvent string
requestId Represents a unique identifier for the specific request. string
timestamp Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. string
locale A string indicating the user's locale. For example: en-US. string
originatingRequestId The requestId of the request to which your skill responded with a StartInputHandler directive. You should store that requestId to use as a filter here to reject any older stray asynchronous InputHanderEvents that show up after you've started a new Input Handler. string
events A list of events sent from the Input Handler. Each event that you specify will be sent only once to your skill as it becomes true. Note that in any InputHandlerEvent request one or more events may have become true at the same time. array
events.name The name of the event as you defined it in your GameEngine.StartInputHandler directive. string
events.inputEvents A chronologically ordered report of the raw Button Events that contributed to this Input Handler Event. array
events.inputEvents.gadgetId The permanent identifier of the Echo Button in question. It matches the gadgetId that you will have discovered in roll call. string
events.inputEvents.timestamp The event's original moment of occurrence, in ISO format. string
events.inputEvents.action Either "down" for a button pressed or "up" for a button released. enum
events.inputEvents.color The hexadecimal RGB values of the button LED at the time of the event. string
events.inputEvents.feature For gadgets with multiple features, this is the feature that the event represents. Echo Buttons have one feature only, so this is always press. string

Valid Response Types

Your skill is not required to return a response to GameEngine requests. However, you might want to provide text-to-speech, show a card, play music, or open the microphone to prompt users for a voice intent.

System.ExceptionEncountered Request

If a GameEngine directive that you send fails (for example, you send an invalid Input Handler definition), then your skill will be invoked with a standard System.ExceptionEncountered request. Any directives included in the response are ignored.

{
  "type": "System.ExceptionEncountered",
  "requestId": "string",
  "timestamp": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  },
  "cause": {
    "requestId": "string"
  }
}

Parameters

Parameter Description Type
type System.ExceptionEncountered string
requestId A unique identifier for the specific request. string
timestamp Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. string
locale A string indicating the user's locale. For example: en-US. string
error An object with error information. object
error.type The specific type of error (INVALID_RESPONSE, DEVICE_COMMUNICATION_ERROR, INTERNAL_ERROR). string
error.message A description of the error the device has encountered. string
cause.requestId The requestId for the request that caused the error. string

Valid Response Types

Your skill cannot return a response to System.ExceptionEncountered.

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces: