====== マッピング ======
==== 導入 ====
マッピングは、クラス、フィールド、およびメソッドの名前を定義します。通常の Loom 環境では、 [[https://github.com/FabricMC/yarn|Yarn]] マッピングが使用され、コミュニティによって決定された Minecraft コードベースに意味のある名前が付けられます。 [[https://github.com/FabricMC/intermediary|Intermediary]] も、 Fabric で使用される重要なタイプのマッピングです。 マッピングの必要性は、複数の課題を提示する Minecraft リリースの難読化から生じています。再マッピングは、コンパイル済みのクラスまたはソースファイルにマッピングを適用するプロセスです。
==== マッピングの使用 ====
Loom では、マッピングは、開発環境で使用される Minecraft のクラス、フィールド、およびメソッドの名前を定義します。これらの名前は、インストールされたマッピングに応じて、開発環境ごとに異なる場合があります。
Yarn は、Loom が使用するデフォルトのマッピングです。貢献が受け入れられると、Yarn は徐々に改善され、新しいリリースを受け取ります。 Loom のマッピングは、ビルドスクリプトの ''mappings'' 依存関係設定を使用して指定され、依存関係を更新することで更新できます。 Minecraft と、 ''modCompile'' などの Mod によって拡張された依存関係構成に含まれる依存関係は、マッピングで再マップされます。 Yarn でマップされていないクラス、フィールド、メソッドには、 ''class_1234''、 ''method_1234''、 ''field_1234'' などの中間名が付けられます。
dependencies {
[...]
mappings "net.fabricmc:yarn:${project.yarn_mappings}"
}
開発環境でマッピングを変更すると、 Minecraft および含まれるすべての Mod のクラス、メソッド、およびフィールドの名前が変更され、変更された名前を参照するようにコードを更新する必要があることが予想されます。 [[tutorial:migratemappings|このプロセスは部分的に自動化できます。]] また、更新されたマッピングで Minecraft ソースにアクセスするには、 ''genSources'' を実行する必要があります。
Loom の ''remapJar'' タスクは、中間の名前を使用してビルドされた jar である主要な Mod アーティファクトを生成します。ただし、テストや検証は実行しません。 ''build'' は、エンド ユーザーが使用する JAR を生成するために常に使用する必要があります。 さらに、 ''sourcesJar'' タスクが存在する場合、 ''remapSourcesJar'' は中間名を使用してソース jar を生成します。 これらの jar は、Mod としてインストールするか、 ''modCompile'' 依存関係構成を使用して開発環境に含めることができます。
* **''-dev'' jar (''jar'' タスク出力)は中間名を使用しないため、役に立ちません。** 開発環境外で Mod としてインストールすることはできず、マッピングが一致する開発環境でのみ機能します。通常の jar (''remapJar'' タスク出力)を代わりに使用し、 ''modCompile'' などの Mod 拡張依存関係構成を使用して開発環境にインストールする必要があります。
* **Yarn の名前は開発環境でのみ適用されます。** 開発環境の外では、中間の名前だけが存在します。つまり、コードは、見たり書いたりしたものと正確には一致しません。このトランジションは Loom が透過的に処理しますが、リフレクションを使用する場合は注意が必要です。
=== Mojang のマッピング ===
Loom 0.5 以降では、次のように、 Yarn ではなく Mojang の公式マッピングを使用することもできます:
dependencies {
[...]
mappings loom.officialMojangMappings()
}
Mojang のマッピングには、使用可能でありながら Yarn よりも制限の厳しいライセンスが付属しています。ご自身の責任で使用してください。
=== カスタムマッピング ===
Gradle プロジェクトのセットアップでは、 Fabric Loom のカスタムの小さなマッピングを使用できます。
たとえば、マッピングに使用したい Yarn のカスタムブランチがある場合は、 "./gradlew build" コマンドで糸をビルドし、 "build/libs" ディレクトリにある jar ファイルを取り出して、次の場所に移動します。 Gradle プロジェクトのフォルダー"mapping"。 次に、マッピングの依存関係エントリを次のように変更します:
dependencies {
mappings fileTree(dir: "mapping", include: "**.jar")
}
マッピングを配置するディレクトリを任意のカスタム名に変更できます。 上記の "dir" 引数の名前を変更するだけです。 マッピング ディレクトリにマッピング jar 以外のファイルがある場合、Gradle ビルドは失敗することに注意してください。
==== 再マッピング ====
再マッピングは、コードにマッピングを適用し、ある名前のセットから別の名前に変換するプロセスです。 Java ソースコードとコンパイル済み Java コードの両方を再マップできます。これには、マッピングに従って参照の名前を変更すること、およびメソッドの名前を慎重に変更してオーバーライドを保持することが含まれます。 [[tutorial:reflection|リフレクション]] で使用される名前には影響しますが、コードの動作は変わりません。
[[https://github.com/FabricMC/tiny-remapper|Tiny Remapper]] は、コンパイルされた Java コードを再マップできるツールです。コマンドラインインターフェースとプログラム可能なインターフェースを備えています。 Loom は Tiny Remapper を多くのタスクに使用し、Fabric Loader は Tiny Remapper を使用して Minecraft コードを仲介に再マッピングします。 Loom は、Java ソースコードをリマップすることもできます。
==== 難読化と難読化解除 ====
Minecraft Java Edition のリリースは、難読化された jar ファイルです。つまり、意味のある名前情報が取り除かれ、むき出しのロジックだけが残されているコンパイル済みのバイナリです。 難読化の背後にある動機は、リバース エンジニアリングを防ぎ、ファイル サイズを縮小することです。 Minecraft のような Java プログラムは逆コンパイルが比較的簡単ですが、難読化によって Mod 製作に役立つ多くの情報が取り除かれています。そもそも Minecraft 向けの開発がどのように可能であるか疑問に思う人もいるかもしれません。
Yarn のようなマッピングは、開発に意味のある名前を提供します。マッピングを使用すると、Minecraft のコードを理解し、そのための Mod を作成できます。マッピングは、クラス、フィールド、メソッド、パラメーター、およびローカル変数の名前を提供できます。 これらのマッピングが完全ではないことは明らかです。 Minecraft 全体をマッピングするには、複数の貢献者による多くの当て推量が必要です。マッピングは不完全な場合があり、より正確な名前が見つかると変更されることがあります。
==== Intermediary ====
Minecraft の難読化の特性は、 Minecraft のバージョン間で常に一貫性があるとは限らないことです。クラスは Minecraft のあるバージョンでは ''abc'' と呼ばれ、別のバージョンでは ''abd'' と呼ばれることがあります。同じ矛盾がフィールドとメソッドにも当てはまります。この不一致により、 Minecraft のバージョン間でバイナリの非互換性が生じます。
ライブラリの 1 つのバージョン用にコンパイルされた Java コードは、別のバージョンでも動作するため、ライブラリの 2 つのバージョンはバイナリ互換性があります。簡単に言えば、ライブラリが同じメソッドと同じ名前のフィールドを持つ少なくとも同じクラスを公開する場合、バイナリ互換性が達成されます。 Minecraft の難読化の不一致は、バイナリ互換性がないため、Mod のライブラリとして Minecraft を使用する際の課題となります。
Intermediary は、 Minecraft のバージョン間で Minecraft の内部の安定した名前を定義します。 中間名の目的は、常に同じクラス、フィールド、またはメソッドを参照することです。 Yarn 名とは異なり、中間名は意味がなく、代わりに ''class_1234''、 ''method_1234''、 ''field_1234''などの数値パターンに従います。
安定したマッピングであるため、 Intermediary は Minecraft のバイナリを複数のバージョン(スナップショットバージョンなど) 間で互換性を持つようにすることができます!互換性は、バージョン間で変更されていないゲームの部分に対してのみ保証されます。開発環境の外にインストールされた場合、 Fabric ローダーは、ゲームが開始される前に Minecraft (および Realms クライアント)を再マッピングすることにより、中間名を持つ環境を提供します。これは、 Fabric ローダーがインストールされた実稼働環境からのクラッシュレポートを調べることで確認できます。これには中間名が含まれます。 Loom によって適用される中間名でコンパイルされた Mod は、当然この環境と互換性があります。