AardDurel-Dinv/README

Summary
=======

The aard_inventory.xml file is a MUSHclient plugin for the Aardwolf mud.
See the wiki for instructions on installing the plugin.


Aard Inventory Manager
======================

This plugin manages your inventory and gives you tools to analyze and use
items in your inventory.

The first step you'll need to take is to find an out-of-the-way room where
you won't disturb anyone and then run "dinv build confirm".  This step
will identify all items you are wearing, all items in your main inventory,
and all items in containers in your inventory.  This will take roughly 5
minutes depending on how many items are in your inventory.  If you need to
halt the build simply go to sleep or go AFK.  You can "refresh" your
inventory later to complete the process of identifying everything you are
carrying.

Once you have a completed inventory table available, I recommend making a
manual backup in case something goes wrong in the future.  You can restore
from the backup and avoid the long build process again.  If anything in
your inventory has changed since the backup, your next refresh will simply 
update it to what you currently have.  To make a manual backup named
"my_first_awesome_backup" type "dinv backup create my_first_awesome_backup".
See "dinv help backup" for more details about creating, viewing, and restoring
backups.

Type "dinv help" for all available usage options.  For detailed examples of
how to use each option, simply type "dinv help <option>".


Usage
=====

  Inventory table access
    dinv build confirm
    dinv refresh [on | off | eager | all] <minutes>
    dinv search [objid | full] <query>

  Item management
    dinv get <query>
    dinv put <container relative name> <query>
    dinv store <query>
    dinv keyword [add | remove] <keyword name> <query>
    dinv organize [add | clear | display] <container relative name> <query>

  Equipment sets
    dinv set [display | wear] <priority name> <level>
    dinv weapon [next | <priority> <damType list>]
    dinv snapshot [create | delete | list | display | wear] <snapshot name>
    dinv priority [list | display | create | clone | delete | edit | copy | paste | compare] <name 1> <name 2>

  Equipment analysis
    dinv analyze [list | create | delete | display] <priority name> <positions>
    dinv usage <priority name | all> <query>
    dinv compare <priority name> <relative name>
    dinv covet <priority name> <auction #>

  Advanced options
    dinv backup [list | create | delete | restore] <backup name>
    dinv reset [list | confirm] <module names | all>
    dinv forget <query>
    dinv notify [none | light | standard | all]
    dinv cache [reset | size] [recent | frequent | custom | all] <# entries>
    dinv tags <names | all> [on | off]
    dinv reload

  Using equipment items
    dinv consume [add | remove | display | buy | small | big] <type> <name or quantity> <container>
    dinv portal [use] <portal object ID>
    dinv pass <pass ID> <# of seconds>

  Plugin info
    dinv version [check | changelog | update confirm]
    dinv help <command>


Release Notes
=============

1) If you give an item to an enchanter to boost the item's stats, you may pull the old stats from a
   cache instead of using the new enchantments when you get the item back.  In this case, you may use
   the "dinv forget <query>" option to remove that item from your inventory table and its related caches.
   The next inventory refresh will pick up the new stats for the item.

2) Most aard operations that modify an item's stats are detected and automatically trigger a 
   re-identification.  For example, enchantment spells, sharpening, reinforcing, tpenchanting, and wset
   all are handled transparently.  There are two known exceptions to this.  First, the setweight
   command does not result in an invitem update from aard's invitem system.  Second, scribing a scroll
   does not trigger an invitem update.  As a result, until this is changed on aard's side of things
   (or we manually add triggers in the plugin to watch for setweight and scribing) you will need to use
   the "dinv forget <query>" option on an item that changes weight or a scroll that is scribed.  This
   will cause the plugin to "forget" the existing data on the item so that the new information will be
   picked up on the next inventory refresh.

3) Wands and staves are not re-identified as they are used.  As a result, the number of charges
   shown in the item's display may not match reality as the item is used.  If this mode is not added
   to the aard invitem system, we may need to add a trigger to watch for this and update charges
   accordingly.

4) The plugin does not automatically open containers that are closed.  As a result, you won't be able
   to get/put items in a closed container.  Keep your containers open! :)

5) If the plugin tags are enabled, they will echo an end tag at the conclusion of an operation.  However,
   if the user goes into a state that doesn't allow echoing (e.g., AFK) then the plugin cannot report the
   end tag.  In this scenario, the plugin will notify the user about the end tag via a warning notification
   instead of an echo.  Triggers cannot catch notifications though so any code relying on end tags should
   either detect when you go AFK or cleanly time out after a reasonable amount of time.

6) If you add the portal wish after you have built your inventory table, you will need to either rebuild
   the table (dinv build confirm) or forget/re-identify your portals (dinv forget type portal) and
   (dinv refresh all).


Feature Wishlist
================

1) Implement a mechanism to (more) fully identify items if the identify wish is not available.
   For example, we could use lore, the identify or object read spells, or Hester's identify
   service found at "runto identify".  This would be a manual process to "clean up" partially
   identified items.