Home

Welcome to Durel's aard-plugins wiki!

The aard_inventory.xml plugin is an inventory manager for the MUSHclient mud client designed for the Aardwolf mud.

Perform the following steps to install the plugin:

1. Copy the plugin file to your MUSHclient plugin directory (typically .../MUSHclient/worlds/plugins)
2. Select the File-->Plugins... menu option
3. Click the "Add" button
4. Navigate to the "aard_inventory.xml" file, select it, and click "Open"

Use the plugin's help system for details on how to use the plugin. You will want to start with the following help files:

• dinv help (to list all options)
• dinv help build
• dinv help refresh
• dinv help search

The first thing you'll want to do after installing the plugin is build your initial inventory table (see "dinv help build" for instructions). The plugin will identify everything that you are wearing, each item in your inventory, and everything in any container you are carrying. This takes roughly 5 minutes for me but that time could vary depending on how much you are carrying and what your latency is to the mud. Once your initial build is available, updates to it are very fast and easy. Also, I recommend making a backup so that you can restore things if something ever goes wrong. You shouldn't ever need to go through the full build process again. See the helpfile at "dinv help backup" for instructions on creating and restoring backups.

If you have the identify wish, you'll see all of the possible information on each item. Otherwise, some fields may not be available when you search for something or display stats on an item. It should still be very usable even without the identify wish though.

When you log in, the first thing the plugin does is quickly scan your inventory to see where everything is and to synchronize your current state with what the plugin expects. You can be as evil as you want to the plugin but it should still recover gracefully. If you log in via telnet and move things around in your inventory the plugin will simply resynch the next time you use it to log in. Everything is transparent. Easy peasy.

Ok, you now have your inventory identified. Let's do some search queries on it! The "dinv help search" and "dinv help query" helpfiles explain the query format and give tons of examples, but let's try a few here just to get the ball rolling...It should (hopefully) be intuitive. The output copied below is normally formatted for a 100-column screen so I needed to truncate it for this note. You can get the rough idea though -- and you can try it yourself with your own inventory too :) The query format supports keys for everything you find if you identify an item.

Example: Find all weapons with a minimum level of 100. This could be handy if you want to look at your dam types to see if you want to tweak something.

dinv search type weapon minLevel 100

Example: Find all equipment for your fingers that provides at least 5 str or at least 5 dex

dinv search wearable finger minStr 5 || wearable finger minDex 5

How many times have you seen someone ask how to get items of a certain level from their bag? That is easy now. Let's get all of our level 71 armor and put it in our main inventory. This will pull the equipment from any containers you have. You don't need to remember where you put the items :) See "dinv help get" for more examples.

dinv get level 71 type armor

You can also put items away into containers easily ("dinv help put"). Let's put all of our quest items (quest equipment has the keyword "aardwolf") into the container "3.bag". This will remove equipment you are wearing if necessary. It will also remove any matching items from other containers and put them into 3.bag.

dinv put 3.bag keyword aardwolf

Some people like to keep bags of keys in their manors. Here is an easy way to put everything that has a type of "key" or a flag named "isKey" into the container named "2.box". This will pull items from anywhere on you, including your keychain.

dinv put 2.box type key || flag isKey

As convenient as the "dinv put ..." command is, wouldn't it be great if you didn't need to remember where you want to keep your items? The plugin remembers the most recently used container for each of your items. If you simply want to put something back where you got it, use the "dinv store ..." command as described at "dinv help store". Let's store those level 71 items we got out in the previous example so that each item goes back into whichever container it was in previously. This is a convenient way to handle equipment sets. Don't worry -- we'll get to equipment sets before too long :)

dinv store level 71

The plugin even gives you the ability to add or remove custom keywords from items and then use those keywords with any of the "dinv [whatever] ..." modes. The mud won't recognize the keywords (this isn't a true replacement for aard's "tpspend name ..." command) but this is still a very convenient ability. Let's say that you just borrowed a bag full of equipment from "Bob". You can mark each item in the bag with a keyword named "borrowedFromBob", use the items as much as you want, and then put them back in the bag to return to him when you are done. For the sake of this example, let's say that the name of the bag containing the equipment is "2.bag". That means that the relative location ("dinv help search" and "dinv help query" explain what a relative location is) of the items is "2.bag". See "dinv help keyword" for more examples.

dinv keyword add borrowedFromBob rlocation 2.bag

[Use the items]

dinv put 2.bag keyword borrowedFromBob

The "dinv put ..." and "dinv store ..." commands are incredibly handy. But wouldn't it be even nicer if we could assign one or more item queries to containers and then let the plugin organize your items into the containers that "match" the items? Guess what...now you can! See "dinv help organize". As a first step, let's assign some search queries to containers. I use four bags for my primary character. I keep equipment from levels 1 - 160 in the first bag, equipment from levels 161 - 291 in the second bag, potions and pills in the third bag, and portals in the fourth bag. Here's how I would add the queries to my containers:

dinv organize add bag type armor maxlevel 160 || type weapon maxlevel 160 || type light maxlevel 160 || key aardwolf maxlevel 160

dinv organize add 2.bag type armor minlevel 161 || type weapon minlevel 161 || type light minlevel 161 || key aardwolf minlevel 161

dinv organize add 3.bag type potion || type pill

dinv organize add 4.bag type portal

Once the containers know what items they "own", we can "dinv organize ..." whichever items we want and any items matching the organize query will see if they need to move to a container. Let's move all potions and pills to their container.

dinv organize type potion || type pill"

In this example, let's say that you notice a "Sword of Awesomeness" in your main inventory and you want to move it to whichever container it belongs. We can use the relative name "awesomeness" to indicate which item we want.

dinv organize rname awesomeness

The "all" query string matches everything in your inventory. If you are reporting and want to put all of your equipment away, use "all". Boom. Everything is now nicely organized :) You can also use the empty query string (i.e., don't give one and just use "dinv organize") to organize all of your items that are not currently equipped.

dinv organize all

Ok, hopefully your appetite has been appropriately whetted :) Now let's get to the really fun stuff -- equipment sets!

You can take a "snapshot" of the equipment you are wearing at any given time. See "dinv help snapshot".

dinv snapshot create myAwesomeLevel131Set

You can list all of your snapshots, display detailed info on what a particular snapshot contains, and delete snapshots. The helpfile covers all of those cases. For now, here is a quick example of how to wear a snapshot. This will remove any equipment that is not in the snapshot, store those items, get all items in the snapshot, and wear them. Easy peasy.

dinv snapshot wear myAwesomeLevel131Set

But wait...there's more! I suspect that most people won't even bother to use snapshots once they learn how to create and use stat priorities (see the helpfile at "dinv help priority"). You are probably familiar with the "score" that you find on equipment. Aard's scoring system uses a fairly simple framework to prioritize which stats are important to your character based on your primary class. See aardwolf's "compare set" command to see the default priorities for your scoring stats. Although aard lets you customize your priorities a little bit, it would be nice if you had more control over this process. This plugin implements a similar scoring mechanism, but it has a LOT more options and dials that you can tweak. For example, the plugin priority mode lets you specify how important item effects are to you, it lets you specify different priorities for different levels or level ranges, it lets you prioritize how important it is to you to maximize a particular stat, it supports prioritizing offhand damage, it gives you the ability to say how important getting a shield's 15% damage reduction is to you, and much much more. It's essentially aard's scoring system on steroids.

As you may have guessed, you can create and wear dynamic equipment sets that maximize the set's total score relative to whatever priorities you specify. Knowing an item's individual "score" is great, but it doesn't tell you the entire picture. Some (or all) of an item's stats may be wasted if you are already maxing out a particular stat from a spellup or other equipment. The plugin can look at your exact situation at any time and find an "optimal" set for you to wear based on your current state. If you get an awesome SH spellup you probably will have different "optimal" equipment than if you have a regular spellup. Dynamic sets to the rescue! See "dinv help priority" and "dinv help set" for lots of details and examples.

Several sample stat priorities are included in the plugin by default. You can use weightings that are identical to aard's scoring system for your class by using a priority with the name of that class. For example, there are "mage", "paladin", "ranger", etc. priorities that use the scoring system as reported on aard by the "compare set" command. I don't recommend using these defaults by themselves, but they can be a convenient starting place for experimentation.

Here is how a primary psi's stats are weighted in aard's default scoring system. The same weightings are used from level 1 all the way up to 291 unless you manually change them.

dinv priority display psi

Priority: "psi" 
  MinLevel      1
  MaxLevel    291

       str   1.00  : Value of 1 point of the strength stat
       int   1.50  : Value of 1 point of the intelligence stat
       wis   1.50  : Value of 1 point of the wisdom stat
       dex   1.00  : Value of 1 point of the dexterity stat
       con   1.00  : Value of 1 point of the constitution stat
       luck  1.20  : Value of 1 point of the luck stat
       dam   0.50  : Value of 1 point of damroll
       hit   0.50  : Value of 1 point of hitroll
    avedam   0.40  : Value of 1 point of primary weapon ave damage
offhandDam   0.40  : Value of 1 point of offhand weapon ave damage

I've included a snippet from the output displaying a "priority" for a primary psi with at least one melee class. I'm continually tweaking this, but this is what I'm leveling with at the moment. Str and dex are emphasized more at lower levels than higher levels. Item effects like haste and sanctuary are weighted higher at lower levels and then they become less important once the haste and sanctuary spells are available. Offhand damage from a dualed weapon is more important at higher levels once more offhand attacks are available. Maxing int and wis at higher levels is important to me as a navigator subclass -- bypass rocks -- so maxed int and wis get a little extra bonus in the psi-melee priority. I'm an eldar and I'm vulnerable to slashing so I should probably give a slight bonus to slash resistance but I haven't bothered with that yet. You get the idea. There are lots of dials you can tweak and the helpfiles cover all of this.

Anyway...here is the psi-melee priority snippet I promised. You can use whatever scaling you want -- it's all relative. My preference is to give a weight of "1" to one stat point my character's primary stat and then go up or down from there for other stats, effects, and abilities. Feel free to do what you want though. The vanilla class stats I "borrowed" from aard's "compare set" command use 15 points for a primary stat and then go down from there for other stats. It really doesn't matter.

dinv priority display psi-melee

Priority: "psi-melee"

    MinLevel      1     51    101    131    171    201
    MaxLevel     50    100    130    170    200    291

         str   1.00   0.90   0.80   0.70   0.70   0.60  : Value of 1 point of the strength stat
         int   0.60   0.80   1.00   1.00   1.00   1.00  : Value of 1 point of the intelligence stat
         wis   0.60   0.80   0.90   1.00   1.00   1.00  : Value of 1 point of the wisdom stat
         dex   0.80   0.70   0.70   0.60   0.50   0.50  : Value of 1 point of the dexterity stat
         con   0.20   0.30   0.40   0.50   0.50   0.50  : Value of 1 point of the constitution stat
        luck   1.00   1.00   1.00   1.00   1.00   1.00  : Value of 1 point of the luck stat
         dam   0.90   0.90   0.80   0.70   0.60   0.50  : Value of 1 point of damroll
         hit   0.40   0.50   0.60   0.60   0.60   0.50  : Value of 1 point of hitroll
      avedam   1.00   1.00   1.00   1.00   1.00   1.00  : Value of 1 point of primary weapon ave damage
  offhandDam   0.30   0.40   0.50   0.60   0.70   0.85  : Value of 1 point of offhand weapon ave damage
          hp   0.02   0.01   0.01   0.01   0.01   0.01  : Value of 1 hit point
        mana   0.01   0.01   0.01   0.01   0.01   0.01  : Value of 1 mana point
   sanctuary  50.00  10.00  10.00  10.00  10.00   5.00  : Value placed on the sanctuary effect 
       haste  20.00   5.00   2.00   2.00   2.00   2.00  : Value placed on the haste effect 
      flying   5.00   4.00   2.00   1.00   1.00   1.00  : Value placed on the flying effect 
       invis  10.00   5.00   3.00   1.00   1.00   1.00  : Value placed on the invisible effect 
regeneration   5.00   5.00   5.00   5.00   5.00   2.00  : Value placed on the regeneration effect
 detectinvis   4.00   4.00   2.00   2.00   2.00   2.00  : Value placed on the detect invis effect 
detecthidden   3.00   3.00   2.00   2.00   2.00   2.00  : Value placed on the detect hidden effect 
  detectevil   2.00   2.00   2.00   2.00   2.00   2.00  : Value placed on the detect evil effect 
  detectgood   2.00   2.00   2.00   2.00   2.00   2.00  : Value placed on the detect good effect 
   dualwield  20.00   0.00   0.00   0.00   0.00   0.00  : Value of an item's dual wield effect
    irongrip   2.00   3.00  20.00  20.00  25.00  30.00  : Value of an item's irongrip effect
      shield   5.00   5.00  10.00  20.00  25.00  30.00  : Value of a shield's damage reduction effect
      maxint   0.00   0.00   0.00   0.00  10.00  40.00  : Value of hitting a level's intelligence ceiling
      maxwis   0.00   0.00   0.00   0.00  10.00  40.00  : Value of hitting a level's wisdom ceiling
     maxluck   0.00   0.00   0.00   0.00   5.00  20.00  : Value of hitting a level's luck ceiling
    allmagic   0.03   0.03   0.05   0.05   0.05   0.05  : Value of 1 point in each magical resist type
     allphys   0.03   0.05   0.10   0.10   0.10   0.10  : Value of 1 point in each physical resist type

So...let's wear a "psi-melee" dynamic set for your current level:

dinv set wear psi-melee

You can also display a dynamic set for any level. This is (in theory) what you would wear at the specified level based on what the plugin knows about your equipment. The only tricky part is that the plugin doesn't know what your spellup would be when you are at that level and the plugin must use some estimates. The plugin starts with a guess as to your spellup at any given level and then it continually adjusts its estimates as you play the game. It keeps a running weighted average for the spellup you have at each level and then uses that weighted average if you ever ask it to guess what equipment would be best at a different level than your current level. If you have a playing style that involves using SH spellups continually, then the plugin will learn that and account for that in your equipment sets. Similarly, if you typically don't bother with spellups, the plugin will learn that too and base its estimates accordingly. In short, the plugin can know your optimal equipment for your current state but it must estimate your optimal equipment for other levels.

dinv set display psi-melee 42

You can also create priorities for specific scenarios. For example, I use an "enchanter" priority so that I can quickly and easily wear a set that boosts int, wis, and luck when I want to enchant something. I use a "psi-balance" priority when I'm desperate to max wis and int. It finds the set that has the biggest difference between int and wis so that I'll get the maximum boost to wis when I cast mental balance. You could create priorities that emphasize particular damage types or damage resistances and quickly and easily swap equipment accordingly.

Simply wearing dynamic sets isn't sufficient. You need to be able to analyze your equipment to your heart's content! See the helpfiles "dinv help analyze" and "dinv help usage" to learn about what you should be wearing at each level and how each piece of equipment fits into that plan.

For example, here is a short report telling me what waist equipment I should use at which levels according to my "psi-melee" priority. At each level where equipment changes, it shows what equipment is removed and what equipment will replace it. The output is truncated here so that it will fit in an 80-column note -- more stats would normally be shown on each line. I find it very helpful (and fun!) to generate large reports covering all my equipment at every level. Yeah, I'm probably strange that way :)

dinv analyze display psi-melee waist

NOTE: I temporarily removed the output here. It was formatted for the mud's color scheme and it looked horrible here. You can run the command yourself and see the output in all of its glory on Aardwolf :)

But wait, there's more! You can pick a specific item and do a deep analysis on exactly what benefits it provides for every equipment set at every level. See "dinv help usage" and "dinv help compare" for instructions on how to evaluate where a particular item is used and how each equipment set would change if the item were not available.

You can even perform a deep analysis of items on auction and on the long-term market to see how your equipment sets would change at each level if you owned that item. See "dinv help covet" for instructions.

There are many other modes the plugin provides but you are probably getting note fatigue by this point and you should be trained to use "dinv help ..." by now :) There are a few items you should know though.

By default, the plugin reports a moderate amount of info about what it is doing. This could be helpful when you first use the plugin. Once you are familiar with it, you can limit which notifications you get to only include higher-priority messages. See "dinv help notify" to change which types of messages the plugin will report to you.

The plugin also includes a full tags system that mimics aard's tag system. You can individually enable or disable end tag reporting for every one of the "dinv [whatever]" commands. If the tag is enabled, you will get the end tag echoed to you when the command completes. I can't tell you how many times I wished that the mapper would have some way to tell me when a mapping command was done. You won't have that problem with this plugin :) The end tag also gives you the return value and a return value string so that your own code can kick off a dinv command and know when it is done and what happened along the way. See "dinv help tags" for details and examples.

Thanks for reading this far :) Feedback is greatly appreciated!