 |
 |
 [UNKNOWN] |
| Welcome to Insanity, Inc. All hail Duchess Allegro! |
|
|
[UNKNOWN] |
| Welcome to Insanity, Inc. All hail Duchess Allegro! |
How do I configure Insane-Bot? |
The bulk of the configuration for Insane-Bot is done in the configuration XML file. By default the file used is the botconfig.xml files in the same directory as insanebot.exe. As you edit your configuration file use the examples below, as well as the simple and complex sample files included with the Insane-Bot installation.
Formatting and content of this XML is strictly enforced when Insane-Bot loads the configuration file. If you see any errors is your AC chat window while Insane-Bot is starting the most likely reason is that your configuration file is incorrect. The botconfig.xsd schema file and validate.js script installed in the Samples directory can be used to validate your configuration file prior to starting Insane-Bot. Both files are located in the Samples directory, along with the sample configuration files.
Over the next several weeks our crack documentation team will be working on a complete update to the online documentation for Insane-Bot. Please visit our forums if you need assistance with configuration while we're updating our documentation here.
A preview of the "in-progress" documentation rewrite is available here. The updated documentation is incomplete at this point, and contains many broken links.
This section contains information on the character(s) that will be running the bot. You must edit this section when installing Insane-Bot to at least set the Name field correctly for your Asheron's Call character. The complex sample gives an example of configuring several characters in the same file. In most case you will not need to have more than one character in your file.
Name must match exactly the spelling and case of the character name in Asheron's Call. If you type this incorrectly Insane-Bot will not recognize your character.
ID is used to identify which bot uses specific command, spells, etc. It may contain any alphabetic characters, and may not contain any spaces. IDs must be unique for each Character defined, but does not need to match any portion of the bot's AC character name.
BuffList defines which SpellArray the bot will use for it's normal buffing. Insane-Bot will ensure that these buffs are always maintained on the bot while running.
Advertise specifies the speech block that will be used for the advertising/stay alive speech and actions. (This attribute was named "Emotes" prior to Alpha release 4.)
Markup is the multiplier applied to component burn costs when reporting command costs. Setting this to 1.3 would add 30% to the actual cost of components burned during the command.
These strings are used by the bot to describe the portal locations which it can summon.
These options set which spells will be used for mana recovery. Insane-Bot will always attempt to use Stamina to Mana first if there is sufficient stamina available. If there is not enough Stamina the bot will attempt to use the Health 2 Mana spells defined.
You can opt to disable portions of the mana recovery options by not including some Options. E.g. If only HighCostStam2Mana, LowCostStam2Mana, and Revitalize are defined the bot will never attempt to use it's health to recover mana. Including the Health2Mana spells and HealSelf but not the stamina Options woudl cause the bot to always use health to recover and ignore Stamina.
When defining Health2Mana or Stam2Mana options both the HighCost and LowCost spells must be included. Failure to include both can result in odd behavior. To ensure proper mana recovery the Low option should use a spell at least one level below the High option.
The Revitalize and HealSelf Options are not required -- the bot will lie down to recover health and stamina. E.g. If you include the HighCostStam2Mana and LowCostStam2Mana Options, but do not include Revitalize the bot will lie down when it is low on Stamina until it is ready to cast again. The bot will also lie down if for any reason its stamina or health drop too low.
Note: You must have at least one form of mana recovery enabled for you bot (either the Stam2Mana or Health2Mana options), or it will fail to operate correctly.
This option sent the default maximum number of pending commands any user can have in the command queue. To prevent the bot from becoming backlogged enough that your users leave before their commands are processed we recommend setting this to a maximum of 5, with 2 or 3 being the preferred setting. You can ovveride this for specific users -- see Users and Rules below.
This option grants any user in a fellowship with the bot a minimum of the specified access level. If a user is granted higher access through a User or Rule option their higher level access overrides this setting. Users granted elevated access through this option will revert to their previous access level when they leave the fellowship. This option defaults to "None".
This option sets the access level that will be granted to any user that is not covered by a User or Rule option. The default access level is "Public". This option can only be set to "None", "Public", "Guest" or "Normal" access.
This option sets whether the Hints option on security rules defaults to on (1) or off (0).
Split Threshold tells the bot when to split a pea. If the number of any component falls below this setting the bot will attempt to split a pea for that component if it has any.
These options set which speech blocks will be used to send text for various conditions.
This setting controls how often one of the bots advertising emotes will be preformed. Setting this to "0" will cause the bot to never advertise.
This setting controls how often the bot checks to see if any of the spells in it’s BuffList spell array need to be recast. Setting this to "0" will cause the bot to no longer automatically stay buffed. Buffs will still be checked prior to running any command that has an associated BuffArray.
This sets how long before spell expiration the bot will recast the spell when checking it’s buffs.
Any user not explicitly included in the User section of the configuration file will be removed from the in memory user collection based on this timer setting. This is done to decrease the memory footprint of the bot and improve performance. In the example above a user would be removed from memory two hours after their last command.
Note that removing a user from the in memory collection does not change their access -- the user will be re-added normally when they next send a command.
This setting controls how often the bot will re-ID users to validate them. Their level, allegiance, etc. will be refreshed on ID. In the example above a user would be revalidated every two hours, regardless of how much they use the bot in that time.
Users that are explicitly included in the Users section of the configuration file will not be reevaluated.
This section defines replacement strings that can be used in text to retrieve data from the bot and output it to users. It should not be edited.
This section allows for special handling of items given to the bot. It forms teh base of the upcomming accounting system. Currently, Item rules allow the bot modify user access levels, send different messages, drop items, return items to the giver, and sort items into packs.
Note: If any item is matched by an ItemRule the default Insane-Bot auto-stacking action will not be preformed. You must explicitly move items into packs to get them to stack using item rules.
This rule will cause the bot to send the text in the GiftRule speech block and drop any trade note under 10,000 pyreals in value. The <Action> elements define what actions will be taken, the <Condition> elements define the properties that the item must have to activate the rule.
This rule will grant "Normal" level access to anyone with Unverified or Public access when they hand the bot a trade note worth 100,000 pyreals (or more). This access grant will last until either the bot is reset, or the ExpireUser timer removes them from the in-memory user collection. (Permanent access level upgrade will be possible once accounting is completed).
This rule also moves the item to Pack 1. (Pack 0 is the main backpack). The item will be merged into ay stack in Pack 1 that contains space.
This rule will remove access fro anyone who give the bot Fruitcake. The access restriction will go away after the ExpireUser timer removes the user from the in-memory collection, as above.
Complex conditions may be created. This rule will ban the user and drop the item when 1 flour or 1 water handed to the bot, but will allow the bot to accept larger stacks of flour or water.
The other supported Action is "ReturnItem". At this point we do not recommend using ReturnItem, as it can allow a user to cause your bot to follow them around the world attempting to return the specified item.
This section controls access to your bot. Rules grant or deny access to one or more characters. Most of your user access settings should be created using Rules.
The Type attribute specifies how this rule will be applied.
Type="0" creates an allegiance rule. The specified character and all
characters who have the specified character as their monarch will be set to the
security level specified. If the specified character is not a monarch this
rule will only apply to names character.
Type="1" is a Patron/Vassals rule. It will be applied to the named
character and any direct vassals of that character.
Type="2" is an individual rule. These rules will apply only to the
names character.
NewLevel sets the security level that all characters matching the rule will receive. If NewLevel is not included it will default to the level set be the Bot's DefaultAccessLevel option. The following access levels are valid: "None", "Unverified", "Public", "Guest", "Normal", "PowerUser", "Admin", and "SuperAdmin" (The numerical values 0, 5, 10, 25, 50, 100, 500, and 1000 also work for backward compatibility with previous config files). .
QueueMax is an optional parameter that overrides the default QueueMax setting for the bot for any characters that match the rule.
Hints turns on or off sending the text defined in the Hint EventSpeach block. This option ovverride teh bot's default Hints setting.
ReasonSpeech sets a text block to be sent to users when they request their first command. This speech block can be used to tell a user why they have been granted an access level, provide a personalized greeting, etc.
MinCharLevel & MaxCharLevel apply character level restrictions to Security Rules. The three Allegro Rules above apply different access levels to followers of Allegro based on their character level. Users level 19 and under receive Guest access. Users level 20 to 39 receive Normal access, and users level 40 and up receive PowerUser access.
Bot & BotExclude -- You can use the Bot="" attribute to specify which bots will apply the rule. If a rule had a Bot="P" attribute Pasta al'Dente (Who's ID is "P") would apply the rule, but Mekle (and any other bot defined in the file) would not. You can put multiple ID strings in the attribute separated by spaces (e.g. Bot="P M" would enable the command for both Pasta and Mekle, but no other bots).You can also use ExcludeBot="" to prevent specific bots from applying a Rule. e.g. if a rule had ExcludeBot="M" every bot defined in the config file except Mekle would grant access according to the rule. Mekle would ignore the rule.
A User record grants (or denies) access to a single user. The ID is the internal object ID of the character used by Asheron's Call. AdminLevel is the security level the user will be granted (use the same security levels used in Rules). QueueMax sets the maximum number of command this user may have pending in the command queue.
You do not need to set any access rights using a User record, but users created using this format can be correctly identified by the bot when they are not within the bot's radar range. Because of this it is helpful to have your bot administrators defined using User records.
Bot="" and ExcludeBot="" may be applied to Users in the same manner as they apply to Rules.
Timers are used to limit how frequently commands may be repeated.
This section is where you define what commands are valid for your bot. When setting commands the following values are valid:
SecLevels: 0=No Access, 5=Unverified Public, 10=Verified Public, 25=Guest, 50=Normal User, 100=Power Users, 500=Admin, 1000=Super Admin
Types: 1=Internal, 2=Spells, 3=TextOnly, 4=InternalOp, 5=Script
TargetType: 0=Self, 1=Other, 2=Weapon, 3=Shield, 4=Bow
Priority: 0=Super, 1=High, 2=Normal, 3=Low (Default is Normal)
IntervalTimer sets which timer is used to conrol how often this command can be run. IntervalSpeech is the speach block that will be sent during the time that the command can't be run.
The Help command is an example of a non-spellcasting command. The Pattern is used to match command names to provide specific help for each command. e.g. A /tell of "Help" will provide general help, while a /tell of "Help Summon" will provide specific help about the Summon command. There are two Help commands here -- the first will only be run for users with an access level of 0, and is not limited by a timer. The second Help command is run for all users with an access level of 10 or higher, and has a timer applied to it. (This timer is in place to prevent the bot from getting into a state where AC thinks it is spamming users with messages and squelches the bot).
Another Example of a text-only command. In the sample config file The "buff" commands are set to respond with jokes and snide comments.
These two commands execute the "summon-primary" spell array. Again security restrictions are used to provide different actions. Normal users are limited in how often a portal can be summoned by the Timer. Power users and higher can get a portal any time.
This command uses the Bot="" attribute to specify which bot will make this command available. In this case Pasta al'Dente (Who's ID is "P") would respond to a command of "crater", but Mekle (and any other bot defined in the file) would not. Any bot character who's ID is matched in the Bot attribute will enable the command. You can separate multiple IDs with spaces (e.g. Bot="P M" would enable the command for both Pasta and Mekle, but no other bots). You can also use ExcludeBot="" to exclude specific bots from a command. e.g. if a command had ExcludeBot="M" then every bot defined in the config file except Mekle would make the command available.
Another example of casting spells as a result of a command. In this case the target of the command is the user who made the request. Once again security levels are used to provide different actions, but in this case the difference is which Spell Array will be run. Different Speech clocks are also used to poke fun at users who spell the command incorrectly. This spell also ensure the bot is properly buffed before casting spells, using the "life" spell array to determine what buffs to check.
These commands target an item. In this case the weapon the user is currently wielding.
Spell Arrays tell Insane-Bot what spells to cast, and in what order.
A simple spell array that cast one spell.
A sample of a self buff spell array. The buff array defined by the <Character> definitiion is checked about every five minutes while the bot is active. Any spells that are less than five minutes from running out will be recast.
You may have noticed that this array has both level 6 and level 7 spells. Mekle needs to buff himself with level 6 spells before he can cast level 7 spells, so he uses this array to make sure he's fully buffed and ready to cast spells at any time.
When performing self buff checks Insane-Bot will not cast a self-buff that would be lower level than a currently active spell. If all of Mekle's buffs have run out he will first cast the level 6 spells, then the level 7 spells. The level 6 spells will not be cast again unless the corresponding level 7 spell expires -- since he'll automatically recast the level 7 spells before they run out the level 6 spells will only be cast at bot startup.
This spell array uses the Character ID codes to determine which spells to cast. In this example Mekle (who's ID is "M", as defined in his <Character> block) will cast the level 7 spells, but not the level 6 spells. Any other character will cast the level 6 spells.
A <Spell> element may optionally include an ID="" attribute. The value of ID should be the internal AC spell ID of the spell you want to cast. If ID is present then the value of Name is ignored, although it is still required. The ID field should generally only be used to overcome problems where the spell name is ambiguous, as happened with "Summon Primary Portal I" in the June 2002 patch.
You could also use the ID to make the Name value more easily readable, e.g. You could use
Where XXX was the ID for Battlemage's Blessing/Boon.
Speech blocks control what your bot says. They include advertising emotes, text for before casting a spell group, text for after casting, help text, etc.
Valid TalkType options: Unsafe Public=0, PrivateTell=1, Fellow=2, Console=3, Pasta=4, Command=5, Safe Public=6. For most cases you will probably only set an explicit TalkType of 6 or 0. TalkType - should be used VERY rarely (only in admin commands), as it allows nearly any keystroke to be sent directly to AC. Any text sent publicly (e.g. not a /tell or other directed command) will default to type 6.
Delay is recorded in MS, and the MinLevel/MaxLevel attributes on a Text Element only apply inside a Spoken element with a Type of "Sequential"
An example of a Random speech block. Only one Text item will be sent. Included in the speech are some Replacement strings that will be processed prior to sending the text (in these example selecting the correct pronoun). Note that replacement strings such as the pronoun cases above are always sent out in all lower case.
A sequential speech block. Each <Text> item will be sent in the order they appear in the block.
This speech block is used to respond to /tells from knows "thief" characters banned from the bot. The first three lines will be sent publicly. The last line will be sent only to the banned character.
These two speech blocks are a portion of the main Emotes the bots use to advertise themselves.
The "Emotes" block is the first called. It randomly selects one <Text> item to execute. If the selected item is one of the ones that contains a Block="" attribute control is passed to the specified speech block. In this example the second block is a sequential block -- all entries will be processed. However, each entry is restricted to a single Bot ID, and passes control on to still another speech block. The ability to nest any number of random or sequential speech blocks allows you to make your bot unique and flexible in how it responds to users.
Note that the ExcludeBot="" attribute can also be used with speech blocks -- it behaves the same as it does in Commands and SpellArrays.
This speech block uses Delays to space out the messages.
This portion of the Help speech block demonstrates using pattern matching and security level restrictions to control which messages are sent to users. The Match="" attributes is used to match the results returned from the Pattern="" attribute of the Help commands. The first four lines all match a "/tell help". But each line also includes security restrictions and passes control on to a second speech block. The net result is that a user will only see help text for their access level.
If any user (regardless of security level) sent a "/tell help help" they would receive only the fourth line.
If the user sent a "/tell help olthoi", and their security level was 25 or higher, they would receive only the sixth line. If their security level was under 25 they would receive no response.