操作マニュアル
汎用エージェントの操作方法について説明します。
本プログラムにはテスト対象ゲームとして Alfort が組み込まれており、本ドキュメントには Alfort を前提に書かれている部分があります。
前準備
環境設定
環境設定 を参照してください。
追加データ
- Playable! のマイページ から Playable!動作確認用追加データ (
alfort_additional_data_{バージョン名}) をダウンロードして任意の場所に解凍します。 - 解凍して得られた
general-agent内のmap_dataフォルダとmap_graphフォルダをplayable-general-agent/Python/data/work_space_base/にコピーします。 - 同じく
general-agent内のWindowsNoEditorフォルダを任意の場所に配置し、playable-general-agent/Python/settings.yamlファイルの game_path にゲームバイナリ (Alfort.exe) へのパスを設定します。game_path: C:/Alfort/WindowsNoEditor/Alfort.exe
OpenAI API key
本ツールの利用には OpenAI の API key が必要です。 ない場合は取得してください。
playable-general-agent/Python/フォルダの.env.sampleファイルを同フォルダにコピーして.envファイルを作成します。playable-general-agent/Python/.envファイルに OpenAI の Organization ID と API key を設定します。- API key は必須項目です。
Organization ID を設定しない場合はコメントアウトしてください。
OPENAI_ORG_KEY=### # OpenAI の Organization ID を設定する
OPENAI_API_KEY=### # OpenAI の API key を設定する *必須- API key は必須項目です。
音声入出力
デフォルトは OpenAI TTS を利用するようになっています。
VOICEVOX を利用する場合は、ツールの設定ファイル playable-general-agent/Python/settings.yaml の text_to_speech_mode を変更してください。
音声合成に OpenAI TTS (Text to speech) を利用する場合
OpenAI TTS が wav 形式での出力をサポートしていないため、mp3 形式を扱うためのソフトウェア FFmpeg をインストールします。
- 公式ダウンロードサイト からビルド済みパッケージをダウンロードして任意の場所に解凍します。
- 解凍したフォルダを任意の場所に配置し、
playable-general-agent/Python/.envファイルの FFMPEG_PATH にbinフォルダへのパスを設定します。FFMPEG_PATH=C:/ffmpeg/bin # FFmpegのパス
音声合成に VOICEVOX を利用する場合
- VOICEVOX をインストールします。
※本ツールを起動する前に VOICEVOX を起動しておく必要があります。
ツールの起動
環境設定 を行っていない場合は済ませます。
Anaconda Prompt を起動後、以下のコマンドを実行して 汎用エージェント用の仮想環境に切り替えます。
conda activate generalagent # 仮想環境の切り替え
cd {playable-general-agent のディレクトリ}/Python # ディレクトリの移動python general_agent.pyを実行してツールを起動します。
以下の起動オプションを付けることも可能です。オプション 説明 -nt --no-top 他のウインドウに切り替えられるモードにする -nf --no-fullscreen フルスクリーンにしない -f --force 内部状態を強制的にリセットする -bd --background-dark 背景を暗くする -ud --use-debugger VSCode 等のデバッガーを使えるモードにする -l --log-dir <LOG_DIR> LOG_DIR にログ出力ディレクトリを作成（未指定の場合は Python/log/）-h --help ヘルプ表示 起動後最初の数秒間はゲームを操作可能な状態にする準備を行っています。
画面左のチャットウインドウに「ゲームが操作可能な状態になりました。指示をどうぞ」が表示されるまでしばらくお待ちください。
ツールの操作
チャットウインドウにボットに指示する内容を入力して【Send】ボタンをクリックすると、チャットボットが指示内容を解釈してタスクに変換し、エージェントがビヘイビアツリーを実行します。
操作の詳細は チャットウインドウの操作 をご参照ください。
ツールの終了
- チャットウインドウのメニューバーの［ファイル］→［アプリの終了］を選択して終了します。
画面構成
汎用エージェントのチャットボットは５つのウインドウで構成されます。
- チャットウインドウ
- チャットボットとのやり取りをするウインドウです。
チャットボットからのメッセージが表示されます。ボットへの指示の入力もここで行います。 - チャットウインドウのメニューバーがツール全体のメニューバーになります。
メニューバーの右端には本ツールのメモリ使用量がリアルタイムで表示されます。
- チャットボットとのやり取りをするウインドウです。
- タスクリストウインドウ
- 実行中および実行予定のタスクリストが表示されます。タスクリストの編集を行うこともできます。
- マップウインドウ
- 現在位置や経路が表示されます。
- ツリーウインドウ
- 実行中のビヘイビアツリーが表示されます。
- ゲームウインドウ
- 操作中のゲーム画面が表示されます。
各ウインドウの操作
チャットウインドウの操作
ゲーム操作を指示する
チャットウインドウ下部の入力エリアにゲームを操作したい内容を入力して【Send】ボタンをクリックするとチャットボットへの指示となります。
主なゲーム操作コマンド
コマンド 説明 [場所 or 人] に移動 ターゲットに移動する [人] と話す ターゲットと話す [敵] を倒す ターゲットを倒す [アイテム] を回収 ターゲットを回収する コマンドの詳細は「ヘルプ」を入力すると表示されます。
チャットボットは LLM を利用して指示内容を解釈してタスクに変換し、キュー（タスクリスト）に追加します。
- 表示されたタスクの コマンド・目的語・位置関係・繰り返し・数量・時間 が合っているかご確認ください。
- 解釈できなかったり誤っている場合は表現を変えて入力し直してみてください。
- LLM を利用しているため同じ入力内容でも解釈結果が異なる場合があります。
実行中および実行予定のタスクがあればそれらの終了後、なければすぐにタスクを実行します。
ゲーム操作を指示する（割り込み）
- チャットウインドウの入力エリア左の［割り込み］チェックボックスを ON にしてから、入力エリアにゲーム操作したい内容を入力して【Send】ボタンをクリックするとチャットボットへの割り込み指示となります。
- チャットボットは LLM を利用して指示内容を解釈してタスクに変換し、キュー（タスクリスト）に割り込みタスクとして追加します。
- 実行中タスクがあればそれを停止して、追加したタスクを割り込み実行します。
- 割り込みタスク終了後、3.で停止したタスクを再実行します。
タスク操作を指示する
チャットウインドウの入力エリアにタスク操作したい内容を入力して【Send】ボタンをクリックします。
主なタスク操作コマンド
コマンド 説明 終了 実行中のタスクを終了する 全終了 実行中および実行予定のタスクをすべて終了する 一時停止 実行中のタスクを一時停止する 再開 一時停止中のタスクを再開する タスク操作はタスクリストウインドウでも行うことができます。 詳細は タスクリストの操作 をご参照ください。
指示したタスク操作が実行されます。
情報を取得する
チャットウインドウの入力エリアに取得したい内容を入力して【Send】ボタンをクリックします。
主な情報取得コマンド
コマンド 説明 現在地 現在地を確認する 経過時間 現在のタスクの経過時間を確認する 進行状況 現在のタスクの進行状況を確認する HP 現在の HP を確認する 場所 ターゲットにできる場所のリストを表示する 人 ターゲットにできる人のリストを表示する 敵 ターゲットにできる敵のリストを表示する アイテム ターゲットにできるアイテムのリストを表示する コマンド一覧は「ヘルプ」を入力すると表示されます。
取得した情報が表示されます。
新規コマンドを自動生成する
チャットウインドウで未実装のコマンドを要求するような指示を入力して【Send】ボタンをクリックします。
チャットボットが新しいコマンドを作成するか聞いてきたら、コマンドの仕様 をよく確認してから「はい」を入力します。
- Behavior Tree Maker 起動時に実行中および実行予定のすべてのタスクが終了されるのでご注意ください。
- 「いいえ」を入力すると元の処理に戻ります。必ず「はい」か「いいえ」を入力する必要があります。
Behavior Tree Maker が起動されると、LLM を利用して「実現したい動作」を解釈してビヘイビアツリーを自動生成し、新規コマンドとして自動保存されます。
メニューバーの［ファイル］→［Behavior Tree Maker の終了］を選択するとチャットボットに戻ります。
音声で入出力する
メニューバーの［ツール］→［音声入出力］チェックボックスを ON にするとチャットウインドウ下部の【Send】ボタンの右にマイクアイコンが表示されます。
この状態の時はチャットボットからの応答メッセージが音声でも出力されます。
- 音声合成には OpenAI TTS（Text to speech）または VOICEVOX を利用します。
VOICEVOX を利用する場合は事前に起動しておいてください。
- 音声合成には OpenAI TTS（Text to speech）または VOICEVOX を利用します。
音声入力したい時はマイクアイコンをクリックしてマイクが赤くなるのを待ちます。
マイクアイコンが赤くなったら PC のマイクに操作したい内容を話しかけてください。
OpenAI SST（Speech to text）を利用してテキストに変換し、チャットボットへの指示となります。
メニューバー（チャットウインドウ）の操作
チャットウインドウのメニューバーでツール全体を操作します。
アプリの終了
- ［ファイル］→［アプリの終了］を選択するとすべてのウインドウを閉じてアプリケーションが終了します。
音声入出力
- ［ツール］→［音声入出力］チェックボックスを ON にすると音声で入出力することができるようになります。
詳細は こちら をご参照ください。
Behavior Tree Maker の起動
- ［ツール］→［Behavior Tree Maker の起動］を選択すると Behavior Tree Maker が起動されます。
Behavior Tree Maker については こちら をご参照ください。
内部状態のリセット
［デバッグ］→［内部状態のリセット］を選択すると確認ダイアログが表示されます。
確認ダイアログで【はい】を選択すると内部状態のリセット処理が実行されます。
内部状態のリセットを実行すると……
Behavior Tree Maker で登録・編集したデータを出荷時の状態に戻します。
チャットボットにより自動生成されたコマンドも削除されます。
具体的にはPython/data/work_spaceフォルダをPython/data/work_space_baseフォルダで上書きしています。
何かしらの異常で状態不一致になる時などにご利用ください。- 例：ビヘイビアツリーを誤って変更してしまった
- 例：ビヘイビアツリーの生成が成功したのにチャットボットから実行できない
タスクリストウインドウの操作
タスクリストウインドウには実行中および実行予定のタスクのリストが表示されています。
タスクリストを操作したい時は、まず【タスクを一時停止】ボタンをクリックしてタスクを一時停止させてください。
タスクが一時停止するとタスクリストを操作可能な状態になります。 操作したいタスクをクリックして選択してください。
- 【選択中のタスクを削除】ボタンをクリックすると選択中のタスクが削除されます。
- 【上へ】ボタンをクリックすると選択中のタスクとすぐ上のタスクの順番が入れ替わります。
- 【下へ】ボタンをクリックすると選択中のタスクとすぐ下のタスクの順番が入れ替わります。
タスクリストの操作が完了したら【再開】ボタンをクリックしてタスクを再開してください。
ツリーウインドウの操作
- マウスのミドルボタン（マウスホイール）を押したまま移動させると画面を動かすことができます。
設定ファイル
環境変数の設定
Python/.env
playable-general-agent/Python/フォルダの.env.sampleファイルを同フォルダにコピーして.envファイルを作成します。playable-general-agent/Python/.envファイルをローカル環境に合わせて編集します。OpenAI API key
OpenAI の API key は必須です。
Organization ID を使用しない場合はコメントアウトしてください。OPENAI_ORG_KEY=### # OpenAIのOrganization ID
OPENAI_API_KEY=### # OpenAIのAPI key *必須その他
FFmpeg を使用する場合は、実際のローカル環境の
binフォルダへのパスを設定してください。FFMPEG_PATH=C:/ffmpeg/bin # FFmpegのパス
ツールの設定
Python/settings.yaml
playable-general-agent/Python/settings.yamlファイルをローカル環境に合わせて編集します。ゲーム情報
game_path には実際のローカル環境のゲームバイナリのパスを設定してください。
game_window_title は 現状固定 の項目なのでこのまま変更しないください。# ゲーム情報
game:
# 実際のローカル環境に合わせて変えてください *必須
game_path: C:/Alfort/WindowsNoEditor/Alfort.exe
# 対象とするゲームウィンドウのタイトル(現状固定) *必須
game_window_title: "Alfort (64-bit Development PCD3D_SM5) "workspace
Python/dataフォルダや配下のwork_space_basework_spaceの場所を移動した場合は、本項目も合わせて変更してください。# work_space *必須
base_workspace_folder: ./data/work_space_base
workspace_folder: ./data/work_spaceチャットボット
チャットボット関連の設定を変えたい場合は、本項目を編集してください。
# chat_bot関連
chat_bot:
# model: gpt-3.5-turbo-0613
model: gpt-3.5-turbo-1106
# model: gpt-4-0613
# model: gpt-4-1106-preview
temperature: 0.0
top_p: 0.0
timeout: 20 # 秒
get_tasks_mode: oneshot # 一括方式
# get_tasks_mode: oneshot_fc # 一括方式(function calling)
# get_tasks_mode: phase # フェーズ方式
text_to_speech_mode: openai_tts
# text_to_speech_mode: voicevox詳細は こちら をご参照ください。
ログの設定
Python/logging.yaml
- 本ツールのログ出力は python の logging ライブラリ を使用しています。
ログの調整はplayable-general-agent/Python/logging.yamlファイルを編集して行ってください。