Alley Cat Executable Format
Alley Cat stores its assets together with the game code in a DOS MZ executable. There is no asset directory, resource-name table or general asset header. Readers must identify the edition and use the addresses supplied by the game routines or the asset viewer.
File format
All header words and embedded data words are little-endian. These are the fields consumed by parseMZ():
| File offset | Data type | Name | Description |
|---|---|---|---|
| 0x00 | BYTE[2] | signature | MZ (4D 5A) |
| 0x02 | UINT16LE | lastPage | Bytes used in the final 512-byte page; zero means a full page |
| 0x04 | UINT16LE | pages | File size in 512-byte pages, including the final page |
| 0x06 | UINT16LE | relocCount | Number of relocation entries |
| 0x08 | UINT16LE | headerParagraphs | Header size in 16-byte paragraphs |
| 0x0E | UINT16LE | ss | Initial stack segment, relative to load image |
| 0x10 | UINT16LE | sp | Initial stack pointer |
| 0x14 | UINT16LE | ip | Entry offset |
| 0x16 | UINT16LE | cs | Entry code segment, relative to load image |
| 0x18 | UINT16LE | relocOff | File offset of relocation table |
The image starts at headerParagraphs * 16. Its end is the declared file size:
lastPage != 0: fileSize = (pages - 1) * 512 + lastPage lastPage == 0: fileSize = pages * 512
Each relocation entry is a UINT16LE offset followed by a UINT16LE segment. It identifies a segment word in the load image. These are DOS relocation entries, not pointers to individual assets.
Identified editions
| Property | CAT.EXE | TANDYCAT.EXE |
|---|---|---|
| Documented size | 55067 bytes | 56881 bytes; see Notes |
| Header size | 0x200 bytes | Viewer address base agrees with an image at 0x200 |
| Relocations | 9 | 0 |
| Entry CS:IP | 0723:0000 | 0000:DB30 |
| Initial SS:SP | 0000:0100 | FFF0:0100 |
| Asset DS base in file | 0x0300 | 0x6940 |
| Viewer data-region length | 0x7130 | 0x74F1 |
SHA-256 identifiers used by the repository:
CAT.EXE 4979c8867826e08881d1d4bec95c95d6bc1ac70fd21050ccdb4f733a50d7bfdd TANDYCAT.EXE 13bc456aa15ce54456fba0618192ecaffc10536109488e5ff9366123844da321
Addressing
In the IBM executable, DS:x is file offset 0x300 + x, and CS:x is file offset 0x7430 + x. The data segment begins 0x100 bytes into the load image; the code begins at image offset 0x7230. Thus CS:x = DS:(0x7130 + x).
The Tandy viewer reads its data at file offset 0x6940 + x. An IBM data address cannot be converted to Tandy by adding one constant. The viewer maps literal addresses through these half-open ranges (start included, end excluded):
| IBM DS start | IBM DS end (exclusive) | Add to get Tandy DS |
|---|---|---|
| 0000 | 043F | 0001 |
| 0440 | 06B7 | 0000 |
| 06B7 | 06C6 | 0003 |
| 06C6 | 0FED | 0020 |
| 0FED | 1664 | 0270 |
| 1664 | 1828 | 0272 |
| 182F | 37AF | 0270 |
| 37AF | 6D37 | 0280 |
| 6D63 | 6D8F | 02C5 |
| 6D8F | 6DF8 | 02C9 |
| 6E01 | 7128 | 02C0 |
All values in this table are hexadecimal. Unlisted ranges have no mapping in the viewer. Do not interpolate across a gap. A pointer read from a Tandy table is already a Tandy DS offset: do not apply the mapping a second time.
Notes
- The first identity table in RE_NOTES.md gives the tentative Tandy size 56865?. The later dedicated analysis states 56881; this article follows the latter. The repository does not include the executable, so the exact SHA-256 is the stronger edition identifier.
- The nine IBM relocation words are in code, at CS offsets 0009, 0541, 1125, 13ED, 14B8, 1501, 2ADE, 3A98 and 5C9F. The notes identify no data relocations.
- The Tandy executable is not packed. The IBM loader reads its MZ image directly without an asset decompression stage.
- Runtime variables, graphics and tables share the data segment. A memory dump is not interchangeable with the initial file bytes.
- The parser is a reader for known originals, not a complete malformed-MZ validator. An editor should check every range before reading or writing and preserve code, relocation entries and unrelated data.
Source code
From re-alleycat, the open-source HTML5 port (revision b003aa63ffbb):
- src/machine/exe.js – MZ parser and exact-hash identification
- src/machine/memory.js – IBM image-to-data-segment mapping
- viewer.html – edition bases and piecewise Tandy address map
- docs/RE_NOTES.md – executable identities and observed address correspondence
Credits
This file format was reverse engineered by VorticonCmdr. Please credit the original research when using this information in your own project, and include a link back to this wiki.