Skill Flow Builder Reference

The Skill Flow Builder provides the following metadata format for games and stories.

• Scene properties
• Scene instructions
• Special terminators
• Special scenes
• Core extensions

Scene properties

In the Skill Flow Builder, scenes are the basic building blocks. Scenes contain various types of content and can be connected in any way you want to create your story or game.

The following shows the structure of a scene:

@scene name
    *say
        content
    *reprompt
        content
    *show
        content
    *then
        scene instructions

The scene name identifies the scene. The scene name:

• Must start with @
• Can be any number of letters, numbers, and spaces
• Must be unique within your story
• Must be contained within the line

Some scene names are reserved for special purposes. For more information, see special scenes.

*say

When the scene plays, Alexa reads aloud to the user the content defined within the *say property. The *say property:

• Is optional
• Can be multiple lines
• Can use SSML
• Can use || to denote variations
• Can inject variable values with curly brackets

|| (dialogue variation)

    *say
        something like this
        ||
        or something like this

|| specifies variations to be selected randomly and can help make your story feel less stale for repeated content. You can use dialogue variation on *say, *reprompt, and *recap.

*reprompt

Alexa reads aloud the content within the *reprompt property if the player doesn't say anything when your game expects a player response. By default, if you do not specify *reprompt, Alexa reprompts the user with the *say content from the last scene.

Like *say, the *reprompt property:

• Is optional
• Can be multiple lines
• Can use SSML
• Can use || to denote variations
• Can inject variable values with curly brackets

*recap

Alexa reads aloud the content within the *recap property if the player responds with an unexpected response.

Like *say, the *recap property:

• Is optional
• Can be multiple lines
• Can use SSML
• Can use || to denote variations
• Can inject variable values with curly brackets

*show

If the player is on a device that supports visual content, the device displays the visual components assigned within this section. See Add visuals.

*then

The *then property provides a list of scene instructions, which are commands that are executed in order after Alexa plays the content for the scene.

Scene instructions

-> (go to)

A terminator that specifies that the Skill Flow Builder should transition to another scene.

    *then
        -> start

The -> instruction:

• Must be followed by a scene name
• Supports variable injection with curly brackets, so if the variable named two has a value of 2, then -> scene {two} would go to @scene 2.
• Is a terminator, which means that it indicates the end of the scene. As soon as a terminator executes, the process immediately moves to the next scene.

hear

The hear instruction specifies the words or phrases to listen for, and what should happen if heard.

    *then
        hear run, get out of here, go {
            decrease courage by 1
            -> run
        }
        hear hide {
            set fear to 10
            -> hide
        }

The hear instruction:

• Can specify multiple phrases to listen for, separated by commas
• Must be surrounded by curly brackets
• Can be inside an if or contain an if statement

if

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

Use if to specify conditions. Conditions defined after if need to be satisfied, in other words be true, to execute the instructions under the if statement.

An if statement:

• 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
  • <=
  • is not
  • !=
  • and
  • &&
  • or
  • ||
  • ()

Set, increase, decrease, clear, flag, unflag

The following instructions set and manipulate variables:

    *then
        set fear to 2       // fear = 2
        increase fear by 10 // fear = fear + 10 = 12
        decrease fear by 5  // fear = fear - 5 = 7
        flag scared         // scared = true
        unflag scared       // scared = false
        clear fear          // fear = null
        clear *             // clear all variables setup by your story/game
        -> start

<-> (go to and return)

You can use the <-> instruction to go to a reusable scene and then return to the flow of your game.

@start
    *then
        <-> test your luck
        >> END

@test your luck
    *say
        You are not lucky.
    *then
        >> RETURN

<-> test your luck takes the player to @test your luck scene, then >> RETURN takes the player back to the line after the <-> instruction.

<-> is a special type of terminator in that instructions after <-> do not execute until a >> RETURN instruction is executed. You can string multiple <-> and multiple >> RETURN instructions together.

bookmark

You can use the bookmark instruction if you want to save the current scene and transition to the same scene later. The following example shows a global listener for "how much money do i have". When the player says this utterance, the bookmark command saves the scene the player is currently on, and then moves on to the @money report scene. From that scene, the -> bookmark command takes the player back to the scene where the instruction bookmark was last executed.

@global prepend
*then
    hear how much money do i have {
        bookmark
        -> money report
    }

@money report
*say
    You have 500 dollars.
*then
    -> bookmark

-> (go to) *property

You can decide what speech property to play as scene transitions. As soon as the transition happens the contents written in the *say section play for the player. You can follow the example below to have the transition play the *recap content instead.

This example also shows the player in the @you cannot do that scene is taken to @menu scene, and as a result of this transition, the player hears "you know me. What do you do?" instead of "Hello this is your menu. What do you do?"

@you cannot do that
*say
    You cannot do that!
*then
    -> menu *recap

@menu
*say
    Hello this is your menu. What do you do?
*recap
    you know me. What do you do?

Special terminators

By convention, you can write special terminators in all caps. However, special terminators function correctly regardless of capitalization.

» RESTART

The >> RESTART terminator:

• Restarts the story or game by executing the start sequence, or onStart function, for all attached extensions
• Resets available choices
• Goes to @start scene

This terminator does not clear the variables used within the game, which helps prevent removal of persistent variables that you want to keep across multiple sessions of your game. To clear variables, run the clear * command.

» PAUSE

The >> PAUSE terminator:

• Pauses the story by immediately stopping the execution of any remaining instructions
• Executes the pause sequence, or onSessionEnded function, for all attached extensions
• If @pause scene is defined, plays the content within the scene before pausing completely

» RESUME

The >> RESUME terminator resumes the game by going to the scene where the player last left off.

This terminator controls the Relaunch behavior as described in the section Control relaunch behavior.

» REPEAT

The >> REPEAT terminator replays the audio artifact that the player just heard, or would have heard previously.

» REPROMPT

The >> REPROMPT terminator replays the audio artifact that was used as a re-prompt.

» BACK

The >> BACK terminator goes back to the start of the previous interaction. An interaction is when a player is prompted to say something to Alexa, such as "yes" or "no."

The start of the previous interaction may be several scenes away from the interaction you want to go back to.

If the previous interaction took the player through multiple scenes, the player is taken back to the first scene when they say "go back."

» END

The >> END terminator:

• Ends the story or game by ending the session.
• Immediately runs the START sequence, running onStart functions for extensions, and setting the next scene to @start.
• The next time player launches the game, takes the player to @start.

» RETURN

The >> RETURN terminator immediately jumps back to the line after the last <-> instruction.

Special scenes

Special scenes have useful behaviors that differentiate them from other scenes.

@start

The @start scene is required and is where your game begins for a new user or after a restart.

@start
    *say
        Your story is starting. Hold on to your hats.
    *then
        -> setup

@resume

The @resume scene plays when a player comes back to the game. You can take the player back to where they left off by using a >> RESUME instruction.

@resume
    *say
        Welcome back to the story. Picking up where you left off.
    *then
        >> RESUME

@pause

The @pause scene plays before the game pauses because of normal pausing behavior, or from executing a >> PAUSE instruction.

    @pause
        *say
            Okay, goodbye for now.

@global prepend

The content of @global prepend is prepended to every scene within the game.

@global prepend
    *say
        Bing!

For an example, see Add visuals to all scenes.

@global append

The content of @global append is appended to every scene within the game.

@global append
    *then
        hear help {
            -> help message
        }
        hear status, what is my status, tell me my status{
            -> status message
        }

For an example, see Let players restart from anywhere.

Core extensions

roll and rollResult

     *then
        roll 2d6,
        set attack to rollResult
        -> resolve attack

Use the roll instruction to roll dice, and use the rollResult to access the result of the roll. The example rolls two six-sided dice and puts the resulting total into the variable rollResult.

• Roll accepts XdY as input where X and Y are whole numbers. X represents the number of dice you are rolling, and Y indicates the number of face on the dice you are rolling.
• You can add or subtract numbers from the roll by writing something like 1d6 + 3 or 1d6 - 3.
• You can roll multiple dice and pick and add the highest Z values with a format XdYkZ, where X is the number of dice, Y is the number of faces, and Z is the number of highest values you want to pick. For example, roll 2d6k1 rolls two six-sided dice and picks the highest number out of the two rolls.

time

    *then
        time
        set timeSinceLast as system_return
        decrease timeSinceLast by lastUpdateTime
        if timeSinceLast >= 300000 {
            -> long time no see
        }

The time instruction saves the current time into a special system variable called system_return. To use the time in your game, assign it to one of your own variables using the set instruction. The time is in epoch milliseconds, which is the number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT).

bgm (background music)

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

Mix background music for the scene's narration.

Background music only works when mixed with foreground audio or narration using custom Amazon Polly. You cannot mix music with Alexa's voice. Music mixing also does not work in preview mode of the editor.

monetization

    *then
        buy item='sample product' success='purchase success' fail='purchase failed'
        declined='purchase declined'
        already_purchased='purchased already' error='purchase error'

Start the monetization workflow for the in-skill product (ISP) mapped to the item name in the ISP ID config file located in the path resources/ProductISPs.json of your project directory. Once the purchase flow finishes successfully, the player is taken to the scene defined by "success", or to @purchase success in the example. If the purchase fails or is cancelled, it transitions to the scene defined by "fail", or to @purchase failed in the example.

The parameters declined, already_purchased, and error are optional. If you do not assign the parameters, the player is taken to the scene defined by the fail parameter. To finely control which scenes the player is taken to on each purchase flow, define the parameters.

You can offer refunds by using the refund instruction. You can trigger the refund monetization workflow by using the refund instruction. Once the refund flow finishes successfully, the skill takes the player to the scene defined by "success", or to @refund success. If the refund flow fails or cancels, the skill transitions to the scene defined by "fail", or to @refund failed.

The following example shows how you can trigger the refund monetization workflow.

    *then
        refund item='sample product' success='refund success' fail='refund failed'