adventure()

From KoLMafia
Jump to: navigation, search

Function Syntax

boolean adventure(int adventures ,location place )

boolean adventure(int adventures ,location place ,string filter )

  • int is the number of adventures to spend.
  • place is the adventuring location.
  • filter is a combat action filter. If filter contains a semicolon it is interpreted as a macro, otherwise this is the name of a top-level function which modifies the current CCS. A combat filter function takes the parameters of a consult script, but returns lines like a CCS, not like a consult script. Essentially, this allows the scripter to put a CCS or macro into a script.

This function runs the specified number of adventures at the given place, keeping up your current mood & obeying restore settings.

If filter contains a semicolon it will use filter as a macro.

If filter is omitted or assigned an empty string, this function will use your current CCS / battle action.

This function returns true if the specified number of adventures were used, and false if not. Possible reasons for returning false include being out of adventures, a location being unavailable, conditions being statisfied before adventures were used up and all auto-stops, including encountering a demon name or hobo glyph.

Note that adventures is the number of adventures to spend in the specified location place. Any "free" turns (choiceadventures that don't consume an adventure, usually) or adventures spend in other locations (by a counterScript or a betweenBattleScript for example) will not count towards this total.

As with auto-adventuring from the Adventure tab, adventure() checks against goals set via add_item_condition() or via other methods of specifying goals in KoLmafia, and will auto-stop if all goals were satisfied.

Code Sample

Adventure 5 times at the Giant's Castle:

adventure(5 , $location[giant's castle]);

Example of a Combat Filter

This uses the combat filter to automatically olfact Goth Giants while adventuring.

string olfact_goth(int round, monster opp, string text) {
   if(opp != $monster[Goth Giant])
      return get_ccs_action(round);
   if(round == 1 && have_effect($effect[On the Trail]) < 1)
      return "skill transcendent olfaction";
   return get_ccs_action(round - 1);
}

adventure(5 , $location[giant castle], "olfact_goth");

Uses a combat filter to ensure that all sewer monsters are being cleeshed while you try to make your way to Hobopolis.

string combat_cleesh(int round, monster opp, string text) {
   if (opp == $monster[frog] || opp == $monster[newt] 
    || opp == $monster[salamander]) {
      return "attack";
   }
   return "skill CLEESH";
}

adventure(1, $location[a maze of sewer tunnels], "combat_cleesh");

This makes use of the combat filter to ensure that salve is being used.

// Adds salve to beginning of combat if it doesn't already exist in the CCS. 
// Otherwise it simply returns the current CCS.
string insert_salve(int round, monster opp, string text) {
   boolean salve = false;
   for i from 1 to 30
      if(get_ccs_action(round) == "skill saucy salve")
         salve = true;
   if(salve)
      return get_ccs_action(round);
   else {
      if(round == 1)
         return "skill saucy salve";
      if(round > 1)
         round = round - 1;              // compensate for insertion
      return get_ccs_action(round);      // for the rest of the combat, executes your existing ccs
   }
}

adventure(5 , $location[giant castle], "insert_salve");

CLI Equivalent

The CLI command "adv" works similarly.

See Also

Special

This function will return false if KoLmafia conditions are met before completing the specified number of turns.

Also, if the filter function is not top-level code, it will not be found, since it's being called outside of ASH. As a result, it will return "void", which may result in the use of $item[ovoid leather thing].