「Coremodsの基礎」を編集中

{{前提MOD|reqmod="ForgeModLoader"}}

ここでは、coremodsフォルダに入れるタイプのmod作成方法を紹介します。

==概要==

===Coremodとは===
通常 Minecraft.jar 内に上書きが必要な変更を施すような mod(前提Modなど等)を、coremods フォルダに入れるだけでインストールできるようにする機能です。

ただし、既存書き換えのMODをそのまま coremod にすることは出来ません。
Mod作者自身が coremod として作成する必要があります。

===仕組み===
FMLでは、Java のデフォルトクラスローダーではなく、独自のクラスローダーを用いてクラスを読み込むように、Minecraftを改変します。通常コンパイル済みのClassファイルの内容は変更できませんが、クラスローダーを差し替えることで、クラスが読まれる直前に、そのバイトコードに対して変更を加えるポイントの追加を実現しています。

この機能を利用するのが、このチュートリアルで解説する Coremod となります。

Coremod を用いる事で、Minecraftの実行中に、初めてクラスがロードされた際に、クラスのバイトコードを置換、または部分的に書き換える事ができるようになります。動的に書き換えるため、Minecraft.jar 内(※Coremod部分以外のFMLコードも含む)および、mods 内の zip 等のClassファイルを、直接上書きして変更することなく改変することを可能とします。

====動的なクラス書き換えって、重くないの？====
クラスのロードは、基本的に最初にクラスの参照が要求された際に、1回だけ行われます。

一度ロードされたクラスは、通常どおりコンパイルされたclassファイルとなんら違いはありません。

つまり、施した改変内容以上のパフォーマンスへの影響は、ほぼ無いと考えて差し支えありません。

===ASMライブラリ===
ASMライブラリとは、クラスのバイトコードに対し、動的に変更を施すことできるバイトコード操作ライブラリのことです。

FMLにバンドルされているので、別途ライブラリを添付することなく、FMLをインストールするだけで利用が可能です。

本チュートリアルでは、最低限の機能のみの実装のみを紹介するため、ASMライブラリ等の使い方については別途検索ください。

==実装==

今回作成するソースファイルは以下になります。

;tutorial/asm/TutorialCorePlugin.java
:coremods読み込みの基点となります。

;tutorial/asm/TutorialModContainer.java
:ModLoaderにおけるmod_XX.classのバージョン情報等のみを格納するものです。
:FMLでは情報を格納するのにアノテーションや mcmod.info ファイルを使うこともできます
:しかし、Coremodは読み込み方法が異なるので記載も別となっています。

;tutorial/asm/TutorialTransformer.java
:Classの改変機能を実装します。

;META-INF/MANIFEST.MF
:ソースファイルではありませんが、FMLがcoremodである事を認識するのに必要です。

※改変を施す部分のコードは、仮実装でありそのままでは動きません。
ソースコメントを参照し、必要な実装を施して書き換えましょう。

===TutorialCorePluginクラス作成===

# 任意の名前のクラス(ここではTutorialCorePlugin)を作成します。
# IFMLLoadingPlugin、IFMLCallHook を実装します。

<source lang="java">
// パッケージは、クラス(ファイル名)の衝突を回避するために、汎用的ではないユニークなパッケージ名を使用しましょう。
// 例) 作者名、ドメイン など (一意性のあるものが好ましい)
// 
// ここでは便宜上 tutorial.asm パッケージとしています。
// asm は ASM機能を使うクラスを配置する場合の慣例ですが、解りやすくする以外の意味はなく、必ずこうしないといけないわけではありません。
package tutorial.asm;

import java.io.File;
import java.util.Map;

import cpw.mods.fml.relauncher.IFMLCallHook;
import cpw.mods.fml.relauncher.IFMLLoadingPlugin;
import cpw.mods.fml.relauncher.IFMLLoadingPlugin.TransformerExclusions;

// TransformerExclusions.value: coremods でロードする際に参照されるため、パッケージ名と一致させてください。
// IFMLLoadingPlugin: Coremods の基礎インタフェース
// IFMLCallHook: Coremods 内で、coremod 自身のパス等を取得する等の際に必要となります。

@TransformerExclusions(value={"tutorial.asm"})
public class TutorialCorePlugin implements IFMLLoadingPlugin, IFMLCallHook
{
    // coremod 自身のファイルパスの保存用
    public static File location;
    
    // 今回は使用しません
    @Override
    public String[] getLibraryRequestClass()
    {
        return null;
    }

    // Class の改変機能を実装したクラスの完全修飾名を返します。
    @Override
    public String[] getASMTransformerClass()
    {
        return new String[]{"tutorial.asm.TutorialTransformer"};
    }

    // coremod の名前やバージョン情報の格納クラスの完全修飾名を返します。
    @Override
    public String getModContainerClass()
    {
        return "tutorial.asm.TutorialModContainer";
    }

    // coremod 読み込みの基点クラスの完全修飾名を返します。
    @Override
    public String getSetupClass()
    {
        return "tutorial.asm.TutorialCorePlugin";
    }

    // IFMLCallHook のメソッドです。
    // 今回は coremod 自身の jar ファイルパスを取得します。
    @Override
    public void injectData(Map<String, Object> data)
    {
        if (data.containsKey("coremodLocation"))
        {
            location = (File) data.get("coremodLocation");
        }
    }

    @Override
    public Void call() throws Exception
    {
        return null;
    }
 }
</source>

===TutorialModContainerクラス作成===

# 任意の名前のクラス(ここではTutorialModContainer)を作成します。
# ModContainer を実装します。

Coremod 用のModでは、通常の mod読み込み処理より前にModContainerが要求されるため、MetaDataアノテーションや、mcmod.infoなど、MODのメタデータ設定処理を利用できません。

そのため、別の形式で記載することが必要になっています。

ID、名前、バージョン情報を変更できれば良いため、ここでは DummyModContainer クラスを継承して作成しています。

<source lang="java">
package tutorial.asm;

import java.util.Arrays;
import java.util.List;

import com.google.common.eventbus.EventBus;
import com.google.common.eventbus.Subscribe;

import cpw.mods.fml.common.DummyModContainer;
import cpw.mods.fml.common.LoadController;
import cpw.mods.fml.common.ModMetadata;
import cpw.mods.fml.common.event.FMLInitializationEvent;
import cpw.mods.fml.common.versioning.ArtifactVersion;

// 必ずしも DummyModContainer を継承している必要はありません。
// cpw.mods.fml.common.ModContainer さえ実装していれば、どんなクラスでも構いません。

public class TutorialModContainer extends DummyModContainer
{
    public TutorialModContainer()
    {
        super(new ModMetadata());

        // 他のModと区別するための一意なIDやmodの名前など、MODのメタデータを設定します。
        ModMetadata meta = getMetadata();

        meta.modId       = "transformertutorial";
        meta.name        = "TransformerTutorial";
        meta.version     = "1.0.0";
        meta.authorList  = Arrays.asList("Author");
        meta.description = "";
        meta.url         = "";
        meta.credits     = "";
    }
}
</source>

===TutorialTransformerクラス作成===

# 任意の名前のクラス(ここではTutorialTransformer)を作成します。
# IClassTransformer インタフェースを実装します。

<source lang="java">
package tutorial.asm;

import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;

import org.objectweb.asm.ClassReader;
import org.objectweb.asm.ClassWriter;
import org.objectweb.asm.Opcodes;
import org.objectweb.asm.tree.ClassNode;
import org.objectweb.asm.tree.InsnList;
import org.objectweb.asm.tree.MethodInsnNode;
import org.objectweb.asm.tree.MethodNode;
import org.objectweb.asm.tree.VarInsnNode;

import cpw.mods.fml.relauncher.FMLRelauncher;
import cpw.mods.fml.relauncher.IClassTransformer;

// Opcodes : インプリメントすると、ASMによるバイトコード定数にアクセスするのに便利です。
// 必須ではありません。不用な場合は implements から削除してください。

public class TutorialTransformer implements IClassTransformer, Opcodes
{
    // 改変対象のクラスの完全修飾名です。
    // 後述でMinecraft.jar内の難読化されるファイルを対象とする場合の簡易な取得方法を紹介します。
    private static final String TARGET_CLASS_NAME = "net.minecraft.src.TargetClass";

    // クラスがロードされる際に呼び出されるメソッドです。
    @Override
    public byte[] transform(String name, byte[] bytes)
    {
        // FMLRelauncher.side() : Client/Server どちらか一方のを対象とする場合や、
        // 一つのMODで Client/Sever 両方に対応したMODで、この値を判定して処理を変える事ができます。
        // 今回は"CLIENT"と比較し、Client側のファイルを対象としている例です。
        // Client側専用のMODとして公開するのであれば、判定は必須ではありません。

        // name : 現在ロードされようとしているクラス名が格納されています。
        if (!FMLRelauncher.side().equals("CLIENT") || !name.equals(TARGET_CLASS_NAME))
        {
            // 処理対象外なので何もしない
            return bytes;
        }

        try
        {
            // --------------------------------------------------------------
            // クラスファイル丸ごと差し替える場合
            // --------------------------------------------------------------
            // return replaceClass(bytes);

            // --------------------------------------------------------------
            // ASMを使用し、既存のクラスファイルに改変を施す場合。
            // --------------------------------------------------------------
            // return hookDoRenderLivingMethod(bytes);

        }
        catch (Exception e)
        {
            throw new RuntimeException("failed : TutorialTransformer loading", e);
        }
    }

    // 下記の想定で実装されています。
    // 対象クラスの bytes を ModifiedTargetClass.class ファイルに置き換える
    private byte[] replaceClass(byte[] bytes) throws IOException
    {
        ZipFile zf = null;
        InputStream zi = null;

        try
        {
            zf = new ZipFile(TutorialCorePlugin.location);

            // 差し替え後のファイルです。coremodのjar内のパスを指定します。
            ZipEntry ze = zf.getEntry("ModifiedTargetClass.class");

            if (ze != null)
            {
                zi = zf.getInputStream(ze);
                bytes = new byte[(int) ze.getSize()];
                zi.read(bytes);
            }

            return bytes;
        }
        finally
        {
            if (zi != null)
            {
                zi.close();
            }

            if (zf != null)
            {
                zf.close();
            }
        }
    }

    // 下記の想定で実装されています。
    // EntityLiving.class の doRenderLiving の先頭に
    // tutorial/test.class の passTestRender(EntityLiving, double, double, double)メソッドの呼び出しを追加する。
    private byte[] hookDoRenderLivingMethod(byte[] bytes)
    {
        // ASMで、bytesに格納されたクラスファイルを解析します。
        ClassNode cnode = new ClassNode();
        ClassReader reader = new ClassReader(bytes);
        reader.accept(cnode, 0);

        // 改変対象のメソッド名です
        String targetMethodName = "doRenderLiving";

        // 改変対象メソッドの戻り値型および、引数型をあらわします
        String targetMethoddesc = "(Lnet/minecraft/entity/EntityLiving;DDDFF)V";

        // 対象のメソッドを検索取得します。
        MethodNode mnode = null;
        for (MethodNode curMnode : (List<MethodNode>) cnode.methods)
        {
            if (targetMethodName.equals(curMnode.name) && targetMethoddesc.equals(curMnode.desc))
            {
                mnode = curMnode;
                break;
            }
        }

        if (mnode != null)
        {
            InsnList overrideList = new InsnList();

            // メソッドコールを、バイトコードであらわした例です。
            overrideList.add(new VarInsnNode(ALOAD, 1));
            overrideList.add(new VarInsnNode(DLOAD, 2));
            overrideList.add(new VarInsnNode(DLOAD, 4));
            overrideList.add(new VarInsnNode(DLOAD, 6));
            overrideList
                    .add(new MethodInsnNode(INVOKESTATIC, "tutorial/test", "passTestRender", "(LEntityLiving;DDD)V"));

            // mnode.instructions.get(1)で、対象のメソッドの先頭を取得
            // mnode.instructions.insertで、指定した位置にバイトコードを挿入します。
            mnode.instructions.insert(mnode.instructions.get(1), overrideList);

            // 改変したクラスファイルをバイト列に書き出します
            ClassWriter cw = new ClassWriter(ClassWriter.COMPUTE_FRAMES | ClassWriter.COMPUTE_MAXS);
            cnode.accept(cw);
            bytes = cw.toByteArray();
        }

        return bytes;
    }
}
</source>

===META-INF/MANIFEST.MFファイルの作成===

# META-INF/MANIFEST.MFファイルを作成します。
# TutorialCorePlugin の完全修飾クラスの名(パッケージ名を含む名前)を指定します。

<source lang="java">
Manifest-Version: 1.0
FMLCorePlugin: tutorial.asm.TutorialCorePlugin
</source>

==jarパッケージへのまとめ方==
前述で作成したclassをjar形式にまとめます。<br />
coremods用のmodではjar形式でなければ読み込まれません。

今回の例では下記のようなファイル構成となります。
* tutorial.jar
** META-INF
*** MANIFEST.MF
** tutorial
*** asm
**** TutorialCorePlugin.class
**** TutorialModContainer.class
**** TutorialTransformer.class
** ModifiedTargetClass.class (丸ごと差し替える場合に用いるクラス)
  
通常の mod のように、zip で圧縮し、拡張子を .zip から .jar に変更すれば完成です。

※jarコマンドを用いて作成することも可能ですが、今回は割愛します。

==テスト、デバッグ方法について==
coremod 形式の mod は、Eclipse でのデバッグで動作させるのは手間がかかります。
機能の実装部分については、書き換え元のクラスを、直接改変して試したほうが簡単でしょう。

coremodとしての動作確認は、実際の動作環境へ放り込んで行ってください。

==難読化への対抗手段の解説==

===準備===
# 改変したいClassを書き換える。
# recompile > reobfuscate し、難読化後のクラスファイルを作成する。

===クラスを丸ごと差し替える場合===
reobfに出力されたクラスファイル名を見てTutorialTransformerを適宜書き換えましょう。

※置き変えてしまうので、同一のクラスを置き買えるものとは競合してしまいます。

===ASMライブラリを用いたクラスの部分改変を行う場合===
reobf/ に出力されたクラスファイルと、改変前のクラスファイルを、JBVD等の適当な ByteCodeViewer で開き、2つを比較して改変された部分を特定します。
それを元にASMのコードに置き変え、TutorialTransformer を適宜書き換えましょう。

サンプルのようなメソッドのフック処理程度であれば、Eclipse 等の ByteCodeOutline プラグインなどで、改変部分のコードを直接ASM形式のコードに変換し、難読化される部分を書きかえる程度の修正で、そのまま使える場合もあります。

※ ByteCode操作の場合、同一クラスにに複数の改変を施すことができるため、競合させずにそれぞれの改変を施すこともできます。

==雑記==
メソッドコールの追加は今回の例のとおりですが<br />
別な処理に置き変えるなど、Javaでできることはほぼなんでも出来ますが<br />
ASMライブラリの使用方法を別途調べる必要があります。(記述時点で、日本語解説はあまり多くありません。)

<comments />
[[Category:その他]]