Added Input Maps (rough draft).

Added additional explanations and moved examples.
Added requirement byte to MemoryInit.
Added GB/C/A gamepad "controller" types.

2 files changed, 356 insertions, 19 deletions

diff --git a/inputmaps.txt b/inputmaps.txt
new file mode 100644
index 0000000..159dc43
--- /dev/null
+++ b/inputmaps.txt
@@ -0,0 +1,324 @@
+When inputs are stored in a TASD file, their values are formatted in a specific order. Data is stored as close to the console-native format as possible.

+

+Most consoles use "active-low" signals for button presses. That means that if a button is pressed, it sends a logical LOW signal, represented as binary '0'. For example, a NES controller pressing 'A' and 'Left' can be represented as binary '01111101' or hex 0x7D. However, some consoles may include "active-high" signals, or have a more complex protocol.

+

+Each controller map will include their spec-defined controller type that's used in PortController packets. All inputs that are active-low, will have a forward slash '/' infront of them. For example, all of the buttons on the NES standard controller are active-low, as seen below. Unless otherwise specified, button inputs without a '/' will be active-high, or have a custom protocol.

+

+

+=== NES Standard ===

+Spec Type: 01 01

+Length: 1 byte

+

+bit 7 = /A

+bit 6 = /B

+bit 5 = /Select

+bit 4 = /Start

+bit 3 = /Up

+bit 2 = /Down

+bit 1 = /Left

+bit 0 = /Right

+

+

+=== NES Multitap (Four Score) ===

+Spec Type: 01 02

+Length: ?

+

+???

+

+

+=== NES Zapper ===

+Spec Type: 01 03

+Length: ?

+

+???

+

+

+=== SNES Standard ===

+Spec Type: 02 01

+Length: 2 bytes

+

+bit 15 = /B

+bit 14 = /Y

+bit 13 = /Select

+bit 12 = /Start

+bit 11 = /Up

+bit 10 = /Down

+bit  9 = /Left

+bit  8 = /Right

+

+bit  7 = /A

+bit  6 = /X

+bit  5 = /L

+bit  4 = /R

+bit  3 = 1

+bit  2 = 1

+bit  1 = 1

+bit  0 = 1

+

+

+=== SNES Multitap ===

+Spec Type: 02 02

+Length: ?

+

+???

+

+

+=== SNES Mouse ===

+Spec Type: 02 03

+Length: ?

+

+???

+

+

+=== SNES Superscope ===

+Spec Type: 02 04

+Length: ?

+

+???

+

+

+=== N64 Standard ===

+Spec Type: 03 01

+Length: 4 bytes

+The N64 uses the Joybus Protocol. Pressed buttons are represented as a binary '1'.

+Protocol details can be found here: https://n64brew.dev/wiki/Joybus_Protocol

+

+bit 31 = A

+bit 30 = B

+bit 29 = Z

+bit 28 = Start

+bit 27 = D-Pad Up

+bit 26 = D-Pad Down

+bit 25 = D-Pad Left

+bit 24 = D-Pad Right

+

+bit 23 = RST (special controller reset bit)

+bit 22 = 0

+bit 21 = Left Trigger

+bit 20 = Right Trigger

+bit 19 = C-Up

+bit 18 = C-Down

+bit 17 = C-Left

+bit 16 = C-Right

+

+bits 15-8 = Analog Stick X-Axis (signed 8bit number, decimal -128 to +127)

+bits  7-0 = Analog Stick Y-Axis (signed 8bit number, decimal -128 to +127)

+

+

+=== N64 Standard with Controller Pak ===

+Spec Type: 03 02

+Identical to N64 Standard (03 01)

+

+

+=== N64 Standard with Transfer Pak ===

+Spec Type: 03 03

+Identical to N64 Standard (03 01)

+

+

+=== N64 Mouse ===

+Spec Type: 03 04

+Length: 4 bytes

+The N64 uses the Joybus Protocol. Pressed buttons are represented as a binary '1'.

+Protocol details can be found here: https://n64brew.dev/wiki/Joybus_Protocol

+

+bit 31 = A

+bit 30 = B

+bits 29-24 = 0

+

+bits 23-16 = 0

+bits 15-8 = Relative X-Axis position (signed 8bit number, decimal -128 to +127)

+bits  7-0 = Relative Y-Axis position (signed 8bit number, decimal -128 to +127)

+

+

+=== N64 Voice Recognition Unit (VRU) ===

+Spec Type: 03 04

+Length: ?

+

+Unknown at this time, more research is required to understand the VRU.

+

+

+=== N64 RandNet Keyboard ===

+Spec Type: 03 05

+Length: 7 bytes

+The N64 uses the Joybus Protocol. Protocol details can be found here: https://n64brew.dev/wiki/Joybus_Protocol

+And Keyboard specific details here: https://sites.google.com/site/consoleprotocols/home/nintendo-joy-bus-documentation/n64-specific/randnet-keyboard

+

+bits 55-40 = first key ID or all zeros

+bits 39-24 = second key ID or all zeros

+bits 23- 8 = third key ID or all zeros

+bits  7- 0 = special keyboard flags

+

+

+=== N64 Densha de Go ===

+Spec Type: 03 06

+Length: 4 bytes

+The N64 uses the Joybus Protocol. Pressed buttons are represented as a binary '1'.

+Protocol details can be found here: https://n64brew.dev/wiki/Joybus_Protocol

+

+bit 31 = B

+bit 30 = A

+bit 29 = Accelerator

+bit 28 = Start

+bit 27 = Accelerator

+bit 26 = 0

+bit 25 = 0

+bit 24 = Accelerator

+

+bit 23 = 0

+bit 22 = 0

+bit 21 = C

+bit 20 = Select

+bits 19-16 = Brake

+

+bits 15-8 = 0

+bits  7-0 = 0

+

+

+=== GC Standard ===

+Spec Type: 04 01

+Length: 8 bytes

+The GC uses the Joybus Protocol. Pressed buttons are represented as a binary '1'.

+Protocol details can be found here: https://n64brew.dev/wiki/Joybus_Protocol

+

+TODO

+

+

+=== GC Keyboard ===

+Spec Type: 04 02

+Length: ?

+The GC uses the Joybus Protocol. Pressed buttons are represented as a binary '1'.

+Protocol details can be found here: https://n64brew.dev/wiki/Joybus_Protocol

+

+TODO

+

+

+=== GB Gamepad ===

+Spec Type: 05 01

+Length: 1 byte

+

+bit 7 = /Down

+bit 6 = /Up

+bit 5 = /Left

+bit 4 = /Right

+bit 3 = /Start

+bit 2 = /Select

+bit 1 = /B

+bit 0 = /A

+

+

+=== GBC Gamepad ===

+Spec Type: 06 01

+Length: 1 byte

+

+Identical to GB Gamepad (05 01)

+

+=== GBA(SP) Gamepad ===

+Spec Type: 07 01

+Length: 2 bytes

+

+bits 15-10 = 1

+bit 9 = /L

+bit 8 = /R

+

+bit 7 = /Down

+bit 6 = /Up

+bit 5 = /Left

+bit 4 = /Right

+bit 3 = /Start

+bit 2 = /Select

+bit 1 = /B

+bit 0 = /A

+

+

+=== Genesis 3-Button ===

+Spec Type: 08 01

+Length: 1 byte

+

+bit 7 = /A

+bit 6 = /Start

+bit 5 = /Up

+bit 4 = /Down

+bit 3 = /Left

+bit 2 = /Right

+bit 1 = /B

+bit 0 = /C

+

+

+=== Genesis 6-Button ===

+Spec Type: 08 02

+Length: 2 bytes

+

+bit 15 = /A

+bit 14 = /Start

+bit 13 = /Up

+bit 12 = /Down

+bit 11 = /Left

+bit 10 = /Right

+bit  9 = /B

+bit  8 = /C

+

+bit 7 = /Z

+bit 6 = /Y

+bit 5 = /X

+bit 4 = /Mode

+bit 3 = 1

+bit 2 = 1

+bit 1 = 1

+bit 0 = 1

+

+

+=== A2600 Joystick ===

+Spec Type: 09 01

+Length: 1 byte

+

+bit 7 = /Up

+bit 6 = /Down

+bit 5 = /Left

+bit 4 = /Right

+bit 3 = 1

+bit 2 = /Button

+bit 1 = 1

+bit 0 = 1

+

+

+=== A2600 Paddle ===

+Spec Type: 09 02

+Length: 1 byte

+

+bit 7 = 1

+bit 6 = 1

+bit 5 = /LeftButton

+bit 4 = /RightButton

+bit 3 = RightPot

+bit 2 = LeftPot

+bit 1 = 1

+bit 0 = 1

+

+

+=== A2600 Keypad ===

+Spec Type: 09 03

+Length: 1 byte

+

+bit 7 = /Row1

+bit 6 = /Row2

+bit 5 = /Row3

+bit 4 = /Row4

+bit 3 = /Column1

+bit 2 = /Column3

+bit 1 = /Column2

+bit 0 = 1

+

+

+

+

+

+

+

+

+

+

+

+

+

+

+

diff --git a/spec.md b/spec.md
index 412b480..e8c7f8f 100644
--- a/spec.md
+++ b/spec.md
@@ -19,21 +19,9 @@ Packets are made up of four parts: `[key] [length exponent] [payload length] [pa
 

 Because a payload could be as small as a few bytes, or much larger than a 16-bit number could convey, a _**length exponent**_ 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────────────────────┘

-                     └───────────────┘

-```

+The **length exponent** or just **exponent** for short, is named this way given that the number of bytes that make up the _**payload length**_, is determined based on (256^exponent - 1).

+

+Packet examples can be found later in this document.

 

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

@@ -44,7 +32,7 @@ _Reminder that every key is optional, and can appear across multiple packets as
 ```

 Key  | Payload Size | Name              | Description

 

-0001 | 1 + p byte   | ConsoleType       | The console this TAS is made for.

+0001 | 1 + p bytes  | ConsoleType       | The console this TAS is made for. p = 0 for all except custom types.

     -> 01 = NES

     -> 02 = SNES

     -> 03 = N64

@@ -54,7 +42,7 @@ Key  | Payload Size | Name              | Description
     -> 07 = GBA

     -> 08 = Genesis

     -> 09 = A2600 (Atari 2600)

-    -> FF = Custom (p = custom name string)

+    -> FF = Custom (p = custom name string, no string length bytes needed)

 

 0002 | 1 byte       | ConsoleRegion     | Console region required to play this TAS.

     -> 01 = NTSC

@@ -75,7 +63,7 @@ Key  | Payload Size | Name              | Description
 000D | 2 bytes      | BlankFrames       | 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).

 000E | 1 byte       | Verified          | Whether or not this TAS has been verified by someone. (boolean, value of either 00 or 01)

 

-000F | 1 + v + k + n + p bytes | MemoryInit | Initialization of named memory space. (1 byte type, v = 1 byte exponent for k, k = length of n, n = name string, p = memory payload)

+000F | 1 + 1 + v + k + n + p bytes | MemoryInit | Initialization of named memory space. First byte is the kind of initialization. Second byte is whether or not this is required for verifications (0 = optional, 1 = required). Then the name of the space. And an optional custom payload. (1 byte type, 1 byte verification requirement, v = 1 byte exponent for k, k = length of n, n = name string, p = memory payload)

     -> 01 = No intialization required (p = 0)

     -> 02 = All 0x00 (p = 0)

     -> 03 = All 0xFF (p = 0)

@@ -104,6 +92,12 @@ Key  | Payload Size | Name              | Description
     -> xx 04 01 = GC Standard

     -> xx 04 02 = GC Keyboard

     

+    -> xx 05 01 = GB Gamepad

+    

+    -> xx 06 01 = GBC Gamepad

+    

+    -> xx 07 01 = GBA(SP) Gamepad

+    

     -> xx 08 01 = Genesis 3-Button

     -> xx 08 02 = Genesis 6-Button

     

@@ -121,7 +115,7 @@ Key  | Payload Size | Name              | Description
 0101 | 1 byte       | LatchFilter       | Latch Filter time span. (value multiplied by 0.1ms; inclusive range of 0.0ms to 25.5ms)

 0102 | 1 byte       | ClockFilter       | Clock Filter time span. (value multiplied by 0.25us; inclusive range of 0.0us to 63.75us)

 0103 | 1 byte       | Overread          | The data value to use when overread clock pulses occur. (active-low: 0 = HIGH, 1 = LOW)

-0105 | 6 or 8 bytes | GameGenieCode     | (string) 6 or 8 character game genie code.

+0104 | 6 or 8 bytes | GameGenieCode     | (string) 6 or 8 character game genie code.

 ```

 

 #### SNES Keys:

@@ -166,6 +160,7 @@ FE01 | 1 + n bytes  | InputChunks       | Port number (1-indexed) + a variable n
     Refer to transitions to know if any controller types change mid-playback.

     These packets, and the input chunks therein, are in sequential order!

     Therefore, any following input packets are appended to the inputs contained in this one.

+    Input values are usually in native format (usually active-low), refer to `inputmaps.txt` for details.

 

 FE02 | 4 + 1 + n bytes | Transition     | Defines a transition at a specific point in the TAS. First 4 bytes is the frame/index number (0-indexed) based on all inputs contained in all FE01 packets. Then 1 byte specifying the transition type. Followed by a variable number of bytes if applicable.

     -> 01 = "Soft" Reset (n = 0)

@@ -183,6 +178,24 @@ FE04 | 4 + 1 + n bytes | MovieTransition | Defines a transition based on the ori
 ## Controller Input Maps

 Each controller from each console has defined data needed for each frame (or frame equivalent), which is stored in a specific number of bytes. This data is what is stored in InputChunks packets. These maps are designed to match the real hardware as much as possible, to make decoding easier. If you need to write an emulator/movie dump script, be aware that emulators may format these inputs in a different order. Refer to the `inputmaps.txt` file for specific details.

 

+## Examples

+These examples should cover most use cases of this file format. If something is still unclear, feel free to ask questions on Discord. All examples use hexadecimal values unless otherwise specified.

+

+A madeup packet, with some 2-byte key, and a payload that is 5 bytes wide:

+```

+ A8 2F   01   05   00 11 22 33 44

+└─key─┘ └──┘ └──┘ └───payload────┘

+```

+Another made up packet, 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────────────────────┘

+                     └───────────────┘

+```

+

 ## Format Goals/Reasoning

 The primary goal of this format is to provided a single comprehensive, replay-device-agnostic, TAS dump format, usable for any console. Additional goals include: no intermediate formats, forward-compatibility, high extensibility, and the ability to easily generate using lua scripting available in emulators. Consideration was also given to how usable the format would be to the software that interacts with replay devices (e.g. methods of ingestion/parsing, and the ease of doing so given various languages).