Slap ROM Patcher
要約
Slapは、ゲームROMファイルにパッチを適用・作成・変換するための、高速で多機能なコマンドラインツールです。HaskellとRustで開発され、クロスプラットフォーム対応、20種類のフォーマットサポート、詳細なエラー報告機能を備えています。特に、パッチの適用における複雑な仕様やエッジケースを正確に処理することに重点を置いています。
全文翻訳
slap
[画像]context
ROMパッチャーは、ゲームファイルに「パッチ」ファイルを適用するツールです。パッチとは、元のファイルを、翻訳、バグ修正、その他のROMハックのような、それ自身のバリアントに変換するためのレシピです。慣例として、ゲーム改造の成果を配布する方法は、元のファイルに適用するためのパッチを作成して配布することです。
私はROMパッチャーを作成しました。それは優れています。無料/FOSSで、マルチプラットフォーム対応、20のフォーマットをサポートし、キュートで、高速で、小さなパッチを作成します。
私がこれを構築したのは、Linuxで利用可能で、私が気に入るようなCLIツールが見つからず、FXPakのパッチ適用を円滑に行うことができなかったからです。そのため、一部はスクリプト連携を考慮して構築されています。しかし、非常に多弁でもあります。あらゆる種類の事柄に対して、構造化されたエラー/警告/観察を提供します。
パッチについては何も仮定しません。無効なものでない限り、あらゆるものを優雅に処理できると確信しています。もし何かが不正な形式であったり、一貫性はあるものの予期しない動作を引き起こしそうであったりした場合、slapはそれが何であり、どこで発生したのかを正確に伝えます。
試してみてください: CLI版、Web版。HaskellとRustで書かれており、ブラウザでうまく動作させるのは興味深い作業でした。
6つの動詞を認識します:
-
apply — パッチ + 元のROM → 変更されたROM
-
create — 2つのROM → パッチ
-
undo — パッチ + 変更されたROM → 元のROM
-
convert — パッチ(あるフォーマット)→ パッチ(別のフォーマット)
-
explain — パッチ → 人間が読める形式で何をするかの説明
-
info — パッチ → そのメタデータ
補足
正確性
現実的に存在する可能性のあるパッチであれば、当然「適用できる、正確に」というのは前提です。しかし、許容される範囲の限界はどこにあるのでしょうか?各フォーマットについて、「プロパティX」について問う必要がありました:
-
プロパティXは「仕様」の一部か?
-
アプリケーション依存の、その場しのぎの種類の事柄か?
-
仕様の一部ではないが、ワイヤー(データ形式)で表現可能な能力か?
いくつか例を挙げます:
よくできたIPSパッチとは何でしょうか?レコードは重複できますか?非単調であってもよいですか?両方とも「はい」であれば、これは当初思っていたよりも適用が難しくなります。切り捨てマーカーが、入力ファイルよりも大きいサイズに「切り捨てる」ように指示している場合、それを尊重するとはどういう意味でしょうか?
IPSは16MiBを超えるアドレスを指定できないため、ファイルの一部のみを変更するような奇妙なエッジケースを除けば、IPSは16MiBまでのファイルに対する変更しか記述できません。おおよそです。16MiBの先を見ることはできませんが、範囲内で開始して、その点を越えて16MiBよりもさらに先に書き込むレコードを記述することはできます。これは一貫性があり、予測可能な結果をもたらし、非常に奇妙です。「仕様内」でしょうか?もちろん、これらのパッチは適用しますが、作成することに同意しますか?
EBPはJSONメタデータをサポートしており、4つの文字列を格納するために使用します。表現力は、実際に行われていることよりもはるかに大きいです。「仕様」とは、「文字列以外のものが存在するならエラー」ということでしょうか?それとも逆で、任意の無限ネストが可能ということでしょうか?少なくともUTF-8でなければならないと判断できますか?
NINJA2にはクールな「正規化」機能があります。入力ROMがすでに「正規形」(インターリーブ解除、ヘッダーなし、N64の場合はz64バイトオーダーなど)でない場合、パッチャーはそれを正規形にするはずです。パッチが正規化手順fooを適用するように指示し、パッチャーが手順fooを知らない場合(これは実際にはこじつけではありません)、適用を拒否します。問題は、このフォーマットは入力のチェックサムも格納していることです。チェックサムは入力の正規化された形式に対するものです。これは保守的すぎると感じており、放棄する前に、入力ファイルがすでに期待される形状であるかどうかを確認すべきです。私のツールにそれを実行させることはできますか、それともそれは私が「抱擁/拡張/消滅」をしているということでしょうか?
BPSは「出力の他の部分からコピーする」ことを許可しているようです。これは一貫性があるのでしょうか、それともないのでしょうか?
PPF3はファイルサイズを追跡せず、undo(元に戻す)を許可します。ワイヤーはサイズの増加を記述できますが、その方法では、undoが不整合になる可能性があります。オリジナルのツールは、サイズの変更をブロックすることを意図しているように見えますが、それが機能しなかったのではないかと疑っています。ユーザーがサイズ変更を伴うundo対応PPF3を作成した場合、どうしますか?ユーザーがundoによる切り捨てを試みていることを検出することがフォーマット構造上の理由で不可能な場合、PPF3のundo機能を使用したい場合はどうしますか?
といった具合です。作成時には、どのツールでも問題なく適用できるものを生成するという保守的なアプローチをとっています。適用時には、各フォーマットの「表現範囲」全体をサポートしようと試みました。これを行うには、「線引き」がどこにあるかを理解する必要がありました。
これには、何かが間違って起こりうる方法について考えることに多くの時間を費やしました。例えば、ワイヤーが無効な命令を表現できることです。その時間の大部分は、パッチが不正な形式になりうるあらゆる方法がその名前で呼ばれるようにすることに費やされました。興味があれば、Error.hs、ApplyError.hs、およびVCDIFF.hsを参照してください。これらは私たちが注意を払っている種類のものです。
テキストエンコーディングに関する話題
一部のフォーマットはテキストメタデータを格納できます。私は、これらのすべて、または少なくともその一部がASCIIのみであるという証拠を見つけることを期待して始めました。しかし、そうではありませんでした!UTF-8を出力しており、すべての場合において「間違ってはいない」とかなり自信を持っています。多く見られるのは、「このフォーマットでは、ルールはUTF-8を使用する」(素晴らしい!)か、「このフォーマットでは、ルールは「システムコードページ」を使用する」(うわー、何だって?)のいずれかです。後者でもUTF-8は許可されます。最新のシステムでは、UTF-8はシステムコードページです。
読み取り/表示側はより複雑です。UTF-8がパッチの読み取り方法ではない場合に備えて、多くの代替デコードオプションを提供しています。
デコード/読み取りするものを保護/サニタイズします。いくつかのフォーマットには、任意のデータ用のメタデータフィールドがあります。任意のテキストではなく、任意のデータです。実際には、これらのフィールドが使用されている場合、テキストを格納するために使用されています。そのため、これらのフィールドを通常の表示およびフォーマット変換中の保持メカニズムから隔離したくはありませんが、疑わしい埋め込みファイルから制御文字の束を読み取ってからそれに基づいて行動したくもありません。実際に行っていること: すべてを表示し、何も実行しません。印刷不可能なコードポイントはエスケープされて表示され(ビープ音ではなく <U+0007>)、選択したエンコーディングでデコードできないバイトシーケンスはU+FFFDになり、どこで発生したかを示す警告が表示されます。
ベンチマーク
[画像]明確にするために
CLIテーブルのすべての数値には、プロセス起動(slapの起動も含む)が含まれています。最小のレースは、パッチ適用ではなく、10〜25ミリ秒の実行と実行時間のフロアによって決定されます。
いくつかのテーブルを用意しました。これらは、リポジトリ内のベンチマークツールから取得したもので、(原理的には)自分で実行できます。
4つのビフォー/アフターペアがあります: 4MiBのGBC ROM、16MiBのGBA ROM、64MiBのN64 ROM、520MiBのディスクイメージ。参照ツールをスクリプト化する良い方法がある各フォーマットについて、各ツールが参照ペアからパッチを作成し、各ツールが適用します。これらは時間計測されており、時間はウォームアップ実行の中央値です。すべての出力は、その時間がカウントされる前に、参照ペアとバイト単位で比較されます。
-
各セルは slap / リファレンス を読み取ります。
-
15秒を超えて実行されたものはすべて 15s+ と記述されます。
-
空白セルは、そのサイズでベンチマークされなかったペアリングです。IPSとEBPは16MiBで上限となるためです。
-
「—」は、実行が行われ、測定できるものが何も生成されなかったことを意味します。
-
ppf3は、両側でundoデータが無効な状態で比較されます。これはリファレンスツールの独自のモードです。
作成
ペアからパッチを作成する時間、slap / リファレンス
| フォーマット / リファレンス | 4MiB | 16MiB | 64MiB | 520MiB |
|---|---|---|---|---|
| ips / flips | 18ms / 12ms | 9ms / 21ms | ||
| ips32 / sips | 15ms / 8ms | 11ms / 17ms | 38ms / 68ms | 150ms / 413ms |
| ups / goUps | 9ms / 12ms | 11ms / 24ms | 44ms / 99ms | 198ms / 588ms |
| bps / flips | 57ms / 327ms | 103ms / 1.29s | 1.55s / 11.94s | 1.88s / 15s+ |
| ppf3 / makeppf3 | 11ms / 10ms | 19ms / 14ms | 74ms / 57ms | 487ms / 333ms |
| ninja1 / ninjaPhp | 17ms / 41ms | 45ms / 53ms | 130ms / 241ms | |
| ninja2 / ninja2Php | 19ms / 145ms | 50ms / 103ms | 204ms / 685ms | 1.47s / 1.59s |
| gdiff / javaxdelta | 18ms / 136ms | 12ms / 249ms | 239ms / 1.27s | 733ms / 10.76s |
| bsdiff / bsdiff | 74ms / 560ms | 110ms / 2.65s | 682ms / 14.79s | 3.57s / 15s+ |
| xdelta1 / xdelta1 | 44ms / 41ms | 45ms / 49ms | 386ms / 270ms | 1.62s / 1.33s |
| xdelta3 / xdelta3 | 76ms / 47ms | 21ms / 34ms | 398ms / 383ms | 596ms / 326ms |
パッチそのもの
作成されたもの、slap / リファレンス
| フォーマット / リファレンス | 4MiB | 16MiB | 64MiB | 520MiB |
|---|---|---|---|---|
| ips / flips | 655KiB / 654KiB | 16KiB / 16KiB | ||
| ips32 / sips | 672KiB / 899KiB | 18KiB / 23KiB | 4.4MiB / 4.7MiB | 388KiB / 613KiB |
| ups / goUps | 888KiB / 888KiB | 11KiB / 11KiB | 4.5MiB / 4.5MiB | 467KiB / 467KiB |
| bps / flips | 276KiB / 272KiB | 10KiB / 12KiB | 1.9MiB / 1.8MiB | 280KiB / — |
| ppf3 / makeppf3 | 922KiB / 937KiB | 24KiB / 33KiB | 4.6MiB / 4.9MiB | 481KiB / 728KiB |
| ninja1 / ninjaPhp | 888KiB / 899KiB | 18KiB / 23KiB | 4.4MiB / 4.7MiB | |
| ninja2 / ninja2Php | 891KiB / 903KiB | 22KiB / 28KiB | 4.4MiB / 4.7MiB | 467KiB / 679KiB |
| gdiff / javaxdelta | 600KiB / 747KiB | 21KiB / 33KiB | 1.9MiB / 1.9MiB | 367KiB / 425KiB |
| bsdiff / bsdiff | 204KiB / 215KiB | 8KiB / 8KiB | 1.9MiB / 1.8MiB | 287KiB / — |
| xdelta1 / xdelta1 | 239KiB / 239KiB | 13KiB / 17KiB | 1.7MiB / 1.8MiB | 275KiB / 279KiB |
| xdelta3 / xdelta3 | 218KiB / 236KiB | 10KiB / 13KiB | 1.7MiB / 1.7MiB | 263KiB / 272KiB |
適用
slapが作成したパッチの適用、slap / フォーマットのリファレンスアプリケーター
| フォーマット / アプリケーター | 4MiB | 16MiB | 64MiB | 520MiB |
|---|---|---|---|---|
| ips / flips | 20ms / 10ms | 33ms / 30ms | ||
| ips32 / atmosphereIps | 21ms / 9ms | 32ms / 27ms | 103ms / 103ms | 835ms / 776ms |
| ups / goUps | 15ms / 12ms | 35ms / 30ms | 126ms / 123ms | 902ms / 918ms |
| bps / flips | 34ms / 38ms | 35ms / 136ms | 122ms / 532ms | 896ms / 4.2s |
| ppf3 / applyppf3 | 16ms / 30ms | 31ms / 19ms | 112ms / 109ms | 837ms / 109ms |
| ninja1 / ninjaPhp | 21ms / 15s+ | 60ms / 15s+ | 163ms / 15s+ | |
| ninja2 / ninja2Php | 23ms / 65ms | 64ms / 51ms | 232ms / 232ms | 1.82s / 1.48s |
| gdiff / javaxdelta | 18ms / 48ms | 33ms / 55ms | 110ms / 165ms | 830ms / 1.01s |
| bsdiff / bsdiff | 44ms / 27ms | 112ms / 59ms | 471ms / 279ms | 3.41s / 1.72s |
| xdelta1 / xdelta1 | 30ms / 19ms | 65ms / 46ms | 238ms / 174ms | 1.84s / 1.18s |
| xdelta3 / xdelta3 | 35ms / 16ms | 35ms / 32ms | 152ms / 134ms | 848ms / 843ms |
sipsとmakeppf3は作成のみを行うため、このテーブルではips32とppf3はそれぞれのフォーマットのリファレンスアプリケーターと比較されています。
適用においては、セルを失う数の方が勝る数よりも多いです。カートリッジサイズでは、差は数十ミリ秒です。ここにあるすべてのアプリケーターは、slapのパッチをバイト単位で正確に受け取ります。
[画像]公平を期すために
-
javaxdeltaは、時間計測される各呼び出し内でJVMを起動します。このコストが4MiBの数値に支配的となり、520MiBではノイズに消えます。ライブラリ自体は高速です。
-
applyppf3とninjaアプリケーターは、新しい出力を書き出すのではなく、ファイルをインプレースで変更します。そのため、各時間計測実行には事前に作成されたコピーが渡され、コピーの作成は時間計測されません。520MiBでは、slapの適用時間のほとんどは520MiBの出力を書き出すことですが、インプレースアプリケーターは変更されたバイトのみを書き込みます。その行は、テーブルを共有する2つの異なるジョブです。
ブラウザ内
Web版slapの自然な比較対象は、コミュニティの長年の標準であるRomPatcher.jsです。
3つのブラウザサイズペア: 上記の4MiBと64MiBのROM、およびIPSとEBP用の8MiBペア(64MiBには対応できません)。
両サイドともslapのパッチを適用します。空白セルは、そのペアリングがそのサイズでベンチマークされなかったことを意味します。
両サイドともウォームアップ状態で時間計測されます(一度起動し、ファイルはすでにメモリ内にあります)。CLIテーブルとは異なり、起動時間はこれらの数値には含まれていません。
作成、Web版slap / RomPatcher.js
| フォーマット | 4MiB | 8MiB | 64MiB |
|---|---|---|---|
| ips | 45ms / 36ms | 17ms / 219ms | |
| ups | 6ms / 43ms | 75ms / 620ms | |
| bps | 60ms / 15s+ | 2.0s / 560ms | |
| ppf | 5ms / 31ms | 72ms / 421ms | |
| ebp | 45ms / 37ms | 17ms / 220ms | |
| aps | 6ms / 33ms | 74ms / 412ms | |
| rup | 14ms / 61ms | 214ms / 789ms |
4MiBでは、RomPatcher.jsは、純粋なJavaScriptで、Rustのdifferが歩むのと同じ検索パスを歩みます。これが15秒以上かかる理由であり、そのパッチはほぼ同じサイズで出力されます。4MiB(ソースコードの閾値)を超えると、より高速な線形パスに切り替わり、より大きなパッチが生成されます。このトレードオフは、以下のパッチテーブルに反映されます。
各々が作成したパッチ、Web版slap / RomPatcher.js
| フォーマット | 4MiB | 8MiB | 64MiB |
|---|---|---|---|
| ips | 655KiB / 886KiB | 554KiB / 556KiB | |
| ups | 888KiB / 888KiB | 4.5MiB / 4.5MiB | |
| bps | 276KiB / 308KiB | 1.9MiB / 4.4MiB | |
| ppf | 922KiB / 936KiB | 4.6MiB / 4.9MiB | |
| ebp | 655KiB / 886KiB | 554KiB / 556KiB | |
| aps | 905KiB / 908KiB | 4.5MiB / 4.6MiB | |
| rup | 891KiB / 903KiB | 4.4MiB / 4.7MiB |
適用、Web版slap / RomPatcher.js
| フォーマット | 4MiB | 8MiB | 64MiB |
|---|---|---|---|
| ips | 22ms / 4ms | 9ms / 14ms | |
| ups | 5ms / 12ms | 82ms / 98ms | |
| bps | 29ms / 10ms | 68ms / 48ms | |
| ppf | 3ms / 10ms | 43ms / 59ms | |
| ebp | 22ms / 3ms | 8ms / 19ms | |
| aps | 24ms / 11ms | 37ms / 66ms | |
| rup | 12ms / 17ms | 176ms / 198ms |
完全なグリッド、ハーネス自体、およびスクリプト化可能な参照ツールを持たない6つのCLIフォーマットは、すべて結果ディレクトリにあります。