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.¶

While files generated by emulator dump scripts should provide as much information as possible, they may be unable to provide everything. Since packets are optional, the file can be expanded later with any additional data as desired. No intermediary file format is necessary.¶

-1.1. Overview and Preliminaries +1.2. Overview and Preliminaries

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

-1.1.1. Notation and Vocabulary +1.2.1. Notation and Vocabulary

Data Types:¶

(S) = String¶ +
(S) = String¶
(A) = Binary Data¶ +
(A) = Binary Data¶
(I) = Signed Integer¶ +
(I) = Signed Integer¶
(N) = Unsigned Integer¶ +
(N) = Unsigned Integer¶
(B) = Boolean¶ +
(B) = Boolean¶
([]N) = List of Unsigned Integers¶ +
([]N) = List of Unsigned Integers¶

Unless specified otherwise, all multi-octet integers are big-endian.¶

We use the terms byte and octet interchangeably in this document.¶

We use the terms Tool Assisted Speedrun, Tool Assisted Superplay and TAS interchangeably in this document.¶

In subsections of (Section 4.2), the term "in direct form" is used. That term is defined to mean a packet in a TASD file directly (first order packet) rather than a packet inside a TRANSITION or MOVIE_TRANSITION packet (second order packet).¶

String values MUST use UTF-8 encoding. As such, string values MAY contain any number of NUL characters and do not make use 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.¶

Both unsigned and signed integers can have different bit widths. For instance, an 8-bit integer can be used in one part of the specification and a 64-bit integer can be used in another part of the specification.¶

Variable-length integer encoding (also known as VarInt or VLQ) is not used in this format. Instead, arbitrarily sized integers, like those used in Section 4, are prefixed with a single octet that specifies the number of octets used to contain the integer value. In most cases, this is less space-efficient than VarInt encoding, but it is simpler to understand and to parse.¶

Boolean values MUST be a single octet with the value of 0 for FALSE or 1 for TRUE.¶

[N octets]

A sequence of octets with a length of N¶ +

Unless specified otherwise, all multi-octet integers are big-endian.¶

We use the terms byte and octet interchangeably in this document.¶

We use the terms Tool Assisted Speedrun, Tool Assisted Superplay and TAS interchangeably in this document.¶

Boolean values MUST be a single octet with the value of 0 for FALSE or 1 for TRUE.¶

[N octets]: A sequence of octets with a length of N¶
[00 7F FF]: A sequence of octets 00, 7F, and FF in that order.¶ +
[00 7F FF]: A sequence of octets 00, 7F, and FF in that order.¶
0-indexed: When counting sequentially, start counting at 0.¶ +
0-indexed: When counting sequentially, start counting at 0.¶
1-indexed: When counting sequentially, start counting at 1.¶ +
1-indexed: When counting sequentially, start counting at 1.¶

In packet diagrams, a single octet is represented with a box like this:¶

       +-----+
       | Var | <-- Vertical bars MAY be missing
       +-----+
-

¶ +¶

- Var is a variable name.¶ +
+ Var is a variable name.¶

In packet diagrams, an arbitrary number of octets are represented with a box like this:¶

       +=====+
       | Var |
       +=====+
-

¶ +¶

- Var is a variable name.¶ +
+ Var is a variable name.¶

In packet diagrams, boxes can be connected like these examples:¶

       +-----------+-----------+
       | Var 1 (B) | Var 2 (I) |
       +-----------+-----------+
-

¶ +¶

In this example, Var 1 is a 1 octet long boolean value and Var 2 is a 1 octet long signed integer.¶ +
In this example, Var 1 is a 1 octet long boolean value and Var 2 is a 1 octet long signed integer.¶

       +-----+-----+===========+
       | Var 1 (N) | Var 2 (S) |
       +-----+-----+===========+
-

¶ +¶

In this example, Var 1 is a 2 octet long unsigned integer and Var 2 is an arbitrary octet length string.¶ +
In this example, Var 1 is a 2 octet long unsigned integer and Var 2 is an arbitrary octet length string.¶

In packet diagrams, boxes MAY have relative offset values above them like in the following example:¶

          0     1       2...
       +-----+-----+===========+
       | Var 1 (N) | Var 2 (S) |
       +-----+-----+===========+
-

¶ +¶

In this example, Var 1 is a 2 octet long unsigned integer and Var 2 is an arbitrary octet length string.¶ +
In this example, Var 1 is a 2 octet long unsigned integer and Var 2 is an arbitrary octet length string.¶

Packet diagrams MAY be split into multiple lined sections like in the following example:¶

             0           1           2           3
       +-----------+-----------+-----------+-----------+
@@ -1740,36 +1750,36 @@ li > p:last-of-type:only-child {
       +-----------+===========+
       | Var 5 (N) | Var 6 (S) |
       +-----------+===========+
-

¶ +¶

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 document. 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 document. 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 +1.3. Motivations

This file format's primary goal is to provide a comprehensive and replay device agnostic TAS input dump format that is usable for any console. Additional goals include:¶

No intermediary formats¶ +
No intermediary formats¶
Forward compatibility¶ +
Forward compatibility¶
High extensibility¶ +
High extensibility¶
Ability to easily generate using lua scripting in emulators¶ +
Ability to easily generate using lua scripting in emulators¶

Consideration is also given to how usable the format would be for the software that interacts with replay devices (examples: methods of ingestion/parsing, ease of ingestion/parsing in various languages).¶

-1.2.1. Problems With Existing Formats +1.3.1. Problems With Existing Formats

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. 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.¶

diff --git a/docs/latest/tasd-spec.txt b/docs/latest/tasd-spec.txt index e4aa9d2..8168511 100644 --- a/docs/latest/tasd-spec.txt +++ b/docs/latest/tasd-spec.txt @@ -30,10 +30,11 @@ Abstract Table of Contents 1. Introduction - 1.1. Overview and Preliminaries - 1.1.1. Notation and Vocabulary - 1.2. Motivations - 1.2.1. Problems With Existing Formats + 1.1. Contributions + 1.2. Overview and Preliminaries + 1.2.1. Notation and Vocabulary + 1.3. Motivations + 1.3.1. Problems With Existing Formats 2. Structure 3. Header 4. Packets @@ -154,7 +155,13 @@ Table of Contents additional data as desired. No intermediary file format is necessary. -1.1. Overview and Preliminaries +1.1. Contributions + + This document's source XML can be found at https://github.com/tasd- + org/tasd-spec. All specification issues and additions should be + addressed there. + +1.2. Overview and Preliminaries The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and @@ -162,7 +169,7 @@ Table of Contents 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. -1.1.1. Notation and Vocabulary +1.2.1. Notation and Vocabulary Data Types: @@ -280,7 +287,7 @@ Table of Contents the variable names to signify that the packet diagram is continuing. -1.2. Motivations +1.3. Motivations This file format's primary goal is to provide a comprehensive and replay device agnostic TAS input dump format that is usable for any @@ -298,7 +305,7 @@ Table of Contents software that interacts with replay devices (examples: methods of ingestion/parsing, ease of ingestion/parsing in various languages). -1.2.1. Problems With Existing Formats +1.3.1. Problems With Existing Formats Existing formats are either incomplete for some verification needs or don't exist at all for some consoles. For example, a format commonly -- cgit v1.2.3