Merci de votre visite. Cette page est disponible en anglais uniquement. Nous travaillons actuellement sur la version française. Merci de votre compréhension.

Walkthrough: Don't Cut That Wire

Don't Cut That Wire is a pattern-matching game skill in which Alexa shows the user a sequence of colors on two or more Echo Buttons, and the user diffuses a bomb by pressing the buttons in the same order.

This topic provides examples of requests to and responses from Don't Cut That Wire. The examples include skill launch, roll call, and key parts of beginning and ending a round. As with any skill:

  • A request is when Alexa contacts the skill. For example, Alexa sends a request to the skill when a user launches the skill or answers a question that the skill narrator asked. Echo Button skills such as this one can also receive Game Engine requests, which report Echo Button input.
  • A response is when the skill responds to Alexa's request. In the response, the skill can include speech for Alexa to say, skill cards to display in the Alexa app, audio to play, and so on. Echo Button skills can also include a Game Engine directive to start or stop monitoring button input and Gadget Controller directives to light up the buttons.

For an overview of how Echo Button skills work, see Understand Echo Button Skills.

Skill Launch

As with other skills, users launch this skill by saying "Alexa, open [skill name]". The skill receives a request such as the one in the following example.

User Launches Skill

Description of this example
This is the request that Alexa sends Don't Cut That Wire when a user launches the skill.

What it demonstrates

Contents of a launch request, including the user ID and supported interfaces.

What happened immediately before it

A user launched the skill with a phrase such as "Alexa, open Don't Cut That Wire".

{
    "version": "1.0",
    "session": {
        "new": true,
        "sessionId": "amzn1.echo-api.session.1",
        "application": {
            "applicationId": "amzn1.ask.skill.1"
        },
        "user": {
            "userId": "amzn1.ask.account.1"
        },
        "attributes": {}
    },

Skills can personalize the user experience across skill sessions by saving the skill state in a database. The database uses this userId as the primary key. As an example of a personalization, if the user is playing this skill for the first time, Alexa gives them a practice round.

    "context": {
        "AudioPlayer": {
            "playerActivity": "IDLE"
        },
        "System": {
            "application": {
                "applicationId": "amzn1.ask.skill.1"
            },
            "user": {
                "userId": "amzn1.ask.account.1"
            },
            "device": {
                "deviceId": "amzn1.ask.device.1",
                "supportedInterfaces": {
                    "AudioPlayer": {}
                }
            },
            "apiEndpoint": "https://api.amazonalexa.com",
            "apiAccessToken": "someToken"
        }
    },


If the Alexa-enabled device has a screen, supportedInterfaces will include the Display interface.


    "request": {
        "type": "LaunchRequest",
        "requestId": "amzn1.echo-api.request.1",
        "timestamp": "2018-05-11T17:33:01Z",
        "locale": "en-US",
        "shouldLinkResultBeReturned": false
    }
}





The skill must save this requestId, because this ID will be the unique ID of the Input Handler that the skill starts in the next response. If the skill doesn't save this ID, the skill won't be able to properly stop the Input Handler or implement logic to ignore old events.

Roll Call

As with all skills that require Echo Buttons, this skill begins with a roll call to determine how many Echo Buttons will be used with the skill.

A skill can accomplish roll call in one of two ways:

  • by asking all players to push their button within a specified time
  • by asking how many players are present, and therefore how many buttons to expect

This skill uses the first method.

Skill Starts Input Handler for Roll Call

To begin roll call, the skill responds to the launch request with a response such as the one in the following example.

Description of this example
This is the response that the skill sends to Alexa in response to the launch request. This response includes speech that asks users to press their buttons and an Input Handler directive that sets up the Game Engine to start monitoring button presses.

What it demonstrates

Setting up an Input Handler to end after a specified duration, using proxies, defining simple button-down recognizers, defining events that are sent only once, output speech, SSML, audio, and use of a display directive.

What happened immediately before it

Alexa sent the skill a LaunchRequest.

{
  "version": "1.0",
  "sessionAttributes": {
    "state": "rollcall"
  },


This skill uses session attributes to store data. These attributes are passed back to the skill in the next request.


  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak> Launching Don't Cut 
                That Wire. When you 
                are ready to quit, 
                just say Alexa, stop.
                <break time='100ms' />
                Please press the 
                buttons you want 
                to use, one at a 
                time, until they 
                turn green.

In its first response, this skill includes output speech. Here it uses SSML to provide additional control over the speech. The <break/> tag inserts a natural-sounding pause.


              <audio src='https://s3.../song.mp3'/>
      </speak>"
     },




As a best practice, use audio such as music or sound effects while waiting for button input, as shown here. This way, the user knows that the skill is still open.

  "directives": [
  {
    "type": "Display.RenderTemplate",
    "template": {
      "type": "BodyTemplate1",
      "token": "launchImage",
      "title": "Don't Cut That Wire",
      "backgroundImage": {
        "sources": [{
        "url": "https://s3.../background.png"
        }]
      },
      "textContent": {
        "primaryText": {
          "type": "RichText",
          "text": "<font size='5'>Defuse the 
                   bomb before the timer runs 
                   out.</font>"
        }
      }
    }
  },

This is a display directive that instructs Alexa to display an image on Alexa-enabled devices with a screen, such as the Echo Show, Echo Spot, and Fire TV Cube.


  {
    "type": "GameEngine.StartInputHandler",







This is one of many Input Handlers that this skill uses. Only one Input Handler can be active at a time. Every time you call StartInputHandler, you replace the current Input Handler with a new one.


    "timeout": 24500,


  

This Input Handler will stop after 24.5 seconds.


    "proxies": ["btn1", "btn2", "btn3", "btn4"],











  


Proxies are optional but enable you to define recognizers (coming up next) without knowing the real gadget IDs of the buttons. The Game Engine assigns proxies to buttons on a first-come, first-served basis. Here, there are four proxies because that is the maximum number of buttons this skill supports.


    "recognizers": {     
      "roll_call_recognizer_btn_1": {  
        "type": "match",
        "fuzzy": true,
        "anchor": "end",
        "pattern": [{
                "gadgetIds": [ "btn1" ],    
                "action": "down"
         } ]
       },   
 
       "roll_call_recognizer_btn_2": {
         "type": "match",
         "fuzzy": true,
         "anchor": "end",
         "pattern": [{
                 "gadgetIds": [ "btn2" ],    
                 "action": "down"
          } ]
       },   
       
      "roll_call_recognizer_btn_3": {
        "type": "match",
        "fuzzy": true,
        "anchor": "end",
        "pattern": [{
                "gadgetIds": [ "btn3" ],    
                "action": "down"
         } ]
       },   
       
      "roll_call_recognizer_btn_4": {
        "type": "match",
        "fuzzy": true,
        "anchor": "end",
        "pattern": [{
                "gadgetIds": [ "btn4" ],    
                "action": "down"
         } ]
       }         
    
      },   
                     

Events, which are defined later in this directive, depend on these recognizers. Recognizers are conditions that evaluate to true or false. This configuration defines individual recognizers to detect a button press for each button. As you can see, these recognizers use the proxies defined earlier, because the skill doesn't know the gadget IDs of the buttons in advance.

       
    "events": {


      "timeout": {
        "meets": ["timed out"],
        "reports": "history",
        "shouldEndInputHandler": true
      },













                     

The timeout event signifies the end of roll call. It is sent to the skill when the Input Handler has been open for the length of time specified by the timeout parameter defined at the top of this directive. Because the Input Handler starts at the beginning of the output speech, timeout is set to 24.5 seconds to give players about 10 seconds beyond the estimated time that Alexa needs to finish reading the outputSpeech.


      "roll_call_event_btn_1": {         
        "meets": ["roll_call_recognizer_btn_1"],
        "reports": "matches",
        "shouldEndInputHandler": false,      
        "maximumInvocations": 1      
       },
       
      "roll_call_event_btn_2": {         
        "meets": ["roll_call_recognizer_btn_2"],
        "reports": "matches",
        "shouldEndInputHandler": false,      
        "maximumInvocations": 1      
       },
       
      "roll_call_event_btn_3": {         
        "meets": ["roll_call_recognizer_btn_3"],
        "reports": "matches",
        "shouldEndInputHandler": false,      
        "maximumInvocations": 1      
       },
                    

This configuration defines one event per button, to notify the skill that the button was pressed. maximumInvocations is set to 1 so that the skill receives each event no more than once. This is all the skill needs to "register" the button and, for example, light up the button in response to the press.


      "roll_call_event_btn_4": {         
        "meets": ["roll_call_recognizer_btn_4"],
        "reports": "matches",
        "shouldEndInputHandler": true,      
        "maximumInvocations": 1      
       }
     }
   }
  ]  
 }
}       


shouldEndInputHandler is set to true here because this event is for the fourth button, and four is the maximum number of buttons that work with this skill. Therefore, when a user presses the fourth button, roll call is over. It doesn't need to wait to time out.

Button Press During Roll Call

When the first user presses their button during roll call, the Game Engine sends the skill a request of type GameEngine.InputHandlerEvent. This request contains the skill-defined event, roll_call_event_btn_1, in the events list. This event, which was defined in the GameEngine.StartInputHandler directive described previously, provides the skill with the gadget ID of the button that the user pressed. The following is an example of this event.

Description of this example
This is a request that the Game Engine sends the skill to notify the skill that a roll_call_event_btn_1 event occurred.

What it demonstrates

Syntax of an event, the button action that caused the event to be sent, and the significance of the originating request ID.

What happened immediately before it

A user pressed an Echo Button during roll call.

{
  "version": "1.0",
  "session": {
    "application": {},
    "user": {}
  },  
  "request": {
    "type": "GameEngine.InputHandlerEvent",  
    "requestId": "amzn1.echo-api.request.2",
    "timestamp": "2017-08-18T01:32:40.027Z",
    "locale": "en-US",


All Echo Button events are requests of type GameEngine.InputHandlerEvent.



    "originatingRequestId":"amzn1.echo-api.request.1",






The originatingRequestId is the requestId of the original request that the skill responded to when it started the Input Handler. In this case, the original request was a launch request.


      "events": [
       {       
          "name": "roll_call_event_btn_1",
          "inputEvents": [
            {
              "gadgetId": "amzn1.ask.gadget.1AQD",
              "timestamp": "2017-08-18T01:32:40.027Z",
              "feature": "press",
              "action": "down",
              "color": "000000"
            }
          ]
        }
      ]
   }
}

This Input Handler defined the roll_call_event_btn_1 event to have reports equal to matches. As such, this event history, inputEvents, contains the button action that made the meets condition true.

Response to Button Press During Roll Call

When a user presses a button during roll call, the skill turns the button green. To make this happen, the skill responds to the GameEngine.InputHandlerEvent request with a response that includes a SetLight directive targeted to the gadget ID of the button that was pressed. The following is an example of a response that includes this directive.

Description of this example
This response, which the skill sends to Alexa in response to the GameEngine.InputHandlerEvent request that was triggered by roll_call_event_btn_1, turns the light of the pressed button green.

What it demonstrates

Sending a SetLight directive to a specific button.

What happened immediately before it

During roll call, the first user pressed their button. This triggered the Game Engine to send the skill a request of type GameEngine.InputHandlerEvent. The request contained roll_call_event_btn_1 in the events list.

{
  "version": "1.0",
  "response": {
    "directives": [
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.1AQD"],









In targetGadgets, we put the gadget ID of the button to send the animation to. This gadget ID was provided by the roll_call_event_btn_1 event. Note that this gadget ID is not a proxy, because proxies have nothing to do with the Gadget Controller. They are only used to help define events in the StartInputHandler directive.


      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 1,
          "sequence": [{
            "durationMs": 60000,            
            "color": "00FE10",   /* Green */
            "blend": true
          }]
        }]
      }
    }]
  }
}

This animation lights up the button green. For guidance on using colors with Echo Buttons, see Echo Button Animations.

Timeout During Roll Call

When the Input Handler has been open for timeout seconds, the skill receives an event of type timeout. This event, which was defined in the GameEngine.StartInputHandler directive described previously, indicates that roll call is complete. The following is an example of a timeout event.

Description of this example
This is a request that the Game Engine sends the skill to notify the skill that a timeout event occurred.

What it demonstrates

Syntax of an event that was sent when the Input Handler timed out, and the history that contributed to the event.

What happened immediately before it

The Input Handler expired after being open for 24.5 seconds. This is timeout that was specified when the Input Hander was defined.

{
  "version": "1.0",
  "session": {
    "application": {},
    "user": {}
   }, 
  "request": {
    "type": "GameEngine.InputHandlerEvent", 
    "requestId": "amzn1.echo-api.request.3",
    "timestamp": "2018-04-27T07:09:31Z",
    "locale": "en-US",
    "originatingRequestId": "amzn1.echo-api.request.1",
    "events": [{
      "name": "timeout",
      "inputEvents": [
      {
        "gadgetId": "amzn1.ask.gadget.1AQD",
        "timestamp": "2018-04-27T07:09:02.054Z",
        "color": "000054",
        "feature": "press",
        "action": "down"
       }, 
       {
         "gadgetId": "amzn1.ask.gadget.1AQD",
         "timestamp": "2018-04-27T07:09:02.287Z",
         "color": "000013",
         "feature": "press",
         "action": "up"
       },          

Because the reports parameter of this Input Handler is set to history, inputEvents contains a list of all the button actions that the Input Handler detected during its 24.5-second duration.

        
         {
          "gadgetId": "amzn1.ask.gadget.2O4E",
          "timestamp": "2018-04-27T07:09:02.054Z",
          "color": "000000",
          "feature": "press",
          "action": "down"
          }, 
          {
           "gadgetId": "amzn1.ask.gadget.2O4E",
           "timestamp": "2018-04-27T07:09:02.287Z",
           "color": "000000",
           "feature": "press",
           "action": "up"
          }
        ]
      }
    ]
  }  
}

Each button can have more than one entry in the inputEvents history, because button down and button up are separate actions.

Response to Timeout of Successful Roll Call

After the Input Handler for roll call times out, Don't Cut That Wire considers roll call to be successful if at least two buttons were detected, because that is the minimum number of Echo Buttons required for this game. (The user should know the minimum number of buttons required for this game because that information is shown in the Alexa Skill Store.) If roll call is successful, the skill pulses the detected buttons green by sending a response that includes SetLight directives to the detected buttons, as in the following example.

Description of this example
This response, which the skill sends to Alexa in response to a timeout request of a successful roll call, pulses the detected buttons green.

What it demonstrates

Sending a SetLight directive to multiple buttons.

What happened immediately before it

The Input Handler for roll call timed out, and the skill logic determined that there were at least two buttons. If there aren't, it sends a response to timeout of failed roll call instead.

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak><audio src='https://s3.../ding.mp3'/>
          Ok, I see we have a mission with two wires today. 
          Is that right?          
        </speak>"
    },
    "directives": [
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.1AQD", 
                        "amzn1.ask.gadget.2O4E",
                        "amzn1.ask.gadget.3BQL",
                        "amzn1.ask.gadget.4N6B"],



The skill sends the pulsing green animation to these four buttons, because these are the buttons it found during roll call.



      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 2,
          "sequence": [
           {
             "durationMs": 400,           
             "color": "00FE10", /* Green */
             "blend": true
            },
            {
             "durationMs": 300,            
             "color": "000000",  /* Black (off) */
             "blend": true
            }
          ]
        }]
      }
    }]
  }
}

This animation pulses the buttons green by alternating between green and black (#000000). Black turns the LEDs off.

Response to Timeout of Failed Roll Call

If fewer than two buttons are detected during roll call, Don't Cut That Wire tells the user to check connectivity, stops the Input Handler, and then ends the skill. The following is an example of such a response.

Description of this example
This response, which the skill sends to Alexa in response to the timeout request of a failed roll call, provides output speech, stops the Input Handler, and ends the skill.

What it demonstrates

Stopping the Input Handler and ending the skill.

What happened immediately before it

The Input Handler for roll call timed out, and the skill logic determined that there were fewer than two buttons.

{
  "version": "1.0",
  "response": {
    "shouldEndSession": true,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak><audio src='https://s3.../ding.mp3'/>
             I didn't hear any buttons. Please check 
             connectivity on your companion app and 
             restart the game when you're ready. 
             Goodbye.     
        </speak>"
     },

By setting shouldEndSession to true, the skill session ends after it sends Alexa this response.


    "directives": [
     {
      "type": "GameEngine.StopInputHandler",
      "originatingRequestId":"amzn1.echo-api.request.1"
     }
   ]
  }
}


This is the request ID of the request to which the skill responded with the StartInputHandler directive. In this case, the original request was the launch request.

Beginning of a Round

This section describes some of the requests and responses that occur at the beginning of a round: a response lights up the buttons a certain pattern, a request then marks the timeout of the Input Handler that ran during the pattern display, a response then sets up the lights for the user to guess the first step of the sequence, and a request then comes in when the user pushes the first button of the sequence.

Pattern Display

For each round of the game, the skill lights the buttons yellow in a certain pattern. The user must memorize this pattern so that they can press the buttons in the same order. The following example assumes that four buttons were found during roll call, so that you can see how the yellow light moves amongst the buttons to display the pattern.

Description of this example
This is a response in which the skill lights up the buttons yellow in the following pattern (using abbreviated gadget IDs here): ...1AQD, ...4N6B, ...2O4E, and ...3BQL. Each button's color at any given time in the pattern is either yellow (on) or black (off). Black is also used to briefly clear all buttons before lighting up the next button in the sequence.

To achieve the pattern, this response contains one animation sequence (SetLight directive) for each button. Across the buttons, the durations of each step in the sequence match, but the colors are different. This causes the buttons to flash in sequence. You can scroll down to examine the individual SetLight directive of each button, or you can view the animation sequences for the four buttons side by side in this image.

This response also starts an Input Handler so that the skill is notified when it is finished displaying the pattern.

What it demonstrates

Displaying a pattern across four buttons, and starting an Input Handler for the purpose of a timer.

What happened immediately before it

Roll call ended successfully, and the skill asked the user "Ok, I see we have a mission with four wires today. Is that right?" to which the user responded "Yes".

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak>
          Round 1. Here's the stink bomb   
          at city hall. Let's do this. 
          <audio src='https://s3.../ticking.mp3'/>        
        </speak>"
   },
    "directives": [
    {
     "type": "GameEngine.StartInputHandler",
     "timeout": 20000,
     "recognizers": { },                 
     "events": {
       "timeout": {
         "meets": ["timed out"],
         "reports": "nothing",
         "shouldEndInputHandler": true
        }
      }
    },

This response starts an Input Handler with a timeout equal to the estimated length of the speech response plus the light pattern that is displayed using the SetLight directives later in this response. The purpose of this Input Handler is just so that the skill is notified when the pattern has been shown and it can move to the stage of the game in which the user enters the pattern.

    {
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.1AQD"],
      "parameters": {
        "triggerEvent": "none",
        "animations": [{
          "repeat": 1,
          "targetLights": ["1"],
          "sequence": [
          {
            "durationMs": 2000,
            "color": "FFFF00",  /* Yellow */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }]
        }]
      }
    },


Animation sequence for button ...1AQD. This is the first button to light up yellow. Note that all buttons have the color set to #000000 (that is, the LED is off) for 213 seconds before the next step in the pattern.

    {
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.2O4E"],
      "parameters": {
        "triggerEvent": "none",
        "animations": [{
          "repeat": 1,
          "targetLights": ["1"],
          "sequence": [
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "FFFF00",  /* Yellow */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000", /* Black (off) */
            "blend": false
          }]
        }]
      }
    },

Animation sequence for button ...2O4E. This button is the third button in the pattern to light up yellow.

    {
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.3BQL"],
      "parameters": {
        "triggerEvent": "none",
        "animations": [{
          "repeat": 1,
          "targetLights": ["1"],
          "sequence": [
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
           }, 
           {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
            }, 
            {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
           "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "FFFF00",  /* Yellow */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }]
        }]
      }
    },


Animation sequence for button ...3BQL. This button is the fourth button in the pattern to light up yellow.

    {
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.4N6B"],
      "parameters": {
        "triggerEvent": "none",
        "animations": [{
          "repeat": 1,
          "targetLights": ["1"],
          "sequence": [
          {
            "durationMs": 2000,
            "color": "000000",
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000", /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "FFFF00",  /* Yellow */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 2000,
            "color": "000000",  /* Black (off) */
            "blend": false
          }, 
          {
            "durationMs": 213,
            "color": "000000",  /* Black (off) */
            "blend": false
          }]
        }]
      }
    }
  ]
 } 
}

Animation sequence for button ...4N6B. This button is the second button in the pattern to light up yellow.

Input Handler Timeout for Pattern Display

The previous response displayed a pattern of lights on the buttons. It also started an Input Handler to serve as a timer so that the skill would be notified after the pattern is displayed, and thus able to proceed with the next step of the game. When the Input Handler times out, the skill receives a timeout event such as the following example.

Description of this example
This is a request that the skill receives when the Input Handler that was started in the response that included the light pattern timed out. The Input Handler contains no details about any button actions that might have occurred while the pattern was displayed, because the Input Handler was configured with reports equal to nothing.

What it demonstrates

Receiving an event that contains no history within inputEvents.

What happened immediately before it

The Input Handler that was started in the previous response timed out.

{
  "version": "1.0",
  "session": {
    "application": {},
    "user": {}
   }, 
  "request": {
    "type": "GameEngine.InputHandlerEvent", 
    "requestId": "amzn1.echo-api.request.5",
    "timestamp": "2018-04-27T07:09:31Z",
    "locale": "en-US",
    "originatingRequestId":"amzn1.echo-api.request.4",
    "events": [
       {
        "name": "timeout",
        "inputEvents": [ ]
       }
     ]
   }  
}

This event was configured with reports equal to nothing, because a list of input events wasn't needed. The Input Handler was only used as a timer.

Waiting for the First Guess

Now that the skill has displayed a pattern of lights to the user, it is time for the user to reproduce the pattern. The user reproduces the pattern step by step. Each time the user presses a button to guess one step, the buttons light up for the next step.

Each step in the pattern has its own Input Handler. A step's Input Handler ends either when the user makes their guess by pressing a button, or when the Input Handler times out because the user did not press a button. The following response sets up the Input Handler for this behavior, and uses setLight directives to light up the buttons in preparation for the first step.

Description of this example
This response lights up the button with the first step in the pattern that the user must reproduce, and starts the Input Handler in preparation for the user's first guess.

What it demonstrates

Starting an Input Handler, defining a timed out event, a button down event, and lighting up the buttons different colors.

What happened immediately before it

The skill displayed a pattern of lights to the user, and the Input Handler that it set for that activity timed out.

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak>
          Don't mess this up. I have a date tonight.  
          <audio src='https://s3.../ticking.mp3'/>       
        </speak>"
    },
    "directives": [
    {
      "type": "GameEngine.StartInputHandler",
      "timeout": 20000,
      "recognizers": {
        "button_down_recognizer": {
          "type": "match",
          "fuzzy": false,
          "anchor": "end",
          "pattern": [{
            "action": "down"
          }]
        }
      },

This is a simple button down recognizer, as we have seen previously.


      "events": {
        "timeout": {
          "meets": ["timed out"],
          "reports": "nothing",
          "shouldEndInputHandler": true
        },


This event is sent if the user doesn't press any buttons. In that case, the user loses.





        "button_down_event": {
          "meets": ["button_down_recognizer"],
          "reports": "matches",
          "shouldEndInputHandler": true
        }
       }
    },







Here, shouldEndInputHandler is set to true because this Input Handler is only waiting for one button press from the user. After that button press, the skill logic will check whether the button press was correct, and then respond to the user accordingly. If the button press was correct, the skill will set up a new Input Handler for the next step in the pattern.


    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.1AQD"],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 1,
          "sequence": [{
            "durationMs": 2000,
            "color": "FFFF00",  /* Yellow */
            "blend": false
           }]
        }]
      }
    }, 
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.2O4E"],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 1,
          "sequence": [{
            "durationMs": 2000,
            "color": "0000FF",  /* Blue */
            "blend": false
           }]
        }]
      }
    }, 
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.3BQL"],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 1,
          "sequence": [{
            "durationMs": 2000,
            "color": "FF00FF",  /* Magenta */
            "blend": false
           }]
        }]
      }
    }, 
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.4N6B"],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 1,
          "sequence": [{
            "durationMs": 2000,
            "color": "FF0000",  /* Red */
            "blend": false
           }]
        }]
      }
    }
  ]
 }
}

To begin a round, the skill lights up all the buttons. Based on the pattern that the skill showed the user previously, the yellow button, ...1AQD, is the correct one for the user to press.

User Presses a Button

When the user presses a button to guess a step of the sequence, the skill receives a button_down_event request as defined by the Input Handler configuration. The following is an example of this type of event.

Description of this example
This is a request that the Game Engine sends the skill to notify the skill that a button_down_event occurred.

What it demonstrates

Syntax of an event, the button action that caused the event to be sent.

What happened immediately before it

A user pressed a button to guess a step of the sequence.

{
  "version": "1.0",
  "session": {
    "application": {},
    "user": {}
   }, 
  "request": {
    "type": "GameEngine.InputHandlerEvent",  
    "requestId": "amzn1.echo-api.request.6",
    "timestamp": "2017-08-18T01:32:40.027Z",
    "locale": "en-US",
    "originatingRequestId":"amzn1.echo-api.request.4",
    "events": [
     {       
        "name": "button_down_event",
        "inputEvents": [
          {
            "gadgetId": "amzn1.ask.gadget.1AQD",
            "timestamp": "2017-08-18T01:32:40.027Z",
            "feature": "press",
            "action": "down",
            "color": "FFFF00"  /* Yellow */
          }
        ]
      }
    ]
  }
}

This is the action that caused the button_down_recognizer, as defined by the Input Handler, to be true. This shows the ID of the button that the user pressed, and that it was yellow when they pressed it. The skill logic will need to confirm that this guess is correct, and respond accordingly.

End of a Round

A round ends when the user either succeeds in pressing the buttons in the correct order, or presses a wrong button and loses. The skill logic examines the button input events, determines which is the case, and responds accordingly. This section contains a response that is sent when the user wins, and when the user loses.

Round Won

If the user presses the buttons in the correct order, the skill plays a cheering noise and pulses all the buttons green. The following is an example of this response.

Description of this example
This response, which the skill sends in response to the final button press event in a winning round, congratulates the user, makes a cheering noise, and pulses the lights green.

What it demonstrates

A pulsing green animation, speech, and audio.

What happened immediately before it

The user correctly pressed the last button in the sequence. Upon receiving the button press event, the skill logic determined that the user pressed the correct button, and that it was the last in the sequence.

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak><audio src='https://s3.../cheering.mp3'/>
        The sergeant is going to buy a round for 
        the whole team.        
        </speak>"
    },
    "directives": [
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.1AQD", 
                        "amzn1.ask.gadget.2O4E",
                        "amzn1.ask.gadget.3BQL",
                        "amzn1.ask.gadget.4N6B"],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 2,
          "sequence": [{
             "durationMs": 400,
             "color": "00FE10", /* Green */
             "blend": true
           },
           {
            "durationMs": 300,           
            "color": "000000",  /* Black (off) */
            "blend": true
           }
          ]
        }]
      }
    }]
  }
}

This animation achieves a pulsing effect by alternating between a color and #000000 (off), with blend set to true.

Round Lost

If the user presses a wrong button, the skill plays an explosion noise and pulses all the buttons red. The following is an example of this response.

Description of this example
This response, which the skill sends in response to a button press event in which the user pressed the incorrect button, plays a sound effect, flashes the lights red, and displays an image on devices that have a screen.

What it demonstrates

A flashing red animation, speech, audio, displaying an image.

What happened immediately before it

The user pressed the wrong button. Upon receiving the button press event, the skill logic determined that the user's choice was incorrect.

{
  "version": "1.0",
  "response": {
    "shouldEndSession": false,
    "outputSpeech": {
      "type": "SSML",
      "ssml": "
        <speak>
          <audio src='https://s3.../explosion-aww.mp3'/>
        </speak>"
    },
    "directives": [
    {
     "type": "Display.RenderTemplate",
     "template": {
       "type": "BodyTemplate1",
       "token": "bombExploding",
       "title": "Don't Cut That Wire",
       "backgroundImage": {
         "sources": [{
         "url": "https://s3.../explosion.png"
         }]
       }
      }
    },

Users with Alexa-enabled devices that have a screen, like Echo Show, typically expect skills to use the display at least minimally. Consider including a simple graphic at key points in your game, as this skill does here.

  
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": ["amzn1.ask.gadget.1AQD", 
                        "amzn1.ask.gadget.2O4E",
                        "amzn1.ask.gadget.3BQL",
                        "amzn1.ask.gadget.4N6B"],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 2,
          "sequence": [{
            "durationMs": 400,
            "color": "FF0000",  /* Red */
            "blend": false
           },
           {
            "durationMs": 200,
            "color": "000000",  /* Black (off) */
            "blend": true
           },
           {
            "durationMs": 300,
            "color": "FF0000",  /* Red */
            "blend": false
           },
           {
            "durationMs": 200,
            "color": "000000",  /* Black (off) */
            "blend": true
           }
          ]
        }]
      }
    }]
  }
}

This animation flashes the buttons red for a bomb exploding effect. This animation is more of a flash than a pulse because blend is set to false when the color switches to red.

Animations

Using animations and audio throughout Echo Button skills, especially when waiting for the user to press the buttons, is a best practice. These indicate to the user that the skill is still in session.

Blue-Magenta-Red-Black Animation

The following animation, which is used in Don't Cut That Wire, pulses the buttons a sequence of blue, magenta, red, and black.

Description of this example
This response lights up all buttons that are paired to the Echo device a sequence of blue, magenta, red, and black. The skill can send this response to Alexa in response to any request.

What it demonstrates

Sending a colorful sequence to all paired buttons.

What happened immediately before it

Any request that Alexa makes of the skill.

{
  "version": "1.0",
  "response": {
    "directives": [
    { 
      "type": "GadgetController.SetLight",
      "version": 1,
      "targetGadgets": [],
      "parameters": {
        "triggerEvent": "none",
        "triggerEventTimeMs": 0,
        "animations": [{
          "targetLights": ["1"],
          "repeat": 3,
          "sequence": [{
            "durationMs": 800,
            "color": "0000FF",  /* Blue */
            "blend": true
           },
           {
             "durationMs": 800,
             "color": "FF00FF",  /* Magenta */
             "blend": true
           },
           {
             "durationMs": 800,
             "color": "FF0000",  /* Red */
             "blend": true
           },
           {
             "durationMs": 500,
             "color": "000000",  /* Black (off) */
             "blend": true
           }           
          ]
        }]
      }
    }]
  } 
}

By leaving targetGadgets empty, this directive is broadcast to all buttons that are paired to the Echo device.