Some more binary format docs

squeek502 · Sep 1, 2018 · 69581ec · 69581ec
1 parent 90114d3
commit 69581ec
Show file tree

Hide file tree

Showing 5 changed files with 38 additions and 4 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -5,4 +5,7 @@
 
 ### File Structures
 
+* [Diablo II items, etc](formats/d2.md)
+* [Diablo II Save Files (.d2s)](formats/d2s.md)
 * [PlugY Save Files (.sss/.d2x)](formats/plugy.md)
+* [ATMA Stash Files (.d2x)](formats/atma.md)
diff --git a/docs/formats/atma.md b/docs/formats/atma.md
@@ -0,0 +1,15 @@
+## ATMA Stash (.d2x) File Format
+
+ATMA is the file format used by the [ATMA](http://atma.incgamers.com/) and [GoMule](http://gomule.sourceforge.net/) muling tools.
+
+Byte Offset | Size (bytes) | Description
+------------|:------------:|-------------
+0x00 | 3 | File header. Must be "D2X".
+0x03 | 2 | Number of items in the file as a 16 bit unsigned integer.
+0x05 | 2 | File version as a 16 bit unsigned integer. Must be 96.
+0x07 | 4 | ATMA checksum. See [here](https://github.com/sylecn/gomule/blob/27731580051afc7e171996997231e42a9f17cd6f/src/gomule/d2x/D2Stash.java#L176-L199) for how this is calculated.
+0x0B | ... | Beginning of [D2 Item List data](d2.md#item-list-data-format) *without* the 'header' and 'number of items' fields. Instead, use the value at offset 0x03 of the ATMA data as the number of 'root' items in the list, and then read the item list as if you're starting at offset 0x04 of the item list data.
+
+## Sources / Further Reading
+
+* [D2Stash.java (GoMule Source Code)](https://github.com/sylecn/gomule/blob/master/src/gomule/d2x/D2Stash.java)
diff --git a/docs/formats/d2.md b/docs/formats/d2.md
@@ -0,0 +1,11 @@
+## Item List Data Format
+
+Byte Offset | Size (bytes) | Description
+------------|:------------:|-------------
+0x00 | 2 | Header. Must be `"JM"` (`0x4D4A` when read as a 16 bit unsigned integer).
+0x02 | 2 | Number of items in the list as a 16 bit unsigned integer.<br/><br/>**Note:** This number only counts 'root' items, i.e. it *does not include* items that have been inserted into the sockets of the 'root' items. That is, an item list with 1 item that has 2 socketed items inside it will have a value of 1 in this field, even though the full data will have 3 items in it. In other words, the items in the sockets should be considered part of the item that they're contained in.
+0x04 | ... | Beginning of contiguous [Item data](#item-data-format)
+
+## Item Data Format
+
+TODO
diff --git a/docs/formats/d2s.md b/docs/formats/d2s.md
@@ -0,0 +1,5 @@
+TODO
+
+## Sources / Further Reading
+
+* [d2s Binary layout (nokka/d2s)](https://github.com/nokka/d2s#binary-layout)
diff --git a/docs/formats/plugy.md b/docs/formats/plugy.md
@@ -12,7 +12,7 @@ When the file version is "01", there will be no shared gold data in the file.
 Byte Offset | Size (bytes) | Description
 ------------|:------------:|-------------
 0x06 | 4 | Number of pages in the stash data as a 32 bit unsigned integer
-0x0A | ... | Beginning of [Stash data](#stash-data-format)
+0x0A | ... | Beginning of contiguous [Stash data](#stash-data-format)
 
 #### File version 2
 
@@ -22,7 +22,7 @@ Byte Offset | Size (bytes) | Description
 ------------|:------------:|-------------
 0x06 | 4 | Shared gold as a 32 bit unsigned integer
 0x0A | 4 | Number of pages in the stash data as a 32 bit unsigned integer
-0x0E | ... | Beginning of [Stash data](#stash-data-format)
+0x0E | ... | Beginning of contiguous [Stash data](#stash-data-format)
 
 ## PlugY Personal Stash (.d2x) File Format
 
@@ -32,7 +32,7 @@ Byte Offset | Size (bytes) | Description
 0x04 | 2 | File version. Will be "01" (0x3130) when file version is 1. No other versions are in use currently.
 0x06 | 4 | Unused bytes
 0x0A | 4 | Number of pages in the stash data as a 32 bit unsigned integer
-0x0E | ... | Beginning of [Stash data](#stash-data-format)
+0x0E | ... | Beginning of contiguous [Stash data](#stash-data-format)
 
 ## Stash Data Format
 
@@ -43,7 +43,7 @@ Byte Offset | Size (bytes) | Description
 0x00 | 2 | Stash header. Must be "ST" (0x5453 when read as a 16 bit unsigned integer).
 0x02 | 0 or 4 | Flags data (added in PlugY 11.02, doesn't exist in save data from earlier versions). The actual flags can be seen [here](https://github.com/ChaosMarc/PlugY/blob/0116cb44b459ba02832cf8f07092ce4f48aeecdf/PlugY/playerCustomData.h#L19-L27). <br/><br/> It's possible to determine if the flags data exists by checking if the 2 bytes following the next null character == the D2 item header ("JM"); see [the PlugY source code for an example](https://github.com/ChaosMarc/PlugY/blob/0116cb44b459ba02832cf8f07092ce4f48aeecdf/PlugY/InfinityStash.cpp#L258-L264).
 0x02 or 0x06 | At least 1 | Stash page name as a null-terminated string. Can be a maximum of 15 characters + the null terminator (16 total bytes).
-Varies | ... | Beginning of [D2 Inventory data](formats/d2.md#inventory-data-format)
+Varies | ... | Beginning of [D2 Item List data](d2.md#item-list-data-format)
 
 ## Sources / Further Reading