Equinox's Debug Tools

Description

This library's primary purpose is to solve the issue of having debug logging in release versions of our mods. Doing this with simple Log.Debug() calls is impractical, as logs end up full of spam, so we delete all our debug logging before release, only to add it back in when someone has an issue that we can't replicate. We could have our logging controlled by bools in the source, but this is a lot of effort and it's easy to forget to set them to false, so this library automates that process.

By using this library, all your debug logging will automatically be disabled when a player installs your mod. Then when they run into issues, you can tell them which config option to enable in order to get the debug info you need.

This library also provides several other functions that are helpful for debugging.

Usage

Log()

public static void Log(
    string category,
    string message
)

This function logs the message given in the argument if the player has enabled debug messages for the given category. Using my MapHotkey mod as an example:

In my mod is the line, EDT.Log("Zoom Updates", "Set zoom level to 6400");. The first time that EDT see's a category ("Zoom Updates"), it creates a config entry like this:

[Mods.MapHotkey]

## Whether debug messages should be logged for MapHotkey - Zoom Updates
# Setting type: Boolean
# Default value: false
Debug Zoom Updates = false

Since this value defaults to false, calls to Log() that use the category 'Zoom Updates' will be ignored. If a player has an issue, I can tell them to enable this particular config entry to generate debug information without needing to send them a new version with new or enabled logging. Once the player has enabled this option, I will see this in their log:

[Debug  :EquinoxsDebugTools] [Zoom Updtes|MapHotkey.MapHotkeyPlugin.Update()]: Set zoom level to 6400

The message is given a prefix with the format:

[Category|Calling Function Path/Name]:

This is to help you see where the message came from in case you have similar debug statements in different funtions.

EDT has a config entry called 'Developer Mode'. When this is set to true, new config entries generated by EDT will default to true. Set this entry to true to avoid having to manually enable config entries while working on mods.

PacedLog()

public static void PacedLog(
    string category,
    string message,
    float delaySeconds = 0f
)

This function works in the same way as above, but it also prevents any other PacedLog() messages from the same function being logged until the delay has ended. This is useful to use in Update() functions as logging every frame can cause performance issues that make developement very difficult, as well as bury important messages in spam.

If you want to log multiple things in an Update() function, for all but the last write:

EDT.PacedLog("Category", "My Message");

Then for your last one in the function, specify the delay before the next group are sent:

EDT.PacedLog("Category", "Last Message In Function", 1f);

SetPacedLogDelay()

public static void SetPacedLogDelay(
    float delaySeconds
)

This function sets the delay that must occur before any more PacedLog() messages from the same function are logged. Use this at the end of your function if the last PacedLog() call is in a loop.

NullCheck()

public static bool NullCheck(
  object obj,
  string name,
  bool shouldLog = false
)

This function can be used to check if the provided object is null and log the result. It's a little cleaner to use this than multiple manual null checks if there's more than one to do in a function. Returns true if obj is not null. Think of this function as a test, see example use for a better explanation.

Note: If obj is null, a warning level messaeg will always be logged, regardless of shouldLog.

Note: Code examples from this point on are written for Techtonica's code, as I haven't found good exmaples of how to use them for Shapez 2 yet. The functions can still be used for Shapez 2.

Example use:

if(NullCheck(UIManager.instance, "UI Manager")){
  if(NullCheck(UIManager.instance.techTreeMenu, "Tech Tree Menu")){
    TechTreeNode node = UIManager.instance.techTreeMenu.GridUI.GetNodeByUnlock(...);
  }
}

This could also be written using guard clauses:

if(!NullCheck(UIManager.instance, "UI Manager")) return;
if(!NullCheck(UIManager.instance.techTreeMenu, "Tech Tree Menu")) return;
TechTreeNode node = UIManager.instance.techTreeMenu.GridUI.GetNodeByUnlock(...);

Read those first two lines as 'If the null check fails, return'

DebugObject()

public static void DebugObject(
    object obj,
    string name
)

This function loops through each member of the obj argument and logs its type, name and value.

Example use:

class Item{
    int id;
    string name;
    double secondsToCraft;
}

Item ironIngot = new Item(){ id = 0, name = "Iron Ingot", secondsToCraft = 0.5 };
EDT.DebugObject(item, "ironIngot");

Output:

[Info   :EquinoxsDebuggingTools] Debugging Item 'ironIngot':
[Info   :EquinoxsDebuggingTools] 	int id = 0
[Info   :EquinoxsDebuggingTools] 	string name = "Iron Ingot"
[Info   :EquinoxsDebuggingTools] 	double secondsToCraft = 0.5

Config Options

Installation

I recommend using a mod loader like ThunderstoreMM or R2ModMan to install this mod.

Manual Install Instructions

Your game folder is likely here:
C:/Program Files (x86)/Steam/steamapps/common/shapez 2 (Drive):/steam/steamapps/common/shapez 2 (Drive):/SteamLibrary/steamapps/common/shapez 2

1. Download BepInEx v5.4.21 from here
2. Follow the installation instructions here
3. Download and install any dependencies.
4. Extract the contents of the .zip file for this mod.
5. Drag the "BepInEx" folder into your game folder.
6. Change config options.

Disclaimer

Before using this mod, please back up your save files to prevent data loss. To do so, navigate to the following folder:

C:\Users\YourUsername\AppData\LocalLow\tobspr Games\shapez 2

Replace YourUsername with your actual Windows username. Copy this folder to a safe location before applying any modifications. This mod is an independent creation and is not affiliated with or endorsed by tobspr Games. All assets, trademarks, and copyrights associated with Shapez 2 remain the property of tobspr Games and its respective owners. This mod is provided as-is, and the author takes no responsibility for any issues that may arise from its use.