Use Skill Flow Builder to Create Your Content

Skill Flow Builder offers designers and game creators many options for structuring their content, logic, images, and audio.

Create the flow of your narrative.

Create a scene

When a player opens your game for the first time, your skill should respond and prompt the player. Define the first-time launch behavior by creating a start scene. The following example shows a start scene that instructs Alexa to say "Welcome to my awesome game!"

@start
    *say
        Welcome to my awesome game!

Every scene starts with the scene name following the at sign (@) on a new line. In the example, the scene name is start. Skill Flow Builder reserves a few scene names such as start. Only use these scene names for special behavior. For more information about reserved scene names, see Special scenes in the Skill Flow Builder Reference.

Add content to the scene by using a scene property such as *say, which tells Alexa what to say during the scene. Specify the scene property on a new line with an asterisk (*) followed by the property name.

    *say
        Welcome to my awesome game!

The sentence Welcome to my awesome game! is the content of the *say property. Content can continue for multiple lines until you define another scene property with *, or another scene with @. Indentation is optional. For more information see Scene properties in the Skill Flow Builder Reference

Give choices to the player

The following example shows a start scene where the player can choose to be a pirate or merchant.

@start
    *say
        Welcome to my awesome game!
        Do you want to be a pirate or a merchant?
    *then
        hear I want to be a pirate, pirate, I'll be a pirate {
            -> choose pirate
        }

        hear I want to be a merchant, merchant, I'll be a merchant {
            -> choose merchant
        }

The scene uses the *say property to have Alexa say "Welcome to my awesome game! Do you want to be a pirate or a merchant?", and uses the *then property to list the following instructions:

        hear I want to be a pirate, pirate, I'll be a pirate {
            -> choose pirate
        }

The hear instruction tells Alexa to listen for specific words or phrases and then do something. You can list synonyms by using commas to separate the entries.

In the example, Alexa listens for "I want to be a pirate," "pirate," or "I'll be a pirate." If Alexa hears any of the phrases from the player, Alexa executes the instructions listed between { and }.

If the player says "pirate", Alexa executes -> choose pirate, which tells Alexa to go to the scene "choose pirate". The transition for the go to instruction occurs immediately, and the remaining instructions within the scene don't execute. For more information see (go to) in the Skill Flow Builder Reference.

String multiple scenes together

Sometimes, you might want to transition between scenes without player input. Consider the following two examples:

Example 1:

@start
    *say
        Welcome to my awesome game!
        Do you want to be a pirate
        or a merchant?
    *then
        hear pirate {
            -> choose pirate
        }
        hear merchant {
            -> choose merchant
        }

Example 2:

@start
    *say
        Welcome to my awesome game!
    *then
        -> choose your trade

@choose your trade
    *say
        Do you want to be a pirate
        or a merchant?
    *then
        hear pirate {
            -> choose pirate
        }
        hear merchant {
            -> choose merchant
        }

Implement Game Logic

The two examples result in identical experiences for the player. However, you might find Example 2 more useful for the following reasons:

  • Later on in your game, you can go directly to @choose your trade question without having to say, "Welcome to my awesome game!"
  • If the player doesn't say anything and Alexa has to repeat the question, Alexa only says the question from the most recent scene.

if

Use if to specify conditions.

    *then
        if not enraged {
            increase fear by 2
        }
        if fear is greater than 10 {
            -> fear warning
        }
        -> next room

Conditions defined after if must be satisfied. In other words the conditions must be true, to execute the instructions under the if statement.

An if statement has the following characteristics:

  • Has instructions that must be surrounded by curly brackets
  • Can be inside or contain a hear statement
  • Can be nested
  • Can use ! in front of a value, where ! means "not"
  • Supports operators:
    • is
    • ==
    • is greater than
    • >
    • is greater than or equal
    • >=
    • is less than
    • <
    • is less than or equal
    • <=
    • is not
    • !=
    • and
    • &&
    • or
    • ||
    • ()

Save player decisions, inventory, or progress

You might want to save information about the player for use later in your game. The following list shows examples of this player information:

  • The player visited Paris
  • The player talked to the wizard
  • The player told the wizard no
  • The player found the skeleton key

The following example shows how to use the flag instruction to save information:

*then
    flag visitedParis
    flag talked_to_wizard
    flag toldWizardNo

Similarly, you can set a flag based on player choice:

*then
    hear pick up the key {
        flag skeletonkey
        -> escape room
    }

If the player says, "pick up the key," a flag named skeletonkey is set, and the game continues to a scene called escape room.

Use the unflag instruction to unset the flag. For example, if the player loses the skeleton key in a scene, unset the flag in the following manner:

    *then
        unflag skeletonkey

For more information about flag and unflag instructions see Set, increase, decrease, clear, flag, unflag, in the Skill Flow Builder Reference.

Use saved player decisions, inventory, or progress to do something

After saving information about a player, you might want to use the information to determine if something should happen.

For example, perhaps a player can only open a door if the player has a skeleton key:

@escape room
    *say
        You are in a room.
    *then
        if skeletonkey {
            -> open door
        }

        -> door locked

If the player flagged skeletonkey earlier in the game, the game continues automatically to a scene called open door. If the player unflagged skeletonkey earlier in the game or never flagged, the game continues automatically to a scene called door locked.

Use the instruction to tell Alexa to check whether the statements after if are true or false. When the statement that follows if is true, for example, the player has set a flag, Alexa executes the instructions between the beginning curly bracket ({) and the ending curly bracket (}). If the player has not set the flag, the if instruction interprets the statement as false, and skips the instructions listed between the beginning curly bracket ({) and the ending curly bracket(}).

Any flag that the player never declares evaluates to false. For more information, see If in the Skill Flow Builder Reference.

The following examples show how to use a not (!) symbol within an if statement. The examples are logically the same and result in the same player experience:

Example 1:

@escape room
    *say
        You are in a room.
    *then
        if skeletonkey {
            -> open door
        }

        -> door locked

Example 2:

@escape room
    *say
        You are in a room.
    *then
        if !skeletonkey {
            -> door locked
        }

        -> open door

The following example shows how to perform multiple instructions inside an if instruction, such as flag or `unflag.' You might find this useful if you intend a skeleton key as a single-use item in the game.

*then
        if skeletonkey {
            unflag skeletonkey
            -> open door
        }

Check more than one flag

Check more than one flag within an if statement by using and or or:

*then
        if skeletonkey and talked_to_wizard {
            -> open door
        }

You might want to use this if you intend for the player to only be able to open the door if the player has the skeleton key and has also talked to the wizard. In the example, you must set both flags for the statement to be true.

The following example shows how to apply or.

*then
        if skeletonkey or talked_to_wizard {
            -> open door
        }

You might want to use this if you intend the player to open the door if the player has the skeleton key or has talked to the wizard, or both.

Set and use variables

Use variables to work with values that you can't determine until players play. For example, create a variable called playerClass to store the character class the player chooses during the game.

The following example shows how to set the player's class based on what the user says:

@choose class
    *say
        Please choose a class. Are you a warrior, a mage,
        or a thief?
    *then
        hear warrior {
            set playerClass as 'warrior'
            -> play introduction
        }

        hear mage {
            set playerClass as 'mage'
            -> play introduction
        }

        hear thief {
            set playerClass as 'thief'
            -> play introduction
        }

In the *then section of the scene, Alexa listens for the player to say "warrior", "mage", or "thief". After the player says any of the expected words, the variable called playerClass receives one of the following values:

  • Set the class to 'warrior' if the user says 'warrior'.
  • Set the class to 'mage' if the user says 'mage'.
  • Set the class to 'thief' if the user says 'thief'.

Use variables in narration

To personalize narration, consider using a variable in the *say and *reprompt section by wrapping the variable with curly brackets ({}). The following example shows how to do this.

@play introduction
    *say
        welcome to our mysterious world. Your class is {playerClass}.

The player hears the phrase with {playerClass} replaced with the value of the variable.

Use variables in game logic

Use variables to control game behavior:

@play introduction
    *say
        welcome to our mysterious world. Your class is {playerClass}.
    *then
        if playerClass is 'mage' {
            -> mage start
        }

        if playerClass is 'warrior' {
            -> warrior start
        }

        if playerClass is 'thief' {
            -> thief start
        }

In the example, the value stored in the variable playerClass determines the next scene.

You can also store numbers in a variable and manipulate the variable as the game plays out. The following example shows a starting value for the variable named playerHealth:

set playerHealth as 10

The following example reduces the value of the variable:

@take damage
    *say
        You take 1 damage.
    *then
        decrease playerHealth by 1

        if playerHealth <= 0 {
            -> game over
        }

The example reduces the value stored in the variable playerHealth, and then immediately checks whether to transition to the scene called gameover. The example does so by checking whether the value is less than zero.

The decrease command decreases the value stored in a variable by the number indicated. For instructions related to variables, see Set, increase,decrease,clear,flag,unflag, in Skill Flow Builder Reference.

If you have never declared a variable, any statement that evaluates the variable returns false. For example, if you don't declar playerHealth, if playerHealth <= 0 returns false, and the game logic proceeds as if playerHealth is a positive value.

Use randomness to make decisions for players

To make a random decision in your game, or to generate a random number for dynamic content for your game, you can use the roll instruction.

The roll instruction takes one argument that combines the number of dice, and the number sides on the dice to roll and returns a result that ranges between 1 and the highest number possible. To roll a standard six-sided die, you can write roll 1d6, or to flip a two-sided coin you can write roll 1d2. If you use the roll instruction on a line by itself, the game stores the result in a special variable called rollResult that you can check on subsequent lines.

The following example shows that when a user says, "Choose for me," the roll instruction sends the player to @scene one or @scene two randomly:

*then
    hear choose for me {
        roll 1d2
            if rollResult == 1 {
            -> scene one
            }
        -> scene two
    }

Add visuals elements

Add Alexa Presentation Language (APL) to your skill by using the *show property to define the visual elements for your scene.

@My Showy Scene
    *say
        Let's go on a hike.
    *show
        template: 'default'
        background:'https://www.example.com/url/to/image.jpg'
        title: 'ACE Framework'
        subtitle: 'Start of the hike'
    *then
        -> startHike

The example defines the following visual elements:

  • 'template' to use the APL template in your project that you named "default"
  • 'background' to be the specified image.
  • 'title' to be 'ACE Framework'.
  • 'subtitle' to be 'Start of the hike'.

For the example story included with the Skill Flow Builder, the file content/en-us/example_story/resources/apl-templates.json defines the APL templates for the story. The example apl-templates.json file defines the "default" template under a "default" key.

The APL templates define the structure of the visual interface. For each APL template, to expose components so that you can pass in content using the *show section in your scene, in the apl-templates.json file, specify the components as datasources. The following example shows an implementation of datasources.

{
    "default": {
        ...
        "datasources": {
            "visualProperties": {
                "background": "https://www.example.com/url/to/image.jpg",
                "title": "",
                "subtitle": ""
            }
        }
    }
}

For each component, specify "" if there is no default value for the component, or specify a default value surrounded by double quotes (").

For more information about creating your own APL templates, see Alexa Presentation Language.

Add visual elements to all scenes

To add a screen that shows by default unless overridden by the specific scene, add a *show property to the @global prepend scene as shown in the following example.

// add visuals to every scene
@global prepend
    *show
        template: 'default'
        background:'https://www.example.com/url/to/image.jpg'
        title: 'ABC Framework'
        subtitle: ''
    *then
        // listen for "start over" everywhere
        hear start over {
            // Go back to the start
            -> start
        }

The example adds a global start over command to all scenes that takes the player back to the start when they say "start over".

The @global prepend is similar to @global append used in the sections Let players restart from anywhere and Add a help menu in Basic Skill Flow Builder Syntax. The @global prepend and @global append are similar because you use them in all other scenes, but you apply them differently in each scene. You would use @global prepend before a scene. You would use `@global append' after a scene.

Add sound effects

You can use any Speech Synthesis Markup language (SSML) tag that Alexa supports to customize your content. To use sound effects and audio files within your content, use the SSML audio tag. For more information see audio tag in the SSML Reference.

@start
    *say
        Welcome to my awesome game!
        <audio src='https://s3.amazonaws.com/.../yourAudioFile.mp3' />
        Do you want to be a pirate or a merchant?

Add different voices

You can use a voice SSML tag to use various voices in your Alexa skill. For more information about voices, see voice in the Speech Synthesis Markup Language (SSML) Reference.

    @start
        *say
            <voice name='Kendra'>I am not a real human.</voice>.

bgm (background music)

    *then
        bgm https://url-to-the-background-music.mp3

Mix background music for the scene's narration.

You can mix background music for a scene's narration. Background music only works when you mix with foreground audio or narration using custom Amazon Polly. You can't mix music with Alexa's voice. Insert bgm after *then.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment