User:Jifodus/Dwarf Fortress Utility Framework

I'm currently writing a framework for Dwarf Fortress utilities. The general idea is to use C++ interfaces in a cross-compiler fashion that is very easy to use.

Please note, since this is still currently under development, I don't have the time to make a pretty WikiPage. I also will not post the interface & file format document for the same reason. Once there is a release, I will have a solid data format that will probably never change, as well as unchanging interfaces.

Overview

Features

Current Features

• Written in C++, using interfaces
  • Incomplete memory data stored in Lua format
• Sample utility for implementation reference
• API header & library
• Complete source code
• Identify Dwarf Fortress version via PE executable timestamp
• Cross-compiler/C compatible using Windows COM style interfaces.

Expected Initial Release

I'm scheduling the initial release date to be December 15, 2007. At that time, the following features will be in place:

• Written in C++, using interfaces
• Memory data
  • Stored in a Lua format
  • Stored in a CSV format
  • Stored in an XML format?
• Sample utility for implementation reference: reimplementation of StartProfile
• Library self-contained in DLL
• API header & library
• Cross-compiler portable
• Complete source code

Second Release

After the first release, and it's been extensively bug checked, the next release will have:

• Auto-retrieve memory data off the internet
• Auto-update framework code itself
• Have an installer that will install the DLL and data file to a shared location, so multiple utilities can use the same library
• Implement specific subsets of the std library; reduce utility size more, no large dependencies for the utilities
  • std::string
  • std::vector
  • Console IO
  • File IO

Future

And further down the road (through auto-update):

• Easy to use GUI framework; for making tools with a nice GUI
• Cross-process memory allocation

Data Format

Requirements

The framework requires definitions of the following types:

• raw: a raw array of bytes; internally it allows access to an array of type.size * type.fixed_array bytes.
• pointer: a pointer to a location in Dwarf Fortress's memory; can represent a 32-bit pointer
• dword: an integer type that is 4 bytes
• word: an integer type that is 2 bytes
• byte: an integer type that is 1 byte
• float: a 32-bit floating point type
• double: a 64-bit floating point type
• string: a type that represents a std::string
  • required members:
    • dword length: defines how many characters string contains
    • dword capacity: defines the maximum number of characters the string buffer can contain
    • pointer buffer_ptr: a pointer to a memory location containing the string data
  • optional members:
    • raw buffer: a fixed-size array of characters containing the string when length < the fixed size of the buffer
• vector: a type representing a std::vector
  • required members:
    • pointer begin: a pointer to the begining of the memory block
    • pointer end: a pointer to just beyond of the last valid element in the vector
    • pointer last: a pointer to just beyond the end of the memory block

Data Files

The data files must supply the following information:

• Types: each element of the type list represents one type; there is a special type called Main, Main represents the global memory map
• Signatures: each signature is designed to uniquely identify each version of Dwarf Fortress

Lua Data Files

Classes:

• Type: 'type =' The value can either be a set containing a type override or the string of a type name.
  • Type: 'type =' A string representing the Type Name of the type to override.
  • Subtypes: An array of type overrides and/or Type Names, that are subtypes of this type.
  • Size: 'size =' An integer overriding the size of the type.
  • Fixed Array Size: 'fixed_size =' An integer overriding the fixed array size of the type.
• Types: 'Types'
  • Version: String representing version
    • TypeName: String representing name of the type, special type is Main.
      • Size: 'size =' an integer representing
      • Members: 'members' a table of of name value pairs; The name being the Member Name; The value is a set containing the Type and Offset.
        • Member Name: String representing the name
          • Type: 'type =' The value can either be a set containing a Type override or the name of the of a type.
          • Offset: 'offset =' The member offset (from the base address).
          • Pointer: 'pointer =' The pointer in memory for which the member can be found. Used for the Main type.
• Signatures 'Signatures'
  • Version: String representing the version (same string as types).
    • PE Timestamp: 'pe_timestamp' The PE header timestamp value.
    • .text Adler32: 'adler32' The Adler32 CRC of the ".text" section of the executable.
    • Text Segments: 'text_segments' An array of segments of the ".text" section of the executable.
      • Address: [1] = The offset into the ".text" section that the following raw data can be found.
      • Raw Data: [2] = The data the ".text" segment is supposed to contain.