Custom Combat Script

Basic CCS

A Custom Combat Script (CCS) is a way of instructing mafia how to handle combat, round by round. For example, a simple CCS would be to tell mafia to pickpocket on round 1, then cast entangling noodles on round 2 and finally on rounds 3+ to use shieldbutt. If it is unable to carry out one of those steps, then that step will be skipped. For instance, if the character failed to get initiative, then pickpocket will be skipped and the character will go straight to entangling noodles. That CCS would look like this:

[ default ]
1: try to steal an item
2: skill entangling noodles
3: skill shieldbutt

If you wanted to treat different monsters differently, that can be accomodated also. For instance, the following CCS will attempt to cast Transcendent Olfaction upon Black Knights while treating all other monsters differently. If the character currently has "On the Trail" then that line will be skipped.

[ default ]
1: try to steal an item
2: skill entangling noodles
3: skill shieldbutt

[ Black Knight ]
1: try to steal an item
2: skill transcendent olfaction
3: skill entangling noodles
4: skill shieldbutt

Legal commands are

• attack
• skill
• item, use
• try to steal an item, pickpocket
• summon pastamancer ghost
• jiggle chefstaff

Consult Scripts

While this may seem reasonably flexible, sometimes you will want to do something too complicated to express in this format. For instance if you want your character to cast a Rave Combo if the character is a Disco Bandit, you'd have to change your CCS every ascension, but a consult script can automatically figure it out.

A consult script is called by using the "consult" command in your CCS, as follows:

[ default ]
1: consult myscript.ash
2: attack

The main() function in the ASH script being consulted must accept three parameters:

void main(int round, monster mob, string page)

These values will be supplied by mafia when the consult script is called.

Example of a Consult Script

This example will attempt to pickpocket if possible. If not successful, then if the character is a Disco Bandit and he has learned the relevant Rave Combo, he will attempt to steal an item with the correct Rave combo.

// Save this as RaveSteal.ash
void main(int initround, monster foe, string url) {
   boolean stolen = false;
   // First check the pages text to see if it is possible to pickpocket
   while(contains_text(url, "form name=steal")) {
      url = steal();
      // Next check to see if pick pocketing was successful.
      if((contains_text(url, "grab something") || contains_text(url, "You manage to wrest")))
         return;   // Something has been stolen. Job done!
   }
   if(my_class() != $class[Disco Bandit]) return;
   // Time to try a rave combo. First check the order of the three skills using a matcher.
   matcher combo = create_matcher("(.+),(.+),(.+)", get_property("raveCombo5"));
   if(combo.find())  // If find() fails, that means the combo is unknown
      for i from 1 to 3 {
         // Check to see if the fight is over and return if true
         if(contains_text(url, "You win the fight")) return;
         // Now use each of the three skills in order.
         url = use_skill(combo.group(i).to_skill());
      }
}

This consult script can then be integrated into a CCS like this:

[ default ]
1: consult RaveSteal.ash
2: attack

Parts of a Combat Consultation Script

As you can see in the above example, a consultation script is called with three parameters.

• The first parameter is the round of combat that the script is called. Sometimes it is important to keep track of the round. This is particularly important to keep from losing the fight by going over 30 rounds.
• The second parameter is the monster that you are fighting. This is important because it enables you to take different actions for different monsters.
• The third parameter is the text of the page. This is important because it enables you to examine every detail of the fight as it is taking place. It can be analyzed for potential actions, damage that you deal to a monster and all other events.

All possible actions you can take in a round of combat are listed under In-combat Consulting.

Resolution of a Combat Consultation Script

The consult script can automate as many, or as few rounds of combat as desired to achieve its goal. When it finishes executing, if the monster is not yet dead, then the CCS will continue combat from the current round. Note that the current round is not always the next line in a script. For instance, if the consult script is called at round 1 and executes three actions, then it will return to the CCS at round 4. This is why most CCSs containing consult script prefer to have only a line after the consult script, usually a simple method of killing a monster.

Employ Scripts

An employ script is a like a consultation script, with benefits. While a consultation script operates turn-by-turn, an employ script operates only at the beginning of the combat and generates a combat macro.

Employ scripts do not yet exist in KolMafia at this time, but they are a goal that jasonharper is working towards as he describes on the mafia forum.

It is currently proposed that they will have the following format:

string main( string opponent, string pageText, string macroSoFar, string parameter )

• opponent is the name of the monster being fought, just as in a consult script or combat filter function.
• pageText is the raw HTML of the initial combat page. This isn't necessarily going to be useful (since it's a one-time snapshot), however you may want to examine the Skills popup to see what conditionally-available skills are actually available.
• macroSoFar is the current text of the macro being built - a mafia-generated header with some useful subroutines defined, followed by macro translations of all the prior lines in the CCS.
• parameter contains any extra text from the CCS line; it could be used to customize the behavior of the script, more conveniently than using a "note" line with a consult script. It also serves the less obvious purpose of making the parameter count something other than 3, so that mistakenly attempting to employ a consult script, or consult an employ script, will fail before any code runs.
• The return value entirely replaces the macro being built. It would probably be an error for this to be any shorter than the original value of macroSoFar.

The simplest thing an employ script could do is to append some commands to macroSoFar, and return that. Other possibilities include:

• It could look back through the previously-generated macro commands to decide what to do. For example, it could refrain from adding a "pickpocket" action if that has already been done
• If it wanted to set up a global abort condition, active throughout the combat, it could insert the command at the beginning of the macro.
• There will be a subroutine called "mafiaround" defined in the header, and called before every combat action to handle things like automatic antidote use. The script could insert commands into that subroutine, for example to implement an eye color check for using He-Boulder major rays.
• There will likely be other defined subroutines for the script to call or modify.