メインコンテンツへ移動
AIチュートリアル

TypeSafe Jevと構造化エミュレーターテレメトリーでスーパーマリオブラザーズを操作

TypeSafe MarioがエミュレーターのテレメトリーとRAMをJev向けの構造化JSONに変換し、モデルの選択をNESコントローラー入力に変える仕組みを解説します。要件、インストール、状態確認、ゲームプレイ、表示モード、実行成果物、モデルの判断、開発時のチェックを取り上げます。

約12分で読了
TypeSafe Jevと構造化エミュレーターテレメトリーでスーパーマリオブラザーズを操作

TypeSafe Marioの概要

TypeSafe Marioは、TypeSafeのJevモデルが初代Super Mario Bros.のコントローラー入力を選択できる実験的なコントローラーです。スクリーンショットを受け取る代わりに、モデルはエミュレーターのテレメトリーとRAMから生成された、オブジェクト中心の簡潔なJSONを受け取ります。

制御ループは次のアーキテクチャに従います。

NESエミュレーター -> テレメトリー/RAMパーサー -> 構造化JSON -> Jev Choice -> コントローラー入力

Jevが合法なアクションを選択すると、エミュレーターが数フレーム進み、新しい状態を生成します。この処理をエピソード全体で繰り返します。ローカルの生タイルグリッドはデバッグログとダッシュボードで引き続き確認できますが、モデル向け入力には重複して含めません。

利用可能なコントローラーアクション

初期のアクション空間は、意図的に7つのコントローラーマクロに限定されています。

  • noop
  • right
  • right_jump
  • right_run
  • right_run_jump
  • jump
  • left

主な機能

  • 構造化されたモデル入力: パーサーは、平坦化した文章やスクリーンショットではなく、TypeSafeにとって意味のあるJSONオブジェクトを送信します。
  • 複数の判断: すべてのリクエストで、コントローラーの選択、前方ジャンプの有用性、直近の危険度を評価します。
  • 反応時間の計測: 状態にはアクションの継続時間と観測からアクションまでの遅延が含まれます。
  • ライブダッシュボード: デフォルト表示では、ゲームプレイに加えて、アクション確率、信頼度、レイテンシ、危険度、報酬、解析済み状態を表示します。
  • 詳細な実行記録: すべての判断をJSON Lines形式で保存し、後から分析や可視化に利用できます。
  • デバッグ表示: 人間が読みやすい状態テキストとローカルのタイルグリッドを引き続き確認できます。

要件と合法的なセットアップ

プロジェクトをインストールする前に、環境が次の要件を満たしていることを確認してください。

  • Python 3.13以降
  • TYPESAFE_API_KEYに保存されたTypeSafe APIキー
  • Super Mario Bros.を合法的に利用できるローカル環境

リポジトリには、Nintendo ROMやその他の著作権で保護されたゲームデータは含まれていません。エミュレーターとゲームファイルを合法的に入手・使用する責任は利用者にあります。

インストール

READMEには、仮想環境の作成、Marioおよび開発用依存関係のインストール、APIキーの設定に使用するPowerShellコマンドが記載されています。

  1. Python 3.13の仮想環境を作成します。
  2. 必要な追加機能を含め、プロジェクトを編集可能モードでインストールします。
  3. 現在のPowerShellセッションにTypeSafe APIキーを設定します。
py -3.13 -m venv .venv
.venv\Scripts\python -m pip install -e ".[mario,dev]"
$env:TYPESAFE_API_KEY = "your-key"

your-keyを実際のTypeSafe APIキーに置き換えてください。このコマンドはPowerShellの環境変数を設定するため、別途変数を永続化しない限り、後続のコマンドは同じ設定済み環境から実行してください。

まずモデル入力を確認する

ゲームを起動する前に、state-demoを使用して、プロジェクトがTypeSafeに送信する正確なJSONとテキストを確認します。

.venv\Scripts\typesafe-mario state-demo

このコマンドはゲームを起動せず、APIも呼び出しません。モデル向けスキーマを理解し、エミュレーターの観測結果がどのように表現されるかを確認する最も安全な方法です。

構造化された状態を理解する

正規オブジェクトは、観測結果を目的別にグループ化します。

  • player: 位置、速度、接地状態、ジャンプフェーズ、パワーアップ。
  • trajectory: 滞空時間、離陸後の距離、マリオが足場の切れ目を越える動作に入っているかどうか。
  • hazard: 最大3体の敵、その予測位置、接触予測時刻、離陸の締切。
  • terrain: 障害物と足場の切れ目の形状、観測の信頼性、最後に接地していた地点のプレビュー。
  • reaction_timing: コントローラーアクションの継続時間と、計測された観測からアクションまでの遅延。
  • recent_control: 直前のアクション、その継続時間、得られた進行度、観測された結果。
  • episode: 残機、時計、進行度、停滞、死亡状態、レベルクリア状況。

構造化JSONがモデル状態の正規表現です。より詳細なテキスト表示は、デバッグとユーザーインターフェースのためだけに用意されています。デバッグスナップショットには、マリオの座標と移動、エピソードの進行度、近くの敵、ローカルの文字ベースのタイルグリッドを含めることができます。

World 1-1を実行する

World 1-1環境を起動し、エミュレーターが8ステップ進むごとにJevにアクションを選択させます。

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8

--envオプションで環境を選択し、--frames-per-decision 8でモデルが判断する間に進むエミュレーターのステップ数を指定します。デフォルト表示では、ライブゲームとモデルのテレメトリーを1つの記録可能なウィンドウにまとめて表示します。

ダッシュボードを使用する

ダッシュボードには、Jevの動作を追跡するために必要な情報が表示されます。

  • 選択されたコントローラーアクション
  • Choiceの完全な確率分布
  • モデルの信頼度
  • Jevリクエストのレイテンシ
  • 前方ジャンプの確率
  • 直近の危険度スコア
  • 報酬
  • 解析済みのゲーム状態

Rキーを押すかRestartをクリックすると、新しいエピソードを開始します。Marioが倒れるかレベルをクリアした後もダッシュボードは開いたままです。終了するにはEscまたはQを押します。

表示モードを選択する

デフォルトの統合ダッシュボードは、プレイの実行を観察または記録する場合に便利です。さらに2つのモードが、より限定的な用途に対応しています。

エミュレーターのみを表示する

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display game

game表示モードでは、エミュレーターウィンドウのみを表示します。

表示なしで実行する

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display none

none表示モードはヘッドレスで実行され、ベンチマーク形式の実行を想定しています。

3つのTypeSafe判定を理解する

各リクエストでは、同じ構造化状態に対して3つの独立した判定を評価します。

  • Choice: 次に実行可能なコントローラーマクロを選択します。
  • Noul: 現在の瞬間に前方へのジャンプが有効かどうかを推定します。
  • Score: ライブ可視化用に、直近の危険度を測定します。

これらの判定にはそれぞれ異なる役割があります。Choiceの結果がMarioを操作し、ジャンプ推定と危険度スコアが追加の解釈と可視化を提供します。

正確なタイミング計算はコード内に残されています。たとえばパーサーは、応答経過時間、敵の動き、アクションの間隔、ジャンプで安全に越えられる時間を組み合わせて、型付きのjump_must_start_this_decisionファクトを生成します。Jevはこのファクトを解釈し、コントローラーの選択を引き続き担当します。ハーネスがスクリプト化された復旧アクションで上書きすることはありません。

記録された判定を確認する

各判定は、タイムスタンプ付きのJSON Linesファイルに書き込まれます。

artifacts/run-<timestamp>.jsonl

レコードには次の情報が含まれます。

  • Jevのレイテンシ
  • アクションの確率
  • 信頼度
  • 正規化されたモデル状態
  • 生のデバッグ状態
  • ゲームの結果

これらのレコードにより、実行後のプレイを確認するために必要なデータが得られます。また、ライブオーバーレイやレンダリングしたソーシャル向けクリップの入力としても利用できます。

高度な利用のヒント

ゲームプレイ前に観測結果を検証する

エミュレーターを起動したりAPI呼び出しを消費したりせずに、モデル向けの表現を確認したい場合は、ライブセッションの前にstate-demoを実行します。正規化された構造化状態と、人間向けのデバッグテキストが分離されている点に特に注意してください。

アクションの間隔と併せてタイミングファクトを解釈する

コントローラーは複数フレーム単位で動作するため、反応タイミングは外部の仮定ではなく状態の一部です。判定を確認するときは、選択されたアクションを、応答遅延、アクション時間、予測される敵との接触、パーサーが報告する離陸期限と比較してください。

タスクに適した表示を使用する

  • モデルの推論シグナルとゲームプレイを同時に確認する場合は、デフォルトのダッシュボードを使用します。
  • エミュレーターの出力だけが必要な場合は、--display gameを使用します。
  • ヘッドレスのベンチマーク実行には--display noneを使用します。

確率分布全体を分析する

選択されたアクションだけに分析を限定しないでください。ダッシュボードとJSONLアーティファクトには、Choiceの確率分布全体と信頼度が含まれています。これにより、Jevが1つのアクションを強く優先したのか、または重みが近い複数の選択肢から選んだのかを確認できます。

開発時のチェックを実行する

リポジトリには、コントリビューター向けのフォーマット、リンティング、テスト用コマンドが含まれています。設定済みの仮想環境から実行してください。

.venv\Scripts\ruff format --check src tests
.venv\Scripts\ruff check src tests
.venv\Scripts\python -m pytest -q

1つ目のコマンドはフォーマットを確認し、2つ目はRuffのリンターチェックを実行し、3つ目は簡潔な出力でテストスイートを実行します。

まとめ

TypeSafe Marioは、スクリーンショット駆動のゲーム操作に代わる構造化されたアプローチを示します。エミュレーターのテレメトリとRAMを正規化されたオブジェクト中心のJSONに変換し、Jevにコンパクトな実行可能アクションの集合から選択させ、ライブ確認や後の分析に備えてすべての判定を記録します。まずstate-demoから始め、ダッシュボードでWorld 1-1を実行し、生成されたJSONLアーティファクトを使って、状態、タイミング、信頼度、結果の関係を理解してください。