Difficulty: The current difficulty is calculated based on how many zones you have completed so far in this run and the number of "base difficulty" challenges you have activated (one or two). The formula is "number of zones" + "number of difficulty challenges" + a bonus difficulty after you've completed at least one zone.

If you have no difficulty challenges on, the difficulty goes 0, 2, 3, 4 If you have one challenge on, the difficulty goes 1, 3, 4, 5 If you have two challenges on, the difficulty goes 2, 4, 5, 6

The formula is defined in patchers/EventManagement.cs

Encounters: Each encounter has a base design and then has the option to get harder at different difficulty levels. There are two ways to make an encounter harder. You can either replace/add an enemy card, or you can "overclock" a turn. Overclocking a turn gives all of the cards deployed in that turn +1.

Encounters are defined using a custom .dat file that I designed. For example: https://github.com/divisionbyz0rro/P03KayceeMod/blob/main/data/neutral_bridgebattle.dat

You can pretty much ignore (i.e., don't touch) anything in these files before you get to "randomReplacementCards". If you want the encounter to have some randomness to it, you need to put the pool of random cards here. You can then add a random card to the encounter using the phrase "RANDOM 100%" (or any percent 100 or above).

The next line is the overclock blueprint. It looks something like this: [D:1/T:0,D:3/T:1,D:5/T:3]. Each command is separated by a comma. D:1/T:0 means "at difficulty level 1, overclock turn 0". D:5/T:3 means "at difficulty level 5, overclock turn 3." You can have an empty overclock blueprint like this: []

Next, each line defines a turn. The first line is turn 0, then turn 1, etc. Commas separate the cards for each turn. If you just put a card name, it appears regardless of difficulty. If you want a card to be replaced by another card at a specific difficulty level (or higher), use the arrow syntax. So: "AlarmBot -> Shieldbot 4" means "play an AlarmBot, but at difficulty level 4 or higher, play a Shieldbot instead." If you want there to be no card unless you're at a specific difficulty level, use "NONE"; i.e., "NONE -> SentryBot 3" which means "play nothing, but at difficulty level 3 or higher play a SentryBot."

Adding new Encounters: If you want to add a new encounter to the mod:

1. Create a new .dat file for the encounter and put it in the data folder.
2. Modify the list of all known encounters near the top of patchers/EncounterBlueprintHelper.cs (this is what loads all of the known blueprints into memory at the start of the game).
3. Modify the list of encounters in the region definition for the region you want to add the encounter to (otherwise it will never get selected by the random map generator!). Region definition happens in patchers/RegionGeneratorData.cs

My thoughts on what it would take to make this work with the API: Based entirely on just reading the new API wiki, I think it would be almost completely straightforward to replace all of my custom .dat files with either with calls to the API or even with JLDR files using the encounter management part of the JSON loader. The only issue I think you'll have is with the overclock blueprint stuff - none of the examples I've seen allow you to set those properties because overclocking a turn is purely an Act 3 thing. You need to be able to do this in order to get the difficulty balance right.

That was the easy part.

I'm completely unclear how you'll add the encounter in such a way that it only appears in Act 3 and only in the correct region. The idea is that neutral encounters can happen in each region, but the rest of the encounters can only happen in their specific region (the map generator will generate three region-specific encounters and one neutral encounter each time it makes a new map). It is not clear to me how you would make sure that this mod doesn't accidentally create encounters in such a way that they would appear in a Leshy run.

You also need to make sure that RegionGeneratorData gets the correct list of encounters. Right now it's hardcoded, but if there's a way to tag encounters as being Part 3 specific, you could pretty easily come up with a way to pull the names of the encounters from the API's list of encounters rather than hardcoding it.

And while I think there is value in supporting custom encounters via the API, I would absolutely not reccomend trying to play nice with the API's definition of regions. Mostly because the map generator is a horrible pile of spaghetti code. If you want to change how the individual regions get generated, I would only look at modifying the way regions are defined in the RegionGeneratorData file - nowhere else. Trying to rewrite the map generator will only lead to sadness.