Introducing Custom Combat

The custom combat settings file (ccs/name.ccs) is arranged in such a way that a player can specify which commands to execute against which monsters. For ease of use, all matching is substring-based. First, an attempt is made to match against the monster name. That failing, an attempt is made to match against the location name - unless the monster is one currently unknown to KoLmafia (and therefore likely to be part of some special event, and not related to the known monsters in that location), in which case a section named "unrecognized" is looked for. In case of multiple matches, the longest match wins.

Customization is designed only to depend only on the monster you are currently fighting -- it is not meant to allow for strategies that a person changes based on remaining health or mana. Advanced customization on this level means that the resulting scripts are difficult to read, which defeats the point of this feature's introduction.

However, in the event that you wish to make use of such advanced customization, there is an undocumented "consult" command which can be used in these scripts -- for more information on how consult scripts work, you will need read through KoLmafia's source code. Do not request documentation of this feature or assistance with this feature; it will not be provided.

File Structure

[ default ]
what to do in round 1 (or all rounds if no more data is specified)
what to do in round 2 (or all rounds after round 1 if no more data is specified)

[ partial name of monster ]
what to do in round 1 (or all rounds if no more data is specified)
what to do in round 2 (or all rounds after round 1 if no more data is specified)

[ partial name of area ]
what to do in round 1 (or all rounds if no more data is specified)
what to do in round 2 (or all rounds after round 1 if no more data is specified)
 

Permitted Values

Any monster or area not flagged internally by KoLmafia as an ultra-rare encounter can be customized; no matter what is specified in the custom combats file, KoLmafia will always abort for ultra-rare monsters.

After setting up your custom combat settings, you might notice that KoLmafia changes it so that all the commands are prefixed with a round number. This is strictly for internal management purposes to make things more compact; you do not have to type things in this way.

Settings can be modified once the player is logged in by clicking the "edit" button in the "Custom Combat" tab of the Adventure window, or by manually modifying the *.ccs file mentioned previously. Note that if you choose to modify the file directly, you must do so before login; KoLmafia will not reload the settings every battle.

Here are the currently supported commands. In the event that KoLmafia fails to understand what you are trying to say, the command will usually be changed into an attack, so it's a good idea to look over the script after it has been saved to make sure everything was interpreted as you intended.

attack

Normal attack with your equipped weapon.

steal

Attempt to pick the monster's pocket, assuming that you're capable of doing so, and the monster has at least one known pickpocketable item drop (that isn't guaranteed to drop anyway, due to your item drop bonus). This action will be skipped if KoLmafia thinks the monster will seriously hurt you, unless it drops an item in your current goals.

jiggle

Jiggle your chefstaff, if you have one equipped.

summon ghost

For Pastamancers only.

delevel

Uses any delevelling skills you have in order to reduce the monster's level to a point where normal attacks will be effective.

run away

Tries to run away.

run away if number% chance of being free

Tries to run away, but only if you have at least the specified chance of this not taking a turn (due to equipment such as the navel ring, or a familiar such as the Bandersnatch).

item name

Uses the specified item. If you have Ambidextrous Funkslinging, another of the item will be used (if you have at least two of them, and it's not something that's only meaningful to use once), or a reusable combat item will be chosen for you. Combat is aborted if you don't have the item.

item name1, name2

Uses two items. If you don't have Ambidextrous Funkslinging, the second item will only be used if you have none of the first. If you do have the skill, it's OK to not have the first item, but you must have at least the second one.

skill name

Use a combat skill. The action taken if you have insufficient MP to use it (either skipping the command, or spending rounds using MP restorers) is specified in the "Special" popup in the Adventure window.

combo name

Use a Disco combo, for example "combo rave nirvana". Does nothing if you aren't a Disco Bandit, don't know all of the skills used in the combo, or don't know the combo itself (in the case of rave combos). If in-combat MP restoration is enabled, it is performed once (for the entire MP cost of the skills), to avoid breaking the combo.

special

This command indicates where certain actions specified by the "Special" popup in the Adventure window should be inserted, such as automatic Transcendent Olfaction use. If no such action is currently needed, the command will be skipped. This should generally go after any commands that stun the monster, but before any commands that might kill it.

default

Continue the script starting with the first line of the section named "default". This must be the final command in the current section.

section name

Continue the script starting with the first line of the indicated section. This must be the final command in the current section.

abort

Immediately aborts combat automation, allowing the user to finish the combat manually. If the CCS was invoked via the Script button in the relay browser, clicking it again will restart the CCS after the "abort" command.

abort after

Does nothing immediately, but automation will end after the current combat is finished.

skip

Continue with the next command in the script. This might be useful to temorarily replace a command, without having to renumber all the following lines.

note text

Does nothing, but allows arbitrary text to be added to the script. The text can be a comment, or a parameter that an ASH script can read via the get_ccs_action() function.

twiddle

Wastes a round doing nothing. It's hard to imagine any reason you'd want to do this, but it's here for completeness.

Custom Combat Settings File Example

As a demonstration of how to structure the file and how the commands should look, the following is what a disco bandit might use for their settings file, assuming they had already acquired the "disco face stab" skill and wanted to use it to weaken some of the game's stronger opponents before taking them down with either moxious maneuvers or standard attacks.

[ default ]
attack

[ mechamech ]
delevel

[ giant skeelton ]
skill moxious maneuver

[ huge ghuol ]
skill moxious maneuver

[ conjoined zmombie ]
skill moxious maneuver

[ giant skeelton ]
skill moxious maneuver

[ gargantulihc ]
skill moxious maneuver

[ orc chasm ]
item dictionary