戻る

Castlevania: Symphony of the Night が ESP32-S3 上でネイティブ動作

錬金術研究所で Castlevania: Symphony of the Night を動かす XIAO ESP32S3 携帯機

Metal Gear Solid の記事では、XIAO ESP32S3 Sense を中心に組み上げた携帯ゲーム機を紹介しました。Castlevania: Symphony of the Night(SOTN)は、それが動かすもう一つの PlayStation ゲームであり、先に動いた方でもあります。携帯機が存在する前から Waveshare の ESP32-S3 開発ボード上で 60 fps で動作しており、後に携帯機へと移りました。

これが可能だった理由は Metal Gear Solid と同じです。SOTN のコミュニティによるデコンパイルはポータブルな C としてビルドできるため、エミュレーションではなく ESP32-S3 向けにゲームをコンパイルできます。

携帯機でのゲームプレイは YouTube で視聴できます。

本記事では、移植がどのように構成されているか、ゲームを SoC のメモリにどう収めるか、ソフトウェアラスタライザがどうやって 60 fps に到達したか、オリジナルのハードウェアが隠していたバグ、そして Seeed XIAO ESP32S3 Sense を中心に組み上げた携帯ゲーム機について扱います。

なぜネイティブ移植が可能なのか

ESP32-S3 上で PlayStation をエミュレーションするのは手が届きません。エミュレータは MIPS CPU と GPU を命令単位で解釈する必要があり、SoC が持つ性能の数倍を要求します。

移植は違います。SOTN のデコンパイルプロジェクトは、PC の実行ファイルにコンパイルできる C ソースとしてゲームを再構築しています。ゲームロジックは普通の C であり、ゲームをコンソールに縛り付けている唯一のものは Sony の SDK です。つまり、ポリゴンを描画し、テクスチャをアップロードし、コントローラを読み、サウンドを再生するライブラリ呼び出しです。PC ビルドはその SDK を psyz に置き換えます。これは SDL の上に再実装されたものです。

したがって、作業は三つの部分からなります。

  1. ゲームを Xtensa 向けにコンパイルする。
  2. psyz の PC バックエンドを SoC 向けのものに置き換える。
  3. すべてを収める。

対象となる SoC は ESP32-S3 です。

アーキテクチャ

ゲームからハードウェアまでのレイヤーは次のとおりです。

  1. ゲーム: デコンパイルされたエンジン、プレイヤーと武器のコード、ステージ
  2. psyz: PSYZ_RENDERER=soft を備えた SDK 再実装
  3. プラットフォーム層(esp32/main): VSync、ルートカウンタ、入力、FAT ファイル、オーディオ、LCD スキャンアウト
  4. ESP32-S3 ハードウェア: LX7 コア、SRAM、PSRAM、フラッシュ、SPI LCD

移植のレイヤーと 2 つのコア。コア 0 にゲームとラスタライザ、コア 1 に LCD スキャンアウトとオーディオ、携帯機ではパネルと microSD が SPI2 を共有する

2 つの設計上の決定が、他のすべてを形作りました。

VRAM はゲーム自身のバッファのままにする。 PlayStation は 1 MB のビデオメモリ、つまり 16 ビットカラーの 1024×512 ピクセルを持っています。デコンパイル版はすでにこれを単なる配列としてモデル化しています。ラスタライザは(PSRAM 内の)それに直接描画し、LCD はそこから供給されます。シャドウコピーも、パネルの RGB565 への最終変換以外のフォーマット変換もありません。

ステージは静的にリンクする。 PC では、各城エリアはオンデマンドでロードされる DLL です。ESP32-S3 には動的リンカがないため、すべてのエリアがファームウェアにコンパイルされ、小さなテーブルがステージ名をその init 関数にマッピングします。この決定は 2 度問題を引き起こしました。後述の「PlayStation が許してくれるバグ」と「ステージを追加する」で説明します。

PlayStation ゲームを 512 KB に収める

研究所の像の隣に立つアルカード

最初のリンクは内蔵 RAM が 3.34 MB 不足して失敗しました。そのほとんどはゲームのせいではありませんでした。

最後のものには罠があります。一部の「読み取り専用」データは書き込まれるのです。SDK はサウンドバンクが開かれるときにバンクヘッダをその場で更新します。const として宣言されているとそれらはフラッシュ上に存在し、キャッシュ経由でフラッシュに書き込むとハードフォールト(「Dbus write to cache」)が発生します。うまくいくパターンは、const のマスタをフラッシュに置き、起動時にそれを PSRAM バッファにコピーし、ゲームにはそのコピーを書き込ませるというものです。

28 回のリンクを経て、数値は次のようになりました。

ソフトウェアラスタライザ、そして 60 fps への到達

研究所の炎。ソフトウェアラスタライザが描画する半透明エフェクト

SOTN は 2D ゲームであり、そのプリミティブの構成は小規模です。テクスチャ付きおよびグーローシェーディングのクワッド、タイルレイヤー用の 16×16 スプライト、矩形、そして線です。3D もジオメトリ変換エンジンもないため、ソフトウェアラスタライザが現実的でした。

ラスタライザは GPU リファレンスビルドに対してビット単位で一致します。最適化のたびに、PC ビルドとボードのフレームチェックサムを比較しました。

フレーム時間のほとんどはメモリアクセスに費やされていました。 テクスチャ付きの各ピクセルは、PSRAM からテクセルとパレットエントリを読み、PSRAM にピクセルを書き込みます。重要だった最適化はすべて、このトラフィックを削減するものです。

ステップ結果
三角形のエッジステッピング: 除算、次に 64 ビットアキュムレータ、次に 32 ビット 16.1664 ビットは 32 ビットコアでは遅くなった。16.16 を採用
スキャンアウトをコア 1 に移動し、notify で供給ゲームが SPI を待つことはなくなった
内蔵 RAM のパレットキャッシュ、IRAM 内のラスタループWarp Room が 31 fps
タイルレイヤーの高速パス: 1 回の読み取りで 4 テクセル、ピクセルペアを 32 ビットストア1 フレームあたり 10.4 ms から 6.1 ms へ
ゲームが描き終えたバッファからスキャンアウトコピーなし、レイテンシが 1 フレーム削減
PSRAM とフラッシュを 80 から 120 MHz へ1 フレームあたり 19.4 ms から 16.4 ms へ。60 fps

三角形ラスタライザにテクスチャ行キャッシュも試しましたが、元に戻しました。GCC がすでにロードを巻き上げていたため、何も得られませんでした。

描き終えたバッファからスキャンアウトする変更には少し説明が必要です。ディスプレイの明白な供給元は SDK の現在の表示エリアですが、それは 1 フレーム遅れています。VSync の時点で、それはゲームがこれから描画しようとしているバッファを指しているのです。そこからスキャンすると、DMA とラスタライザがフレーム全体を通して VRAM の同じ半分を奪い合うことになります。表示原点をゲーム自身のバッファ構造体から読むことで、両者は構造上、常に反対側の半分で作業するようになります。

PlayStation が許してくれるバグ

PlayStation にはメモリ保護がない。不正な読み取りはそこにある値をそのまま返し、不正な書き込みは誰もチェックしないようなメモリに着地する。PC ビルドもこうしたバグのほとんどを隠してしまう。静的領域が大きく寛容だからだ。ESP32-S3 には MMU があり、メモリは厳しく、隣人は重要である。だからこそ、移植は潜在バグを見つける非常に良い方法であることが判明した。

携帯機上で錬金術研究所での戦闘

どうやって見つけたか

パニックのバックトレースは被害者を名指しするが、犯人を名指しするわけではない。役に立ったツールは、SoC 内蔵の USB-JTAG 経由の OpenOCD と、GDB の組み合わせだった。

  1. OpenOCD 経由で SoC をリセットして停止する。
  2. パニックハンドラにブレークポイントを設定する。
  3. ヒットしたら、パニックフレームから実際の PC をデコードする。
  4. 必ず書き込んだ正確な ELF に対してデコードする。再ビルドのたびにアドレスは変わるからだ。

範囲外のパレットアニメーション

錬金術研究所はパレットアニメーション (tileset & 0xFF) + 0x7FFF | 0x4000 を要求し、これはステージのパレットテーブルのエントリ 2 をインデックスする。テーブルにはエントリが 1 つしかない。範囲外の読み取りは隣接するスプライトバンクテーブルに着地し、それがパレットアニメーション記述子として登録され、毎フレーム書き込まれた。

修正は、範囲がパレットバッファを超える記述子を拒否するものだ。同じ未定義動作は上流にも存在しており、PC では大きな BSS がそれを吸収している。

2 つのステージ、1 つの HitDetection

ステージが静的にリンクされると、122 個のグローバルシンボルが複数のステージで定義された。共有ヘッダは衝突判定やエンティティ更新などを実装しており、PlayStation では常に 1 つのステージしかロードされなかった。静的アーカイブでは、リンカが各名前を 1 つの定義に黙って解決してしまう。錬金術研究所はワープルームの HitDetection を自身のエンティティテーブルに対して実行し、破壊は 1 層後になって現れた。

修正は、2 つのステージが共有するすべてのシンボルのリストを生成し、-D 定義でステージごとにリネームするものだ。

自分のマップを書き換える部屋

扉や壊せる壁は部屋のタイルマップに書き込む。生成されたマップがフラッシュにある状態で、最初の扉がゲームをクラッシュさせた。修正は、アクティブな部屋の前景レイヤーを書き込み可能な PSRAM バッファにコピーする単一のポイントだ。

敵の名前

画面下部の敵名ボックス。かつてスタックをオーバーランしていたのと同じ BottomCornerText コードで描画されている

フェアリースクロールのレリックがあると、ゲームは攻撃した敵の名前を表示する。BottomCornerText は文字列を PlayStation の FF 00 終端文字までスキャンする。PC の文字列は普通の C 文字列なので、スキャンは終端を越えて走り、64 バイトのスタックバッファを上書きした。症状は「敵に触れた途端にフリーズする」だった。修正はスキャンに境界を設けるものだ。

PlayStation には存在しなかった競合

オーディオは 2 つ目のコアで動作し、オーディオのプルがルートカウンタを進めていた。これらのカウンタはゲームの VSync ハンドラ、テクスチャアップロード、GPU キューのコールバックを発火させる。PlayStation ではこれらは同じ CPU 上の割り込みだ。ここでは、もう一方のコアでゲームと同時に実行されていた。

修正は、カウンタのティックをコア 1 で蓄積し、ゲームスレッド上でハンドラを発火させるものだ。

決して届かなかった入力

報告は「ジャンプできない」だった。3 つのバグが積み重なっていた。

携帯機 — XIAO ESP32S3 Sense でのハードウェア立ち上げ

完成した携帯機を上から見たところ。ILI9341 パネル、ドローン用ジンバルのスティック、ボタン、そしてユニバーサル基板上の XIAO

携帯機の背面。ユニバーサル基板上のポイントツーポイント配線と、パネル自身の SD スロット(未使用)。取り外した XIAO のカメラモジュールがその横にある

携帯機の前面と、その横にある XIAO のカメラモジュール。移植では使わず、取り外した

目標は携帯ゲーム機だった。後に Metal Gear Solid を動かすのと同じハードウェアである。SOTN はその最初のゲームだった。部品は次のとおり。

XIAO には使用可能なピンが 11 本ある。パネルには 5 本(SCK、MOSI、MISO、CS、DC)とリセット線が必要で、スティックには 2 本の ADC ピンが必要だ。残りは 3 本、ボタンは 8 つ。

6 つのボタンは抵抗ラダーを介して 1 本の ADC ピンを共有する。10k のプルアップと、ボタンごとにグラウンドへの抵抗(0 Ω、2k2、4k7、10k、22k、47k)を置く。各ボタンは異なる電圧を生み出す。制約は、2 つのボタンを同時に押すと低い方として読まれることだ。各ゲームで同時に押すペア(SOTN では攻撃とジャンプ)には、残りの 2 本の専用ピンを割り当てる。

配線図全体、部品リスト、ボタンマップはリポジトリ内のハードウェアガイドにある。

携帯機の配線図。Velxio の部品アートで描画。XIAO ESP32S3 Sense、ILI9341 パネル、アナログスティック、6 ボタン抵抗ラダー、2 つの直接ボタン

立ち上げ自体が教訓のリストだった。ゲームに触る前に、カラーバーを描画し、すべてのボタンとスティックを画面に表示する別のシェイクダウンファームウェアを書いた。

携帯機 — ディスプレイ、入力、そしてウォッチポイントが捕まえたクラッシュ

すべては SD カード上に

8 MB のフラッシュには、3 MB のアプリと 3.7 MB のゲームデータを並べて置くことはできません。そのため携帯機では、すべてのデータは microSD カードから読み込まれます。このカードはパネルと SPI バスを共有しており、それが後に独自のクラッシュを引き起こしました(後述の「共有 SPI バス」を参照)。

このボード固有の 2 つの罠

GPIO43 はパネルの data/command ピンであると同時に UART0 TX でもある。 Waveshare のコードはシリアルコンソール用に UART ドライバをインストールしていました。これをやると、ピンは黙って UART に戻され、パネルはコマンドとピクセルを区別できなくなります。携帯機ではコンソールにはネイティブ USB のみを使用しています。

ネイティブ USB 経由の printf は、誰も読んでいないとブロックする。 PC を接続しているときは気づきません。しかし接続を外すと、送信バッファは数秒で埋まり、ゲームは printf の中で停止します — しかもこれは、接続を外した状態で動かすことを想定したデバイスです。ESP-IDF 自身のログを含むすべての出力は、タイムアウト 0 で書き込み、誰も読まないものは捨てるラッパーを通すようになりました。

ちらつき、そして横滑りする矩形

最初のビルドはちらつきました。SPI クロックが遅すぎるのだと思い、40 から 80 MHz に上げました。少しは改善しましたが、スキャンアウトに計測を仕込むと、実際に起きていたことが見えてきました。

タイムライン — ゲームは 16.7 ms ごとにバッファ A と B へフレームを描画し、パネルは 1 フレームの受信に約 24 ms かかるため、ゲームは DMA がまだ送信中のバッファを再描画してしまう

これはバッファコヒーレンスの問題でした。修正は、Waveshare 移植が安全網として残していたコピーパスでした — 完成したフレームをコピーし、そのコピーを送るのです。この最初のバージョンには 2 つのバグがありました。

両方の修正後も矩形は残りました。SPI クロックを 40 MHz に戻すと消えました — ジャンパワイヤが 80 MHz に耐えられなかった のです。1 バイトずれると 8 ラインのバンド全体がずれます。S3 の SPI クロックは 80 MHz のソースを分周するため、選択肢は 80 と 40 MHz しかなく、中間はありません。

ワイヤがボトルネックとなると、残された選択肢は送るデータを減らすことでした。各 8 ラインバンドは RGB565 に変換される際にフィンガープリントが取られ、パネルがすでに表示しているものと同一のバンドはスキップされます。ドロップされるフレームは約 40% から 6% に減りました。これにより、カメラが静止しているときは画面上でおよそ 55 fps が出る一方、ゲームロジックはフルスピードのままです。

ハードウェアウォッチポイントが捕まえたクラッシュ

次の報告は「START を押したら再起動した」でした。それ以前には別の報告もありました — 「テキストが表示され、その後画面が白くなり、再起動した」。

パニックは ClearOTag で発生し、メインループから 0x4b8 というオーダリングテーブルポインタで呼び出されていました。メインループは g_CurrentBuffer = g_CurrentBuffer->next で進むので、逆算すると、2 つの GPU バッファのうちの 1 つの next リンクに何かが 0x44 を書き込んでいたのです。

ESP32-S3 にはハードウェアウォッチポイントが 2 つあります。両方を、各バッファの next フィールドに、起動から 2 秒後 — 唯一の正当な書き込みが起きたずっと後に — 仕掛けました。START を押すと、CPU は犯人のストアで停止しました。

Debug exception reason: Watchpoint 1 triggered
AddPrim ← MenuDrawImg ← MenuDrawChar ← MenuDrawStr ← MenuDrawStats ← MenuDraw

ポーズメニューは &g_CurrentBuffer->sprite[g_GpuUsage.sp] で次の空きスプライトを取得し、境界チェックを一切していません。sprite[] は GPU バッファの最後のフィールドで、2 つ目のバッファはそのすぐ後ろ — next リンクから始まる形で — 配置されています。統計テキストの描画が 512 スプライトを超え、AddPrim がリンクの上にプリミティブヘッダを書き込んでいました。同じゲームは他所では g_GpuUsage.sp < MAX_SPRT_COUNT をチェックしていますが、メニューはしていませんでした。2 行で修正できました。

2 つの GPU バッファはメモリ上で背中合わせに並んでいる。ポーズメニューの 513 番目のスプライトが次のバッファの next リンクに着地し、それをハードウェアウォッチポイントが捕まえた

共有 SPI バス

その直後、ステージロード時に別のクラッシュが現れました — SPI ドライバのアサーション running_cmd == 0 です。パネルの DMA 転送がまだワイヤ上にある間に、カードがコマンドを開始していました。Waveshare ボードではカードはオプションの音楽をストリーミングするだけでしたが、携帯機ではすべてを担っています。

修正はミューテックスです。

自分を誤解させずに計測する

この期間からの 2 つの教訓です。

ボードに書き込まずに各ビルドを実行する

数時間の試行錯誤の後、変更のたびにボードへ書き込むことがループの中で最も遅い部分になっていました — USB 経由でイメージを書き込み、再起動を待ち、ボードを再びリセットせずにシリアルポートへ再接続し、ログを読み、繰り返す。そこで各ビルドを実行・確認するために、Velxio のコマンドラインクライアントである velxio-cli を使いました。これは私のツールチェーンが生成したのと同じ .bin を受け取り、Velxio のシミュレートされた ESP32-S3 上で一定のシミュレート時間だけ実行し、シリアル出力を返してくれるので、ハードウェアに触れることなくカウンタやタイミングを読むことができました。ボードに新しいイメージが書き込まれるのは、ビルドがそれに値するときだけでした。

# velxio.toml, next to the build: board = "xiao-esp32-s3", firmware = the merged .bin
velxio-cli run --timeout 5000 --timeout-exit-code 0 --serial-log-file serial.log .

インストールして最初の実行を行うには数分かかります — velxio-cli クイックスタートを参照してください。

ステージを追加する — 再びメモリ予算

Alchemy Lab を出ると Castle Entrance(NP3)へつながります。これを追加すると、内部 RAM が 160 KB オーバーフローしました。このステージの圧縮グラフィックス、パレット、タイルマップ、スプライトテーブルは書き込み可能として宣言されていたため、起動時に RAM へコピーされていました。それらを const にすることでフラッシュへ移動しました。上流の PC 移植はすでに NP3 を追加しており、そのコミットはきれいに取り込めました。

さらに 2 つの発見がありました。

生成ファイルは各ユーザーのディスクから再生成されるため、const の変更は生成されたソースではなくスクリプト(esp32/const_stage_tables.py)に置かれています。

同様の移植へのアドバイス

現状と次のステップ

携帯機での錬金術研究所のもう一つの戦い

コードは GitHub の davidmonterocrespo24/sotn-decomp(ブランチ esp32-port)にあります。配線図と部品リストはハードウェアガイドにあります。ゲーム本体はご自身で用意する必要があります。リポジトリにはゲームデータは含まれていません。

SOTN デコンパイルのコントリビューターの皆さん、そして psyz の Xeeynamo に感謝します。このプロジェクトは彼らの成果の上に成り立っています。


共有:
David Montero

執筆者

David Montero

Creator of Velxio, the open-source circuit and Arduino simulator.

GitHub velxio.dev

関連記事


前の記事
ブラウザ上のRaspberry Pi 4と5 — 基本モードとLinuxモードを順を追って解説
次の記事
ESP32-S3でネイティブ動作するMetal Gear Solid