EQ2Bot¶
Preface¶
This article is still in draft and much of it was written from recollection without access to screenshots or running scripts. Some terms, exact phrasing, etc may vary from the article and the actual UI.
Introduction¶
This page contains more detailed information regarding installing, using, and developing for EQ2Bot.
(Note: You will need a subscription to InnerSpace to use the download links on this page.)
Understanding EQ2Bot¶
EQ2Bot is in itself a bot scripting core. All basic shared functionality needed to manipulate an adventure bot in EQ2 exists within the core EQ2Bot script. The core script handles basic functionality such as positioning the toon for using spells, designating main tank, designating the parameters around which mobs to engage or ignore, etc.
The EQ2Bot core script when started will examine your characters class and load a designated Class File for that class. If no Class File exists in the EQ2Bot Class Files directory the script will fail to run. The Class File contains more specific functions defined for the exact class being botted. The Class File contains standard functions that EQ2Bot will call for defiend events as they occur. This allows one class file's combat function to behave very differently than anothers while all being controlled via one shared core driven by a simple UI. By example, EQ2Bot handles determining when your toon is in combat, and once identified contues to call the combat function in the Class File until such time as the incombat event is no longer true.
This script design allows for class file contributors to focus on what needs to be defined uniquely for thier class without having to duplicate common mundane tasks. In this way the contributor does not need to understand a high level of game interaction mechanics and can focus on the key events and reactions needed that are unique to the Class File being created.
Beyond the core script and Class Files, script contributors have also provided Function Libraries to support additional, optional features that would be common to all class files. Examples of such functionality would be Shard Requests and Usage, Heroic Opportunity functions to advance and complete Heroic Opportunities. These functions serve as additional tools for Class File contributors to easily include common functionality in a standardized manner accross different classes.
Installing EQ2Bot¶
All EQ2 scripts are now distributed via the ISXGAMES Script SVN repository. This is a script library that is regularly updated by contributors. The nice part about this repository is that it is a single location for users to go to get the latest and greatest release of every script available.
''Information about the Repository can be found at: {http://www.isxgames.com/forums/showthread.php?t=531]
''A good SVN client can be found at:1
Once you have checked out the SVN tree, you will need to make sure you place the /interface and /scripts folders in your InnerSpace folder. If you installed to default locations it will be something similar to C:\Program Files\Innerspace\
Note, all scripts and support files are now maintained in a script repository. For information on the repository see this thread: Script Repository
Running EQ2Bot¶
You begin the script as you do any other EQ2 Script file by opening your IS console window and executing: run eq2bot
First Time Setup¶
The first time EQ2Bot runs for each of your characters, it creates a Character Config file. These files are stored in the Character Config directory within the EQ2Bot directory and the file will be named the same as your toon's name.
It is recommended that you go thru each tab now before starting the bot and select the options that you feel apply to your toon. Depending on the class file executed, you will see different tabs in the EQ2Bot UI. Some examples are: Main, EQ2Bot Options, Class, HO, Misc
For the first time run, set your EQ2bot Options, any settings you feel appropriate in Class, and under Misc select the option to participate in HO's.
''Note: It is normal not to see the HO tab on the first run as it is an optional tab enabled by the 'Participate in HO' option.
Now end the script. The end script button on the Main tab does not work. Open your console and execute endscript eq2bot
Note: You can always end all scripts that are running using: endscript *
Re-Run EQ2Bot. You will now see all the options you previously set are still selected, and if your Class File has HO Object integration, you will now see the HO tab. Take your time going thru this tab and select the spell you wish for your toon to use in order to advance each of the Heroic Op icons.
You are now ready to run EQ2Bot.
Running EQ2Bot¶
There are many UI options that will impact how the bot behaves once you click the start button. Understanding these options and how they affect Bot behavior is important.
MISC Tab¶
Exact options, and even the existance of this tab varies between Class Files, however some common options are:
AutoFollow On:
This enables the in game autofollow functionality and will set the bot to use this after each fight so that the bot will always follow a specific group member when not in combat. The drop down for this option will contain group members that are in the current zone to save as your auto follow target.
Remember: If durring combat the autofollow target gets outside of max range to execute the autofollow command the bot will get left behind. Also if there is a constant stream of combat the autofollow command will not get executed as it is a part of the post combat instructions.
Warn Tank on Agro:
If your Class File supports it, the bot will send a tell message to the designated Main Assist when it determines the bot has agro. /tell MainASsist Help, I have agro!
Note: The exact message text is found in your class file and can be changed to your liking if you are so inclined
Request Shards From:
This drop down will contain a list of Necro or Conjurers in your Group or Raid. Selecting a name will designate who the bot will send tells to requesting shards. This functionality will only execute if your Class File supports it. When supported, anytime the bot does not have a mana shard, it will send a /tell Shard Please.
Participate in HOs:
This selection triggers the existance of the HO tab at EQ2Bot runtime. If your Class File has Heroic OP Object support, when the HO Wheel is present, the bot will cast the spells you've designated for each HO Wheel Icon. How prioritized these casts are, and if they are called at all is Class File dependent. There is no other options you need to set once clicking this box and setting the spells on the HO tab.
Pet Guard Self/Me:
Selecting this option will reset your pet to either protect you after each fight, or to not to protect you and self after each fight. It is generally recommended not to check this box unless you are soloing a pet class, or attempting to use a pet as a group tank.
HO Tab¶
This tab has 2 selections for each HO Wheel Icon. Select corresponding spells for each selection. If for example your class only has one spell on a 'star' icon, then only select a value in Star1, leave Star2 blank. As your bot levels up, you will need to periodicaly reset these values to the newer spells. Keeping the HO Object using your highest level spells will cut down on resists and keep the wheel moving.
Class Tab¶
The class tab usually has options about what profile to play the class with. For fighters it might have Offensive, Defensive, and Taunt options. For Pet classes it might have options about what pets to use. For others it might have options to use or not use AoE abilities. Generally selecting targets for single target buffs that your class can cast are located on this tab. These settings are exposed to you by the Class File Contributors. If you feel additional options need to exist for your class, contact the contributor and discuss the request.
EQ2Bot Options Tab¶
There are many options on this tab that affect what mobs are engaged, and what is done once combat begins. At the time of writing this article, I do not have the UI in front of me, so I will define the items to the best of my recollection.
Ignore MOB COLOR
There are several options about ignoreing mobs based upon con. The important thing to remember here is your bot will do NOTHING to these mobs. So, if for some reason a grey or red mob does agro you, if you have ignore grey or ignore red checked, your bot will stand there and not react.
When chosing a hunting location, proper consideration to these options is important. I recommend setting your Main Assist to ignore the encounter types you don't want to engage, but on all your other bots do not limit the encounters by type. In this way if your Main Assist gets grey agro from an AoE. While he will just stand there and get beat on, you other toons will react when dammage shield or auto ripostle gets the mob down to an assist percentage.
Looting
Several options around looting.
Accept, Decline, Idle - These are the general looting operating methods. The bot will handle FFA, NBG, and Lotto looting using the assigned method. There are additional toggles for Lore or No Trade items. These toggles will override the looting method. So if you have accept but no-trade is not checked, the bot will accept all loot unless it see's a no-trade item, in which case it will decline.
To actually loot corpses and chests is a seperate option. The above methods apply to what the bot does when it sees a loot window. To actually loot corpses and chests, you need to check the box for looting. The bot will wait for 80% health before looting to prevent trap death. Scout classes will auto-disarm chests before looting.
Pulling
Pull non agro mobs. Straight forward, ignore the non-agro stuff or pull it.
Automatically Pull. Do you want this bot to pull mobs. Setting this option without defining a Pull spell or type, and setitng a distance does nothing
Wait for priest Power. Generally should always be checked, however if there is no priest in the group or for solo play, go ahead and uncheck this option.
Pull Spell. While the bot supports using range attack for pulling, I do not recommend it as you will at some time run out of ammo and run arround to mobs and fail to pull them, then move to the next mob and fail to pull them. There is no endscript when out of ammo. Spells do not run out of ammo. Choose a fairly long range spell or ability that is not on a long timer. Type the Spell name into the box using the exact cast in the spell (ex: 'Solar Burn') then select the range value. EQ2Bot range values are close to those in the game, but not exact. If the spell range is 35, I recommend a value of 30, always chose a slightly lower range than listed on the spell examine.
IMPORTANT: Remember to click the set button anytime you change the pull spell, or the ranges associated with it
Engage in AutoAttack
Self explanitory, but understand if you are not the Main Tank, EQ2Bot will position you behind the mob on autoattack by default. This has some consideration when fighting in tight places, and in general it isn't wise to auto attack on non melee classes like priests and mages for this reason.
Assist and Switch Targets at 30%
This is a powerful option. Bots will assist you and change targets. However if this is checked and the MT changes targets once the current kill target is under 30%, the bots will stay on the nearly dead target and switch after it is dead. This is the best method in fighting multi-mob encounters as the tank moves on to establish agro lock prior to dps switching to new target. It also optimizes aoe dps output.
Main Tab¶
There are three very important options on this tab
Main Assist
This drop down contains a list of all players, and pets in your group or raid. If you are not the tank and not solo you do not check the checkbox and must select a person from the drop down. Who you select is important, as if the selected toon is not targeting a mob who's health drops below the value set for the assist percentage, your toon will not engage the mob. As a priest you will react to changes in group health, but your combat routine will never run. Selecting the actual tank or designated group or raid main assist is important. In a group of bots, always chose the tank.
Follow on:
This is a built in EQ2Bot follow function that actually traces the movement of the designated person with a standard deviance and range that you set. This can sometimes be much more useful than ingame autofollow, but also has its own limitations and in certain zones and areas some known bugs and follow loops. You will only get a feel for this by using it and observing it. There are 2 camps on the subject. Most players chose either this option or the Misc Tab's Autofollow that uses the built in functions. Some use both, however I believe that to be problematic.
Behavior Options
The last set of check boxes set the bots behavior. If you plan to use the in game autofollow, chose manual movement. There are many implied behaviors from this list of boxes and you need to consider it carefully. Depending on how you are botting, how many in group, where you are working, etc; You will likely want to have some group members on one setting and others on another.
Autohunting
Set the range to search for mobs and the bot will do just that, search the area around it, select a target, kill, search again, select, kill, repeat. The bot can roam great distances with this option so be wary.
Limited Movement
This option basically sets the current location as its homepoint and if set to pull will grab mobs within the distance defined on the pull spell. The bot will only react to mobs within that limited range. This is useful for setting up camps at specific locations.
Dungeon Crawl
An entire page could be devoted to dungeon crawl. I don't recommend attempting this setting until you've worked with the bots in other modes first. However you can use the navigation tab in eq2bot to set an actual path to move the bots along and kill what they come accross. Generally you set only one bot to use the crawl, and the others set to follow that one. You want to define a start and finish point, and if you want anything other than a linear path you want to add points of interest while creating your path, and select in the multi-select the order to navigate those POI's.
Class Files¶
Class files are individual definitions of functions with logic specific to the class being botted. They are in themselves a .ISS file in the Class Routines subfolder of EQ2Bot and are a collection of functions that are called by EQ2Bot when specific events are recognized and triggered.
Class files may also contain additional functions not called directly from EQ2Bot, but serve as extended functionality called from one of the functions that EQ2Bot does call.
Future section defining class files, required functions and link to blank sample class file.
Spell List Files¶
Spell List files are XML files for each class located in the Spell List subdirectory of EQ2Bot. The EQ2Bot core will parse this spell list on runtime and match known spells to the spell book that your toon has. The format of this XML document is very specific and the conventions must be followed. Also Spell names in this file have to match the game spells with EXACT syntax.
For each spell type, EQ2Bot will only use the highest available spell of that type. It is a known bug that if the spell type exists in the XML file, but your character has not scribed that spell, that EQ2Bot will NOT use the lower level version that is scribed. Also, EQ2Bot will use the highest level of whichever spell regardless if the lower level master 2 choice might be more effective. Editing of the XML file to change any of this behavior is done so at your own risk, and don't expect much help with problems you create for yourself doing so. However it _is_ possible to override some of this behavior by creative editing.
Class UI Files¶
For class Files that use a custom UI tab, there must also be a UI file to define that tab. These are XML files that define the UI elements, give them names, handle reading and writing those values to your character routine, as well as making your selections available to the Class File.
Developing Class Files¶
Every class file has some default functions that must be defined, even if they are blank. The class file author can of course define additional functions in the class file for class specific behavior (mezing, charming, etc), but they will need to be called and managed from the default functions that are called from EQ2Bot. Adding a MezMobs() function to a class file without calling it from a default function will provide no functionality as EQ2Bot core will never call MezMobs().
Here is a sample class file with all required functions, and one local function implemented to show an example:
Always Include some basic documentation and revision history as a best practice:
;*************************************************************
;MyClass.iss
;version 20070404a
;by Pygar
;
;20070404a
; Initial Build
;
;This script doesn't do anything, but is just an example of
;both required functions, and how to create custom functions.
;This also demonstrates common BotLib calls.
;*************************************************************
Before defining any functions make optional includes:
;Optional Includes for Function Libraries
# ifndef _Eq2Botlib_
#include "${LavishScript.HomeDirectory}/Scripts/EQ2Bot/Class Routines/EQ2BotLib.iss"
# endif
Required Function Class_Declaration - This function is called once when the bot is started to set up values and UI settings.
function Class_Declaration()
{
;Declare Script Variables here
declare AoEMode bool script FALSE
;Initialize any function Libraries here
call EQ2BotLib_Init
;Load Values from Class UI Tab HEre
AoEMode:Set[${SettingXML[${charfile}].Set[${Me.SubClass}].GetString[Cast AoE Spells,FALSE]}]
}
Required Function Buff_Init() - This function populates a data set (array) of buff spells to be used when calling the buffing function later. These abilities are keyed numerically. You may have up to 40 actions in your data set, and each action can have as many individual spells as you like.
function Buff_Init()
{
PreAction[1]:Set[MySelfBuff]
PreSpellRange[1,1]:Set[30]
PreAction[2]:Set[MyGroupBuffs]
PreSpellRange[2,1]:Set[25]
PreSpellRange[2,2]:Set[26]
}
Required Function Combat_Init() - This works just like Buff_Init(), however it sets the specific combat actions that will be taken. Again there is a 40 action limit.
function Combat_Init()
{
Action[1]:Set[Nukes]
SpellRange[1,1]:Set[170]
SpellRange[1,2]:Set[171]
Action[2]:Set[Taunt]
SpellRange[2,1]:Set[160]
Action[3]:Set[AOE]
SpellRange[3,1]:Set[161]
Action[4]:Set[ThermalShocker]
}
Required Function PostCombat Init() - Works like Buff_Init() but has a limit of 20 actions.
function PostCombat_Init()
{
PostAction[1]:Set[AA_BindWound]
PostSpellRange[1,1]:Set[172]
}
Required Function Buff_Routine() - This function will be called by EQ2Bot when the buffing event is triggered. By default, it will be called 40 times, however setting a default case to reset the Action pointer to 40 will prevent it from being called more times than needed.
function Buff_Routine(int xAction)
{
;declare any local variables here (Incremental Vars, Loop Couts, targets, etc)
declare tempvar int local
declare Counter int local
declare BuffMember string local
declare BuffTarget string local
;Function Library Calls
;This is an eq2botlib function to reset your equiped gear to the default config from when you started the bot
call WeaponChange
;this is an eq2botlib function that will consume a shard if needed, and if none exist request from the designated providor
if ${ShardMode}
{
call Shard
}
;This is an eq2botlib atomic function that will resume following your designated target if you are not currently in follow mode
if ${AutoFollowMode}
{
ExecuteAtom AutoFollowTank
}
;Preform Buff Actions
switch ${PreAction[${xAction}]}
{
case MySelfBuff
call CastSpellRange ${PreSpellRange[${xAction},1]} 0 0 0 0
break
case MyGroupBuffs
call CastSpellRange ${PreSpellRange[${xAction},1]} ${PreSpellRange[${xAction},2]}
break
Default
Action:Set[40]
break
}
}
Required Function Combat_Routine() - Like Buff_Routine, it will be called repeatedly by EQ2Bot core for the durration of combat. Each time it is called it will step the Action pointer from 1 to 40. If you have less than 40 actions, you will want to advance the pointer to 40 after the last valid action.
function Combat_Routine(int xAction)
{
;Stops auto follow for combat routine, this is optional, but if you stay on follow you look like a crappy bot
AutoFollowingMA:Set[FALSE]
if ${Me.ToActor.WhoFollowing(exists)}
{
EQ2Execute /stopfollow
}
;Function Library Calls
;This one will advance an HO if you have selected to participate in them
if ${DoHOs}
{
objHeroicOp:DoHO
}
;Sampe code to start an HO if one isn't currently going
if !${EQ2.HOWindowActive} && ${Me.InCombat}
{
call CastSpellRange 303
}
;Call local functions to the script file
call CheckHeals
;Add persistant checks you want the bot to do every round of combat, these are optional
if ${Me.ToActor.Health}<60
{
call CastSpellRange 156
}
if ${Me.ToActor.Health}<40
{
call CastSpellRange 155
}
;Local function call
call Checkheals
;Preform Combat Actions
switch ${Action[${xAction}]}
{
case Nukes
call CastSpellRange ${SpellRange[${xAction},1]} ${SpellRange[${xAction},2]} 0 0 ${KillTarget}
break
case Taunt
call CastSpellRange ${SpellRange[${xAction},1]} 0 1 0 ${KillTarget} 0 0 1
break
case AOE
if ${AoEMode} && ${Mob.Count}>1
{
call CastSpellRange ${SpellRange[${xAction},1]} 0 1 0 ${KillTarget} 0 0 1
}
break
case ThermalShocker
if ${Me.Inventory[ExactName,"Brock's Thermal Shocker"](exists)} && ${Me.Inventory[ExactName,"Brock's Thermal Shocker"].IsReady}
{
Me.Inventory[ExactName,"Brock's Thermal Shocker"]:Use
}
break
case default
Action:Set[40]
break
}
}
}
Require Function Post_Combat_Routine() - This works just like Buff_Routine() and is called at the end of combat before any other action is taken. Checking and canceling FD, or maintaining some situational buffs is typically handled here.
function Post_Combat_Routine(int xAction)
{
switch ${PostAction[${xAction}]}
{
case AA_BindWound
if ${Me.Ability[${SpellType[${PostSpellRange[${xAction},1]}]}].IsReady}
{
call CastSpellRange ${PostSpellRange[${xAction},1]}
}
break
case Default
Action:Set[20]
break
}
}
<pre>
Required Function Have_Aggro() - This function is only called if EQ2Bot finds you have agro from a hostile NPC and you are NOT the maintank. This is a good place to call FD, Aggro Dump, etc
<pre>
function Have_Aggro()
{
}
Required Function Lost_Aggro() - This function is only called if you are the MainTank, and EQ2bot has found that you lost Aggro on an engaged target. This is a good place to but things like calls to Rescue, Intercepts, or other situational abilities.
function Lost_Aggro(int mobid)
{
}
Required Funtion Lost_Aggro() - This function is called when EQ2Bot determines the MainTank lost aggro. I realized it is mis-named, but that is the condition for calling. As a dps class, you might want to place a wait loop in here to stop combat action till aggro is established. Other classes might use situational targetable hate reducers like FD on whoever stole aggro.
function MA_Lost_Aggro()
{
}
Required Function MA_Dead() - This function is called with the MainTank dies. In this example this script sets itself as the MainTank when this happens. Other scripts might want to evac, or cast a rez to the MainTank, or maybe FD...
function MA_Dead()
{
MainTank:Set[TRUE]
MainTankPC:Set[${Me.Name}]
KillTarget:Set[]
}
Required Function Cancel_Root() - Rarely used, but if you have any abilities that root you in place, add methods to cancel them here. EQ2Bot calls this when in combat movement is needed.
function Cancel_Root()
{
}
Optional Function CheckHeals() - Strange as it may seem, EQ2Bot does not handle healing in the core. Each healer class has very specific heal strategy, logic, and abilities. Many classes don't have traditional heals, but have abilities that should be used when health changes. This is a sample CheckHeals() function that is called from Combat_Routine. Some classes might want to call CheckHeals from the Buff_Routine as well, others only have combat related health checks.
;Sample Class File Local funciton
function CheckHeals()
{
;Declare Local Variables
declare temphl int local
declare grpheal int local 0
declare lowest int local 0
declare MTinMyGroup bool local FALSE
grpcnt:Set[${Me.GroupCount}]
hurt:Set[FALSE]
temphl:Set[1]
grpcure:Set[0]
lowest:Set[1]
;Function Library Calls
;This one will check group health and use a defiler summoned spirit shard that heals group.
call UseCrystallizedSpirit
;Sample script to determin if a group heal is needed
do
{
if ${Me.Group[${temphl}].ZoneName.Equal["${Zone.Name}"]}
{
if ${Me.Group[${temphl}].ToActor.Health} < 100 && ${Me.Group[${temphl}].ToActor.Health}>-99 && ${Me.Group[${temphl}].ToActor(exists)}
{
if ${Me.Group[${temphl}].ToActor.Health} < ${Me.Group[${lowest}].ToActor.Health}
{
lowest:Set[${temphl}]
}
}
if ${Me.Group[${temphl}].ToActor.Health}>-99 && ${Me.Group[${temphl}].ToActor.Health}<60
{
grpheal:Inc
}
if ${Me.Group[${temphl}].Name.Equal[${MainTankPC}]}
{
MTinMyGroup:Set[TRUE]
}
}
}
while ${temphl:Inc}<${grpcnt}
;If a group heal was determined, cast some spells
if ${grpheal}>1
{
if ${Me.Ability[${SpellType[316]}].IsReady}
{
call CastSpellRange 316
}
if ${Me.Ability[${SpellType[271]}].IsReady}
{
call CastSpellRange 271
}
}
}
Developing Function Libraries¶
Future Section
Contributors¶
Exact information here is a bit fuzy.
EQ2Bot is currently maintained and modified by
<!--
h='happyhacker.com';a='@';n='pygar';e=n+a+h;
document.write('<a h'+'ref'+'="ma'+'ilto'+':'+e+'" clas'+'s="em' + 'ail">'+'mailto:pygar@happyhacker.com'+'<\/'+'a'+'>');
// -->
mailto:pygar@happyhacker.com (pygar at happyhacker dot com) Pygar.
I believe the first incarnation was released by Blazer who merged several existing bot structures together to get the functionality. Significant amount of the initial code may have come from EQ1 bots.
The project was later taken over by Kayre who cleaned up and extended the bot significantly.
Current Class Files have been contributed by: Pygar, Kayre, Ownagejoo, Mandrake, and others. If you need to contact these authors for questions or support try posting to ISXGAMES forums or visit the #isxeq2 channel on IRC.
Getting Help¶
IRC is a great place to ask questions you may have about EQ2Bot that are not addressed in this wiki or in the isxgames forums. The contributors on IRC are generally amiable to assiting with understanding how to opprate the bot as well as providing help and tips for creating your own script files.
We are on #isxeq2 on the LavishSoft irc server: irc.lavishsoft.com that responds on the default IRC port 6667