Patch - solaris0115/RimWorldModGuide GitHub Wiki

패치 함수

기존의 함수에 접근, 제어하는 하모니 함수들을 패치 함수라고 합니다.
패치 함수들은 다음과 같은 속성이나 함수를 이용해 만들 수 있습니다.
[HarmonyTargetMethod], [HarmonyPrepare], [HarmonyPrefix], [HarmonyPostfix], [HarmonyTranspiler]

TargetMethod(), Prepare(), Prefix(), Postfix(), Transpiler()

TargetMethod

미확인

Prepare

미확인

Prefix

Prefix는 기존의 함수 이전에 먼저 실행됩니다.
Prefix는 두가지 형태로 반환이 가능합니다. void와 bool
bool로 반환할 경우 반환값에 따라 기존의 함수가 실행될지 여부를 결정하게 됩니다.
true 일경우 기존의 함수를 실행하고 false일 경우 기존의 함수를 실행하지 않습니다.

Postfix

Postfix는 기존의 함수 이후에 실행 됩니다.
Postfix는 void 형태만 반환이 가능합니다.

Transpiler

Transpiler는 C# 어셈블리어인 IL을 통해 기존의 코드를 교체하는 속성입니다.
이것을 사용하면 기존 함수에서의 명령어 세트를 부분적 수정,교체,삭제가 가능합니다.

Patch 지침

Prefix와 Postfix 모두 원본함수에서 사용될 파라메터와 해당 클래스의 변수들에 접근할 수 있습니다.
해당 파라메터와 패치할 클래스에 접근을 하기위해서는 아래와 같은 규칙들을 따라야 합니다.

• 패치함수는 static형태의 함수여야 합니다.
• Prefix의 반환형은 void 또는 bool 만 가능합니다.
• Postfix는 void형태의 반환만 가능합니다.
• 패치할 클래스가 static형태가 아니라면 파라메터로 __instance라는 변수명을 사용하셔야 해당 인스턴스값에 액세스 할 수 있습니다. 구조체의 경우 값전달에서의 오버헤드를 피하기 위해 ref키워드를 통해 전달됩니다.
• 기존 함수의 반환값에 접근하기 위해서는 ref 키워드와 __result를 사용 하셔야 합니다.(클래스 타입이던, 구조체던)
• 패치 함수의 파라메터는 기존 함수의 파라메터들을 모두 선언할 필요 없습니다. (안해도 괜찮습니다.)
• 만약 기존 함수의 파라메터에 접근하기 위해서는 패치 함수에 파라메터명과 타입을 반드시 동일하게 해주셔야 합니다.
• 패치 함수는 파라메터를 가져올때 일반 혹은 ref형식을 이용할 수 있습니다. Transpilers에는 2가지 선택적 매개 변수가 있습니다.
• MethodBase는 패치된 기존의 함수 그 자체입니다.
• IEnumerable<CodeInstruction>는 기존 함수에서 실행되는 내부 어셈블리 명령어 집합입니다.

사용 예

다음 예제들을 통해 각각 패치 함수들이 어떤 방식으로 쓰이는지 알아볼 것 입니다.

예제에서 사용될 클래스는 BiomeWorker_Desert로 세계지도에서 사막 식생에 대한 정보를 결정합니다.
여기서 BiomeWorker에서 상속받은 GetScore함수를 통해 각각의 바이옴들은 각 타일로부터 식생을 결정하게 됩니다.

이것을 기존 함수 미실행, 해발고도 600이하 0이상, 강수량 300이하일 온도는 35도 이상일때만 생성되도록 변경하고자 합니다. 각각의 패치 형태별로 예제를 보여드릴것 입니다.

기존 함수

• BiomeWorker_Desert클래스는 Static 클래스가 아닙니다. 즉 각각의 인스턴스가 존재합니다. 만약 BiomeWorker_Desert의 멤버변수를 사용할 일이 있다면 BiomeWorker __instance혹은 BiomeWorker_Desert __instance라는 매개 변수가 필요합니다.[여기선 아닙니다.]
• GetScore함수는 Tile타입의 파라메터를 가지고있고 그 이름은 tile입니다. 동일하게 작성해주어야 합니다.
• GetScore함수의 반환형은 float타입 입니다. 반환값을 임의 지정하고자 한다면 float __result를 포함하셔야 합니다.

//RimWorld.BiomeWorker_Desert 
public class BiomeWorker_Desert : BiomeWorker
{
    public override float GetScore(Tile tile)
    {
        if (tile.WaterCovered)//해발 고도 0이하면 -100점
        {
            return -100f;
        }
        if (tile.rainfall >= 600f)//강수량이 600이상이면 0점
        {
            return 0f;
        }
        return tile.temperature + 0.0001f; //온도+0.0001점을 반환
    }
}

Prefix

• 기존 클래스에서의 멤버변수를 사용할 필요가 없음으로 __instance파라메터는 제거
• GetScore의 반환되는 float타입의 점수로 바이옴이 책정됨으로 __result을 포함
• Tile tile의 멤버를 접근하여 조건검사를 해야함으로 포함
• 기존 함수가 미실행 되기 원함으로 bool타입의 함수로 작성후 return 값은 false

[HarmonyPatch(typeof(BiomeWorker_Desert))]
[HarmonyPatch("GetScore")]
[HarmonyPatch(new Type[] { typeof(Tile) })]
internal class DesertBiome_Patch
{
    static bool Prefix(ref float __result,Tile tile)
    {
        if ((tile.elevation>600)||(tile.elevation < 0))//해발고도 600초과 0미만
        {
            __result= - 100f;
            return false;
        }
        if (tile.temperature <35 )//강수량이 600이상이면 0점
        {
            __result= 0f;
            return false;
        }
        __result= tile.temperature + 0.0001f; //온도+0.0001점을 반환
        return false;//false임으로 기본 함수는 미실행됨.
    }
}

Postfix

• 기존 클래스에서의 멤버변수를 사용할 필요가 없음으로 __instance파라메터는 제거
• GetScore의 반환되는 float타입의 점수로 바이옴이 책정됨으로 __result을 포함
• Tile tile의 멤버를 접근하여 조건검사를 해야함으로 포함
• 기존 함수의 반환값을 무시하고 새값을 설정해야함

[HarmonyPatch(typeof(BiomeWorker_Desert))]
[HarmonyPatch("GetScore")]
[HarmonyPatch(new Type[] { typeof(Tile) })]
internal class DesertBiome_Patch
{
    static void Postfix(ref float __result,Tile tile)
    {
        __result= 0;
        if ((tile.elevation>600)||(tile.elevation < 0))//해발고도 600초과 0미만
        {
            __result= - 100f;
        }
        if (tile.temperature <35 )//강수량이 600이상이면 0점
        {
            __result= 0f;
        }
        __result= tile.temperature + 0.0001f; //온도+0.0001점을 반환
    }
}

TransPiler

TransPiler를 통해 C#를 빌드하면 만들어지는 중간코드를 수정할 수 있습니다. prefix를 통해 통째로 코드를 가로채거나 또는 후위에 붙여서 수정할 수 없다면 TransPiler를 통해 기존의 코드를 수정할 수 있습니다.
OpCodes

기존 BiomeWorker_Desert의 IL코드

.class public auto ansi beforefieldinit RimWorld.BiomeWorker_Desert
	extends RimWorld.BiomeWorker
{
	// Methods
	.method public hidebysig specialname rtspecialname 
		instance void .ctor () cil managed 
	{
		// Method begins at RVA 0xb3744
		// Code size 7 (0x7)
		.maxstack 8

		IL_0000: ldarg.0
		IL_0001: call instance void RimWorld.BiomeWorker::.ctor()
		IL_0006: ret
	} // end of method BiomeWorker_Desert::.ctor

        //여기서부터 GetScore 어셈블리 명령어입니다.
	.method public hidebysig virtual 
		instance float32 GetScore (
			class RimWorld.Planet.Tile tile
		) cil managed 
	{
		// Method begins at RVA 0xb374c
		// Code size 52 (0x34)
		.maxstack 8

		IL_0000: ldarg.1  //첫번째 인수를 계산 스택에 적재
		IL_0001: callvirt instance bool RimWorld.Planet.Tile::get_WaterCovered()//waterCovered값을 계산스택으로 푸쉬
		IL_0006: brfalse IL_0011//결과값이 flase면 IL_0011로 이동

		IL_000b: ldc.r4 -100 //계산스택에 -100을 float형태로 푸쉬
		IL_0010: ret//현 매서드 제어를 반환하고 해당 메서드를 호출한 메서드의 계산스택으로 결과값 푸쉬

		IL_0011: ldarg.1//첫번째 인수를 계산 스택에 적재
		IL_0012: ldfld float32 RimWorld.Planet.Tile::rainfall //계산 스택에 tile.rainfall 값을 가져옴
		IL_0017: ldc.r4 600 //다음 계산 스택에 600f푸쉬
		IL_001c: blt.un IL_0027 //계산스택의 첫번째값과 두번째값을 비교후 false일경우 IL_0027로 이동

		IL_0021: ldc.r4 0.0 // 계산 스택에 0.0f값을 푸쉬
		IL_0026: ret//현 매서드 제어를 반환하고 해당 메서드를 호출한 메서드의 계산스택으로 결과값 푸쉬

		IL_0027: ldarg.1//첫번째 인수를 계산 스택에 적재
		IL_0028: ldfld float32 RimWorld.Planet.Tile::temperature//tile.temperature값을 가져옴
		IL_002d: ldc.r4 0.0001//계산 스택에 0.0001f푸쉬
		IL_0032: add//계산 스택 상위 두값을 합산 후 계산스택에 푸쉬
		IL_0033: ret//현 매서드 제어를 반환하고 해당 메서드를 호출한 메서드의 계산스택으로 결과값 푸쉬
	} // end of method BiomeWorker_Desert::GetScore

} // end of class RimWorld.BiomeWorker_Desert

장황하게 어셈블리어로 작성되었지만 단순하게 요약하면 다음과 같습니다.

• 매 If문 분기마다 스택메모리에 비교검사할 값들을 적재하고 비교검사후 건너뜀
• ret 명령어를 통해 현재함수를 종료하고 최상위에 적재된 결과값을 해당 GetScore함수를 불러온 다른함수 스택최상위에 적재.

따라서 TransPiler는 IL_0000부터 IL_0033의 16개의 명령어 집합으로 이루어져 있습니다.
이것을 전부 지우고 새로운 명령어 집합을 넣으셔도 되고 부분적으로 명령어 분기를 새로 만들어 주셔도 됩니다.

이제 아래의 기존 함수를 IL을 이용해 모든 지형이 사막이 되도록 바꿔보겠습니다.

[HarmonyPatch(typeof(BiomeWorker_Desert))]
[HarmonyPatch("GetScore")]
public static class DesertBiome_Patch
{
    static IEnumerable<CodeInstruction> Transpiler(MethodBase original, IEnumerable<CodeInstruction> instructions)
    {
        yield return new CodeInstruction(OpCodes.Ldc_R4, 10000f);//스택 최상단에 10000f 푸쉬
        yield return new CodeInstruction(OpCodes.Ret);//제어반환후 10000f를 호출함수 스택최상단에 푸쉬
    }
   
}

위와 같이 하면 다음과 같은 결과가 나옵니다.

다음 : 대상함수 지정