Some people seem to be confused about the nature of between battle scripts, so I figured I'd make an introductory post here explaining how they're supposed to work (they may not work like this from time to time due to changes I make to the codebase without thinking about them). Anyway, there are three classes of between battle scripts -- actual between battle scripts, unconditional trigger scripts, and KoLmafia's auto-recovery scripts.
betweenBattleScript: This is an undocumented KoLmafia property that you can set to tell KoLmafia that you want to do something between battles. This script starts up before any other between battle script, and thus, it can be used for mood specification (which is why it continues to exist). In essence, the idea is all general purpose scripts where you want full control of the end-result is meant to run between battles should run here. KoLmafia doesn't even swap back equipment when it does purchases.
unconditional trigger: These can be set in the mood interface and they involve anything that you want to run between battles where you don't mind if KoLmafia switches your equipment back if you're done. They run before KoLmafia's moods trigger, so you can use them to set up equipment that will get swapped back out when moods are done, but their main use is to let you specify use all of an item scripts (fantasy chests, toolboxes) without interfering with between battle scripts.
auto-recovery scripts: These are executed after all of the above have been executed, and they include conditional triggers (mood maintenance), MP burning, autorecovery of HP, and autorecovery of MP, in that order. You can customize them based on your settings, but since this is KoLmafia's internal routines running, they're kinda invincible to full-blown customization. A lot of people ask for the ability to specify whole integer values instead of vague percentages, but I disagree with that entirely.
So in review, this is the order of events, as they are intended for the unreleased v10.7 and all releases thereafter:
- KoLmafia runs the script specified by betweenBattleScript
- KoLmafia creates an implicit checkpoint to return to when it's done
- KoLmafia runs your unconditional trigger script
- KoLmafia runs its mood maintenance routine
- KoLmafia attempts to auto-restore your HP
- KoLmafia runs its excess mana burning routine
- KoLmafia attempts to auto-restore your MP
- KoLmafia reverts to the implicit checkpoint it created earlier
In KoLmafia v10.6, steps 1 and 2 are flipped, and you can imagine the problems that creates.
