開発者としてSkill Flow Builderをセットアップ

開発者としてSkill Flow Builderをセットアップ

Skill Flow Builderを使うと、メタデータ形式を使って、対話型ノベルやロールプレイング、アドベンチャーゲームといった、ゲームやストーリーのコンテンツを作成できます。エンジンでは次のような機能が提供されます。

  • ゲームやストーリー向けの標準形式
  • ゲームロジック、カスタム関数を実装するフック、ゲーム内の指示を追加するビルトイン拡張機能
  • ゲームやストーリーの状態を保存したり読み込んだりする機能をシミュレートするバーチャルAlexaエミュレーター
  • コンテンツの編集やテストを行うグラフィカルユーザーインターフェース

開発者はSkill Flow Builderを使って、ライターやデザイナーが作成したコンテンツをAlexaで読み込み可能な言語に統合できます。

はじめに

  • Node.jsバージョン10以上をインストールします。
  • 最新バージョンのGitをインストールします。
  • Pythonをインストールします。Windowsでは、Pythonバージョン2.7.14を使用します。Windows版のSkill Flow Builderは、最新バージョンのPythonでは正常に動作しません。Macでも、Pythonバージョン 2.7.14が推奨されます。
  • それぞれ最新バージョンのASK CLIとAWS CLIをインストールします。
  • （Windowsのみ）最新バージョンのwindows-build-toolsモジュールをインストールします。
  • （任意）最新バージョンのVisual Studio Codeをインストールします。Skill Flow BuilderはVisual Studio Codeに最適化されています。

Skill Flow Builderをインストールする

Node.jsをインストールすると、NPMも含まれています。Skill Flow Builderをインストールするには、NPMのコンフィギュレーションを変更する必要があります。

コマンドラインインターフェースをセットアップする

コマンドラインをグローバルにセットアップしてどのディレクトリからでも、コマンドプロンプトやターミナルでSkill Flow Builderのコマンドを実行できるようにするには、次を実行します。

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

コマンドラインインターフェースをグローバルにセットアップする代わりに、alexa-sfbパッケージをローカルにセットアップするディレクトリにディレクトリを変更し、次を実行します。

npm install @alexa-games/sfb-cli

npx alexa-sfbを使ってコマンドラインインターフェースを実行します。ローカルにalexa-sfbパッケージをセットアップする場合、ディレクトリをローカルディレクトリに変更し、次のコマンドを実行します。

npx alexa-sfb

Visual Studio Code拡張機能をセットアップする

コマンドプロンプトまたはターミナルで、プロジェクトのルートフォルダに移動し、次のコマンドを実行してVisual Studio Codeの言語拡張機能をインストールします。この拡張機能では、構文の強調表示、エラー診断、定義箇所への移動が可能になります。

npx alexa-sfb vscode

Visual Studio Codeで提供される定義部分への移動機能では、シーンを定義したファイルや行に移動できます。たとえば、コンテンツに-> myscene指示が含まれる場合、mysceneをクリックしてF12を押すか、定義に移動を右クリックすると、そのシーンを定義した行に移動できます。

スキルプロジェクトを作成する

npx alexa-sfb newを使って新しいゲームやストーリーを作成します。コマンドを実行する場合は、ファイル、ゲーム、ストーリーを保存するフォルダへのパスを指定します。たとえば、次のようになります。

npx alexa-sfb new my_best_story

シミュレーターを使用してスキルのコンテンツをデバッグする

シミュレーターを使ってコンテンツを通しで再生し、コンテンツの動作を確認できます。シミュレーターでは、スキルではなくコンテンツのランタイム実行をテストします。

ターミナルまたはコンソールで、次のコマンドを実行し、シミュレーターでコンテンツをプレビューします。

npx alexa-sfb simulate <ユーザーの_プロジェクト_パス>

Alexaスキルをデプロイする

次のステップを実行し、ゲームやストーリーをAlexaスキルとしてデプロイします。

  1. ASKプロファイルをセットアップします。Alexa Skills Kit（ASK）プロファイルは、開発者アカウントを使ってセットアップし、AWSアカウントをリンクします。次のコマンドを実行し、プロンプトに従います。

    ask init

    「default」以外のASKプロファイルを使うには、<ユーザーの_プロジェクト_パス>/abcConfig.jsonを開き、"ask-profile-name"アトリビュートに使いたいプロファイルを指定します。

    使用するユーザーのAWSアカウントセキュリティ認証情報がある、アクティブなAWSアカウントを指定する必要があります。認証情報のあるIAMユーザーがない場合、AWSコンソールを開いてIAMタブに移動します。「ユーザーを追加」をクリックして新しいユーザー名を作成します。「プログラムによるアクセス」チェックボックスを選択して、以下の設定を使用してポリシーの権限を付与します。

    {
    "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": "*"
        }
    ]
}

  2. スキルをコンフィギュレーションします。コンフィギュレーションを一切変更することなく、スキルを作成しデプロイできます。コンフィギュレーションを更新するには、<ユーザーの_プロジェクト_パス>/abcConfig.jsonで、スキルのコンフィギュレーションファイルの次の項目を更新します。

    • "ask-skill-directory-name"： ASK CLIで使用するスキルの名前です。AWS Lambda関数名とスキル名は、この値から取得します。このフィールドには、アルファベットの大文字および小文字（A～Z、a～z）、数字（0～9）、アンダースコア（_）、ダッシュ（-）を含めることができます。

    • "skill-invocation-name"： ユーザーがスキルを呼び出す方法を定義します。詳細については、ユーザーによるカスタムスキルの呼び出しを参照してください。

    • "publish-locales"： Alexaがサポートするロケールのリストです。これらのロケールがスキルの公開先となります。

  3. デプロイします。すべての準備が整ったら、次のコマンドを実行してスキルをデプロイします。

    npx alexa-sfb deploy <ユーザーの_プロジェクト_パス>

    Windowsからスクリプトを実行する場合は、ターミナルを管理者として開きます。こうすることで、デプロイメントプロセスの一環としてスクリプトでPowerShellバッチファイルを実行する際の権限エラーを防ぐことができます。

    「AccessDenied: User: arn:aws:iam::... is not authorized to perform: iam:CreateRole on resource: ...」のエラーによりスキルを公開できなかった場合、AWSコンソールのIAMに移動して、ユーザーにステップ1で説明したポリシーの権限が付与されているかどうか確認してください。

  4. AWS IAMロールをセットアップします。開発者アカウントでスキルを作成し、AWS Lambda関数を作成したら、DynamoDB、Amazon S3、Amazon Pollyの権限をAWS Lambda関数用に作成したIAMロールに追加する必要があります。

    スキルのデフォルトロール名は、ask-lambda-「スキルのプロジェクト名」となります。

    AWS Lambdaでスキルコードを実行するには、あらかじめロールAWSLambdaBasicExecutionRoleの管理ポリシーがなければなりません。

    以下の設定の新しいポリシーを追加して、AWS Lambda関数がDynamoDBにアクセスできるようにします。

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

    さらに多くの権限を上記のポリシーに追加するには、 Amazon Polly音声をセットアップする（任意）を参照してください。

    一部のデフォルトAWS Lambda設定の変更が必要になる場合があります。AWSコンソールで、AWS Lambda関数を見つけ、次の設定を変更します。

    • ランタイム環境が「Node.js 8.10」であることを確認します。
    • タイムアウトが15秒以上であることを確認します。

  5. スキルを起動します。呼び出し名を言ってAlexa搭載デバイスでスキルをテストします。

    スキルを初めて起動するときは、AWS Lambda関数が状態管理のDynamoDBテーブルを生成しようとするためにエラーメッセージが出ます。15秒後にはDynamoDBテーブルが作成されるので、もう一度スキルの起動を試行します。

コア拡張機能を使用する

roll、rollResult

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

roll指示はサイコロを転がすのに使用します。rollResult指示はrollの結果にアクセスできます。この例では、6面のサイコロを2つ転がして、出た目の合計をrollResult変数に入れています。

  • rollは入力としてXdYを受け取ります。XとYは整数です。Xは転がすサイコロの数、Yはサイコロの面の数を表します。
  • 1d6 + 3、1d6 - 3のように記述することで、数を足したり引いたりできます。
  • 複数のサイコロを転がして、最も大きな数をZ個取り出すこともできます。その場合は、XdYkZのように記述します。Xがサイコロの数、Yが面の数、Zが取り出したい最大値の数を表します。たとえば、roll 2d6k1では、6面のサイコロを2つ転がして、最も大きな数を1つ取り出します。

time

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

time指示は、現在時刻をsystem_returnという特殊なシステム変数に保存します。ゲームで時刻を使うには、set指示を使って時刻を独自の変数に割り当てます。時刻はエポックミリ秒形式です。つまり、1970年1月1日（UTC/GMTの深夜0時）からの経過時間をミリ秒で表したものです。

monetization

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

プロジェクトディレクトリのresources/ProductISPs.jsonにあるISP IDコンフィギュレーションファイルで、アイテム名にマッピングしたスキル内商品（ISP）の収益化フローを開始します。購入フローが正常に完了すると、プレイヤーは「success」に定義されたシーン、またはこの例にある@purchase successに遷移します。購入フローが失敗またはキャンセルされると、「fail」に定義されたシーン、またはこの例にある@purchase failedに遷移します。

declined、already_purchased、errorのパラメーターは任意です。これらのパラメーターを割り当てなかった場合、プレイヤーはfailパラメーターで定義されたシーンに遷移します。各購入フローでプレイヤーが遷移するシーンを細かく制御したい場合は、これらのパラメーターを定義してください。

カスタム拡張機能を作成する

コンテンツの作成と同時に、特定のシーン中に独自コードを実行するカスタムコマンドを作成する必要があります。sfb-fモジュールから3つの拡張インターフェースのうち1つを実装して、機能をカスタマイズしてSFBでビルドしたスキルに追加できます。3つの拡張機能は以下のとおりです。

  • ImporterExtension - StoryMetadataとしてソースコンテンツをインポートする前、またはした後に適用します。
  • DriverExtension - リクエストがストーリー実行に適用される前、またはされた後に適用します。
  • InstructionExtension - コンテンツ内のカスタム指示を処理するために、ストーリー実行中に適用します。

ImporterExtension

@alexa-games/sfb-fモジュールからこのインターフェースをインポートして実装します。インターフェースは次のようになります。

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

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

  • コンテンツのインポート手順のカスタムロジックを追加するには、ImporterExtensionを実装します。

  • ソースファイルのプレーンテキストが StoryMetadataとしてインポートされる直前にextendSourceContentが呼び出されます。

  • インポートの完了後にextendImportedContentが呼び出されます。通常、これは結果として取得したStoryMetadataのいくつかのコンポーネントを変更するために実装されます。

DriverExtension

@alexa-games/sfb-fモジュールからこのインターフェースをインポートして実装します。インターフェースは次のようになります。

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

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

  • ドライバーの実行前後にカスタムロジックを追加するには、DriverExtensionを実装します。

  • ドライバーの実行前にpreが呼び出されます。通常、これはドライバーの実行前にリクエスト解析ロジックをカスタマイズするために実装されます。

  • ドライバーの実行後にpostが呼び出されます。通常、これは応答構築ロジックをカスタマイズするために実装されます。

InstructionExtension

@alexa-gamessfb-fモジュールからこのインターフェースをインポートして実装します。インターフェースは次のようになります。

interface InstructionExtension {
}

コンテンツライターに向けてカスタマイズした指示を追加するには、このインターフェースを実装します。たとえば、戦闘に必要なすべての変数が設定されている場合に、setupForCombatと言う新しい指示を追加してみましょう。拡張機能クラスは以下のようになります。

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;
    }
}

この拡張機能を使用してプロジェクトをビルドすると、setupForCombatを使用するたびに、拡張機能にある同じ名前のメソッドが呼び出されます。

たとえば、.abc ファイルは次のように表示されます。

@start combat
    *say
        rawr starting combat
    *then
        setupForCombat //ストーリーがここに到達すると、カスタム指示が実行されます。
        -> next turn in combat

拡張機能をプロジェクトに追加する

SFB Extensionをプロジェクトに追加するには、code/extensions/ExtensionLoader.tsを開きます。これがまだ修正されていないプロジェクトの場合は、クラスのコンストラクターに既に追加された4つの拡張機能があるはずです。

    constructor(param: ExtensionLoaderParameter) {
        this.registeredExtensions = [
            // Alexa SFB extension
            new AlexaExtension(),
            new AlexaAPLExtension(param.locale, param.configAccessor),
            new AlexaMonetizationExtension(param.locale, param.configAccessor),

            // サンプルのカスタム拡張機能
            new SampleCustomExtension()
        ];
    }

拡張機能を追加するには、拡張機能のインスタンスをこのリストの項目として追加するだけです。

Amazon Polly音声をセットアップする（任意）

Amazon Pollyは、テキストを音声に変換するクラウドサービスです。Amazon Pollyの詳細については、Amazon Polly開発者ガイドを参照してください。デフォルトでは、Alexa SSMLを使ってAmazon Pollyを使用できます。追加のセットアップは不要です。ただし、バックグラウンドミュージックなど、高度な音声ミキシング機能を使う場合には追加のセットアップが必要です。

  1. AWS IAMロールをセットアップします。スキルでAmazon Pollyを使用するには、AWS Lambda関数のIAMロールに使用する「SFB Lambda」というカスタムIAMポリシーに以下の権限を追加します。

    • s3:GetObject - 生成されたサウンドファイルを保存したりキャッシュに保存する場合にアタッチします。
    • s3:PutObject - 生成されたサウンドファイルを保存したりキャッシュに保存する場合にアタッチします。
    • s3:PutObjectAcl - 生成されたサウンドファイルを保存したりキャッシュに保存する場合にアタッチします。
    • polly:SynthesizeSpeech - Amazon Pollyサービスを使ってAmazon Polly音声を使うサウンドファイルを生成する場合にアタッチします。

  2. S3バケットをセットアップします。Amazon S3バケットをセットアップして、生成されたサウンドファイルを保存します。バケットの作成とセットアップを行う際、次のパブリックアクセスオプションを必ずオフにしてください。

    • 新しいパブリックACLとパブリックオブジェクトのアップロードをブロックする：このオプションをオフにすると、パブリックアクセス（表示）可能なオブジェクトを追加できます。スキルで使うサウンドファイルは公開読み込み可能である必要があります。

    • パブリックACLを通じて付与されたパブリックアクセスを削除する：このオプションをオフにすると、公開オブジェクトへのパブリックアクセスが可能になります。

  3. スキルのコンフィギュレーションをセットアップします。デフォルトのAlexa SSML構文でvoiceタグがサポートされるようになったため、追加のセットアップをしなくても、スキルでカスタムAmazon Polly音声を使用できます。

    Amazon Pollyを使って音声にバックグラウンドミュージックを組み合わせるには、一部、Amazon Pollyの設定可能なプロパティをセットアップする必要があります。それ以外は、polly-configを無効にした状態で、Amazon Polly音声を単独で使うことができます。Skill Flow Builderのコンフィギュレーションファイルは、<ユーザーの_プロジェクト_パス>/abcConfig.jsonにあります。以下は設定可能なプロパティです。

    • "s3-bucket-name"： 生成されたサウンドファイルを保存するAmazon S3バケットの名前です。

    • "s3-domain-name"： Amazon S3ファイルがサービスを提供するドメイン名です。通常はすべてのグローバルバケットについて「s3.amazonaws.com」ですが、リージョン固有のバケットを使う場合は対応する値を指定する必要があります。

    • "polly-config -> enabled"： trueの場合、Alexa SSMLで提供されるビルトインの<voice>タグ機能を使う代わりにAmazon Pollyを呼び出します。

    • "polly-config -> combineAudioTags"： trueの場合、複数のオーディオファイルを1つの.mp3ファイルに結合します。

    • "polly-config -> dontUseCache"： trueの場合、すべてのリクエストに対してAmazon Pollyサービスを呼び出します。falseの場合、スキルは以前に生成したサウンドファイルを使おうとします（生成済みの場合）。

    • "default-narrator -> enabled"： trueの場合、ナレーターの音声がAlexaのデフォルト音声ではなくAmazon Pollyの音声に変わります。

    • "default-narrator -> name"： 音声リストにあるデフォルトのナレーター音声のAmazon Polly名です。

    • "default-narrator -> pitch"： デフォルト音声の高さを変更します。「+0%」にセットするとデフォルトの高さが使われます。

    • "default-narrator -> rate"： デフォルト音声の速さを変更します。「+0%」にセットするとデフォルトの速さが使われます。

セットアップのトラブルシューティングを行う

  • Windowsへのインストール

    Windowsで、「MSBUILD : error MSB4132」のエラーが出た場合、windows-build-toolsモジュールがない可能性があります。管理者権限でPowerShellウィンドウを開き、次のコマンドを実行します。

    npm install --global windows-build-tools

  • ペイロード

    公開スクリプトで作成したペイロードパッケージを確認するには、<ユーザーの_プロジェクト_パス>/.deploy/{your-ask-skill-directory-name}にあるスキルのペイロードを参照します。

    デプロイを実行せずにペイロードをビルドするには、次のコマンドを実行します。

    npx alexa-sfb build <ユーザーの_プロジェクト_パス>

  • 新しいバージョンのパッケージ

    既存プロジェクトにSkill Flow Builderパッケージの新しいバージョンを取り込んだ場合は、ワークスペースをクリーンアップしてプロジェクトへの変更を適用します。最初に、次のコマンドを実行します。

    npm install

    次に、次のコマンドを実行してalexa-sfbを再インストールします。

    cd <ユーザーの_プロジェクト_パス>
npm upgrade

    Skill Flow Builderコマンドラインインターフェースをグローバルにインストールした場合は、次のコマンドを実行する方法もあります。その際、<sfb>をフルパスに置き換えてください。

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

    Mac OSまたはLinuxでは、sudoプレフィックスを追加します。

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

Skill Flow Builderをアンインストールする

Skill Flow Builderパッケージは、プロジェクトフォルダの範囲外に追加のパッケージをインストールすることはありません。プロジェクトのトレースをすべて削除するには、プロジェクトを含むディレクトリを削除します。

alexa-sfbをグローバルにインストールした場合、次のコマンドを実行して削除します。その際、<SFB>をフルパスに置き換えてください。

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

Windowsの場合

npm uninstall -g @alexa-sfb/sfb-cli
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment