Wyvern Autobag Command

You are reading the Wyvern Autobag Command reference. Good luck!

Contents

Intro

Wyvern provides a powerful command called "autobag" that lets you place items in bags automatically when you pick them up. The command is a bit complicated to use, but it's well worth learning. It's one more step along the road to becoming a Expert HoFer.

Shortcuts

By popular demand, we've provided some shortcuts for popular autobag rules. The current shortcuts are listed in the table below.

To use a shortcut, all you have to do is type "autobag shortcut arrows" (or whatever the shortcut is), and it takes care of setting up the rule for you. You can use "autobag list" and "autobag delete" to manage your rule list.

Current shortcuts:

Shortcut What it does
autobag shortcut arrows puts all arrows into your first quiver
autobag shortcut reagents puts all reagents into your first reagent pouch
autobag shortcut potions puts all potions into your first potion pouch
autobag shortcut stones puts all sling stones into your first rock pouch

If you want more control over which items go in which bags, you can use the autobag mini-language, which is described below. It's a lot of reading, so if it seems scary, you may be better off finding another player to help you write your rules.

Overview

At a high level, "autobag" works like this:

  1. You set up rules for which items go in which bags
  2. You can add, delete, rename, or swap rules
  3. When you pick up an item, all your rules are checked
  4. If one of the rules matches, the item goes in that bag

We'll go into how all this works shortly, but to whet your appetite, here are some examples. See if you can figure out what they do. If you can't, don't worry! We'll explain it all. By the time you finish reading this web page, you'll know how to make all of these rules, and even more complicated ones if you need them.

Example 1

  AUTOBAG INTO quiver WHERE name LIKE "arrow" CALL RULE "normal arrows"

Example 2

  AUTOBAG INTO "elixir pouch" WHERE type is potion CALL RULE "potions"

Example 3

  AUTOBAG INTO "Master Wizard's Reagent Pouch", "reagent pouch"
     WHERE type is "reagent"
       AND NOT (name LIKE "dragon heart" or name LIKE "dragon claw")

Example 4

AUTOBAG

   INTO "quiver of holding 1", "quiver of holding 2", "backpack"

   WHERE

     ((name like "arrow") and name like "slaying"
      and quantity <= 100)
      AND
      item is not cursed
      and (item is blessed or item is uncursed)
      and not item is unpaid

    CALL RULE "this is one crazy rule!"

Autobag Syntax

The autobag command is actually a mini-language, similar to mail filtering. The basic syntax looks like this:

   autobag <subcommand> [arguments]

Naming Conventions

We're following the Unix operating system naming conventions above:

  • When you see the syntax for a command (e.g. in the Wyvern Command Reference), the first word is always the command verb — in this case, "autobag".

  • When you see something in <angle brackets>, it means it's required.

  • When you see something in [square backets], it means it's optional.

So in this syntax snippet:

autobag <subcommand> [arguments]

it means that you always need to provide a subcommand, but some subcommands don't need arguments.

Incidentally, "arguments" to commands are just extra information you pass along to the command. For instance, if you type "get all from corpse", the command verb is "get", and the arguments are "all from corpse". Simple!

Autobag Subcommands

Autobag has five subcommands. You specify which subcommand to use with the second argument. For example, if you type autobag list, then autobag is the command, and list is the subcommand.

The five subcommands are:
into: creates a new rule
list: shows your current rules
rename: changes the name of one of your rules
delete: permanently deletes one of your rules
adjust: switches the position of a rule in the list

The most interesting and complicated subcommand is "into", which creates a new autobag rule. We'll cover all of the subcommands in the sections below.

INTO subcommand

This sub-command is used to create new rules.

Every rule has three parts:

  1. A name, which you specify with CALL RULE
  2. A set of conditions, which you specify with WHERE
  3. A set of bags, which you specify with INTO
You have to specify all three of these things to make a rule. As it turns out, we've listed them backwards. The basic syntax is:
  autobag INTO <bag> [, bag]* WHERE <conditions> CALL RULE "<name>"
The keywords above (INTO, WHERE, and CALL RULE) are all shown in uppercase. We'll often show them in uppercase in this manual, even though you can type them in any case you want. If you want to type CaLl RuLe, it'll still work. We use uppercase because it makes the sections stand out more clearly.

For the rest of this manual, we'll often put the bag names in purple, the rule conditions in green, and the rule name in red, just to make things a bit easier to read.

How Autobag Rules Work

When you pick up any object (or take it out of a corpse, chest, or other container on the ground), Wyvern checks your autobag rules to see if the object should go into a bag in your inventory.

If you have more than one rule, it will check each rule in order. The first rule that "matches" the item you picked up wins. If none of your rules match, the item just stays in your top-level inventory.

As a quick example, let's say you have three simple rules defined. We've broken the rule sections into separate lines, for readability. Keep in mind that in the game, you always have to type out the entire rule on one line.

Here are our example rules:

  autobag
    INTO "quiver"
    WHERE name LIKE "arrow"
    CALL RULE "arrows"

  autobag
    INTO "backpack"
    WHERE name LIKE "tiny round shield"
    CALL RULE "shields"

  autobag
    INTO "elixir pouch"
    WHERE name LIKE "potion"
    CALL RULE "potions"
If you pick up a potion of healing, the system tries all three rules:
  1. First it tries your "arrows" rule. The "arrows" rule says that if the object's name is like "arrow", put the object in your first quiver.

    In this case, the potion of healing's name is definitely not like "arrow", so we move to the next rule.

  2. Next, it tries your "shields" rule. This rule says that if the object's name is like "tiny round shield", put it in your first backpack. The potion is not a shield, either, so we move on.

  3. Last, it tries the "potions" rule. This rule says that if the object's name is like "potion", stuff it in your first bag called "elixir pouch". The name "potion of healing" is like "potion" (later we'll define that that means, exactly), so the Autobag system puts the potion in your elixir pouch!

    Of course, if you don't have an elixir pouch, it doesn't do anything. You just wind up carrying the potion.

That's it for our high-level overview of autobag rules. Make sense so far? Next we'll get into exactly how to say which bags to put things in.

Specifying Bags

For each rule, you can specify one or more bags to put the items in. If an object you pick up satisfies that rule's conditions, then the system tries to put the object in one of the bags you specified.

The first thing to know is that you usually only need to specify one bag. The object can only go in one bag, so the other bags you mention in the rule are just backups, in case the first bag fails.

A bag can "fail" for 2 reasons:

  1. It's full, and has no room for the new object.
  2. Or, the bag's not in your inventory.
In the Bags section of your autobag rule, you're simply specifying the names of the bags. The system doesn't check to see if you spelled it correctly, or if you own a bag with that name. You could type:
  autobag
    INTO "doggy's mouth"
    WHERE name like "biscuit"
    CALL RULE "nice doggy"
but if you don't have a bag called "doggy's mouth", then your biscuits aren't going to go into it.

Multiple Bags

If you want to specify more than one bag, separate the names with commas:
  autobag
    INTO "quiver of holding", quiver
    WHERE name like "arrow"
    CALL RULE "arrows"
In the rule above, we've specified two bags: one called "quiver of holding", and a second one called "quiver". The game will try to put arrows you pick up into your first quiver of holding, and if it can't, it'll try your first quiver of any kind.

Note that it doesn't matter what order the quivers appear in in your inventory. The order in the rule does matter. You could have a regular quiver in your inventory before the quiver of holding, but your rule says to try the quiver of holding first, so that's what it does.

Notice that we didn't put any quotation marks around the second bag name. We just said quiver, with no quotes. In general, you only need to use quotes around a name if there are spaces in it.

Finally, bag names are matched with LIKE, which means that the game only uses partial matching, not exact matching. The next section discusses this in more detail. It's important!

Name Matching with LIKE

Let's say you have three quivers in your inventory, in this order:
  1. quivering blob corpse
  2. quiver
  3. quiver of holding
Admittedly, you can't carry corpses right now, unless you're a Wizard, but bear with us for the moment.

The multi-bag example above looked like this:

  autobag
    INTO "quiver of holding", quiver
    WHERE name like "arrow"
    CALL RULE "arrows"
This rule says to first try the "quiver of holding". If you have a quiver of holding, and it can hold your arrow, then the arrow will go in there.

However, if the quiver of holding is full (or you're not carrying it), the game goes on to the second bag, which is specified simply with quiver (quotes don't matter since it's just one word.)

But look at your inventory — your first bag that matches "quiver" is actually the quivering blob corpse.

Why? Because bag names are matched with LIKE, which checks if the name you specified is a substring of the object's short description.

An object's "short description" is the text you see when you're looking at it in your inventory, or on the ground. It includes modifiers like "(unpaid)" and "(cursed)".

A substring means that string A appears anywhere inside string B. So "quiver" is a substring of "quivering blob corpse" — it starts at the beginning. "blob co" is also a substring of "quivering blob corpse", for what it's worth.

So, our rule, which failed to find a "quiver of holding" (because you weren't carrying one, or it was full), tries to find a bag matching quiver, and finds the corpse. You can't put things in corpses, only take things out, so the bolt doesn't go in any bags.

You can get around this problem by giving your bags very specific names.

Naming Your Bags

You can find Bag Naming services in various places in the game. We won't publish their locations in this manual, but ask around, and you're sure to find one.

Rule Conditions

This section is the real "meat" of autobagging. The rest is just veggies, a side of potatoes, and maybe some garnish. If you can master this section, then you'll be able to make really cool rules.

We'll work our way up from simple conditions to complex ones. The simplest (and most common) rule is to match something's name. As we described in Name Matching with LIKE above, name matching can use LIKE to do partial matching. It matches what you type against the object's short description.

Name Matches

For our first example, let's say you want all dragon claws you pick up to go into your backpack automatically. You could write a rule like this:
  autobag
    INTO backpack
    WHERE name like "dragon claw"
    CALL RULE "dragon claws"
If you type this command in, and you type it correctly, you should see:
  Added rule 'dragon claws' as rule #1
It's that simple! Now, whenever you pick up a dragon claw, the game will try to put it in the first backpack in your inventory.

You can see your rules by typing "autobag list". We show a little command session below, where the commands you type are in brown, and the game output is in black:

  autobag into backpack where name like "dragon claw" call rule "dragon claws"
  Added rule 'dragon claws' as rule #1

  autobag list
  1.   dragon claws

  autobag list 1
  Autobag Rule: dragon claws
    Bags to add to: "backpack"
    Conditions:
      name LIKE "dragon claw"

Exact Match Example

Let's say someone comes out with "powdered dragon claw", but you don't want the powdered claws to be put in your backpack automatically. The rule in the example above would put it in your pack, because we specified name LIKE "dragon claw" — and "powdered dragon claw" is very much like "dragon claw". We can fix this by using an exact name match.

We change the rule to use "=" instead of "like":

  autobag
    INTO backpack
    WHERE name = "dragon claw"
    CALL RULE "dragon claws"
Now the items will only go into the bag if their exact name is "dragon claw".

Some computer languages use '==' instead of '=' to test for equality. Since autobagging is a simple language, we've tried to make it easy for everyone, and you can use '==' if you prefer.

Quantity Match

You can make conditions that compare item quantities. Let's say you're a scruffy yet likeable Halfling who uses a Sling as your weapon of choice. You want to collect sling stones as you wander around dungeons, stepping on rock traps and so on.

At first, you might think "well, I'll just pick up rocks and put them in my Rock Pouch", like so:

  autobag
    INTO "rock pouch"
    WHERE name like "sling stone"
    CALL RULE "sling stones"
Unfortunately, if you have autograb missiles on, and you happen to step on a giant pile of stones, say 250 of them, then your rule will happily stuff all 250 stones in your pouch, and you'll start moving more like a Halfling Zombie. What you really want is a rule that only picks up stones if there are only a few of them.

You can fix this by checking the quantity of the item you're picking up. Here's a rule that does it:

  autobag
    INTO "rock pouch"
    WHERE name like "sling stone" AND quantity <= 50 
    CALL RULE "sling stones"
Now, whenever you pick up a pile of sling stones, only groups of 50 or less will go into your Rock Pouch.

Notice that we used a new operator, AND, to combine two conditions. We'll talk about the AND operator a bit more later on.

Note: If you're an experienced Wyvern player, you might be wondering what the heck a Rock Pouch is, and where you can get one. Well, as it happens, we decided while writing this tutorial that it would be a useful thing to have, so we made one. Look for it in your local shop!

Note about that note: As we were writing this tutorial, we found an ancient comment in the Wyvern source code for Slings, dating back to June 10th 1998, that said "we need sling stone pouches". It took the autobag command to convince us to make one!

Combining Conditions
You may have noticed that the rule doesn't help you if you happen to be unlucky enough to pick up 250 stones automatically. What you really want is to drop those 250 stones faster than a grocery bag full of nose hair. And we have just the rule for you.

  autobag
    INTO "drop item"
    WHERE name like "sling stone" AND quantity > 50 
    CALL RULE "drop too many sling stones"
If you use the special bag name "drop item", then instead of putting the item in a bag, the Autobagger will drop it for you automatically. The rule above tells the Autobagger to drop any group of sling stones with 50 or more stones.

You can use the following comparison operators for matching quantities:

  • < (less than)
  • > (greater than)
  • <= (less than or equal to)
  • >= (greater than or equal to)
  • != (not equal)
  • <> (not equal — same as !=)
  • = (equal to)
  • == (equal to: same as =)

Type Match

So far you've seen two kinds of conditions (also called "matches"):
  1. Name match, which checks an item's description
  2. Quantity match, which checks an item's quantity
Another basic kind of match is a Type Match. You may be familiar with types from the autograb command. A type is a sort of catch-all that covers a wide range of objects.

The autograb command currently supports seven types: food, magic, armor, weapons, missiles, and treasure.

The autobag command goes a step further and supports many more types. Here is the current list:

Type Description
magic all potions, scrolls, spellbooks, wands, rods, girdles, amulets, rings and reagents.
potion potions
wand wands and rods
reagent reagents
book spellbooks
ring rings
amulet amulets
girdle girdles
armor all armor types
cloak cloaks
bodyarmor platemail, chainmail, etc.
helmet helmets
shield shields
bracers bracers
boots boots
gloves gloves
weapon all weapon types
range-weapon bows, crossbows, slings
hurled-weapon spears, javelins, throwing knives, etc.
melee-weapon swords, clubs, axes, flails, whips, etc.
axe axes only
blade katanas, foils, scimitars, other non-sword blades
bow bows
claws Rakshasa claws
club clubs, maces
crossbow crossbows only
flail flails, morningstars
foil foils only
gun blowguns
hammer war hammers
missile any ammo
sling slings only
spear spears, javelins
staff quarterstaff
sword all swords
whip whips, cat-o'-nine tails, multi-whips
treasure all treasure
coins coins only
gemstone gems only
food all food types

To do a type match, use the following syntax:

  TYPE IS <type>
You can use quotes around types, but since they're all single-word types, you don't need them. A hyphenated word is still considered a single word by the autobag parser.

We will eventually update autograb to have finer-grained types to match the autobag types.

Property Match

You can match objects you pick up based on certain "properties" they possess. The properties you can check for are:
  • cursed
  • blessed
  • uncursed
  • kept
  • unpaid
We'll be adding to this list as time goes on. There are dozens if not hundreds of object properties that could potentially be used, and we're investigating which ones would be useful for Autobag rules.

The syntax for matching a property is:

  ITEM IS <property>
For instance, suppose you want to sort all the armor you pick up into three bags: one for cursed, one for normal/uncursed, and one for blessed. You can do this by writing three rules:
  autobag
    INTO "uncursed armor bag"
    WHERE type is armor AND item is uncursed
    CALL RULE "uncursed armor"
  autobag
    INTO "cursed armor bag"
    WHERE type is armor AND item is cursed
    CALL RULE "cursed armor"
  autobag
    INTO "blessed armor bag"
    WHERE type is armor AND item is blessed
    CALL RULE "blessed armor"
Note that you'd have to have three separate bags with the correct names in order for these rules to work — this is why bag naming is so important for using the autobag command effectively.

Inverted Property Match

Let's say you want to autobag ALL cursed items into a single bag called "cursed stuff", and everything else into "uncursed stuff". (So your "uncursed stuff" bag will have both uncursed and blessed items.)

You can write this with two rules. You want to put stuff that's NOT cursed into the "uncursed stuff" bag, and cursed stuff into the "cursed stuff" bag.

One of the rules introduces a new operator called, appropriately, NOT. The rules look like this:

  autobag
    INTO "cursed stuff"
    WHERE item is cursed
    CALL RULE "cursed stuff"
  autobag
    INTO "uncursed stuff"
    WHERE item is NOT cursed
    CALL RULE "non-cursed stuff"
We used a new operator, NOT, to say that we want the inverse of "cursed", which includes "blessed" and "uncursed". (Note that "damned", which is an extremely awful kind of curse, still qualifies as "cursed", so damned items would go into your cursed bag with the rules above.)

There are actually two flavors for using NOT with property matching, both of which have identical results:

  NOT item is <property>
and
  item is NOT <property>
The first version is more general: you can stick a NOT in front of any expression and invert the test. The second one is a shorthand that's only available for property tests.

AND rules

The keyword AND just glues two conditions together. It means both conditions have to be true, or the rule will fail.

You can chain as many conditions together as you want by putting AND between each of them.

For example, if you type:

  autobag
    INTO "blessed quiver"
    WHERE name like "arrow" AND item is blessed AND quantity < 100 
    CALL RULE "blessed arrows"
Then when you pick up an object, and this rule is checked, THREE conditions have to be true for the object to go into your "blessed quiver":
  1. The object's name has to match "arrow"
  2. AND the object has to be blessed
  3. AND the quantity has to be less than 100
If you chain 2 or more conditions using AND, then all of them have to be true. If any of them fails, the whole rule fails.

OR rules

OR lets you string conditions together, similar to the way AND does. The difference is that with OR, if any of the conditions are true, the whole rule succeeds. For the rule to fail, all of the OR'ed conditions have to be false. That's the opposite of the way AND works.

For example, if you want to put items that are blessed or cursed in a special bag, but not if they're uncursed, then you can do this:

  autobag
    INTO "blessed/cursed"
    WHERE item is blessed OR item is cursed
    CALL RULE "blessed and cursed stuff"
When the rule is evaluated, it does two checks on the object:
  1. Is it blessed? If so, it bags it.
  2. Is it cursed? If so, it bags it.
In this case, AND would have been totally inappropriate, since it would require the item to be blessed and cursed at the same time, which is impossible. OR is definitely the way to go here.

NOT rules

NOT inverts a rule, turning true into false, and false into true, just like in English. The following two English statements are opposites:
  1. I like spinach.
  2. I like spinach — NOT!

To use NOT, let's say you only want to autobag item if they're not cursed. You can write the rule like this:

  autobag
    INTO "uncursed"
    WHERE item is NOT cursed
    CALL RULE "blessed and uncursed stuff"
There are two ways to write this rule. You can say "not item is cursed", or "item is not cursed". They both work, and they both do the same test.

However, the more general version is "NOT item is cursed". You can think of it like this:

  1. the test is item is cursed
  2. to invert it, put a "not" in front, like this: NOT item is cursed
There's a reason you need to know this. The problem is that the "item is not cursed" version doesn't work for certain types of tests. For example, you can't say this:
  autobag
    INTO "quiver"
    WHERE quantity NOT <= 100
    CALL RULE "this rule is broken!"
It will give you a syntax error and the rule won't appear in your list. You'd actually need to write the rule above like this:
  autobag
    INTO "quiver"
    WHERE NOT quantity <= 100
    CALL RULE "this rule works!"
However, "not less than or equal" is exactly the same as "greater than", so the rule would be even simpler as:
  autobag
    INTO "quiver"
    WHERE quantity > 100
    CALL RULE "even better!"
Similarly, you can't write name NOT like "bob" or type is NOT treasure. The special shortcut of "item is NOT cursed" only works for Property Rules.

Probably the easiest way to get it right is to remember two things:

  • You can't stick a NOT keyword in any old place in your rule.
  • You can always stick a NOT in front of a condition.

Incidentally, that means that you can do wacky stuff like
  autobag
    INTO "quiver"
    WHERE name like arrow and NOT NOT NOT NOT NOT item is cursed
    CALL RULE "this rule is weird!"
But we don't recommend it!

Mixing AND, OR, and NOT

As we've seen in the earlier sections, you can mix conditions together. Take a look at this rule and see if you can figure out what it does:
  autobag
    INTO "small pouch"
    WHERE type is reagent AND name like "clover" OR item is cursed
    CALL RULE "this rule is tricky!"
There are two possible interpretations for this rule, depending on whether the AND or the OR is "stronger":
  1. It could mean that if you pick up an an object, autobag it into your small pouch if it's a reagent whose name is like "clover", or if it's any cursed object at all.

  2. Or, it could mean that if you find a reagent, autobag it into the "small pouch" if its name is like "clover", or if the reagent is cursed.

The first interpretation assumes that "AND" is stronger, combining the "type is reagent" and "name like clover" condition into a single condition, like this:

   (type is reagent AND name like "clover") OR (item is cursed)

The second interpretation assumes that OR is stronger, and makes a single condition out of the two around it, like this:

   (type is reagent) AND (name like "clover" OR item is cursed)

So which one is it?

The first interpretation is the correct one! AND is in fact stronger than OR. So in the tricky rule above, all cursed objects would go into your small pouch. Probably not what you wanted, is it?

Precedence

Instead of saying that AND is "stronger", we say that AND has a higher "precedence" than OR. Means the same thing, though. In a shooting match, AND wins. You can think of AND as placing parentheses around itself and the conditions to its left and right: (a AND b).

The NOT keyword has an even higher precedence than AND or OR. However, it's used differently. AND and OR go between two other conditions, linking them together. NOT goes before a condition, inverting its meaning.

It's usually best if you write complex rules using parentheses, to make sure your meaning is clear. This is especially true if you mix AND and OR in the same rule.

Grouping Conditions with Parentheses: ()

You can put parens around any condition. For example, these two rules have the same meaning:
  autobag
    INTO "weapons"
    WHERE type is weapon
    CALL RULE "weapons to sell"
  autobag
    INTO "weapons"
    WHERE (type is weapon)
    CALL RULE "weapons to sell"
The parentheses in this case don't do anything special. You can nest parentheses as deeply as you want, so this rule is the same as the ones above:
  autobag
    INTO "weapons"
    WHERE ((((type is weapon))))
    CALL RULE "weapons to sell"
The total number of open-parens in your rule must be the same as the number of close-parens.

Parens become useful when you want to mix AND and OR in a complex rule.

Grouping Example
Let's pick a semi-useful rule as an example. Let's say you want to do the following:
  1. You want all your arrows of slaying to go into a quiver called "magic quiver".

  2. But you only want blessed and cursed magic arrows to go there.
    If they're cursed, you want them to go into "cursed quiver".

  3. All other arrows go into "quiver of holding".

Since magical arrows aren't (currently) marked as "magic", you need to match them by name. Let's say you're only interested in the following arrow types:
  1. arrow of slay demon
  2. arrow of slay dragon
  3. silver arrow
The most straightforward way to do this is with three rules:
  1. One rule that matches all uncursed/blessed slaying arrows, and puts them into "magic quiver".

  2. A second rule that matches all cursed slaying arrows, and puts them into "cursed quiver".

  3. A final rule that matches all other arrows, putting them in "quiver".
Here's what the rules look like:
  autobag
    INTO "magic quiver"
    WHERE 
      (name like "arrow" AND (name like "slaying" OR name like "silver"))
      AND item is not cursed
    CALL RULE "uncursed slaying arrows"
  Added rule 'uncursed slaying arrows' as rule #1
  autobag
    INTO "cursed quiver"
    WHERE 
      name like "arrow" AND (name like "slaying" OR name like "silver")
    CALL RULE "cursed slaying arrows"
  Added rule 'cursed slaying arrows' as rule #2
  autobag
    INTO "quiver"
    WHERE name like "arrow"
    CALL RULE "all other arrows"
  Added rule 'all other arrows' as rule #3
autobag list
Your autobag rules:
1. uncursed slaying arrows
2. cursed slaying arrows
3. all other arrows
These three rules meet the requirements we specified.

Simplifying Our Example
It turns out (and this isn't documented anywhere but here yet, but we'll try to fix that) that all weapons of slaying have a "slays" property. That means you can use this property in a property-match rule, so the three rules above can be simplified like so:
  autobag
    INTO "magic quiver"
    WHERE type is arrow AND item is slays AND item is not cursed
    CALL RULE "uncursed slaying arrows"
  Added rule 'uncursed slaying arrows' as rule #1
  autobag
    INTO "cursed quiver"
    WHERE type is arrow AND item is slays
    CALL RULE "cursed slaying arrows"
  Added rule 'cursed slaying arrows' as rule #2
  autobag
    INTO "quiver"
    WHERE name like "arrow"
    CALL RULE "all other arrows"
  Added rule 'all other arrows' as rule #3

Notice that you don't need parentheses if you're not mixing AND and OR in the same rule.

Not only are these rules simpler to read than the first three, they also cover any new types of slaying arrows that are added to the game, because they're matching on a property, not the item name.

Unfortunately, knowing which items have common properties that you can test for is impossible without asking a Wizard. If you are trying to do complex matching on object names, and you think you could use a new property to make your rule simpler, ask any Wizard to clone and examine the objects you're trying to match, to see if there are any props you can take advantage of.

If there aren't any, or no Wizards are available, feel free to mail Rhialto in the village post office. It's easy for us to add properties to objects, and this kind of suggestion is very welcome.

Final Notes about Rule Conditions

If you've read this far, you've learned a lot! By now you've mastered (or at least been introduced to) the techniques you need in order to write sophisticated autobagging rules.

Here are a few last things to keep in mind as you write your rules:

  1. Don't try to pack too much into a single rule. You can often achieve the same results by setting up a series of rules that check for more and more general cases.

  2. Prefer type and property matches to name matches. Name matches are slower than type and property matching. Name matching is also more error-prone. We sometimes change the names of objects in the game, and if you're matching an exact name, your rule may break when we change the object.

  3. Ask for help if you need it. The autobag minilanguage is very rich; it's similar (in miniature form) to SQL, which is used to query and administer databases. If you master the autobag language, you're well on your way to learning how to be a computer programmer!

The remaining sections are shorter, and cover the subcommands you'll use once you've created some autobag rules.

LIST subcommand

You can examine the rules you've created using the LIST subcommand. There are two flavors for this command:
    autobag list
and
    autobag list <number>
"autobag list" will produce a numbered list, showing you the names of the rules you've made. For example:
  Your autobag rules:
  1. cursed reagents
  2. uncursed dragon claws and hearts
  3. drop >50 sling stones
  4. tiny shields
If you type "autobag list" plus a rule number, it will show you the full description of that rule. Example:
autobag list 3
Autobag Rule: drop >50 sling stones
  Bags to add to: "drop item"
  Conditions:
    (name = "sling stones") AND (quantity > 50)

Canonical Form

When you write a rule, you have some choices you can make about how to use capitalization, quotes, parentheses, operators. Because the Autobag language tries to be fairly flexible, there are many ways to write any given rule.

For example, these two sets of conditions are exactly the same:

  name like dog or name == fish and item is not cursed
  (name LIKE "dog") OR ((name = "fish") AND (NOT item IS cursed))
When your rule conditions are printed out by "autobag list", they are printed in what's called "canonical form". This simply means that we make consistent choices about when to use quotes, parens, capitalization and so on. A rule in canonical form always looks the same.

Here are the choices we make in canonical form:

  • all keywords are uppercased (such as AND, OR, NOT, LIKE, IS, WHERE, ...)

  • parentheses are always shown for rules composed with AND and OR, so you don't have to remember the precedence

  • names always have quotes around them, except for property matches, since we currently think it's clearer not to have quotes for "ITEM IS unpaid". We may change our minds about this, but it won't affect your rules, just how they're printed out.

  • NOT is always moved in front of the rule, so "item is not cursed" becomes "NOT item IS cursed".

  • canonical form always uses '=' instead of the synonymous '==', and '!=' instead '<>'.
That's pretty much it for canonical form. There are only two reasons you need to know about canonical form:
  1. If if you don't write your rules in canonical form, you'll see them in canonical form with "autobag list <num>", which may be a bit surprising.

  2. If you're writing a rule and it just doesn't seem to be working, you might try writing it in canonical form, since it's clearer. You may find rule mistakes faster that way.

See the Hints section for more tips and information on debugging your rules.

RENAME subcommand

The names you give to your rules can be anything you like. The names are just reminders that tell you what the rule does. You can make your rule names up to 100 characters long.

If you decide to rename a rule, use the RENAME subcommand. The syntax is simple:

  autobag rename <number> <name>
For example, if your 6th rule is named "test", and you want to give it a better name now that you've debugged the rule, you might type:
  autobag rename 6 runes into rune bag
  Renamed "test" to "runes into rune bag".
You can have two rules with the same name, although we don't recommend it.

DELETE subcommand

Deleting a rule is simple:
  autobag delete <number>
Make absolutely certain that you are deleting the right number, since deleting a rule is permanent. We usually find it best to list out all our rules before doing a delete. Then, if you need a rule back, you can copy and paste its name and conditions from the server output window.

If you accidentally delete a rule you needed, you can always rewrite it.

ADJUST subcommand

Every time you pick up an object, your rules are evaluated in order. As soon as the Autobagger finds a rule that matches the object, it applies that rule. The rule can either succeed or fail. The rule is considered a success if it move the object into a bag.

If a rule matches but then fails, the Autobagger keeps evaluating more rules in your list, until finds a rule that succeeds, or it runs out of rules.

The consequence of all this is that the order that your rules appear is very important. If you have a rule that's too general early in your list, it may apply to objects you didn't expect it to.

Here's a simple example that should help illustrate:

autobag into "cloak of thieving" where type is magic call rule "magic items"
Added rule 'magic' as rule #1.

autobag into "reagent pouch" where type is reagent call rule "reagents"
Added rule 'reagents' as rule #2.

autobag list
Your autobag rules:
1. magic
2. reagents

autobag list 1
Autobag Rule: magic
  Bags to add to: "cloak of thieving"
  Conditions:
    TYPE IS "magic"

autobag list 2
Autobag Rule: reagents
  Bags to add to: "reagent pouch"
  Conditions:
    TYPE IS "reagent"
OK, it all looks good, right? When you pick up reagents, they go into your reagent pouch, and all other magic items go into your Thieves' Cloak.

Unfortunately, this set of rules doesn't work that way. The problem is that reagents are (or can be) marked as "magic", so the first rule will kick in before the second rule ever gets a chance. Any reagents that are marked by the game as "magic" will get stuffed into your cloak, using the rules above.

The solution: just adjust rule 2 into spot 1:

autobag adjust 2 1
Rule 2 adjusted to position 1.
Your autobag rules:
1. reagents
2. magic
This is similar to the way the adjust command works for moving things in your inventory. If you specify a destination number that's 0 or negative, it always moves the rule to the first spot. If the destination number is beyond the end of the list, it moves the rule to the end of the list.

Hints

When you're writing autobag rules, it's easy to make a typo. Typos fall into two categories:
  1. Typos that make that autobag system unhappy. It will spit out error messages at you.

  2. Typos that cause otherwise well-formed rules to do something different from what you intended. These are harder to find!

For example, while I was writing the system, I spent over an hour tracking what I thought was a bug, only to discover that my rule was broken. I had written:

  autobag
    INTO "backback"
    WHERE name LIKE "sword"
    CALL RULE "sword testing"
Can you spot what's wrong with this rule? I typed "backpack" wrong. The autobag system was looking for a bag in my inventory called "backback", and of course I didn't have one, so it just didn't autobag my swords.

The moral of the story is: review your rules carefully, since they can do unexpected things (or nothing at all!)

Error Messages

The error messages emitted by the Autobag system are not currently very intuitive. For example, let's say you enter a rule, but you forget to use CALL RULE to give it a name. Here's what you'll see:
autobag into backpack where type is magic
You have a syntax error in your rule:
Encountered "<EOF>" at line 1, column 33.
Was expecting one of:
    "or" ...
    "and" ...
    "call" ...
We're working on making better error messages. In the meantime, we'll describe what common ones you might see, to help you debug your rules.

The error above says that it encountered <EOF> but was expecting "or", "and", or "call". That means it was parsing your rule definition, and it got to the end ("EOF" means End Of File), and was still waiting for some more input.

In this case, there are actually three possible keywords you could have typed. The last thing in the rule is type is magic, so you could have put an AND or an OR there to continue the conditions, or a CALL RULE there to finish the conditions and name the rule. So it was expecting "or", "and", or "call". Make sense?

If you look at the second line of the error message, it says "line 1, column 33". This can be helpful information. The line number will always be line 1, since you enter the entire rule on one line. But the column number is how many characters into the rule definition it got before it puked. If you trace along what you typed, counting characters until you get to that column, you'll see where your mistake is located.

Let's look at another error message. If we type in the rule:

autobag into blah
You have a syntax error in your rule:
Encountered "<EOF>" at line 1, column 9.
Was expecting one of:
    "where" ...
    "," ...
Once again, it's telling us exactly what went wrong, just a bit cryptically. It got to EOF (the end of the rule), 9 characters into it, and was expecting you to type WHERE (for conditions), or "," (for more bag names).

The weirdest error messages are when you forget to type in a bag name, property name, or other string. For example, if we type "autobag into where", it was expecting a bag name between the "INTO" and the "WHERE", and gives a weird message:

autobag into where
You have a syntax error in your rule:
Encountered "where" at line 1, column 6.
Was expecting one of:
    <STRING_LITERAL> ...
    <TYPE_LITERAL> ...
All you really have to know is that <STRING_LITERAL> is a string with double-quotes around it, and <TYPE_LITERAL> is a string without double quotes. This error message just means you forgot a name at that position.

Someday we'll try to improve the error messages, but in the meantime, hopefully this is enough to get you started. Again, if you have a lot of trouble with a particular rule, make sure you mail Rhialto at your local post office, and give as much detail as you can.

Autobag Todo List

Here's a partial list of features we'd like to add to the Autobag system:
  1. The ability to temporarily disable and re-enable rules.

    For instance, if you're walking through an area that has a bunch of reagents that you don't want to pick up, but you DO want to pick up other items, it'd be nice to disable some of your rules for a while.

    You can always work around it by turning autograb off.

  2. The ability to "borrow" autobag rules from other players. Some players may have autobag rules that you want to use, and it would be convenient to have an "autobag borrow" subcommand that lets you use a rule from another player.

    You can always ask the player to do an "autobag list <num>" and send you the rule conditions.

  3. Getting rid of Coin Purses.

    Coin purses are useful — when you pick up coins, they automatically go into your coin purse. However, they use a low-level game mechanism that requires you to drop the coin purse on the ground to get coins out of it.

    Fortunately, buying and selling automatically uses your coin purse money, so you should rarely need to get coins out of your coin purse.

  4. Adding new triggers for rules.

    Your autobag rules are only evaluated when you pick up an item, or get an item out of a container on the ground. It would be nice to extend the minilanguage to allow you to say "WHEN" <some trigger>, for example "WHEN given", so when people give you things, they get autobagged automatically.

    For now, you have to drop something and pick it up again to get it autobagged, if it entered your inventory in some way other than picking it up.

  5. Better error messages.

    As we described in the Error Messages section, the error messages tell you what's wrong, but in a fairly hard-to-read format. It's possible to use the parser to give better error messaging. We'll do this if people are getting really confused over the current error messages.

  6. Auto-selling

    This isn't part of autobagging per se, but it would be a nice feature to be able to say "sell all from bag X".

I'm sure you can think of other features you'd like to see. If you have any good ideas, send them in!

Suggestions

The Autobag mini-language is designed to make your Wyvern game-playing experience simpler and more effective. We will continue to add inventory-management features to the game, to minimize the amount of work you have to do in keeping track of all your stuff.

If you have a rule that isn't working, first try rewriting it in a different form. If that doesn't work, talk to a Wizard or HoFer, and see if they can give you suggestions on how to make it work. If your rule still doesn't seem to work, it may be a bug in the autobag system. If you find a bug, email Rhialto at the village post office, and let him know which character and rule name are having trouble.

If you like the Autobag system, and there's a particular feature that you really wish it had, feel free to mail Rhialto and let him know. Some features may be easy to add, and some may be very hard, but he'll be happy to consider any suggestions that you come up with.

Enjoy!

<< Previous Chapter Next Chapter >>