Logging

Introduction

Logging is saving arbitrary text or values that you want to inspect, into a text file. This allows you to confirm that the sequence of code execution is as you expect & allows you to inspect the values of variables at the given state. Modding Api has logging support built into it, so you can create and view existing logs easily.

Simplest way to write something out to the log is having the following line in your code :

	Modding.Logger.Log("Hello World");

This will write the text Hello World to your modlog.txt in your saves folder.

Note : There are some recommended best practices to follow when creating logs in your mods, see Creating a log for more details on how to create a log that will be most helpful during development and after releasing your mod.

Logging during development

• Isolate issues by logging around suspect code, and seeing which logs show up
• Check values that are passed to or generated by your code
• Inspect in-game data structures

Logging For troubleshooting

• Request the modlog from the players of your mods to debug issues as they come up.
• For this reason if you expect some information to be valuable to resolve issues, you should log it even when you know the expected values.

Viewing logs

• The logs of the last game session can be found in the modlog.txt, this will be the current session if the game is still open.
• You can also enable the in-game console so that the logs can be viewed in-game in real time.

To Enable the In-game console :

• Make sure the game is closed
• Navigate to the saves folder
• open ModdingApi.GlobalSettings.json
• set the value of ShowDebugLogInGame to true.

"ShowDebugLogInGame": true

• you can show and hide the log in-game now by hitting F10

Hint: Older sessions' modlogs, are preserved in the Old ModLogs folder inside the saves folder.

Creating a Log:

To write to the log in your mod's main class, the one that inherits from the Mod baseclass, you can simply call the log functions, for example :

public class MyFirstMod : Mod
{
	public override void Initialize()
	{
		Log("Initialize!.");
	}
}

This will create the following line in the log:

[MyFirstMod] - Initialize!.

To write to the log from any of the other classes you create, you should use the Log function by accessing the instance of your mod class, this is to ensure that the name of your Mod prefixes your log, to allow you to search for it easier and to distinguish it from logs made by other mods.

Example:

public class MyFirstMod : Mod
{
	//Create a static variable that holds the instance of your main mod class
	public static MyFirstMod Instance;
	
	public override void Initialize()
	{
		//Assign the current instance of your mod using the keyword 'this`
		Instance = this;
		//Now the variable 'Instance' can be used in other classes to get hold of the current Mod instance.
	}
}

//In a different class you can access it like so
public class OtherClass
{
	public void Start()
	{
		MyFirstMod.Instance.Log("Start called from OtherClass.");
	}
}

Output:

[MyFirstMod] - Start called from OtherClass.

Note: You can use the Modding.Logger class from the Modding API directly but it is not recommended to do in release builds because it doesn't display the name of your mod in the log, making it difficult for anyone looking at the log to identify and resolve issues.

Player.log:

Some unity errors & crashes are not logged to modlog.txt but rather to player.log. This can be found in the same folder as modlog.txt. It can be very useful especially because it provides the stack traces of the errors, and some errors that do not show up in the modlog can show up here.

you can log to this file by using standard unity logging, for example UnityEngine.Debug.Log();

Log Levels:

There are 5 different levels of logs:

Level	Function	Description
Error	LogError();	Should be used to log errors that occurred.
Warn	LogWarn();	Should be used to log warning to users.
Info	Log();	Should be used for normal logs.
Debug	LogDebug();	Should be used for log to debug code. Using default settings, it won't be seen on regular user's modlog
Fine	LogFine();	Use when you are going to spam a log of content into the modlog.

By default, LogDebug and LogFine will not be seen in the modlog and/or ingame console, To change the level of logs you can see, locate the ModdingApi.GlobalSettings.json in the saves folder. There you will be able to see a setting called LoggingLevel. The default is 2 but it is recommended to set it to 1, so that you can LogDebug while you develop, and share the same dll file as release ( where it won't spam the player's modlog due to settings ) :

"LoggingLevel": 1

The acceptable values for this range from 0-5 where 5 is the least amount of logging and 0 is the most:

Level	Amount of Logging
5	None
4	Error.
3	Error, Warn.
2	Error, Warn, Info. (This is the default setting)
1	Error, Warn, Info, Debug.
0	Error, Warn, Info, Debug, Fine.

Finding your modlog:

ModLog.txt can be found in the same folder as your save files:

• Windows: %APPDATA%\..\LocalLow\Team Cherry\Hollow Knight\
• MacOS : ~/Library/Application Support/unity.Team Cherry.Hollow Knight/
• Linux : ~/.config/unity3d/Team Cherry/Hollow Knight/

To easily get ModLog on Windows:

• Press Windows logo key + R
• Copy and paste this into it %appdata%\..\LocalLow\Team Cherry\Hollow Knight and hit "OK"
• ModLog.txt is in this folder.

Additionally you can make a shortcut to the folder to find it easier the next time around.