From e57f8b2b9c27753c1e2c9f0ef598fd0adef3fd39 Mon Sep 17 00:00:00 2001 From: bigbass1997 Date: Sat, 1 Feb 2025 22:55:14 -0600 Subject: Updated changelog, readme, and todo docs. Rebuilt updated draft document. --- docs/tasd-spec-0001/draft-tasd-spec-0001.txt | 178 +++++++++++++++------------ 1 file changed, 101 insertions(+), 77 deletions(-) (limited to 'docs/tasd-spec-0001/draft-tasd-spec-0001.txt') diff --git a/docs/tasd-spec-0001/draft-tasd-spec-0001.txt b/docs/tasd-spec-0001/draft-tasd-spec-0001.txt index c7f2222..ba5b0b9 100644 --- a/docs/tasd-spec-0001/draft-tasd-spec-0001.txt +++ b/docs/tasd-spec-0001/draft-tasd-spec-0001.txt @@ -7,7 +7,7 @@ Independent TAS Console Replay Research Group V. Grey Bigbass rasteri - 15 October 2023 + 1 February 2025 TASD File Format Specification Version 1 @@ -145,8 +145,7 @@ Table of Contents Packets of a given type 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. + predefined delimiter to separate pieces of data. While files generated by emulator dump scripts should provide as much information as possible, because packets are optional, the file can @@ -184,11 +183,13 @@ Table of Contents (first order packet) rather than a packet inside a TRANSITION or MOVIE_TRANSITION packet (second order packet). - String values MUST use UTF-8 encoding. If an example of a string - value is given, the example will be between quotation marks. The - quotation marks are not included in the string. Not all content - between quotations will be string value examples, so be aware of that - when continuing through this document. + String values MUST use UTF-8 encoding. As such, string values MAY + contain any number of NUL characters and have no concept of "null + termination". If an example of a string value is given, the example + will be between quotation marks. The quotation marks are not + included in the string. Not all content between quotations will be + string value examples, so be aware of that when continuing through + this document. Unsigned and signed integers can have different bit widths. For instance, an 8-bit integer can be used in one part of the @@ -263,11 +264,12 @@ Table of Contents | Var 5 (N) | Var 6 (S) | +-----------+===========+ - In this example, enough variable boxes are in the packet diagram - to require being split into 2 sections to take up less horizontal - space in this documentation. The packet diagram is separated by - an ellipsis (...) on the same text row as the variable names to - signify that the packet diagram is continuing. + In this example, the packet diagram contains enough variable boxes + to require being split into 2 sections, in order to maintain + consistent horizontal spacing in this documentation. The packet + diagram is separated by an ellipsis (...) on the same text row as + the variable names to signify that the packet diagram is + continuing. 1.2. Motivations @@ -289,22 +291,22 @@ Table of Contents 1.2.1. Problems With Existing Formats - Most existing formats are either incomplete for some verification - needs or don't exist at all for some consoles. A format commonly + Existing formats are either incomplete for some verification needs or + don't exist at all for some consoles. For example, a format commonly used for NES console verifications (r08) only encodes 2 standard - controllers worth of sequential data and a format commonly used for - SNES console verifications (r16m) only encodes up to 8 standard - controllers worth of sequential data. There is no built in way to - store *RESET* timing information or indicate additional settings/ - information. Non-standard controllers are also not supported in - commonly used formats. - - For consoles not as popular as the NES and SNES, controller input - formats would frequently be written in a way that is meant only to - work and not in a "standard" way. While that process works for a - specific device, it's less than ideal for redistribution of console - replays so that others (especially with differing TAS replay devices) - can also verify the same TAS. + controllers worth of sequential data. The format doesn't indicate + whether those inputs are per latch or per frame. It also doesn't + contain *RESET* timing information, additional settings, or metadata. + Non-standard controllers, such as the NES Zapper, aren't supported + either. + + Until now, controller input formats were written in a way that was + "good enough" for each use case, but rarely in a "standard" way. + Often, any additional data had to be supplied separately as command- + line arguments. While that process may work for a specific device, + it's less than ideal when it comes time to redistribute the replay + data so that others (especially those using different replay devices) + can also successfully replay the same TAS. 2. Structure @@ -344,7 +346,7 @@ Table of Contents *Version* Version of the *TASD* file format. Version currently MUST be a - value of 1. + value of 1, but SHOULD be incremented in future versions. *G_KEYLEN* Global length of *Key* values of packets. G_KEYLEN currently MUST @@ -640,17 +642,19 @@ Table of Contents Specifies a chunk of input data for the TAS when played on hardware. All data from INPUT_CHUNK packets are concatenated together in order of appearance in the *TASD* file. If the - INPUT_CHUNK packet type is used, the PORT_CONTROLLER packet type - MUST be used. If the INPUT_CHUNK packet type is used, the - INPUT_MOMENT packet type SHOULD NOT be used. This packet type is - OPTIONAL and a *TASD* file MAY contain more than 1 of this packet - type. Discussed in (Section 4.3.5.1). + INPUT_CHUNK packet type is used in a TASD file, the + PORT_CONTROLLER packet type MUST also be used at least once. If + the INPUT_CHUNK packet type is used, the INPUT_MOMENT packet type + SHOULD NOT be used. This packet type is OPTIONAL and a *TASD* + file MAY contain more than 1 of this packet type. Discussed in + (Section 4.3.5.1). [FE 02] - INPUT_MOMENT - Specifies input data that is sent from the replay device to the - console with specific timing. If the INPUT_MOMENT packet type is - used, the PORT_CONTROLLER packet type MUST be used. If the - INPUT_MOMENT packet type is used, the INPUT_CHUNK packet type + Specifies a single instance of input data that is sent from the + replay device to the console with specific timing. If the + INPUT_MOMENT packet type is used in a TASD file, the + PORT_CONTROLLER packet type MUST also be used at least once. If + the INPUT_MOMENT packet type is used, the INPUT_CHUNK packet type SHOULD NOT be used. This packet type is OPTIONAL and a *TASD* file MAY contain more than 1 of this packet type. Discussed in (Section 4.3.5.2). @@ -1410,72 +1414,90 @@ Table of Contents Controller port number (*Port* number MUST be *1-indexed*). *Inputs* - Controller input data for controller on *Port*. Input values are - usually in native format (usually active-low). Input formats for - specific controller types are described in Section 5. + Controller input data for controller on *Port*. Input formats for + each controller type is described in Section 5. *PLEN* Length of the packet payload. - A single INPUT_CHUNK packet MAY contain up to every input of a TAS - movie console replay and MAY contain fewer than every input of a TAS - movie console replay. If there are more than 1 INPUT_CHUNK packets, - the INPUT_CHUNK packets MUST be in order of the TAS movie console - replay inputs, where earlier inputs in the TAS movie console replay - are earlier in the *TASD* file and later inputs in the TAS movie - console replay are later in the *TASD* file. + All INPUT_CHUNK packets with corresponding Port values in the *TASD* + file MUST be in chronological order, where earlier inputs in the TAS + movie console replay are earlier in the *TASD* file and later inputs + in the TAS movie console replay are later in the *TASD* file. If + there are more than one INPUT_CHUNK packets for a specific Port, the + input data MUST be interpreted as if all their contents were + concatenated into a single INPUT_CHUNK packet. As such, a single + INPUT_CHUNK packet MAY contain up to every input of a TAS movie + console replay and MAY contain fewer than every input of a TAS movie + console replay. The input data contained in *Inputs* is divided up based on the PORT_CONTROLLER type corresponding to the *Port* number. Refer to Section 5 for each available type and the number of bytes used for - each instance of controller input. Keep in mind that the - PORT_CONTROLLER type can be changed using TRANSITION packets. + each instance of controller input. The PORT_CONTROLLER type MAY be + changed using TRANSITION packets, which MAY change the interpretation + of the input data until either the end of the replay or until the + next PORT_CONTROLLER transition. + 4.3.5.2. INPUT_MOMENT Packet INPUT_MOMENT packets MUST be in the following format: - 0 1 2 3 4 5 7 8 9 10 - +----------+----------------+--+--+--+--+--+--+--+--+ - | Port (N) | Index Type (A) | Index (N) | ... - +----------+----------------+--+--+--+--+--+--+--+--+ - 11... - +============+ - | Inputs (B) | - +============+ + 0 1 2 + +----------+----------+----------------+ + | Port (N) | Hold (B) | Index Type (A) | ... + +----------+----------+----------------+ + 3 4 5 6 7 8 9 10 11... + +--+--+--+--+--+--+--+--+============+ + | Index (N) | Inputs (B) | + +--+--+--+--+--+--+--+--+============+ Port (Unsigned Integer) [1 octet] + Hold (Boolean) [1 octet] Index Type (Binary Data): [1 octet] [01] - Frame [02] - Cycle Count [03] - Milliseconds [04] - Microseconds * 10 Index (Unsigned Integer) [8 octets] - Inputs (Binary Data) [PLEN - 10 octets] + Inputs (Binary Data) [PLEN - 11 octets] *Port* Controller port number (*Port* number MUST be *1-indexed*). - *Type* - Determines specific timing type for start of *Inputs*. + *Hold* + Determines whether the *Input* data MUST continue to be held after + the controller state has been read. + + *Index Type* + Specifies timing methodology of a specific moment when *Input* + data MUST be applied. *Index* - Time value to start sending *Inputs* data. + Time value in units based on *Index Type*. - *Inputs* - Controller input data for controller on *Port*. Input values are - usually in native format (usually active-low). Input formats for - specific controller types are described in Section 5. + *Input* + A single instance of controller input data for the controller on + the specified *Port*. Input formats for each controller type is + described in Section 5. *PLEN* Length of the packet payload. - The input data contained in *Inputs* is divided up based on the - PORT_CONTROLLER type corresponding to the *Port* number. Refer to - Section 5 for each available type and the number of bytes used for - each instance of controller input. Keep in mind that the - PORT_CONTROLLER type can be changed using TRANSITION packets. + Each INPUT_MOMENT packet contains a single instance of controller + input data for a specific moment during a TAS replay. The input + data's format depends on the PORT_CONTROLLER type corresponding to + the *Port* number. Refer to Section 5 for each available type. The + PORT_CONTROLLER type MAY be changed using TRANSITION packets, which + MAY change the interpretation of the input data. + + If *Hold* is *TRUE*, the controller MUST continually hold the input + state until the next INPUT_MOMENT for the same *Port* number. If + *Hold* is *FALSE*, the controller MUST hold only until the console + reads the input state, or until the next INPUT_MOMENT for the same + *Port* number. 4.3.5.3. TRANSITION Packet @@ -1495,7 +1517,7 @@ Table of Contents [02] - Cycle Count [03] - Milliseconds [04] - Microseconds * 10 - [05] - INPUT_CHUNK Index + [05] - INPUT_CHUNK Byte Index Port (Unsigned Integer) [1 octet] Index (Unsigned Integer) [8 octets] Type (Binary Data): [1 octet] @@ -1509,14 +1531,16 @@ Table of Contents Determines specific timing type for start of transition. *Port* - Controller port number of input index. If *Index Type* is [05], - *Port* MUST be *1-indexed* Port number, otherwise *Port* MAY be - any value. + Controller port number (*Port* number MUST be *1-indexed*). *Index* Time or offset value to start transition. If *Index Type* is - [05], *Index* MUST be the byte offset of *INPUT_CHUNK* data from + [05], *Index* MUST be interpreted as the *byte offset* + (*0-indexed*) into the concatenated input data from all *INPUT_CHUNK* packets for the controller port specified by *Port*. + If *Index Type* is [05], the byte offset MUST also point to the + first byte of an instance of controller input data (according to + the PORT_CONTROLLER format at that moment in the TAS replay.) *Type* Type of transition. If *Type* is [FF], the transition action will @@ -2270,7 +2294,7 @@ Table of Contents Copyright Notice - Copyright (c) 2021-2023, Vi Grey, Bigbass, and rasteri + Copyright (c) 2021-2025, Vi Grey, Bigbass, and rasteri All rights reserved. -- cgit v1.2.3