AODB.ResourceTool 0.9.3.0 BETA ReadMe -- Sept. 19th 2004

Recent Updates

• Fixed a bug causing parsing not to work on some european locales

• Modified PatchAdded/PatchUpdated version ID output--output is now done with double-digit precision on all values (i.e. 15.5.1 -> 15.0501)
• Added support for new nano Flag lookup values, AODB.Lookup.NanoFlagName function added
• Added Inheritable/Overridable AODB.Default_Plugins.Null plugin class to make basic plugin-building a bit easier
• Added 'Perk Definition' output option to the 'Export RDB Data' tab (Exports a list of PerkIDs to ItemIDs, and also perk level/parent progression data)
• Rebuilt AODB.Default_Plugins.ListNames to be .ListItems; added ItemType, QL, and a few other outputs (New version also inherits from .Null, so source of .ListItems code is a good exmaple for this process)
• Updated AODB.Lookup class to support newer and a few previously unknown lookup values
• Updated AODB.Lookup class with a few more accurate labels for previously labeled stats and actions. 'UniversalAdvantage' has become 'ScalingModify' and 'OnNanoTerminate' has become simply 'OnTerminate'
• Updated parser core to support some newer functions
• Updated source/aomf_storedprocs.sql file to include two missing user-defined functions
• Fixed a few minor parser/interface bugs

• Added support for transparant GIF extraction of Icons, fixed a few minor display bugs.

About

AODB.ResourceTool was created to provide easy access for coders wanting to utilize data from the Anarchy Online ResourceDatabase file. The application contains a parser core, which performs all the parse logic, as well as an interface for passing data from the parser core to any given plugin assembly. The parser (AODB.Parser) is a seperate entity from the AODB.ResourceTool, however they are designed to work together to provide an easy to use front-end for your plugins and other related functionality.

Feel free to develop plugins for use with the tool, and if you believe you have come up with something which would be of good use to the community, I would be happy to include it in future default installs.

Please note, this is a BETA version of the tool, and while fully-functional some things may need tweaking or be tweaked before the final release. I will avoid changing the plugin interface contract if at all possible between now and release, but there may be minor tweaks before the 1.0 version.

AODB.ResourceTool requires the .Net Framework to be installed on the machine to run. If you do not yet have it installed, it can be obtained through Windows Update. While there are projects (such as Mono) which allow the usage of .Net on non-Windows platforms, your experience using the tool on them may vary. Only core objects were used during the development of the tool, so it is quite possible such approaches would work--but they are currently not supported at this time during the BETA phase.

This tool is copyright its author, and freely licensed for any non-commercial usage. Commercial usage is prohibited without written consent from the author. While the author maintains that, to the best of his knowledge, the files contained in this package do not contain any malicious code, nor will they cause any damage to your computer, computer-related oddities are known to happen. Use at own risk.

Instructions

AODB.ResourceTool has two primary functions: a) To extract ResourceDatabase data in its raw form and b) To parse raw itemdata and pass this parsed data through the plugin interface system. To parse data, you must first extract itemdata via the extraction functionality. The extraction functionality may also be used to extract other types of data, such as Icons and Textures.

To extract raw ItemData, Icons, or Textures:

1. Click on 'Extract RDB Data' tab
2. Specify your AO root folder of choice for the 'Input' field--the AO version ID will display under 'Selected Version' when a valid folder has been selected.
3. Specify the folder you would like to extract data to for the 'Output' field--all Item/Nano data will be stored in the root of that folder labeled by version, and all Texture/Icon data will be stored in a subfolder of this folder labeled by version.
4. Select the type of data you would like to extract via the pull-down menu
5. Click the 'Do Extract!' button

Depending on the speed of your PC, this process may take some time, as CTree can be rather sluggish at times. A pop-up alert will inform you on the completion of this process.

To parse ItemData and process with a plugin:

1. Select a Plugin
   1. Click on the 'Select/Import Plugins' tab
   2. If this is your first time running the tool, or you have added a plugin, click the 'Rescan Plugins' button
   3. Click on the list of available plugins to select which to use during your next parse
2. Parse with Selected Plugin
   1. Click on the 'Quick Start' tab (will be replaced with the 'Parse/Output Data' tab in final release version)
   2. Your current plugin will be displayed on this panel
   3. Specify the source folder containing your extracted ItemData as the 'Input' field--this will probably be the same as the 'Output' folder selected during the extract phase.
   4. Specify the folder you would like to direct plugin output to--note that not all plugins may utilize output, although most will.
   5. Upon selecting an 'Input' folder containing valid ItemData, the drop-down menus will populate with every extracted version currently available in that folder. The drop-downs are used in the following capacity: Left drop-down is the 'Previous' version, and is optional..when a previous version is selected, a checksum comparison will be performed between the 'Previous' and 'New' version and *only* modified/added items will be sent to the parser. Select 'No Comparison' if you wish to output all data. The right drop-down is the 'New' version, and will be the file from which the data is based on.
   6. Uncheck the 'Items?' or 'Nanos?' checkboxes if you do not wish to output one of those data types.
   7. Click 'Do Parse!' button

There are a few 'default' plugins included with this version of AODB.Resource tool within the AODB.Plugin_Default assembly. Currently these are:
1) AODB.Plugin_Default.ListNames -Comma-separated list of ID/Name for all items
2) AODB.Plugin_Default.Mainframe_Output -Plugin used to generate data for aodb.info SQL import
3) AODB.Plugin_Default.XMLOutput -XML-based output for all items

There are likely to be a few more default plugins added before the tool is released in final form. You are free to develop your own plugins, please see below for information on how to do so.

Those are the basics to operating the tool--fairly straightforward, and hopefully rather painless. As noted in the About section, this is the BETA version of the tool, and this process is subject to modification. Any suggestions or issue reports are certainly welcome.

Plugin Development

Developing a plugin for use with AODB.ResourceTool should be fairly painless for anyone with a bit of .Net Framework development experience. The plugins are based on an Inferface defined within the parser assembly (AODB.dll) within the AODB namespace. This interface is currently defined as:

  Public Interface PluginInterface
        Property GLOBAL_ItemEquipmentPage() As Long
        Property GLOBAL_IsNano() As Boolean
        Property GLOBAL_CurrentVersion() As Double
        Property GLOBAL_CurrentFile() As String
        Property GLOBAL_OutputPath() As String
        Property GLOBAL_ItemQL() As Long
        Property GLOBAL_ItemStrain() As Long
        Property GLOBAL_ItemNCUCost() As Long
        Property GLOBAL_ItemStacking() As Long
        Property GLOBAL_DefaultPosVal() As Long
        Property GLOBAL_PlacementVal() As Long
        Property GLOBAL_ItemSlot() As String
        Property GLOBAL_ItemPage() As String
        Property GLOBAL_ItemType() As String
        Property GLOBAL_HasDefaultPos() As Boolean
        Property GLOBAL_HasPlacement() As Boolean
        Property GLOBAL_IsTower() As Boolean

        Sub Insert_Init()
        Sub Insert_Close()
        Sub InsertItem_Init(ByVal ItemID As Long, ByVal CurrentPos As Long, ByVal TotalPos As Long)
        Sub InsertItem(ByVal ItemID As Long, ByVal IsNano As Boolean, ByVal ItemName As String, _
            ByVal Description As String, ByVal ItemQL As Long, ByVal ItemType As String)
        Sub InsertItem_Close(ByVal ItemID As Long, ByVal IsNano As Boolean, ByVal ItemName As String, _
            ByVal Description As String, ByVal ItemQL As Long, ByVal ItemType As String)
        Sub InsertNano_Init(ByVal ItemID As Long, ByVal CurrentPos As Long, ByVal TotalPos As Long)
        Sub InsertNano(ByVal ItemID As Long, ByVal IsNano As Boolean, ByVal ItemName As String, _
            ByVal Description As String, ByVal ItemStrain As Long, ByVal ItemStacking As Long, _
            ByVal ItemNCUCost As Long)
        Sub InsertNano_Close(ByVal ItemID As Long, ByVal IsNano As Boolean, ByVal ItemName As String, _
            ByVal Description As String, ByVal ItemStrain As Long, ByVal ItemStacking As Long, _
            ByVal ItemNCUCost As Long)
        Sub InsertAttribute(ByVal ItemID As Long, ByVal AttrNum As Long, ByVal AttrValue As Long)
        Sub InsertAttackVal(ByVal ItemID As Long, ByVal AttrNum As Long, ByVal AttrValue As Long)
        Sub InsertDefVal(ByVal ItemID As Long, ByVal AttrNum As Long, ByVal AttrValue As Long)
        Sub InsertAction(ByVal ItemID As Long, ByVal ActionNum As Long)
        Sub InsertActionReq(ByVal ItemID As Long, ByVal AttrNum As Long, ByVal AttrOp As Long, _
            ByVal AttrValue As Long, ByVal ReqTarget As Long, ByVal ChildOp As String)
        Sub InsertOnEvent(ByVal ItemID As Long, ByVal EventNum As Long)
        Sub InsertFunction(ByVal ItemID As Long, ByVal FuncName As String, ByVal FuncTarget As String, _
            ByVal DOTCount As Long, ByVal DOTInterval As Long)
        Sub InsertFunctionReq(ByVal ItemID As Long, ByVal AttrNum As Long, ByVal AttrOp As Long, _
            ByVal AttrValue As Long, ByVal ReqTarget As Long, ByVal ChildOp As String)
        Sub InsertNumArg(ByVal ItemID As Long, ByVal NumValue As Long)
        Sub InsertStrArg(ByVal ItemID As Long, ByVal StrValue As String)
        Sub InsertAnim(ByVal ItemID As Long, ByVal ActionNum As Long, ByVal AnimNum As Long)
        Sub InsertSound(ByVal ItemID As Long, ByVal ActionNum As Long, ByVal SoundNum As Long)
        Sub InsertUpdateNote(ByVal itemid As Long, ByVal itemname As String, ByVal updatetype As String)
        Sub OutputDebugMessage(ByVal message As String)
  End Interface

Utilizing this interface will probably require you to reference the AODB(.dll) namespace from within your assembly. Working source code examples of the ListNames and XMLOutput plugins can be found in the Source\ folder of this archive. These examples should give you a very easy template to work off of to create working plugin assemblies.

Once a plugin has been developed, simply drop it in the Plugins\ folder and it will show up when you 'Rescan Plugins' if it follows the interface guidelines. Any class which does not conform to the interface will be ignored.

For plugin development, the order of called subs are as follows:
*denotes that it may be called multiple times in a row within a loop

Insert_Init InsertUpdateNote* InsertItem_Init -or- InsertNano_Init InsertAttribute* InsertItem -or- InsertNano InsertAttackVal* InsertDefVal* InsertAction* InsertActionReq* InsertOnEvent* InsertFunction* InsertFunctionReq* InsertNumArg* InsertStrArg* InsertAnim* InsertSound* InsertItem_Close -or- InsertNano_Close Insert_Close

-Parser Initialization -Output from updated/new comparison check -Item begin -Item Attributes (Mass, Value, QL, etc.) -Additional Item Data -Atk. Skill entries -Def. Skill entries -Item Actions (ToUse, ToWield, etc.) -Requirements for Action -Events (OnUse, OnWear, etc.) -Function trigger requirements -Function argument (numeric) -Function argument (text) -Item Action->Animation triggers -Item Action->Sound triggers -Item end -Parser close and cleanup

For plugin development, the function of the public properties are as follows:

GLOBAL_ItemEquipmentPage() As Long GLOBAL_IsNano() As Boolean GLOBAL_CurrentVersion() As Double GLOBAL_CurrentFile() As String GLOBAL_OutputPath() As String GLOBAL_ItemQL() As Long GLOBAL_ItemStrain() As Long GLOBAL_ItemNCUCost() As Long GLOBAL_ItemStacking() As Long GLOBAL_DefaultPosVal() As Long GLOBAL_PlacementVal() As Long GLOBAL_ItemSlot() As String GLOBAL_ItemPage() As String GLOBAL_ItemType() As String GLOBAL_HasDefaultPos() As Boolean GLOBAL_HasPlacement() GLOBAL_IsTower() As Boolean

-Attribute, 0:None, 1:Weapon, 2:Armor, 3:Implant, 4:NPC, 5:Spirit2) -Was parse triggered by InsertItem (0) or InsertNano (1) -Current version ID sent from AODB.ResourceTool -Current output versionid as string (i.e. "15.03.00.01") -Current output path (i.e. "c:\aodb.resourcetool\output") -Attribute, Quality Level of item -Attrinute, Nanoline of nano -Attribute, NCUCost of nano -Attribute, StackingOrder of nano -Attribute, DefaultPos of item -Attribute, Placement bitfield of item -Attribute, Comma-seperated, string translated version of PlacementVal -Attribute, String translated version of ItemEquipmentPage -Indexed value based on logic block -DefaultPos attribute present? -Placement attribute present? -Was parse triggered by a Tower item?

Some of these properties are rarely used by plugins, however many are referenced by the parser core for minor logic blocks which alter the method of processing used. As a side-effect of this, some may be handy for occasional plugin functionality--although you may end up ignoring most and/or building your own index values. These values are re-initialized from within the parser core automatically before every InsertItem_Init/InsertNano_Init call.

NOTE: While the author asserts that, to the best of his knowledge, the compiled code contained within this distribution contains no malicious code, plugins are not scanned, verified, or limited in any way before execution. Do not run plugins obtained from a party you do not trust to provide you with safe code. All plugins included in the default install will be personally verified, however the functionality of 3rd-party plugins are the exclusive responsibility of their author.

For more plugin-related questions/feedback, please e-mail me at jayde@aodb.info. Please consult the example plugin source files before requesting assistance on getting a new plugin developed.

Using AODB.Utilities

Another assembly included in this package is the AODB.Utilities.dll, which is utilized heavily in both the parser core and most plugins. This assembly provides some very useful classes for performing lookups and other common functions. More features may be added to this before final release.

AODB.Utilities.CTree
-Ctree extraction interface routines... Documentation in progress...

AODB.Utilities.Misc
-Various misc function, currently only contains:

  Public Function CheckBit(ByVal InputValue As Long, ByVal Position As Integer) As Boolean
	Takes input bitfield and bit position as parameters, returns boolean value
	if the current bit is set

AODB.Utilities.Lookup
-Numeric->Textual lookup conversions--reverse functions will be available next versions

  Public Function ActionName(ByVal ActionNum As Long) As String
	Action numbers (ToUse, ToWear, etc.)
  Public Function AttributeName(ByVal AttrNum As Integer) As String
	Attributes/Statistics (MaxHealth, Pistol, etc.)
  Public Function AttributeValue(ByVal AttrNum As Long, ByVal AttrValue As Long) As String
	Second-level attribute reference lookup..used for stats in which values reference 
	other stats. Currently for AttrNum as:
	76 (EquipmentPage)
	339, 436, 440 (DamageType, InitiativeType)
	60, 368 (Profession, VisualProfession)
	4, 367 (Breed, VisualBreed)
	59, 369 (Sex, VisualSex)
	33, 213 (Side, TeamSide)
	405 (School)
	251 (PetCounter)
	471, 472 (MapsA, MapsB)
	47 (Fatness)
	470 (MapOptions)
	224 (Features)
  Public Function CanFlagName(ByVal Pos As Integer) As String
	Can Flags by position (Carry, Wear, etc.)
  Public Function FlagName(ByVal Pos As Integer) As String
	Flags by position (VisibleFlag, ModifiedDescription, etc.)
  Public Function FuncName(ByVal FuncNum As System.Int32) As String
	Function names (Modify, Set, etc.)
  Public Function OnName(ByVal EventNum As Long) As String
	Event names (OnUse, OnWear, etc.)
  Public Function OpName(ByVal OpNum As Long) As String
	Operator names (Equal To, Less Than, etc.)
  Public Function PlacementArmorFlagName(ByVal Pos As Integer) As String
	Armor placement slots by position (Neck, Chest, etc.)
  Public Function PlacementImplantFlagName(ByVal Pos As Integer) As String
	Implant placement slots by position (Eye, Ear, etc.)
  Public Function PlacementWeaponFlagName(ByVal Pos As Integer) As String
	Weapon/Utility placement slots by position (HUD1, UTIL1, etc.)
  Public Function TargetName(ByVal TargNum As Long) As String
	Target names (Self, FightingTarget, etc.)

You may find uses for this assembly outside the context of plugins, and are free to use it as such. It is recommended to reference this assembly within your plugins if you wish to lookup any numeric values. Note that currently some values are already looked up by the parser, although I may change this to be 100% plugin-based before release.

I plan to add extended playfield numeric lookups as well as nanoline lookups to the final version of the AODB.Utilities.Lookup class...these will likely make it into the 1.0 release.

Additional Info

Additional information regarding this tool will be added as the versions progress. If you have any questions or suggestions as to other information to contain in this document, please contact me.

FAQs

Q: Who developed this tool?
A: The tool was developed from the ground-up in .Net by myself (Jayde), and based on my previous parser core as described at the URL: http://aodb.info/about.asp. The main CTree interface code was contributed by Timber and later modified for additional functionality.

Q: Why develop the tool?
A: Many people seem to be looking for a fairly easy way to extract this or that without having access to a large database setup, or wanting to rewrite or adapt a parser core from scratch. This tool tries to do most of the hard work while leaving the data manipulation to the user.

Q: Am I free to develop plugins and use them however I wish?
A: Absolutely. That's what this tool is for! The one caveat is, however, that this version of the tool is not licensed for any commercial or business use. If you wish to use it for non-personal projects, please contact me to discuss your needs.

Q: Is the source code available?
A: Not right now. While I am currently planning to provide source to plugins, I am not releasing the core parser or application code at this moment. The parser rarely needs to be updated, and I would rather handle modifications personally. In order to provide a stable platform for plugin development, I would rather not have modified versions of the application floating around potentially causing problems. The good news is, however, that plugins are free to do whatever they want with the data passed to them. If I ever choose to discontinue development of the tool, however, the source will be released.

Q: The tool crashes, what should I do?
A: Please report any incidents to me so I can look into it. Before contacting me, please confirm if it is the plugin you are using which is causing the problem. (i.e. does something like AODB.Plugin_Default.ListNames work with the same settings, but yours does not?) The current version of the tool has error-handling to gracefully not crash if a plugin fails, however I will be providing a developers-only version which outputs more detailed exception error messages soon.