Modding:Adding Code at Startup

Overview
There are a variety of ways to run code before a new game starts or an existing save is loaded.

Mod-Sensitive Cache
Tag any C# class with the  attribute to indicate that the class includes mod-sensitive code that the game should run at initial game startup, as well as any time that the list of active mods changes.

Timing
Mod-sensitive cache code is invoked by the  method, which is called at the following times:
 * When the player's active scripting mods are compiled on startup.
 * During a hotload, which occurs any time the active mod configuration changes.
 * When the "reload" wish is used.

Implementation
The mod-sensitive cache is implemented in a similar fashion to the game-sensitive cache (see section below), but there is no special handling for a  method and there are a few other subtle differences.

Classes with  attribute are treated as follows (in this order):
 * If the class has any static fields with the  attribute, those fields are (re)initialized to their default value (for value types) or set to null (for object types). Note that the null object type default behavior is opposite from the default behavior of GameBasedStaticCache. To force an object field to be populated with a newly created instance via , specify.
 * If the class has any static methods with the  attribute, the game invokes those methods.

Blueprint Preload
Tag any class that inherits  with the   attribute to indicate that the game should pre-load all ObjectBlueprints that include this part.

Blueprint preload is a process completed during game startup (and when mod configuration changes). During this process, the game creates an instance of all ObjectBlueprints that include an IPart which has requested preload. This can serve a number of purposes. For example, the base game's TinkerItem part requests blueprint preload in order to create a tinker recipe for each item with a TinkerItem part. In older versions of Caves of Qud, all ObjectBlueprints were preloaded at game startup. Now, this framework has been adjusted to only preload blueprints that include a part which specifically requests the preload behavior.

Timing
Blueprint preload is invoked by the  method and occurs immediately after mod-sensitive cache code is processed. Refer to the Mod-Sensitive Cache > Timing section above for more detail.

Implementation
During the blueprint preload, the game goes through all objects defined in. If it finds an object that includes a part whose class has the  attribute, the game creates a temporary GameObject based on that blueprint, and then calls   on the object. This results in the following behavior:
 * The GameObject calls  on each of its parts. A custom part may override this function to perform custom behavior during blueprint preload. This function is not called during normal gameplay, so it's a good place to put one-time initialization code for the part (However, keep in mind that this function might still be called multiple times during the blueprint preload process, if the part is present on more than one object).
 * The class constructor is called for each IPart on the object. This will also be true whenever an object is created during normal gameplay, so it's generally not recommended to put blueprint preload logic into the class constructor.

Example
Here's an example straight from the game code

Game-Based Cache
Tag any C# class with the  attribute to indicate that the class includes game-sensitive code that the game should run each time a new game starts or a save game is loaded.

Timing
Game-based cache code is invoked by the  method, which is called at the following times:
 * Immediately after selecting "New Game" option from main menu (before the player object exists or world generation occurs)
 * Immediately after loading a saved game (including scenarios such as a reload due to Precognition)

Implementation
Classes with  attribute are treated as follows (in this order):
 * If the class has any static fields with the  attribute, those fields are (re)initialized to their default value (for value types) or set to a new instance via   (for object types). Object types can specify   to force the field to be set to null instead of creating a new instance.
 * If the class has a static  method, the game invokes that method.
 * If the class has any other static methods with the  attribute, the game invokes those methods.

Pre-Game Cache
The pre-game cache is an additional load point that is similar to the game-based cache. The overall order in which cache code runs is as follows:
 * 1) Mod-sensitive cache code
 * 2) Pre-game cache code (including Blueprint preload)
 * 3) Game-based cache code

To use the pre-game cache, add either the  attribute or the   attribute to your class (it works with both). Then, add the  attribute to one or more methods in your class. The pre-game cache method is invoked after mod-sensitive cache code runs, and before game-sensitive cache code runs.

Note that pre-game cache methods are run before every new game or loaded game, even if they are inside a class with only the  attribute. So be particularly careful if you're implementing a pre-game cache method that you only want to run after the mod loadout changes.