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

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.