Difference between revisions of "Custom Combat Script"

From Kolmafia
Jump to navigation Jump to search
imported>Bale
(Improve example again)
 
(11 intermediate revisions by 5 users not shown)
Line 29: Line 29:
 
Note that when you use a CCS, your CLI will report "character executes a macro!" because the CCS is converted into a macro to save on page loads
 
Note that when you use a CCS, your CLI will report "character executes a macro!" because the CCS is converted into a macro to save on page loads
  
=== Legal commands are ===
+
=== Available Commands ===
 
* attack
 
* attack
 
* skill
 
* skill
Line 39: Line 39:
 
** Disco Concentration, Disco Nirvana, Disco Inferno, Disco Bleeding, Disco Blindness
 
** Disco Concentration, Disco Nirvana, Disco Inferno, Disco Bleeding, Disco Blindness
 
** Rave Knockout, Rave Bleeding, Rave Concentration, Rave Steal, Rave Nirvana, Rave Stats
 
** Rave Knockout, Rave Bleeding, Rave Concentration, Rave Steal, Rave Nirvana, Rave Stats
 +
** [http://kolmafia.us/showthread.php?5709-Add-rave-combo-learning-to-quot-special-action-quot&p=42107&viewfull=1#post42107 random rave]
 
* abort
 
* abort
 +
* abort after
 +
* section [section name]
 +
* special
 +
* delevel
 +
* skip
 +
* note
 +
* twiddle
 +
 +
=== Using ASH Constants in CCS ===
 +
Certain ASH constants can be used in CCS as section headers.
 +
* '''$phylum[ ]''' refers to the 22 {{kolwiki|Monster Types|Monster Phylumn}}.
 +
* '''$element[ ]''' refers to either the attack or the defense element. As long as one matches, this check will be satisfied.
 +
* '''$item[ ]''' refers to an item that the monster drops. If there are multiple monsters that drop the item (such as SGEEA) it will match any of those monsters.
 +
 +
You may specify more than one of these, but unless everything matches, it won't match. So if you specify an impossible combination, that CCS section will not run.
 +
 +
 +
<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
 +
[ $element[ spooky ] $item[ hobo nickel ] ]<br />
 +
skill entangling noodles<br />
 +
skill weapon of the pastalord<br />
 +
 +
[ bathroom $element[ spooky ] ]<br />
 +
attack<br />
 +
 +
[ $phylum[ beast ] ]<br />
 +
skill stomp<br />
 +
attack<br />
 +
</div>
  
 
== Macros in CCS ==
 
== Macros in CCS ==
Line 45: Line 75:
  
 
Also there is a section in the CCS called "global prefix" which will be part of every combat macro KoLmafia generates, regardless of the monster encountered.  
 
Also there is a section in the CCS called "global prefix" which will be part of every combat macro KoLmafia generates, regardless of the monster encountered.  
 
  
 
=== Example of CCS Macro ===
 
=== Example of CCS Macro ===
Line 83: Line 112:
 
:if hascombatitem dictionary
 
:if hascombatitem dictionary
 
::item dictionary
 
::item dictionary
::goto _endstasisitem
 
:endif
 
:if hascombatitem fat stacks of cash
 
::item fat stacks of cash
 
 
::goto _endstasisitem
 
::goto _endstasisitem
 
:endif
 
:endif
Line 100: Line 125:
  
 
=== Concerns for macros in CCS ===
 
=== Concerns for macros in CCS ===
*A macro's abort command needs to be encased in quotes because abort is also a legal CCS command. that's why all aborts in the previous example were quoted.  
+
*A macro's abort command needs to be encased in quotes because abort is also a legal CCS command. That's why all aborts in the previous example were quoted.  
  
 
*If a comment is the last line in a CCS, that will be used as your finishing attack even though it does nothing. Never conclude a CCS with a macro comment or it will abort to the mini-browser with a warning from KoL that you executed 37 commands in a row without taking an action.
 
*If a comment is the last line in a CCS, that will be used as your finishing attack even though it does nothing. Never conclude a CCS with a macro comment or it will abort to the mini-browser with a warning from KoL that you executed 37 commands in a row without taking an action.
  
 
== Consult Scripts ==
 
== 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 take different actions based on your characters current stats or current monster level, a consult script can automatically figure it out. There are few limits to what a consult script can enable. The downside to using a consult script is that KoLmafia will not be able to generate a combat macro to pass to KoL. As a result multi-round combat will take somewhat longer.
+
While a CCS may seem reasonably flexible, sometimes you will want to do something too complicated to express in that format. For instance if you want your character to take different actions based on your characters current stats or current monster level, a consult script can automatically figure it out. There are few limits to what a consult script can enable. The downside to using a consult script is that KoLmafia will not be able to generate a combat macro to pass to KoL. As a result multi-round combat will take somewhat longer.
  
 
A consult script is called by using the "consult" command in your CCS, as follows:
 
A consult script is called by using the "consult" command in your CCS, as follows:
Line 114: Line 139:
 
attack<br />
 
attack<br />
 
</div>
 
</div>
 +
  
 
The main() function in the ASH script being consulted must accept three parameters:
 
The main() function in the ASH script being consulted must accept three parameters:
  
  void main(int round, monster mob, string page)
+
  void main(int round, monster mob, string page_text)
  
 
These values will be supplied by mafia when the consult script is called.
 
These values will be supplied by mafia when the consult script is called.
Line 126: Line 152:
 
// Save this as SauceSplash.ash
 
// Save this as SauceSplash.ash
 
boolean sauceSplash() {
 
boolean sauceSplash() {
   if(!(have_effect($effect[Jabañero Saucesphere]) >0
+
   if(!my_class() == $class[Sauceror])
      || have_effect($effect[Jalapeño Saucesphere]) >0))
 
 
         return false;
 
         return false;
 
   int normal = numeric_modifier("spell damage");
 
   int normal = numeric_modifier("spell damage");
Line 134: Line 159:
 
   int cold = numeric_modifier("cold spell damage");
 
   int cold = numeric_modifier("cold spell damage");
 
   int hot = numeric_modifier("hot spell damage");
 
   int hot = numeric_modifier("hot spell damage");
   if(have_skill($skill[Immaculate Seasoning])
+
 
 +
   #deal with monsters weak to cold
 +
  if(((((monster_element() == $element[stench]) || (monster_element() == $element[sleaze]))
 +
    && have_skill($skill[Immaculate Seasoning]))
 +
    || have_equipped($item[Gazpacho's Glacial Grimoire]))
 +
    && cold + normal >= 25)
 +
        return true;
 +
  #deal with monsters weak to hot
 +
  else if((((((monster_element() == $element[cold]) || (monster_element() == $element[spooky]))
 +
    && have_skill($skill[Immaculate Seasoning]))
 +
    || have_equipped($item[Codex of Capsaicin Conjuration])
 +
    || have_equipped($item[Ol' Scratch's manacles])
 +
    || have_equipped($item[Ol' Scratch's ash can]))
 +
    && hot + normal >= 25)
 +
  #deal with monsters weak to neither (hot/non-aligned)
 +
  else if(have_skill($skill[Immaculate Seasoning])
 
       && cold != hot && max(cold, hot) + normal >= 25)
 
       && cold != hot && max(cold, hot) + normal >= 25)
 
         return true;
 
         return true;
   if(monster_element() == $element[cold] && cold + normal >= 25
+
   else return false;
    && (have_skill($skill[Immaculate Seasoning])
 
    || have_equipped($item[Gazpacho's Glacial Grimoire])))
 
        return true;
 
  if(monster_element() == $element[hot] && hot + normal >= 25
 
    && (have_skill($skill[Immaculate Seasoning])
 
    || have_equipped($item[Codex of Capsaicin Conjuration])
 
    || have_equipped($item[Ol' Scratch's manacles])
 
    || (have_equipped($item[Ol' Scratch's ash can]) && my_class() == $class[Sauceror])))
 
        return true;
 
  return false;
 
 
}
 
}
  
void main(int initround, monster foe, string url) {
+
void main(int initround, monster foe, string page) {
 
   if(have_effect($effect[Burning Soul]) || have_effect($effect[Soul Freeze]) || !sauceSplash())
 
   if(have_effect($effect[Burning Soul]) || have_effect($effect[Soul Freeze]) || !sauceSplash())
 
       use_skill($skill[Saucegeyser]);
 
       use_skill($skill[Saucegeyser]);
Line 177: Line 207:
 
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.
 
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.
  
 +
Note: unlike CCS themselves or macros, consult scripts will NOT automatically stop if the monster dies. The entire consult script is seen as a single "action" by the CCS, which will go through its entirety before deciding whether to keep fighting or to give the control back to whatever script/player action/automation was going on prior to the fight.<br>
 +
This means that a consult script such as...
 +
<syntaxhighlight>
 +
void main(int initround, monster foe, string page){
 +
  use_skill($skill[Saucegeyser]);
 +
  use_skill($skill[Saucegeyser]);
 +
}
 +
</syntaxhighlight>
 +
...will GENERATE AN ERROR if the first saucegeyser defeats the monster, as mafia will try to look for a skill called "saucegeyser" to cast once out of combat.<br>
 +
However, this also means that if you are sure the combat will be over at a certain point, you could include actions like changing your equipment, eating, or straight up adventuring at another location!
  
== Employ Scripts ==
+
=== Macros in Consult Scripts ===
<div style="padding: 1em; border: solid 1px red; color: red; font-weight: bold;">Please note! This section is speculative; Employ Scripts have not yet been implemented.</div>
+
It is possible for a consult script to submit a macro. As a simple example, if your consult script wants to submit a macro that simply attacks the monster until the combat ends...
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 [http://kolmafia.us/showthread.php?4098-Dynamic-Combat-in-the-Age-of-Macros describes on the mafia forum].
+
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
 
+
string macro = "attack; repeat"
 
+
visit_url("fight.php?action=macro&macrotext=" + url_encode(macro) ,true,true);
It is currently proposed that they will have the following format:
+
</syntaxhighlight></div>
 
 
'''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.
+
Between macro commands you need to insert either <code>\n</code> or a semi-colon as in the above example. Your submitted macro can be as complicated as you wish.
* 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.
 
  
 
[[Category:Scripting]]
 
[[Category:Scripting]]

Latest revision as of 08:04, 15 March 2021

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 ]
try to steal an item
skill entangling noodles
skill shieldbutt


If you wanted to treat different monsters differently, that can be accommodated 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.


[ Black Knight ]
try to steal an item
skill transcendent olfaction
skill entangling noodles
skill shieldbutt

[ default ]
try to steal an item
skill entangling noodles
skill shieldbutt

Note that when you use a CCS, your CLI will report "character executes a macro!" because the CCS is converted into a macro to save on page loads

Available Commands

  • attack
  • skill
  • item, use
  • try to steal an item, pickpocket
  • summon pastamancer ghost
  • jiggle chefstaff
  • combo {followed by one of the following}
    • Disco Concentration, Disco Nirvana, Disco Inferno, Disco Bleeding, Disco Blindness
    • Rave Knockout, Rave Bleeding, Rave Concentration, Rave Steal, Rave Nirvana, Rave Stats
    • random rave
  • abort
  • abort after
  • section [section name]
  • special
  • delevel
  • skip
  • note
  • twiddle

Using ASH Constants in CCS

Certain ASH constants can be used in CCS as section headers.

  • $phylum[ ] refers to the 22 Monster Phylumn.
  • $element[ ] refers to either the attack or the defense element. As long as one matches, this check will be satisfied.
  • $item[ ] refers to an item that the monster drops. If there are multiple monsters that drop the item (such as SGEEA) it will match any of those monsters.

You may specify more than one of these, but unless everything matches, it won't match. So if you specify an impossible combination, that CCS section will not run.


[ $element[ spooky ] $item[ hobo nickel ] ]
skill entangling noodles
skill weapon of the pastalord

[ bathroom $element[ spooky ] ]
attack

[ $phylum[ beast ] ]
skill stomp
attack

Macros in CCS

Macros may be used in a Custom Combat Script in addition to the basic commands. Any line in quotes and any macro command used in a CCS will be made into part of the macro which KoLmafia is passing to KoL. You can find an primer on all KoL's macros at Combat Macros.

Also there is a section in the CCS called "global prefix" which will be part of every combat macro KoLmafia generates, regardless of the monster encountered.

Example of CCS Macro

Here's an example of a CCS that generates a macro which will cause KoL to wait for a hobo monkey to steal meat from your enemy before launching attacks.

[ default ]
sub monkey_stasis

while !match "climbs up and sits on your shoulder" && !pastround 20 && !hppercentbelow 20
call stasis_item
endwhile

endsub
call monkey_stasis
attack


[ global prefix ]
scrollwhendone
"abort missed 5"
"abort pastround 27"
sub stasis_item

if hascombatitem facsimile dictionary
item facsimile dictionary
goto _endstasisitem
endif
if hascombatitem seal tooth
item seal tooth
goto _endstasisitem
endif
if hascombatitem spices
item spices
goto _endstasisitem
endif
if hascombatitem spectre scepter
item spectre scepter
goto _endstasisitem
endif
if hascombatitem dictionary
item dictionary
goto _endstasisitem
endif
"abort "No infinite use items detected!" "
mark _endstasisitem

endsub
sub stasis

while !pastround 20 && !hppercentbelow 20 && mppercentbelow 99
call stasis_item
endwhile

endsub

Concerns for macros in CCS

  • A macro's abort command needs to be encased in quotes because abort is also a legal CCS command. That's why all aborts in the previous example were quoted.
  • If a comment is the last line in a CCS, that will be used as your finishing attack even though it does nothing. Never conclude a CCS with a macro comment or it will abort to the mini-browser with a warning from KoL that you executed 37 commands in a row without taking an action.

Consult Scripts

While a CCS may seem reasonably flexible, sometimes you will want to do something too complicated to express in that format. For instance if you want your character to take different actions based on your characters current stats or current monster level, a consult script can automatically figure it out. There are few limits to what a consult script can enable. The downside to using a consult script is that KoLmafia will not be able to generate a combat macro to pass to KoL. As a result multi-round combat will take somewhat longer.

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

[ default ]
consult myscript.ash
attack


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

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

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

Example of a Consult Script

This example will attempt to maximize use of a Sauceror's spells as a Sauceror by making use of sauce splash effects when they can be used.

// Save this as SauceSplash.ash
boolean sauceSplash() {
   if(!my_class() == $class[Sauceror])
         return false;
   int normal = numeric_modifier("spell damage");
   if(normal >= 25)
      return true;
   int cold = numeric_modifier("cold spell damage");
   int hot = numeric_modifier("hot spell damage");

   #deal with monsters weak to cold
   if(((((monster_element() == $element[stench]) || (monster_element() == $element[sleaze]))
     && have_skill($skill[Immaculate Seasoning]))
     || have_equipped($item[Gazpacho's Glacial Grimoire]))
     && cold + normal >= 25)
        return true;
   #deal with monsters weak to hot
   else if((((((monster_element() == $element[cold]) || (monster_element() == $element[spooky]))
     && have_skill($skill[Immaculate Seasoning]))
     || have_equipped($item[Codex of Capsaicin Conjuration])
     || have_equipped($item[Ol' Scratch's manacles])
     || have_equipped($item[Ol' Scratch's ash can]))
     && hot + normal >= 25)
   #deal with monsters weak to neither (hot/non-aligned)
   else if(have_skill($skill[Immaculate Seasoning])
      && cold != hot && max(cold, hot) + normal >= 25)
         return true;
   else return false;
}

void main(int initround, monster foe, string page) {
   if(have_effect($effect[Burning Soul]) || have_effect($effect[Soul Freeze]) || !sauceSplash())
      use_skill($skill[Saucegeyser]);
   else
      use_skill($skill[Wave of Sauce]);
}


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

[ default ]
consult SauceSplash.ash
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.

Note: unlike CCS themselves or macros, consult scripts will NOT automatically stop if the monster dies. The entire consult script is seen as a single "action" by the CCS, which will go through its entirety before deciding whether to keep fighting or to give the control back to whatever script/player action/automation was going on prior to the fight.
This means that a consult script such as...

void main(int initround, monster foe, string page){
  use_skill($skill[Saucegeyser]);
  use_skill($skill[Saucegeyser]);
}

...will GENERATE AN ERROR if the first saucegeyser defeats the monster, as mafia will try to look for a skill called "saucegeyser" to cast once out of combat.
However, this also means that if you are sure the combat will be over at a certain point, you could include actions like changing your equipment, eating, or straight up adventuring at another location!

Macros in Consult Scripts

It is possible for a consult script to submit a macro. As a simple example, if your consult script wants to submit a macro that simply attacks the monster until the combat ends...

string macro = "attack; repeat"
visit_url("fight.php?action=macro&macrotext=" + url_encode(macro) ,true,true);

Between macro commands you need to insert either \n or a semi-colon as in the above example. Your submitted macro can be as complicated as you wish.