diff options
| -rw-r--r-- | spec.md | 149 |
1 files changed, 149 insertions, 0 deletions
@@ -0,0 +1,149 @@ +# TASD Format Specification
+## Introduction
+Created to be hardware and software agnostic, the Tool Assisted Speedrun Dump (TASD) interchange format uses a key-based, binary, packet format to break up pieces of information into easily-parsable and forward-compatible chunks. The format is extensible by simply defining additional keys or value types as necessary. When parsing the file, software can skip any packets whose key is unknown or unsupported.
+
+Keys can be used multiple times or completely omitted as needed. This reusability eliminates the need of a predefined delimiter to separate pieces of data such as a list of TAS authors.
+
+While files generated by emulator dump scripts should provide as much as much information as possible, because keys are optional, the file can be expanded later with any additional data as desired. No intermediary file format is necessary.
+
+## Header
+A very short binary header is used for special/unique data, in the following order:
+```
+ 54 41 53 44 00 01 02
++---Magic #---+ +-Version-+ +-Key Width-+
+```
+The magic number is the ASCII equivalent of `TASD`. The key width defines the how large each key is (in number of bytes). It's unlikely it'll ever be larger than 2 bytes, but it's specified for the sake of forward-compatibility.
+
+## Packet Format
+Packets are made up of four parts: `[key] [length specifier] [payload length] [payload]`
+
+Because a payload could be as small as a few bytes, or much larger than a 16-bit number could convey, a _**length specifier**_ is used to define how many bytes make up the _**payload length**_. Whereas the _**payload length**_ defines how many bytes are in the _**payload**_ itself.
+
+### Examples
+Below is the hexadecimal representation of a package, with some 2-byte key, and a payload that is 5 bytes wide:
+```
+ A8 2F 01 05 00 11 22 33 44
++-key-+ +--+ +--+ +---payload----+
+```
+Here is another example of a different key, with a payload that is 260 bytes wide:
+```
+ A8 2F 02 01 04 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
++-key-+ +--+ +-----+ 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
+ ......
+ F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF
+ 00 01 02 03 04 +----payload--------------------+
+ +---------------+
+```
+
+## Key Definitions
+Packets will often have an intended size depending on the key, however, they will still follow the packet format. Some keys will have a list of type specifiers with defined ID values.
+
+_Reminder that every key is optional, and can appear across multiple packets as necessary._
+
+#### Console-agnostic Keys:
+```
+Key | Payload Size | Description
+
+0001 | 1 byte | Console Type
+ -> 01 = NES
+ -> 02 = SNES
+ -> 03 = N64
+ -> 04 = Gamecube
+ -> 05 = GB
+ -> 06 = GBC
+ -> 07 = GBA
+ -> 08 = Genesis
+ -> 09 = A2600
+
+0002 | 1 byte | Console Region
+ -> 01 = NTSC
+ -> 02 = PAL
+
+0003 | variable | Game Title (string)
+00xx | ? bytes | Some kind of hash
+00xx | ? bytes | Some kind of hash
+00xx | ? bytes | Some kind of hash
+0004 | variable | Author (string; e.g. "Bender B. Rodriguez")
+0005 | variable | Category (string; e.g. "any%")
+0006 | variable | Emulator Name (string)
+0007 | variable | Emulator Version (string)
+
+0008 | 8 bytes | Last time the TAS movie was edited (Unix Epoch in seconds; usually TASVideos.org publication date)
+0009 | 8 bytes | Last time this file was edited (Unix Epoch in seconds)
+000A | 4 bytes | Total number of frames from original movie, including lag frames (useful for calculating movie length)
+000B | 4 bytes | TAS rerecord count
+000C | variable | URL link to publication, video upload of this TAS, or any other relevant websites
+
+000D | 1 byte | RAM Initialization Pattern (if any)
+ -> 01 = No intialization required
+ -> 02 = Custom (refer to key XXXX)
+ -> 03 = All 0x00
+ -> 04 = All 0xFF
+ -> 05 = 00 00 00 00 FF FF FF FF (repeating)
+
+000E | 1 byte | Save Memory Initialization (if any)
+ -> 01 = No intialization required
+ -> 02 = Custom (refer to key XXXX)
+ -> 03 = All 0x00
+ -> 04 = All 0xFF
+ -> 05 = 00 00 00 00 FF FF FF FF (repeating)
+
+000F | 2 bytes | Signed 16-bit number of blank frames to prepend to the TAS inputs (positive number), or frames to ignore from the start of the TAS (negative number)
+0010 | 1 byte | Whether or not this TAS has been verified by someone (boolean, either 00 or 01)
+```
+
+#### NES Keys:
+```
+Key | Payload Size | Description
+
+TODO
+```
+
+#### SNES Keys:
+```
+Key | Payload Size | Description
+
+TODO
+```
+
+#### N64 Keys:
+```
+Key | Payload Size | Description
+
+TODO
+```
+
+#### GB/C/A Keys:
+```
+Key | Payload Size | Description
+
+TODO
+```
+
+#### Genesis Keys:
+```
+Key | Payload Size | Description
+
+TODO
+```
+
+#### A2600 Keys:
+```
+Key | Payload Size | Description
+
+TODO
+```
+
+#### Input Frame/Timing Keys:
+```
+Key | Payload Size | Description
+
+FE01 | 1 + n bytes | Port number (1-indexed) + a variable number of input chunks for that port. Each chunk can vary in size depending on the controller type in use on the respective frame.
+
+FE02 | 4 + 4 bytes | Specifies a chunk of lag frames based on the original TAS movie. First 4 bytes is the frame number this chunk starts on. Second 4 bytes is the number of sequential lag frames in this chunk.
+
+FE03 | 4 + 1 + n bytes | Specifies a transition frame. First 4 bytes is the frame number. Then 1 byte specifying the transition type. Followed by a variable number of bytes depending on the transition used.
+ -> 01 = "Soft" Reset
+ -> 02 = Power Reset
+ -> 03 = Controller Swap ( 1 byte port number + 1 byte new controller type )
+```
|