Step1：サンプルゲーム（Alfort）で自動テストを体験する

はじめに

Playable!を理解するために、まずは Playable!組込済のサンプルゲーム（Alfort）で自動テストを体験してみましょう。
すぐにテストを体験いただけるように、ビルド済のゲームデータと、マップスキャン後のデータなど事前に準備する必要のあるデータを配布しています。

この Step で学ぶこと

• Playable!に必要なデータのダウンロードと環境構築の方法
• Playthrough Tester を使用した通しプレイの自動テスト方法
• Collision Checker を使用した自動コリジョンチェックの結果確認方法
• General Agent による自動テストの実行方法

必要なもの

Playable! のマイページ から以下のファイルをダウンロードしてください。

• ソリューション本体：Playable!ライブラリ
• サンプルゲーム：Playable!組み込み済みサンプルゲーム(Alfort)
• お試し用データ：Playable!動作確認用追加データ

それぞれの ZIP ファイルを取得したら、ドライブのできるだけ階層の浅い、日本語を含まないディレクトリへ展開してください。

危険

ディレクトリパスに日本語が含まれていると正しく動作しないおそれがあります。

環境構築

Playable!各ツールの利用にはAnacondaが必要となります。
以下よりダウンロード・インストールしてください。

https://www.anaconda.com/download/success

注記

Playable! では、ツールごとに専用の Python 仮想環境を用意することを前提としています。
この環境を簡単に構築するために、Anaconda の仮想環境を利用しています。

インストールが完了したら、Anaconda Prompt が立ち上がることを確認してください。
各ツールの利用は Anaconda Prompt から行います。

Playthrough Tester を使用した自動テストを行う

まずは Playthrough Tester を使用して、通しプレイの自動テストを行ってみましょう。

ツールの起動

まず、Windows のスタートメニューから、Anaconda Prompt を起動してください。

Playable!ライブラリ（\playabletoolkit{バージョン名}\playable-playthrough-tester） の配下にある、run.bat を、Anaconda Prompt にドラッグアンドドロップします。
run.bat までのパスが Anaconda Prompt にコピーされますので、そのまま Enter キーを押してください。

注記

以下のコマンド入力を実行しても同じ結果が得られます。

$ conda activate playthrough
$ cd {playable-playthrough-tester のディレクトリ}
$ python playthrough.py

起動が完了すると以下のウィンドウが表示されます。

ゲームの起動

Playable! Playthrough Tester の GUI が起動している状態で以下の操作を行います。

1. [ゲームファイルを選択] ボタンを押し、ゲーム実行ファイルの場所（\WindowsNoEditor\Alfort.exe）を指定します。
2. [フォルダを選択] ボタンを押し、手本データの保存先フォルダの場所（\alfortadditional{バージョン名}\playthrough-tester\demo）を指定します。
3. 2 つのフィールドを指定したら、[起動] ボタンを押し、ゲームを起動します。

テスト実行

ゲームが起動すると、▼ モード選択 以下の UI が表示されます。

[>>再生モードに切り替え] ボタンを押してモードを切り替え、 [全て選択]→[再生開始] の順にボタンを押してください。
[再生開始] ボタンを押すと、ゲームの自動操作が開始されます。

注記

サンプルゲーム（Alfort）での通しプレイ完了には、おおよそ 20 分ほどかかります。

ヒント

より詳しくツールについて知りたい場合は、Playable! Playthrough Tester をご覧ください。

Collision Checker を使用した自動テストの結果を確認する

次に Collision Checker を使用し、コリジョンチェックの動作を確認してみましょう。

コリジョンテストには多くの時間とマシンパワーを必要とするため、チュートリアル Step1 では テスト実施を事前に終えたデータ を利用してテスト結果を確認します。

注記

チュートリアル Step2では実際に Collision Checker を実行し、自動テストを行います。

ヒント

より詳しくツールについて知りたい場合は、Playable! Collision Checker およびビューワー操作マニュアルをご覧ください。

データの準備

テスト実施を事前に終えたデータを Collision Checker が認識できるように以下の操作を行います。

Playable!動作確認用追加データ（\alfortadditional{バージョン名}\collision-checker） の配下にある、 data ディレクトリを \playabletoolkit{バージョン名}\playable-collision-checker\Python ディレクトリにコピーしてください。

ツールの起動

テスト結果の確認には Playable! Collision Checker Result Viewer を使用します。

まず、Playthrough Tester のときと同様に、Windows のスタートメニューから、Anaconda Prompt を起動してください。

\playable_toolkit_v1.2.0\playable-collision-checker\Python の配下にある、run_result_viewer.bat を、Anaconda Prompt にドラッグアンドドロップします。
run_result_viewer.bat までのパスが Anaconda Prompt にコピーされますので、そのまま Enter キーを押してください。

注記

以下のコマンド入力を実行しても同じ結果が得られます。

$ conda activate collisionchecker $ cd {playable-collision-checker のディレクトリ} \Python $ python result_viewer.py

起動が完了すると以下のウィンドウが表示されます。

ゲームの起動

Playable! Collision Checker Result Viewer の GUI が起動している状態で以下の操作を行います。

1. [ゲームファイルを選択] ボタンを押し、ゲーム実行ファイルの場所（\WindowsNoEditor\Alfort.exe）を指定します。
2. [マップ選択] ボタンを押し、守り岩の滝 を指定します。
3. 2 つのフィールドを指定したら、[起動] ボタンを押し、ゲームを起動します。

起動が完了すると、結果を再現させるためのゲーム画面とともに、テスト結果を確認するための GUI が表示されます。

コリジョン抜けを確認する

サンプルゲーム（Alfort）には、コリジョン抜けをシミュレーションするために 「コリジョン抜け」自体を ON にするオプション があります。
今回利用する事前データでは、このオプションを有効にしたうえでコリジョンチェックを行っています。
そのため、テスト結果を再現させる場合もこのオプションを有効にする必要があります。

キーボードの 0 キー 、あるいは コントローラーの LT、RT を押下しながら R スティック押し込み（R3） でデバッグメニューを表示させ、「バグコリジョン切り替え」 を選択してください。

オプション設定が完了したら、以下の手順で実際にコリジョン抜けを再現してみましょう。

1. 落下点の表示 にチェックを入れる
2. 落下点の一覧ウィンドウが表示されるので、No.005 の落下点に対して ここに移動 ボタンを押す

ボタンを押すとプレイヤーは落下する直前の場所にワープし、プレイヤーがどのように移動したかを示す経路情報が青矢印で表示されます。
経路情報に沿ってプレイヤーを操作し、コリジョン抜けに伴う奈落落ちが発生することをご確認ください。

なお、初期位置にワープ ボタンを押すと、プレイヤーが初期位置にワープし、奈落落ち状態から抜け出すことができます。

General Agent を使用した自動テストの実行を行う

次に General Agent を使用し、自動テストを行ってみましょう。

データの準備

1. お試し用データ：Playable!動作確認用追加データ (alfortadditional_data{バージョン名})内の、general_agent ディレクトリ以下のmap_dataとmap_graphフォルダを、 \playabletoolkit{バージョン名}\playable-general-agent\Python\data\alfort_work_space_base ディレクトリにコピーしてください。

2. playabletoolkit{バージョン名}内にある playable-game-python-bridgeフォルダ を\playabletoolkit{バージョン名}\playable-general-agent\Pythonディレクトリにコピーしてください

3. general_agent内のWindowsNoEditorディレクトリ以下にあるAlfort.exeのパスを、playable-general-agent/Python/settings.yamlのgame_pathに設定してください。

settings.yaml

# ゲーム情報
game:
  # 実際のローカル環境に合わせて変えてください *必須
  game_path: ./Windows/MyUEProject52.exe
  # 対象とするゲームウィンドウのタイトル(現状固定) *必須
  game_window_title: "MyUEProject52 (64-bit Development PCD3D_SM6) "
# 以下省略

注記

game_pathにAlfort.exeのパスを設定する際、パス区切り文字が環境によって異なります。
（例：Windows ではバックスラッシュ \ を、Python ではスラッシュ / を使用します）
特にコピー＆ペーストで設定する場合は、正しい表記となっているかご確認ください。

OpenAI API key の取得

General Agent は、OpenAI の API を使用して動作します。 事前に OpenAI のウェブサイトから API キーを取得してください。 なお、この Step では gpt-3.5-turbo-1106 の model を使用して動作確認を行っております。 利用する model は settings.yaml から変更可能です。 model に付いての詳細は こちら をご参照ください。

OpenAI API key の設定

1. playable-general-agent/Python/フォルダ内の.env.sampleをコピーし、.envという名前で保存してください。
2. .envファイルを開き、取得した API キーを設定してください。

OPENAI_ORG_KEY=###      # OpenAI の Organization ID を設定する *任意
OPENAI_API_KEY=###      # OpenAI の API key を設定する *必須
FFMPEG_PATH=###         # FFmpeg のパスを設定する(音声認識機能の為の設定) *任意

ヒント

FFmpeg についてもっと詳しく知りたい場合は、音声入出力をご覧ください。

Organization ID と FFmpeg に関して、設定をしない場合はコメントアウトしてください。

ツールの起動

Windows のスタートメニューから、Anaconda Prompt を起動してください。 以下のコマンドを一行ずつ実行します。

conda create -n generalagent python==3.8.18

conda activate generalagent

cd {playable-general-agent のディレクトリ} \Python

pip install -r requirements.txt

下記を実行することで、General Agent が起動します。

python general_agent.py

起動オプションを付けることも可能です。 詳細は操作マニュアルを参照してください。

起動後最初の数秒間はゲームを操作可能な状態にする準備を行っています。 画面左のチャットウインドウに「ゲームが操作可能な状態になりました。指示をどうぞ」が表示されるまでしばらくお待ちください。

画面構成

General Agent は、以下の 5 つのウィンドウで構成されています。

1. チャットウィンドウ：チャットボットとの対話を行うウィンドウです。
   • チャットボットへの指示入力や、チャットボットからの応答が表示されます。
   • このウィンドウのメニューバーが General Agent 全体のメニューバーとなります。
2. タスクリストウィンドウ：チャットボットからのタスクリストが表示されるウィンドウです。
   • 実行中及び実行予定のタスクリストが表示されます。
   • タスクリストの編集が可能です。
3. マップウィンドウ：プレイヤーの現在位置や、移動タスク中の経路が表示されるウィンドウです。
4. ツリーウィンドウ：ビヘイビアツリーの状態が表示されるウィンドウです。
   • ビヘイビアツリーの状態がリアルタイムで表示されます。
5. ゲームウィンドウ：ゲーム画面が表示されるウィンドウです。

チャットボットの応答

チャットボットは LLM を利用して指示内容を解釈して実行可能となる場合、タスクに変換してキュー（タスクリスト）に追加されます。 解釈できなかったり誤っている場合は表現を変えて入力し直してみてください. LLM を利用しているため同じ入力内容でも解釈結果が異なる場合があります。

チャットウィンドウの操作方法

チャットウインドウ下部の入力エリアにゲームを操作したい内容を入力して【Send】ボタンをクリックするとチャットボットへの指示となります。

1. プレイヤーキャラクターを動かす
   • チャットボットに「ヘルプ」と入力すると、Alfort で利用可能なコマンドの一覧が表示されます。

• 試しに「平原街道へ移動」と入力してみましょう。

新規コマンドの追加

AI の機能を用いて、新たなコマンド指示を追加してみましょう。

1. チャットウィンドウに「3 回ジャンプする」と入力してください。
2. チャットウィンドウに以下のメッセージが表示されるので、「はい」と入力してください。
   • この時、「実現したい動作」が正しいか確認してください。
3. 自動的に Behavior Tree Maker が起動され、自動生成が開始し保存されます。
4. メニューバーの［ファイル］→［Behavior Tree Maker の終了］を選択するとチャットボットに戻ります。

これで、新たに「ジャンプ」コマンドが追加されました。

次のステップ

おつかれさまでした！
Playable!を使用した自動テストがどのように動作するかについて、ご理解いただけたでしょうか？

STEP2 では Unreal Engine の Third Person Template を利用して、既存のゲームに Playable!を導入する手順を確かめてみましょう。
チュートリアル Step2 へ