Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

Set up the Skill Flow Builder as a Developer

With Skill Flow Builder you can use a metadata format to create content for games and stories including interactive fiction, role-playing games, and adventure games. The suite provides:

  • A standard format for games and stories.
  • Built-in extensions to add game logic, and hooks to implement custom functions and instructions within your game.
  • A virtual Alexa emulator that provides simulation, with features for you to save and load the current state of the game or story.
  • A graphical user interface (UI) to edit and test your content.
  • A command line interface for developers.

As a developer you can use Skill Flow Builder to integrate content from writers or designers into language Alexa can understand.

Get started

  • Install the latest version of Git.
  • Install the latest version of the Amazon Web Services (AWS CLI).
  • (Windows only) Install the latest version of the windows-build-tools module.
  • Install Python. On Windows, use Python version 2.7.14. Skill Flow Builder doesn't run correctly on Windows with the latest version of Python. On the Mac, use Python version 2.7.14 - 2.7.16.

Prerequisite

When you install Node.js, the installation includes Node Package Manager (NMP). To install the Skill Flow Builder, you need to modify the NPM configuration.

  • Install Node.js version 10.15 or later.

Install and set up SFB CLI globally

You can set up the SFB CLI globally so that you can run commands for the Skill Flow Builder from any directory. Or you can set up the alexa-sfb package locally:

To install and set up SFB CLI globally

Open a command prompt or terminal, type the following code, and then press Enter.

npm install --global @alexa-games/sfb-cli

To install and set up the SFB CLI locally

Alternatively, instead of globally setting up the CLI, you can set it locally.

  1. Change the directory to the one where you want to set up the alexa-sfb package locally.

  2. Open a command prompt, type the following code, and then press Enter.

npm install @alexa-games/sfb-cli

To run the CLI

If you set up the CLI globally, use npx alexa-sfb. Or if you set up the alexa-sfb package locally, change the directory to the local directory, type the following code, and then press Enter.

npx alexa-sfb

Install and set up the Visual Studio Code Extension

Install the latest version of Visual Studio Code. Amazon has optimized Skill Flow Builder for Visual Studio Code.

Install a language extension for Visual Studio Code to provide syntax highlighting, error diagnostics, and definition jumps. Open a command prompt, at the root folder for your project, type the following code, and then press Enter.

npx alexa-sfb vscode

In Visual Studio Code, a definition jump allows you to jump to the file and line that defines a scene. For example, if your content contains the instruction -> myscene, click myscene and then press F12 or right-click and select Go to Definition to go to the line that defines the scene.

Create the skill project

After you've installed and set up your Skill Flow Builder software, you are ready to create your skill project for your new game or story.

To create your skill project

Open a command prompt, type npx alexa-sfb new and then type a path to the folder where you want to store the files or your game or story, for example:

npx alexa-sfb new my_best_story

Debug skill content using the simulator

You can run the simulator to play through your content and verify the behavior of the content. The simulator tests the runtime execution of the content, not the skill.

To preview content with the simulator

Open a command prompt, type the following code, and then press Enter.

npx alexa-sfb simulate <your_project_path>

Deploy your Alexa Skill

After you have debugged your content with the simulator, complete the following steps to deploy your game or story as an Alexa skill.

Step 1: Set up your ASK profile

To being to deploy your Alexa skill

  1. Set up your Alexa Skills Kit (ASK) profile with your developer account, and link your AWS account. Open a command prompt, type the following code, and then follow the prompts. ask init

To use an ASK profile other than "default".

Open <your_project_path>/abcConfig.json and then edit the attribute "ask-profile-name" to specify the profile you want to use.

  1. You must provide a working AWS account with AWS account security credentials set up for your user.
  2. If you don't have an IAM user with credentials, open the AWS console.
  3. Click the "IAM" tab, click "Add User," and then create a new user name.
  4. Select the check box for "programmatic access," and then grant a policy with the following structure:

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Sid": "SFB Developer",
                 "Effect": "Allow",
                 "Action": [
                     "iam:AttachRolePolicy",
                     "iam:CreateRole",
                     "iam:GetRole",
                     "iam:PassRole",
                     "lambda:AddPermission",
                     "lambda:CreateFunction",
                     "lambda:GetFunction",
                     "lambda:ListFunctions",
                     "lambda:UpdateFunctionCode",
                     "logs:DescribeLogStreams",
                     "logs:FilterLogEvents",
                     "logs:GetLogEvents",
                     "s3:GetObject",
                     "s3:PutObject",
                     "s3:PutObjectAcl",
                     "polly:SynthesizeSpeech"
                 ],
                 "Resource": "*"
             }
         ]
     }
    

Step 2: Update the skill configuration

You can create and deploy your skill without changing any configuration.

To update the configuration

  1. Open <your_project_path>/abcConfig.json, and then update the following information in the skill configuration file:

    • "ask-skill-directory-name": The name of your skill as used by the ASK CLI. Your AWS Lambda function name and the skill name derive from this value. You can use contain upper and lowercase letters (A-Z, a-z), numbers (0-9), underscores (_), and dashes (-).

    • "skill-invocation-name": Defines how your skill is invoked by users. For more information, see Understand How Users Invoke Custom Skills.

    • "publish-locales": A list of Alexa-supported locales where you can publish the skill.

Step 3: Finish the Deployment

To finish the deployment of your skill

  1. Open a command prompt, type the following code, and then press Enter.

     npx alexa-sfb deploy <your_project_path>
    
    
  2. If your skill fails to publish with the error "AccessDenied: User: arn:aws:iam::... is not authorized to perform: iam:CreateRole on resource: ..., in the AWS console, go to IAM, and then verify that your user has the policy described in Step 1: Set up your ASK profile.

Step 4: Set up AWS IAM role

After you create the skill in your developer account and create the AWS Lambda function, you need to add permissions. You add permissions for DynamoDB, Amazon S3, and Amazon Polly to the IAM role created for your AWS Lambda function.

The name of the default role created for your skill is `ask-lambda-"your skill project name"``

There should already be a managed policy for the role `AWSLambdaBasicExecutionRole` for running the skill code on AWS Lambda.

To add a new policy so that AWS Lambda function can access DynamoDB

In the AWS Console, add the following policy:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SFB Lambda",
            "Effect": "Allow",
            "Action": [
                "dynamodb:CreateTable",
                "dynamodb:PutItem",
                "dynamodb:DeleteItem",
                "dynamodb:GetItem"
            ],
            "Resource": "*"
        }
    ]
}
```

To add further permissions to the above policy, see the section [Set up Amazon Polly voices (Optional)](#polly).

<div markdown="span" class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> You might need to change some of the default AWS Lambda settings. In the AWS console, find your AWS Lambda function and change the following settings:
* Verify the runtime environment is Node.js 8.10
* Verify the timeout is set to at least 15 seconds</div>

Step 5: Launch your skill

  1. On your Alexa device, test your skill by saying the wake word, followed by the invocation name. For example, say, "Alexa, open the Hi Low Game."
  1. Wait about 15 seconds for the AWS Lambda function to create the DynamoDB table, and then say the wake word, followed by the skill invocation name. For example, say, "Alexa, open the Hi Low Game.

Use core extensions

roll and rollResult

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

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

Details

  • 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

The time instruction saves the current time into a special system variable called system_return.

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

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).

monetization

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.

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

After 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 don't 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.

Create a custom extension

While creating your content, you might need to create a custom command to run your own code during a particular scene. You can implement one of the three extension interfaces from the sfb-f module to customize and add features and functionalities to your SFB built skill. The three extensions are:

  • ImporterExtension - applied before or/and after importing a source content as a StoryMetadata
  • DriverExtension - applied before or/and after the request has been applied for the story run.
  • InstructionExtension - applied during the story run to handle custom instructions within the content.

ImporterExtension

Import this interface from @alexa-games/sfb-f module to implement. The following example shows the interface:

interface ImporterExtension {
    extendSourceContent(sourceHelper: SourceContentHelper): Promise<void>;

    extendImportedContent(metadataHelper: StoryMetadataHelper): Promise<void>;
}

Details

  • Implement ImporterExtension to add custom logic for the content import step.

  • extendSourceContent is invoked right before the raw text of the source file is imported as a StoryMetadata.

  • extendImportedContent is invoked after the importing is finished. Typically, it is implemented to modify some components of the resulting StoryMetadata.

DriverExtension

Import this interface from @alexa-games/sfb-f module to implement. The following example shows the interface:

interface DriverExtension {
    pre(param: DriverExtensionParameter): Promise<void>;

    post(param: DriverExtensionParameter): Promise<void>;
}

Details

  • Implement DriverExtension to add custom logic for before and/or after driver execution.

  • pre is invoked before the driver runs. Typically, it is implemented to customize the request parsing logic before the driver runs.

  • post is invoked after the driver runs. Typically, it is implemented to customize the response construction logic.

InstructionExtension

Import this interface from @alexa-gamessfb-f module to implement. The following example shows the interface:

interface InstructionExtension {
}

Implement this interface to add custom instructions for your content writers. For example, let's add a new instruction called setupForCombat, where all of the varaibles required for a combat is set. The following example shows what that extension class might look like:

import { InstructionExtension, InstructionExtensionParameter } from '@alexa-games/sfb-f';

export class CombatInstructionExtension implements InstructionExtension {
    async public setupForCombat(param: InstructionExtensionParameter): Promise<void> {
        param.storyState.health = 100;
        param.storyState.energy = 0;
        param.storyState.enemyHelath = 100;
        param.storyState.enemyEnergy = 100;
    }
}

After you build your project with this extension, whenever you use the instruction setupForCombat the method of the same name in your extensions is invoked.

The following example shows what your .abc file might look like:

@start combat
    *say
        rawr starting combat
    *then
        setupForCombat // your custom instruction will run when the story reaches here.
        -> next turn in combat

Add Extension to your project

  1. Open code/extensions/ExtensionLoader.ts. If this is an unmodified project, you should see four extensions already added within the class constructor:
    constructor(param: ExtensionLoaderParameter) {
        this.registeredExtensions = [
            // Alexa SFB extensions
            new AlexaExtension(),
            new AlexaAPLExtension(param.locale, param.configAccessor),
            new AlexaMonetizationExtension(param.locale, param.configAccessor),

            // sample custom extension
            new SampleCustomExtension()
        ];
    }
  • To add your extension, add an instance of your extension as an item within this list.

Set up Amazon Polly voices (Optional)

By default, you can use Amazon Polly voices with Alexa SSML without further setup of Amazon Polly. You must perform Additional setup only if you want to use advanced voice-mixing features like background music.

Step 1: Set up AWS IAM role

To use Amazon Polly in your skill

  1. Add the following permissions to your custom IAM policy called "SFB Lambda" that is used by the IAM role for your AWS Lambda function:

    • s3:GetObject for storing and caching the generated sound files.
    • s3:PutObject for storing and caching the generated sound files.
    • s3:PutObjectAcl for storing and caching the generated sound files.
    • polly:SynthesizeSpeech for using the Amazon Polly service to generate the sound file using the Amazon Polly voices.

Example:

    "s3":"GetObject"
    "s3":"PutObject"
    "s3":"PutObjectAcl"
    "polly":"SynthesizeSpeech"

Step 2: Set up Amazon S3 bucket

To store the generated sound file.

  1. When you create and set up the bucket, make sure to clear the following public access options:

    • Block new public ACLs and uploading public objects. When you clear this option you can add objects that you customers can see. The sound files used by the skill must be public-readable.

    • Remove public access granted through public ACLs. When you clear this option your customers can access the public objects.

Step 3: Configure your skill

The default Alexa SSML syntax supports voice tags. With the tags you can use custom Amazon Polly voices in your skill without additional setup.

To use Amazon Polly to mix voices with background music,
you need to set up  a few configurable properties.  Otherwise, you can use Amazon Polly voices alone while leaving

`polly-config` disabled. The configuration file for the Skill Flow Builder is at
`<your_project_path>/abcConfig.json`.

To configure your skill set up the following configurable properties:

* `"s3-bucket-name"`: Name of the Amazon S3 bucket to store the generated
sound files.

* `"s3-domain-name"`: Name of the domain where your Amazon S3 files are served.
Usually "s3.amazonaws.com" for all global buckets, but if using a regionalized
bucket, you need to provide the correct value.

* `"polly-config -> enabled"`: If true, calls Amazon Polly instead of using
    the built-in `<voice>` tag functionality provided via Alexa SSML.

* `"polly-config -> combineAudioTags"`: If true, combines multiple audio
files into a single .mp3 file.

* `"polly-config -> dontUseCache"`: If true, calls the Amazon Polly
service for every request. If false, the skill tries to use the previously
generated sound files if already generated.

* `"default-narrator -> enabled"`: If true, the narrator's voice is changed
to the Amazon Polly voice instead of Alexa's default voice.

* `"default-narrator -> name"`: Amazon Polly name of the default narrator's voice
as shown in the [voice list](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html).

* `"default-narrator -> pitch"`: Pitch shift of the default voice. Set to
"+0%" to use the default pitch.

* `"default-narrator -> rate"`: Rate/speed shift of the default voice.
Set to "+0%" to use the default rate.

Troubleshoot your setup

Windows installation

On Windows, if the error "MSBUILD : error MSB4132" occurs, the windows-build-tools module might be missing. In a PowerShell window with administrator permissions, type the following code, and then press Enter.

  npm install --global windows-build-tools

Payload

To verify the payload package created by the publish script, find the skill payload at <your_project_path>/.deploy/{your-ask-skill-directory-name}.

To build the payload without performing a deployment, open a command prompt, type the following code, and then press Enter.

  npx alexa-sfb build <your_project_path>

New package version

When you pull a new version of the Skill Flow Builder package to an existing project, clean the workspace to apply the changes to your project.

  1. Open a command prompt, type npm install and then press Enter.

  2. To reinstall alexa-sfb type the following commands.

  cd <your_project_path>
  npm upgrade

Alternatively, if you installed the Skill Flow Builder CLI globally, complete the following procedure.

  • Open a command prompt, and type the following command, and then replace <sfb> with the full path.
  npm --global upgrade <SFB>/lib/moduleSrc/alexa-sfb

  • On Mac OS add the sudo prefix:

  sudo npm --global upgrade <SFB>/lib/moduleSrc/alexa-sfb

Uninstall the Skill Flow Builder

The Skill Flow Builder package doesn't install additional packages outside of the scope of the project folder.

To remove all traces of the project

  • Remove the directory that contains the project.
sudo npm uninstall -g @alexa-sfb/sfb-cli

On Windows

npm uninstall -g @alexa-sfb/sfb-cli