Add README

README.md

@@ -0,0 +1,83 @@
+# autopon
+
+A python script to automatically drum commands for Patapon games
+
+## Requirements
+
+1. `ydotool` must be installed, in `$PATH`, and its socket configured appropriately. If necessary, specify the envvar `YDOTOOL_SOCKET` per ydotool(1)
+
+2. PPSSPP must be installed and running the game (obviously)
+
+3. Bindings for PPSSPP must be their default: SQUARE on A, TRIANGLE on S, CIRCLE on X, and CROSS on Z
+
+4. PPSSPP must have focus while the script runs
+
+## Usage
+
+See `./autopon.py -h` for a full list of usage options.
+
+The short invocation is like so:
+
+```
+./autopon.py L-L-L-R-
+```
+
+Autopon will then prompt you to hit Enter on a drumbeat, after which you have 1 measure to change focus to the game. You'll need to [tune the startup delay](#Startup_Delay) as well.
+
+## Exiting
+
+Tab over to your terminal on a rest measure and give it Ctrl+C
+
+## Song Encoding
+
+Songs are encoded as a sequence of characters where each character corresponds to an eighth note. The script will automatically provide a full measure of rest at the start of invocation and between every command, keeping up with the call-and-response syntax of Patapon's commands:
+
+An example sequence of "March of Mobility" looks like this:
+
+```
+L-L-L-R-
+```
+
+Which will be automatically processed by the program into this looping sequence:
+
+```
+--------L-L-L-R-
+```
+
+The letters for each drum correspond to their cardinal direction on the face of a PlayStation controller:
+
+| Drum    | Character |
+| ------- | --------- |
+| Pata    | L         |
+| Pon     | R         |
+| Don     | D         |
+| Chaka   | U         |
+| Rest    | -         |
+
+Thus "Aria of Attack" would be "R-R-L-R-", and "Song of Miracles" would be "D-DD-DD-".
+
+Several commands can be chained in sequence to, for example, automate charge-attacking:
+
+```
+./autopon.py R-R-U-U- R-R-L-R-
+[...]
+Song sequence: --------R-R-U-U---------R-R-L-R-
+```
+
+## Tuning
+
+Several components of this program are timing sensitive.
+
+### Game BPM
+
+As it turns out, Patapon (all of them) doesn't actually run at a round 120BPM. Instead, The actual observed BPM is 119.880BPM, and the program is hardcoded to only issue commands at this cadence. This value was picked by beating up the door at Castle of Justice for 
+
+### Startup Delay
+
+The striking rhythm, while consistent, has some level of processing overhead due to needing to call out to an extra binary. Thus there will be a consistent, unavoidable delay between the rhythm that the script keeps and the rhythm observed by the game. In order to sync these two rhythms up, a startup delay will need to be tuned, for which Autopon provides a mechanism.
+
+The startup delay can be tuned by passing the `--startup-delay` parameter. Adjust this value by gutfeel until hitting Enter when prompted to sync the game up nails a perfect measure.
+
+### Key Delay
+
+The default value is such that you're unlikely to need to tune it, but if you need to, you can adjust how long a key is held by specifying `--key-delay`. Adjust this value if your game drops inputs -- Patapon is typically picky about anything under 50ms.