search

alexa-games / skill-flow-builder

Development suite that helps you create narrative-driven Alexa skills, including a GUI editor and CLI
Other
69 stars 17 forks source link

readme

Skill Flow Builder

Warning DEPRECATED The Alexa Games team will no longer support or maintain this official distribution of Skill Flow Builder. Thank you to all the folks who have used SFB to make great Alexa skills over the years!

Alexa’s Skill Flow Builder is a development suite that helps you create narrative-driven Alexa skills more quickly using a simple language that can model any narrative structure. It includes the Skill Flow Builder Editor application for designers and writers, and a Visual Studio Code extension for developers. Designers and writers can quickly prototype and modify content. In parallel, developers can build differentiated features and minimize time spent on content changes. The tools share a common source file format, which helps make handoffs between teams more efficient.

Skill Flow Builder Editor

Using the Skill Flow Builder Editor, designers and writers can visualize their story using the built-in story tree/map view. Skill Flow Builder structures the narrative as a series of connected scenes, which you can navigate with the click of a button. Without involving a development team, you can write or update the narrative, add visuals and sound effects, and implement game logic. You can also assign Amazon Polly voices to specific characters, add images, and add background audio.

Use the built-in simulator to preview, demo, and test your content. When finished, export and share a Skill Flow Builder format (.abc) file with your development team, or export text for narration or localization.

For more information, see Use the Skill Flow Builder Editor

Skill Flow Builder Core Tools

For developers, Skill Flow Builder offers a command line interface, content debugger, integration with existing developer tools, and extension support. With Skill Flow Builder, you can use tools like the Alexa Skills Kit SDKs, ASK Command Line Interface (ASK CLI), and the AWS CLI. Skill Flow Builder integrates with extensions for Alexa Presentation Language (APL) templates and in-skill purchasing, which saves you implementation time.

When you receive a new Skill Flow Builder format (.abc) file from designers and writers, you can deploy and validate the content as a skill before touching the code. You can also implement business logic directly in the .abc file by using the built-in scripting ability called scene instructions.

The content debugger helps isolate debugging process from the content. You can view variables used, save state for later testing, and view content execution steps.

See a more detailed view of the structure of typical SFB project.

For more information, see Set up Skill Flow Builder as a Developer

Packages

The following packages are in this repository.

@sfb-f

The Skill Flow Builder Content Framework. This module contains the core collection of utility and driver functionalities that powers the Editor and the CLI. It also enables and aids importing and creating interactive story skills for Alexa.

@sfb-editor

The Skill Flow Builder Editor. Contains a native desktop client built with Electron, an application in which designers and writers can visualize, create, and review their SFB project story.

@sfb-cli

The Skill Flow Builder CLI. Adds build, validation, and deploy command line tooling for Skill Flow Builder stories. Installing this globally installs the alexa-sfb command line tool.

@sfb-skill

The Skill Flow Builder Skill Library. The module that joins Alexa skill code to the SFB engine.

@sfb-polly

The Skill Flow Builder Polly integration. Enables Text To Speech in different voices & languages with Amazon Polly

@sfb-util

The Skill Flow Builder Utility Library. Contains various Alexa/SFB utility functions.

@sfb-story-debugger

The Skill Flow Builder Debugger. Enables you to simulate your project’s behavior locally without deploying.

@sfb-vscode-extension

The Skill Flow Builder Visual Studio Code Extension. An extension for Skill Flow Builder projects that provides syntax highlighting for Skill Flow Builder project files.

Developer Setup

Prerequisites

Environment Setup

Install Dependencies

This package uses yarn to manage dependencies, you can install yarn globally with

npm install -g yarn

FFmpeg & LAME

To enable the audio mixing features of SFB, we recommend installing FFmpeg and LAME. FFmpeg is called as a stand-alone application in the editor to mix audio when using the Voice Preview functionality, as well as in the Lambda endpoint to mix audio to return in Alexa Skill responses. LAME is utilized to perform MP3 encoding for the mixed audio.

Scripts to build and install both LAME and FFmpeg are available in the scripts/setup/ directory, and you can run the following command to build them in the root directory:

yarn dependencies:OPERATING_SYSTEM

Where OPERATING_SYSTEM is the operating system you wish to build for:

For example:

yarn dependencies:mac

Note: For Windows, the script is designed to be used with Msys2 while running the MINGW64 shell. It can be difficult to install Node.js under Msys2, so unless you are already working in Msys2 with Node.js, we suggest running scripts/setup/InstallDependenciesWin.sh directly.

Additional information on how to build and install FFmpeg with LAME can be found in the FFmpeg Compilation Guide.

Quick Start

To get everything up and running, first clone and navigate into this repository with:

git clone https://github.com/alexa-games/skill-flow-builder.git && cd skill-flow-builder/

To install the node dependencies and build all the modules in the packages/ directory:

yarn install

To rebuild the packages at any time, run the yarn build-modules command.

Tests are run as part of the build process. You can run the full test coverage report by running yarn coverage. Tests can also be run locally inside any package directory, (i.e. packages/sfb-cli) with yarn test.

Cleaning is also available through yarn clean

Installing the CLI

Install sfb-cli globally using yarn:

yarn global add @alexa-games/sfb-cli

To link the CLI from a local install, use:

yarn global add /full/path/to/AlexaGamesSkillFlowBuilder/packages/sfb-cli

Yarn is required here, else the packages may not be linked correctly. Assuming the packages installed correctly, you should be able to use the alexa-sfb command to interact with the SFB CLI. For example, to create a new story use:

alexa-sfb new <storyName>

Start the Editor

After running yarn build-modules, you can start the editor by running:

yarn editor

This will launch the SFB editor, which will visualize your skill’s behavior and content. You can create a new project, or open an existing project using the buttons on the top left.

Using Modifications to Core Libraries

If you want to use any modifications to the core SFB libraries, you must add them all as a local file path dependency in your skill's code/package.json file.

...
"dependencies": {
    "@alexa-games/sfb-f": "file:/path/to/skill-flow-builder/packages/sfb-f",
    "@alexa-games/sfb-polly": "file:/path/to/skill-flow-builder/packages/sfb-polly",
    "@alexa-games/sfb-skill": "file:/path/to/skill-flow-builder/packages/sfb-skill",
    "@alexa-games/sfb-util": "file:/path/to/skill-flow-builder/packages/sfb-util",
    "ask-sdk": "latest"
},
...

Next, add the sfbLocalTesting and ask-hooks-directory property to your abcConfig.json file:

...
"default": {
    ...
    "sfbLocalTesting": true,
    "ask-hooks-directory": "hooks",
    ...
}
...

Finally, copy the scripts/local-packages/hooks folder into your SFB project folder (i.e. there should be a hooks folder at the same level as your code and content folders). These two changes will force the SFB CLI and the ASK CLI to use yarn instead of npm when building your skill, allowing you to properly reference the local dependency packages.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the Amazon Software License.