Skill Flow Builderのリファレンス

Skill Flow Builderのリファレンス

Skill Flow Builderには、ゲームやストーリー向けに次のようなメタデータ形式が用意されています。

シーンのプロパティ

Skill Flow Builderでは、シーンが基本要素です。シーンにはさまざまなタイプのコンテンツが含まれ、ストーリーやゲームの流れに応じてあらゆる方向につなげていくことができます。

以下は、あるシーンの構造を表しています。

@scene name
    *say
        コンテンツ
    *reprompt
        コンテンツ
    *show
        コンテンツ
    *then
        シーンの指示

シーン名でシーンを特定します。シーン名の形式は次のとおりです。

  • @で始める必要があります。
  • 英字、数字、スペースで構成し、文字数制限はありません。
  • ストーリー内で一意である必要があります。
  • シーン名は1行に収める必要があります。

一部のシーン名は特殊用途向けに予約されています。詳細については、特殊シーンを参照してください。

*say

シーンが再生されると、Alexaは*sayプロパティで定義したコンテンツをユーザーに読み上げます。*sayプロパティの形式は次のとおりです。

  • 任意です。
  • 複数行に記述できます
  • SSMLを使用できます。
  • バリエーションを示すために||を使用できます。
  • 波括弧を使って変数値を挿入できます。

||（ダイアログバリエーション）

    *say
        このようなものですか
        ||
        それともこのようなものですか

||は、ランダムに選択されるバリエーションを指定します。コンテンツの繰り返しによってストーリーが退屈にならないようにするのに効果的です。ダイアログバリエーションは、*say、*reprompt、*recapで使用できます。

*reprompt

Alexaは、ゲームでプレイヤーが答えるべきときに何も言わない場合、*repromptプロパティのコンテンツを声に出して読み上げます。*repromptを指定しなかった場合、Alexaはデフォルトで直前のシーンに指定した*sayコンテンツを再度読み上げます。

*sayと同様に、*repromptプロパティにも次のような形式が定められています。

  • 任意です。
  • 複数行に記述できます
  • SSMLを使用できます。
  • バリエーションを示すために||を使用できます。
  • 波括弧を使って変数値を挿入できます。

*recap

Alexaは、プレイヤーが想定外の応答をした場合、*recapプロパティのコンテンツを声に出して読み上げます。

*sayと同様に、*recapプロパティにも次のような形式が定められています。

  • 任意です。
  • 複数行に記述できます
  • SSMLを使用できます。
  • バリエーションを示すために||を使用できます。
  • 波括弧を使って変数値を挿入できます。

*show

プレイヤーが視覚を使用するコンテンツに対応するデバイスを使っている場合、デバイスはこのセクションに割り当てられた視覚コンポーネントを表示します。視覚要素を追加するを参照してください。

*then

*thenプロパティには、シーンの指示が入ります。シーンの指示とは、Alexaがそのシーンのコンテンツを再生した後に順次実行されるコマンドのことです。

シーンの指示

-> （遷移先のシーン）

Skill Flow Builderに、別のシーンに遷移するよう指定する終端子です。

    *then
        -> start

->指示の形式は次のとおりです。

  • 直後にシーン名を指定する必要があります。
  • 波括弧を使って変数を挿入できます。たとえば、twoという変数の値が2の場合、-> scene {two}は@scene 2に遷移します。
  • 終端子のため、シーンの終わりを表します。終端子が実行されたらすぐに、処理は次のシーンに遷移します。

hear

hear指示は、Alexaが聞き取る単語やフレーズと、聞き取った後のアクションを指定します。

    *then
        hear 逃げて, ここから出て, 行って {
            decrease courage by 1
            -> run
        }
        hear 隠れて {
            set fear to 10
            -> hide
        }

hear指示の形式は次のとおりです。

  • カンマで区切って複数のフレーズを指定できます。
  • 波括弧で囲む必要があります。
  • if文の中でも使用できます。また、if文を含めることもできます。

if

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

状況を限定する場合には、ifを使用します。if文以下の指示は、if文に定義した状況に該当する場合（trueの場合）にのみ実行されます。

if文の形式は次のとおりです。

  • 指示を波括弧で囲む必要があります。
  • hear文の中でも使用できます。またhear文を含めることもできます。
  • 入れ子にできます。
  • 値の前に!を使用できます。!は「...ではない」ことを意味します。
  • サポートされる演算子は次のとおりです。
    • 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

次の指示は変数の値をセットしたり、操作したりするのに使用します。

    *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 *             // ストーリーやゲームでセットした変数をすべてクリア
        -> start

<-> （遷移して戻る）

<->指示を使うと、再利用可能なシーンに遷移してから、またゲームのフローに戻ることができます。

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

@test your luck
    *say
        残念でした。
    *then
        >> RETURN

プレイヤーは、<-> test your luckにより@test your luckシーンに遷移してから、>> RETURNにより<->指示以降の行に戻ります。

<->は特殊な種類の終端子で、<->以降の指示は>> RETURN指示が実行されるまで実行されません。複数の<->指示と複数の>> RETURN指示をつなげて使うこともできます。

特殊終端子

慣例的に、特殊終端子はすべて大文字で記述しますが、大文字にしなくても機能には影響しません。

» RESTART

>> RESTART終端子の形式は次のとおりです。

  • 付加されたすべての拡張子について、startシーケンス、またはonStart関数を実行することでストーリーやゲームを再開します。
  • 利用可能な選択肢をリセットします。
  • @startシーンに遷移します。

この終端子はゲーム内で使用されている変数をクリアしません。つまり、ゲームの複数セッション間で保持する必要のある永続的な変数を削除しないようにできます。変数をクリアするには、clear *コマンドを実行します。

» PAUSE

>> PAUSE終端子の形式は次のとおりです。

  • 残りの指示をすべて直ちに停止することで、ストーリーを一時停止します。
  • 付加されたすべての拡張子について、pauseシーケンス、またはonSessionEnded関数を実行します。
  • @pauseシーンが定義されている場合は、完全に一時停止する前にシーン内のコンテンツを再生します。

» RESUME

>> RESUME終端子は、プレイヤーが前回プレイした最後のシーンからゲームを再開します。

この終端子はRelaunch動作を制御します。詳細は、再起動の動作を制御するを参照してください。

» REPEAT

>> REPEAT終端子はプレイヤーが今聴いたか、以前に聴いたことのあるオーディオ構成要素をリプレイします。

» REPROMPT

>> REPROMPT終端子は、再プロンプトとして使われたオーディオ構成要素をリプレイします。

» BACK

>> BACK終端子は、前回の対話の最初に戻ります。プレイヤーが「はい」または「いいえ」など、Alexaに何かを言うように促された場合の対話です。

前回の対話の開始点が、戻りたい対話とは何シーンか離れている場合があります。

前回の対話によってプレイヤーが複数のシーンに遷移した場合、プレイヤーが「戻って」と言った場合、プレイヤーは最初のシーンに戻ります。

» END

>> END終端子の形式は次のとおりです。

  • セッションを終了することでストーリーやゲームを終了します。
  • STARTシーケンスを直ちに実行し、拡張子に対してonStart関数を実行して次のシーンを@startにセットします。
  • プレイヤーが次回ゲームを起動すると、プレイヤーは@startシーンに遷移します。

» RETURN

>> RETURN終端子は、最後の<->指示以降の行に直ちに戻ります。

特殊シーン

特殊シーンには、ほかのシーンと異なる便利な動作があります。

@start

@startシーンは必須です。新しいユーザーまたは再起動後のゲームは、このシーンから開始します。

@start
    *say
        さあ物語の始まりです。準備はいいですか？
    *then
        -> setup

@resume

@resumeシーンは、プレイヤーがゲームを再開すると再生されます。>> RESUME指示を使い、プレイヤーがゲームを終了したシーンに戻すことができます。

@resume
    *say
        お帰りなさい。前回の続きから始めますね。
    *then
        >> RESUME

@pause

@pauseシーンは通常の一時停止動作によりゲームを一時停止する前、あるいは>> PAUSE指示から再生されます。

    @pause
        *say
            では、ひとまずさようなら。

@global prepend

@global prependのコンテンツは、ゲーム内のすべてのシーンの前に付加されます。

@global prepend
    *say
        ピーッ！

例については、すべてのシーンに視覚要素を追加するを参照してください。

@global append

@global appendのコンテンツは、ゲーム内のすべてのシーンの後に付加されます。

@global append
    *then
        hear ヘルプ {
            -> help message
        }
        hear ステータス, 今のステータス, ステータスを教えて{
            -> status message.
        }

例については、プレイヤーがどこからでも再起動できるようにするを参照してください。

コア拡張子

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時）からの経過時間をミリ秒で表したものです。

bgm（バックグラウンドミュージック）

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

シーンのナレーションにBGMを組み合わせます。

BGMは、カスタムのAmazon Pollyを使ったフォアグラウンドのオーディオまたはナレーションと組み合わせた場合にのみ機能します。Alexaの音声と組み合わせることはできません。また、エディターのプレビューモードでも機能しません。

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パラメーターで定義されたシーンに遷移します。各購入フローでプレイヤーが遷移するシーンを細かく制御したい場合は、これらのパラメーターを定義してください。