From c9539f1127e3fe50a07c87a9420df3bcc3380cea Mon Sep 17 00:00:00 2001 From: bigbass1997 Date: Wed, 16 Apr 2025 15:48:50 -0500 Subject: Hopefully final specification changes before version 1 release. --- docs/latest/draft-tasd-spec.html | 129 +++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 60 deletions(-) (limited to 'docs/latest/draft-tasd-spec.html') diff --git a/docs/latest/draft-tasd-spec.html b/docs/latest/draft-tasd-spec.html index a216583..e3a41cc 100644 --- a/docs/latest/draft-tasd-spec.html +++ b/docs/latest/draft-tasd-spec.html @@ -9,7 +9,7 @@ @@ -1211,7 +1211,7 @@ li > p:last-of-type:only-child { TASD File Format Specification -February 2025 +April 2025 Grey, et al. @@ -1226,7 +1226,7 @@ li > p:last-of-type:only-child {
Independent TAS Console Replay Research Group
Published:
- +
Authors:
@@ -1245,7 +1245,7 @@ li > p:last-of-type:only-child {

TASD File Format Specification Version 1

Abstract

-

The TASD file format is used for storing "Tool Assisted Speedrun" or "Tool Assisted Superplay" (TAS) data for TAS replay devices to replay on physical video game console hardware. The format is defined to be expandable for future needs. The format is also defined to be parsable by programs that do not understand portions of the format, whether that is due to incomplete support of the format specification or due to new features being added to later versions of the specification at a later date.

+

The TASD file format is used for storing "Tool Assisted Speedrun" or "Tool Assisted Superplay" (TAS) input and configuration data for use with devices (known as "TAS replay devices") that replay inputs on physical video game hardware. The format is defined to be expandable for future needs. The format is also defined to be parsable by programs that do not understand portions of the format, whether that is due to incomplete support of the format specification or due to new features being added to later versions of the specification.

This document defines the file format specification for TASD files.

@@ -1614,9 +1614,9 @@ li > p:last-of-type:only-child {

1. Introduction

-

The Tool Assisted Speedrun Dump (TASD) interchange format is a file format for storing data to allow "Tool Assisted Speedruns" or "Tool Assisted Superplays" to be played on physical video game console hardware using TAS replay devices. Created to be hardware and software agnostic, the 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.

+

The Tool Assisted Speedrun Dump (TASD) interchange format is a file format for storing data that enables "Tool Assisted Speedruns" or "Tool Assisted Superplays" to be played on physical video game hardware using TAS replay devices. Created to be hardware and software agnostic, the 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.

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, because packets are optional, the file can be expanded later with any additional data as desired. No intermediary file format is necessary.

+

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 @@ -1641,95 +1641,96 @@ li > p:last-of-type:only-child {
  • ([]N) = List of Unsigned Integers
    • -

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

    -

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

    +

    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 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 specification and a 64-bit integer can be used in another part of the specification.

    -

    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 +

    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
    -
    [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:

    -
    +

    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:

    -
    +

    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:

    -
    +

    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:

    -
    +

    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:

    -
    +

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

    +
                 0           1           2           3
       +-----------+-----------+-----------+-----------+
@@ -1739,10 +1740,10 @@ 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 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 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.

    @@ -1751,7 +1752,7 @@ li > p:last-of-type:only-child {

    1.2. Motivations

    -

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

    +

    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
      • @@ -1820,7 +1821,7 @@ li > p:last-of-type:only-child {
    Magic Number
    -
    4 octet value that MUST be [54 41 53 44](ASCII value TASD). +
    4 octet value that MUST be [54 41 53 44] (ASCII value TASD).
    Version
    @@ -2273,12 +2274,12 @@ li > p:last-of-type:only-child {
    [FE 01] - INPUT_CHUNK
    -
    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 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). +
    Specifies a chunk of input data for the TAS when played on hardware. All data from INPUT_CHUNK packets for each controller port are concatenated together in order of appearance in the TASD file. 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 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). +
    Specifies a single instance of input data that is sent from the replay device to the console with specific timing. 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).
    @@ -2394,7 +2395,7 @@ li > p:last-of-type:only-child {
    Video Signal
    -
    Specifies the video signal of the game console being emulated while dumping the TAS movie controller inputs. +
    Specifies the video signal of the game console being emulated while dumping the TAS movie's controller inputs.
    @@ -2889,10 +2890,14 @@ li > p:last-of-type:only-child {

    GAME_IDENTIFIER packets MUST be in the following format:

    -           0            1            2         3...        3+NLEN...
-      +----------+--------------+----------+==========+================+
-      | Type (A) | Encoding (A) | NLEN (N) | Name (S) | Identifier (A) |
-      +----------+--------------+----------+==========+================+
+           0            1            2         3...
+      +----------+--------------+----------+==========+
+      | Type (A) | Encoding (A) | NLEN (N) | Name (S) | ...
+      +----------+--------------+----------+==========+
+           3+NLEN...
+      +================+
+      | Identifier (A) |
+      +================+
 
       Type (Binary Data):                     [1 octet]
          [01] - MD5 Hash
@@ -2917,7 +2922,8 @@ li > p:last-of-type:only-child {
          [04] - Base 64
       NLEN (Unsigned Integer)                 [1 octet]
       Name (String)                           [NLEN octets]
-      Identifier (Binary Data)                [PLEN - 2 octets]
+      Identifier (Binary Data)                [PLEN - NLEN -
+                                               3 octets]
    @@ -3389,7 +3395,8 @@ li > p:last-of-type:only-child { [01] - Frame [02] - Cycle Count [03] - Milliseconds - [04] - Microseconds * 10 + [04] - Microseconds + [05] - Nanoseconds Index (Unsigned Integer) [8 octets] Inputs (Binary Data) [PLEN - 11 octets] @@ -3401,7 +3408,7 @@ li > p:last-of-type:only-child {
    Hold
    -
    Determines whether the Input data MUST continue to be held after the controller state has been read. +
    If TRUE, the Input data MUST continue to be held after the controller state has been read. Otherwise if FALSE, the Input data is held only until the data has been used once.
    Index Type
    @@ -3423,6 +3430,7 @@ li > p:last-of-type:only-child {

    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.

    +

    If an INPUT_MOMENT overlaps with input data from one or more INPUT_CHUNKs, the INPUT_MOMENT's Input data MUST be used instead of the data contained in the INPUT_CHUNKs. INPUT_CHUNK data MUST still be incremented as it normally would. Hold MUST still behave as specified.

    @@ -3446,8 +3454,9 @@ li > p:last-of-type:only-child { [01] - Frame [02] - Cycle Count [03] - Milliseconds - [04] - Microseconds * 10 - [05] - INPUT_CHUNK Byte Index + [04] - Microseconds + [05] - Nanoseconds + [06] - INPUT_CHUNK Byte Index Port (Unsigned Integer) [1 octet] Index (Unsigned Integer) [8 octets] Type (Binary Data): [1 octet] @@ -3468,7 +3477,7 @@ li > p:last-of-type:only-child {
    Index
    -
    Time or offset value to start transition. If Index Type is [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.) +
    Time or offset value to start transition. If Index Type is [06], 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 [06], 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
    -- cgit v1.2.3