Modlet

Windows をお使いの皆様は、Visual Studio Community を利用する選択肢が最も有力です。

インストーラを起動して、.NET デスクトップ開発にチェックを入れます。インストールされる個別のコンポーネントの中に、.NET Framework 4.x SDK と Targeting Pack が含まれていることを確認してください。執筆時点の最新版は 4.8.1 です。
インストールにはしばらく時間がかかります。再起動を促された場合、無理して続行せず再起動をして仕切り直しましょう。

Visual Studio を起動して、新しくプロジェクトを作成します。以下の設定を確認してください:

• プロジェクト テンプレートは Class Library(.NET Framework) を選択すること
• フレームワーク バージョンはインストールしたバージョンを選択すること

.NET Core や WPF .NET Framework 等をターゲットにコンパイルされた DLL は、7DTD に認識されません。 必ずプレーンな .NET Framework を選択してください。

ソリューションの名前は TestProject とします。

ソリューションが作成されたら、必要に応じて参照を追加してください。必須の参照は 0Harmony.dll と Assembly-CSharp.dll です。
Steam デフォルト設定では以下のパスに存在します:
%PROGRAMFILES(X86)%\Steam\steamapps\common\7 Days To Die\7DaysToDie_Data\Managed\

macOS や Linux ディストリビューションをお使いの皆様は、Visual Studio Code を利用する選択肢が最も有力です。

加えて、以下の SDK を入手してください:

• Mono Project

SDK がインストールされると、mcs コマンドが使用可能になります。使用できない場合、お使いの OS に対応していない可能性があります。OS を最新版に更新する、もしくは他の無料の Linux ディストリビューションを利用する、Windows を利用する等、回避策を検討してください。

Visual Studio Code を起動して、ワークスペースを準備します。ディレクトリ名は TestProject とします。

TestProject ディレクトリに .vscode という名前のディレクトリを配置し、tasks.json という名前のファイルを準備します。
もしくは、ショートカットキー Ctrl + Shift + B (macの場合は ⌘Cmd + ⇧Shift + B) から、テンプレート Others のタスクを構成してください。

□ .vscode/tasks.json

{
    "tasks": [
        {
            "label": "compile",
            "type": "shell",
            "command": "mcs",
            "args": [
                "-target:library",
                "-warn:0",
                "-o+",
                "-unsafe",
                "-r:${userHome}/.steam/steam/steamapps/common/7 Days To Die/7DaysToDie_Data/Managed/0Harmony.dll",
                "-r:${userHome}/.steam/steam/steamapps/common/7 Days To Die/7DaysToDie_Data/Managed/Assembly-CSharp.dll",
                "-r:${userHome}/.steam/steam/steamapps/common/7 Days To Die/7DaysToDie_Data/Managed/UnityEngine.CoreModule.dll",
                "-langversion:latest",
                "-out:${workspaceFolderBasename}.dll",
                "**/*.cs",
            ],
            "options": {
                "cwd": "${workspaceFolder}"
            },
            "problemMatcher": [],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

0Harmony.dll や Assembly-CSharp.dll までのパスは、ご自身の環境に置き換えてください。必要に応じて、参照を追加してください。

Harmony に対してフックを仕掛けるには、インターフェース IModApi を実装したクラスが必要です。

□ Harmony/TestProject_HarmonyInit.cs

using HarmonyLib;
using System.Reflection;
using UnityEngine;

public class TestProject_HarmonyInit : IModApi
{
    public void InitMod(Mod _instance)
    {
        Debug.Log($" Loading Patch: {GetType()} Mod: {_instance.ModInfo.Name}");
        var harmony = new Harmony(GetType().ToString());
        harmony.PatchAll(Assembly.GetExecutingAssembly());
    }
}

このコードにより、7DTD 側に Harmony を実装している Modlet であると宣言することになります。
ビルドが正常終了することを確かめてください。

よくあるエラー

出てきたエラーコード error CSXXXX を検索すれば、だいたい docs.microsoft.com のトラブルシューティング ページに案内されます。ここでは、陥りやすいエラーとその回避策を記述します。

error CS1525: Unexpected symbol `***'(, expecting `***' or ...)

文法エラーです。C# の文法に則っているか確認してください。

error CS0117: `***' does not contain a definition for `***'

定義が不足しています。対象のクラスや名前空間に定義が含まれているかどうか、キーワードが正しいかどうか確認してください。

error CS0246: The type or namespace name `***' could not be found. Are you missing an assembly reference?

参照が不足しているため、クラスや名前空間が利用できない状態です。Managed ディレクトリの中から必要な DLL を参照に追加してください。

error CS0006: Metadata file `/.../7 Days To Die/7DaysToDie_Data/Managed/***.dll' could not be found

参照までのパスが間違っています。パスが正しいかどうか確認してください。

error CS1070: The type `***' has been forwarded to an assembly that is not referenced. Consider adding a reference to assembly `***, Version=X.X.X.X, Culture=***, PublicKeyToken=***'

参照の実体は別のアセンブリに含まれています。サジェストされた DLL を参照に追加してください。

この例では、ツールベルトを15個に増やします。

□ Harmony/FifteenSlotToolbelt_Inventory.cs

using HarmonyLib;

public class FifteenSlotToolbelt_Inventory
{
    /**
     * <summary>New slot number for Toolbelt</summary>
     */
    public const int INVENTORY_SLOT_NEW = 15;

    [HarmonyPatch(typeof(Inventory))]
    [HarmonyPatch("get_PUBLIC_SLOTS")]
    public class FifteenSlotToolbelt_harmony_Inventory_get_PUBLIC_SLOTS
    {
        public static void Postfix(ref int __result)
        {
            __result = INVENTORY_SLOT_NEW;
        }
    }
}

解説

HarmonyPatch 属性を駆使して、既存のコードを書き換えます。

10行目 [HarmonyPatch(typeof(Inventory))]

クラス Inventory に対してコード書き換えを行う宣言です。

11行目 [HarmonyPatch("get_PUBLIC_SLOTS")]

メソッド get_PUBLIC_SLOTS に対してコード書き換えを行う宣言です。

Assembly-CSharp.dll の中に、int 型の Inventory.PUBLIC_SLOTS というプロパティが存在します。この値をもとにして、ツールベルトの数が決まります。
C# では中間言語 (以下: IL) にコンパイルされる時点で、プロパティの getter は get_${PROPERTY_NAME} という名前のメソッドに変換されます。

14行目 public static void Postfix(ref int __result)

対象のメソッド内の処理が完了した後、このメソッドに記述されているコードが実行されます。

16行目 __result = INVENTORY_SLOT_NEW;

引数を書き換えます。

引数 __result はオリジナルの戻り値を受け取ります。今回は戻り値を書き換えるため、ref キーワードを設定して戻り値に影響を及ぼさせます。
引数 __result にはツールベルトの数が設定されています。処理して返されたオリジナルの値がどんなものであろうと、INVENTORY_SLOT_NEW (=今回は15) に書き換えます。

ビルドが正常終了することを確かめてください。

また、IL の中身を覗いてみたい衝動に駆られた方は、ILSpy や dnSpy を利用してください。

続いて、このままではツールベルトの HUD が2行になるにも関わらず、残りの5つを選択することができなくなります。見た目を改善するため、Config/XUi/windows.xml を書き換えます。

□ Config/XUi/windows.xml

<modconfig>
    <set xpath="/windows/window[@name='windowToolbelt']/@width">1128</set><!-- ツールベルト ウィンドウサイズ -->
    <set xpath="/windows/window[@name='windowToolbelt']/@pos">-575,92</set><!-- ツールベルト ウィンドウをどこに表示させるか、親コンポーネントからの相対位置 -->
    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@controller='Toolbelt']/grid[@name='inventory']/@cols">15</set><!-- スロットは15個 -->

    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@controller='Toolbelt']/grid[@name='inventory2']/@visible">false</set><!-- 2行目は非表示 -->

    <set xpath="/windows/window[@name='windowToolbelt']/rect/sprite[@fill='{xp}']/@width">1125</set><!-- 大きくなったウィンドウサイズに経験値インジケータを合わせる -->

    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@stat_type='Food']/@width">565</set><!-- 食料インジケータも合わせる -->
    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@stat_type='Food']/filledsprite[@name='BarContent']/@width">563</set>

    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@stat_type='Water']/@width">565</set><!-- 水分インジケータも合わせる -->
    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@stat_type='Water']/@pos">563,-77</set>
    <set xpath="/windows/window[@name='windowToolbelt']/rect/rect[@stat_type='Water']/filledsprite[@name='BarContent']/@width">562</set>
</modconfig>

以上で、Modlet に使うすべてのファイルが揃いました。

できあがった DLL を、ModInfo.xml と同じ階層に配置してください。ModInfo.xml の記述方法は、上記 Modlet の詳細を参考にしてください。
Config を書き換える XML ファイルも同じ階層に配置して問題ありませんが、7DTD の慣例に従うと、見やすくなるのと同時にわかりやすくなります。

ファイル配置の例:

TestProject/
├ Config/
│ └ XUi/
│   └ windows.xml
├ Harmony/
│ ├ TestProject_HarmonyInit.cs
│ └ FifteenSlotToolbelt_Inventory.cs
├ ModInfo.xml
└ TestProject.dll

既存のセーブデータの破損を避けるため、新しくセーブを作成することをおすすめします。
Mods ディレクトリに配置し、実際にゲームを起動して、ツールベルトが15個に増えているか確かめてみてください。
もしエラーが起こった場合、コンパイル時にエラーとして出てこないものは、[HarmonyPatch] 属性の指定部分です。スペルミスがないか確かめてください。
また、Alpha20.6(b9) の情報がすでに古くなっている可能性や、筆者がダウンロードした 7DTD は、もしかしたら一般的に知られている 7DTD ではない可能性が考えられます。IL をじっくり読んでエラーの改善を試してみてください。

オリジナルメソッドが実行される前に割り込みます。以下のような場合に用いられます:

• オリジナルメソッドの引数にアクセスしたり、変更したりする場合
• オリジナルメソッドの戻り値を変更する場合
• オリジナルメソッド内の処理をスキップさせ、以下で説明する Postfix にすべての処理を任せる場合
• あらかじめ値をセットしておき、Postfix にて処理を行う場合

usage:

• static void Prefix(ORIGINAL_ARGS...)
• static bool Prefix(ORIGINAL_ARGS...)
• static void Prefix(ref RETURN_TYPE __result, ORIGINAL_ARGS...)
• static bool Prefix(ref RETURN_TYPE __result, ORIGINAL_ARGS...)

using UnityEngine;

public class OriginalCode
{
    public void Test(int counter, string name)
    {
        // ...
    }
}

[HarmonyPatch(typeof(OriginalCode))]
[HarmonyPatch("Test")]
class Patch
{
    static void Prefix(int counter, ref string name)
    {
        Debug.Log("counter = " + counter); // 値を読む
        name = "test"; // ref キーワードを設定しているため、name が変更された状態でオリジナルメソッドの処理が走る
    }
}

public class OriginalCode
{
    public string Test(int counter, string name)
    {
        // ...
    }
}

[HarmonyPatch(typeof(OriginalCode))]
[HarmonyPatch("Test")]
class Patch
{
    static bool Prefix(ref string __result, int counter, string name)
    {
        __result = "test"; // 戻り値を書き換える
        return false; // false を返すと、オリジナルメソッドの中身は実行されない
    }
}

オリジナルメソッドが実行された後に割り込みます。以下のような場合に用いられます:

• オリジナルメソッドの戻り値にアクセスしたり、変更したりする場合
• オリジナルメソッドの引数にアクセスする場合
• オリジナルメソッドが実行された後、必ず実行させたい処理がある場合
• Prefix にて、あらかじめセットされた値を処理する場合

usage:

• static void Postfix(ORIGINAL_ARGS...)
• static void Postfix(ref RETURN_TYPE __result, ORIGINAL_ARGS...)
• static RETURN_TYPE Postfix(RETURN_TYPE __result, ORIGINAL_ARGS...)

RETURN_TYPE に ref キーワードが使えない場合で、戻り値を変更したい場合、3つ目のメソッド シグネチャを使用します。

public class OriginalCode
{
    public string Test()
    {
        return this.name;
    }
}

[HarmonyPatch(typeof(OriginalCode))]
[HarmonyPatch("Test")]
class Patch
{
    static void Postfix(ref string __result)
    {
        if (__result == "test") {
            __result = "modified";
        }
    }
}

public class OriginalCode
{
    public IEnumerable<int> GetNumbers()
    {
        yield return 1;
        yield return 2;
        yield return 3;
    }
}

[HarmonyPatch(typeof(OriginalCode))]
[HarmonyPatch("GetNumbers")]
class Patch
{
    static IEnumerable<int> Postfix(IEnumerable<int> __result)
    {
        yield return 0;
        foreach (var value in __result)
            if (value > 1)
                yield return value * 5;
        yield return 60;
    }
    // 戻り値は [ 1, 2, 3 ] から [ 0, 10, 15, 60 ] に変更される
}

using System.Diagnostics;
using UnityEngine;

public class OriginalCode
{
    public string Test(int counter, string name)
    {
        // ...
    }
}

[HarmonyPatch(typeof(OriginalCode))]
[HarmonyPatch("Test")]
class Patch
{
    static void Prefix(out Stopwatch __state)
    {
        __state = new Stopwatch(); // 独自の値を設定
        __state.Start();
    }

    static void Postfix(Stopwatch __state)
    {
        __state.Stop();
        Debug.Log(__state.Elapsed.ToString()); // 実行時間をログに表示
    }
}