AoCEQ

A Proxying Equipment Database for Age of Chaos

Copyright © 2004, 2010 Shadrach (Eglin, Dibzahab, etc)

[Quick Start] [Abstract] [Installation] [Advanced Usage] [Troubleshooting and Debugging]

Quick Start

Double-click AoCEQ.exe to launch the application. Connect to localhost or 127.0.0.1, port 4000. Use the item [shortname] command to view an item's details, i.e.: "item claws panther" Use the details [shortname] command to view a familiar and detailed item listing, i.e.: "details claws panther" Use the pops [longname] command to view an item's source, i.e.: "pops the panther claws" Use the loads [mobname] command to find out what a given mob may drop, i.e.: "loads the black panther"

If AoCEQ's clipboard option is enabled, the last query's results will be placed into the clipboard so that they can be easily shared or logged (ctrl+v works well for pasting in most CUA applications).

If you use a MUD client that supports MXP, try right-clicking the wheel in the taskbar, choosing settings, and enabling MXP.

If you already have aliases setup for commands of the same name, you may change the AoCEQ command-names using the settings dialog in order to avert conflict.

Abstract

Having access to comprehensive and accessible game data makes playing Age of Chaos more fun. This application integrates a sizable equipment database into an existing play environment. At its most basic level, it provides a trivial means of querying for item statistics. With more advanced usage, it is possible to issue and process complex queries involving item properties and origins.

Installation

AoCEQ is a "standalone" executable. Aside from utility built into modern Windows operating systems, it has no external dependencies. This means that it can be executed from any location that the operating system has access to, be it thumb-drive, website, network share, temporary file storage, or other location without the need for a formal installation process. Configuration settings are stored in the current-user section of the system registry if it is writable by the current user as a convenience, but the program should still function just fine on a totally locked-down system.

To use the program, simply execute AoCEQ.exe. Upon execution, a small rotating wheel/globe should appear in the system notification area near the time display on the taskbar. The rotation indicates that the program is waiting for a connection. Hovering the mouse cursor over the icon should present a popup indicating the status of the application. Because the application acts as a proxy between the user's MUD client and the Age of Chaos game, it will need to be able to accept connections from local clients and initiate connections to the Age of Chaos server. Personal firewalls, such as Zone Alarm, will need to be instructed to allow such communication - if you are prompted by your firewall during this time, please take a moment to ensure that appropriate settings are chosen. By default, the AoCEQ application will act as a server on port 4000, the same port that Age of Chaos listens on. If another application, such as a personal MUD server or another proxy is already using this port, alternatives may be chosen by right-clicking the rotating globe and choosing settings from the popup window.

Advanced Usage

Internally, AoCEQ stores information in three table-like structures. This data can be extracted using queries modeled after the SQL (Structured Command Language). By default, the "qeq" command is used to issue queries. However, it is necessary to have some understanding of the way the tables are structured to make effective use of this command. Below are figures summarizing the internal table data formats:

	Table: EQ
Field Name	Field Type	Description
Name	Character String	This is the item's short name, as seen in the title when identified in-game using a scroll.
Damage	Character String	This is an item's damage dice - i.e., "4d6". Not to be confused with the "Dam" field, which refers to bonus damage, i.e. +3 dam.
Armor	Scalar Integer	This refers to bonus armor, i.e., what you might find on a robe or necklace versus the base protection offered by a breastplate.
AC	Scalar Integer	This is an item's ACAP (Armor Capacity to Apply). Not to be confused with the "Armor" field, which refers to bonus armor, i.e. -7 AC.
Kind	Character String	This field mimics AoC's "Item Type" field, i.e. "armor", "wand", etc.
Wear	Character String	This field refers to the slot in which an item may be equipped.
Dam, Hit, Weight, Weight, Moves, Value, HP, Mana, Age, Str, Con, Wis, Int, Cha, Dex, PEarth, PAir, PFire, PWater, PSpirit, MEarth, MAir, MFire, MWater, MSpirit, Charges, Castlevel, Perc_cast	Scalar Integer	These numeric fields mirror the in-game equivalents.
Anticlass	Character String	A comma separated list of character classes and/or races who cannot equip this item.
Antialignment	Character String	A comma separated list of character alignments who cannot equip this item.
Affects	Character String	A list of affects granted by the item.
Spells	Character String	A list of spells that the item can cast.
Flags	Character String	A list of flags the item has, mirroring in-game - i.e., "magic", "glow", etc.

	Table: Pops
Field Name	Field Type	Description
Who	Character String	A mob's name.
What	Character String	An item's long-name.

	Table: Namemap
Field Name	Field Type	Description
Shortname	Character String	An item's short-name.
Longname	Character String	An item's long-name.

Armed with this data and a working knowledge of SQL, we can make use of the powerful "qeq" command. The "qeq" command can be considered shorthand for the SQL fragment "SELECT name FROM eq ". Thus, "qeq where name like '%burn%'" translates into the SQL query, "SELECT name FROM eq WHERE name LIKE '%burn%'". Executing this command will, as one might guess, return a list of all equipment in the database that features the word-fragment burn anywhere in the name - i.e., 2 items: burnished bronze headband, iron breastplate plate burnished. The best way to illustrate its usefulness is probably through example, so below are some examples.

What I want

What I type

What I get

Show me all the chest pieces that a barbarian can use.

qeq where wear='body' and anticlass not like '%barb%'

"82 items: armor bone wood carved suit, armor death, ..."

Show me all the chest pieces that a barbarian can use sorted by their ACAP.

qeq where wear='body' and anticlass not like '%barb%' order by ac desc

"82 items: armor sigmar, shining steel breastplate plate..."

Show me all the enchantable chest pieces that a barbarian can use sorted by their ACAP.

qeq where wear='body' and anticlass not like '%barb%' and flags = 'nobits' order by ac desc

"51 items: plate adamantine breastplate breast, silver breastplate ancient,..."

Show me all the rings an evil mage can wear that have both mfire and mspirit.

qeq where wear='finger' and mfire > 0 and mspirit > 0 and anticlass not like '%mage%' and antialignment not like '%evil%'

"ring maggot infested rotting roses - +4mfire -2mwater +4mspirit +ProtGood - Usable by: evil or nuetral arti, cc, mu, oc"

Show me all the weapons that proc desecrate, ordered by the proc frequency.

qeq where kind='weapon' and spells like '%desec%' order by perc_cast desc

"4 items: silver scythe silvery, onyx hammer bloody ssinssrigg'del elgg, blackened short sword stone-wrought gorgon's groom, ornate arrow runes dark"

Show me all the featherfall gear a goodie warrior can wear.

qeq where affects like '%fall%' and antialignment not like '%good%' and anticlass not like '%war%'

"16 items: black marble ring, black robe shimmering doomlord balrog skin..."

Show me 2 items that are flagged "dark."

qeq where flags like '%dark%' limit 2

"187 items: a black mithril stiletto, accursed sword greatsword fireblade"

Show me pearth robes.

qeq where pearth > 0 and wear='about'

2 items: robe kabaa, tabor drum instrument leather sling feathered eagle

Understanding the remaining tables and the load/pop functionality requires a bit of background information. As a player of AoC, I was unable to access the game data directly. The equipment information within this program was primarily captured by parsing an awful lot of auctions, identify spells and scrolls. The game identifies each item this way using a SHORT_NAME. The information describing who loads what was gathered primarily by parsing lines of text from the MUD of the form, "X loots LONG_ITEMNAME from MOBNAME." Unfortunately, this method of gathering information is problematic because automated filtering of tweaks and mapping of short-names to and from long-names is non-trivial. The most grievous errors that the program will produce are therefore related to the pops/loads functionality. It can also be quite confusing to get the stats for an item you've found that doesn't have a unique and obvious keyword to search for. As an example, consider finding a "beautiful forest green cloak" in the game. The first attempt to query for the item would naturally be "qeq forest", which would give you at least six results containing at least two cloaks. Although one can often simply equip the cloak and examine stat changes to determine which of the results is correct, the ambiguity is not always relegated to items held in-hand. As such, issuing queries across the namemap table becomes useful. We can query according to the longname (assuming it has been captured) with a query constructed thusly: "qeq where name=(select shortname from namemap where longname='a beautiful forest green cloak')" which gives the unique and desired result.

The most frequent request I get from folks who have used this program in the past is to add functionality to add or modify data records. Formerly, the data was pulled directly from the database that ran the stabbing.us backend. Because it could be pulled directly from the database in an automated fashion, the avoidance of formatting errors and so forth was assured. As such, my overwhelming preference was to modify the website and filter the changes down through the proxy. Now that the website is no more, however, it seems worthwhile to have some way to update the program. Ideally, the program would directly consume records from whatever sort of format the user had them in, be it MS Excel, a zMud database, or just a text file with a bunch of random notes. We're going to have to settle for the next best thing - a simple flat-file database of comma-delimited new-line separated records. In the case of ambiguity between internal data and values provided by the user, the user's data will be given priority with the internal data being discarded. In the case of ambiguity between entries in the user-data, such as duplicates, the first record will be given priority and subsequent entries will be discarded. The file containing user data should be formatted as follows (refer to the table descriptions above for more detail on each field):

A line for each piece of equipment containing the following comma-separated fields. The order is important, the string values for name, kind, wear, spells, antialignment, and anticlass must not be empty, strings must be enclosed in single-quotes, and strings containing apostrophes must be adjusted so that the apostrophe is doubled - i.e., ' becomes ''.

name, damage, dam, hit, armor, ac, kind, wear, weight, value, hp, mana, age, str, con, wis, int, cha, dex, pearth, pair, pfire, pwater, pspirit, mearth, mair, mfire, mwater, mspirit, moves, charges, castlevel, affects, spells, perc_cast, antialignment, flags, anticlass

An example:

'blackened short sword stone-wrought gorgon''s groom', '2D3', 3, 0, 0, 0, 'weapon', 'wield', 18, 17500, 0, 0, 0, 0, 0, 0, 0, -3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 'NONE', 'desecrate', 4, '!good,!neutral', 'dark,magic', 'artificer,barbarian,bard,chaos cleric,druid,magic user,monk,order cleric,paladin,ranger,thief,warrior'

Although the formatting in this document may not reflect it, the above example should be contained entirely within one line of text.

Following a series of such lines should be a line containing the single word, "NAMEMAP" - case being significant.

After the NAMEMAP, the file should have a series of lines consisting of shortname,longname pairs. Neither string should be empty, and the same rules for escaping apostrophes hold.

'blackened short sword stone-wrought gorgon''s groom', 'a blackened, stone-wrought short sword, ''The Gorgon''s Groom'''

Following a series of such lines should be a line containing the single word, "POPS" - case being significant.

After the POPS, the file should have a series of lines consisting of who,what pairs.

'Qithazria the Medusa', 'a blackened, stone-wrought short sword, ''The Gorgon''s Groom'''

Finally, the last line in the file should contain the word "END" on a line by itself.

Thus, barring word-wrap artifacts, a complete and correct data file might look like the following:

'blackened short sword stone-wrought gorgon''s groom', '2D3', 3, 0, 0, 0, 'weapon', 'wield', 18, 17500, 0, 0, 0, 0, 0, 0, 0, -3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 'NONE', 'desecrate', 4, '!good,!neutral', 'dark,magic', 'artificer,barbarian,bard,chaos cleric,druid,magic user,monk,order cleric,paladin,ranger,thief,warrior'

NAMEMAP
'blackened short sword stone-wrought gorgon''s groom', 'a blackened, stone-wrought short sword, ''The Gorgon''s Groom'''
POPS
'Qithazria the Medusa', 'a blackened, stone-wrought short sword, ''The Gorgon''s Groom'''
END

Such a file saved in AoCEQ's working directory with the name "aoceq.csv" will be loaded and used by AoCEQ without incident. Files edited on UNIX may need to be passed through sed or unix2dos to convert from cr to cr/lf formatting. Be warned, however, that proper formatting is essential and that AoCEQ will not give detailed error messages for malformed input - honestly, this functionality is an afterthought implemented by request rather than a design goal. Your mileage may vary. If you are successful, however, please do share your efforts with others!

Troubleshooting and Debugging

Troubleshooting the program can largely be done via changes keys in the registry. The program stores configuration data in HKEY_CURRENT_USER\Software\AoC EQ Proxy. These values can be modified easily using the "regedit" program that ships with Windows. If keys named "host name" (string) and/or "host port" (dword) are defined, AoCEQ will use those values to connect to Age of Chaos instead of the default of pandapub.com:4000. This can be useful for logging into the test server or for the case that a user, such as myself, uses multiple proxies chained together (I have one for mapping, one for equipment, one for triggers, etc.). Creating a key titled "masslog" (dword) with a value of one should cause AoCEQ to produce a file titled aoceq.log and a file titled masslog.log in its working directory. The aoceq.log file presents the results of some basic sanity checks such as connections being made, the database being populated, etc. The masslog.log file is more like a constant dump of the exchange between the MUD and the game client. The usefulness of these files to anyone without knowledge of AoCEQ code is dubious, but in the absence of any other avenues of support may be worth considering. The masslog.log file might also be useful to someone wishing for a transcript of their game session using a client that does not support logging (i.e., MS DOS telnet), although the file will contain raw ANSI control codes from the MUD and various interjections by AoCEQ. Your mileage may vary.