Implement better replay support

[nmlgc]

We can do better than storing a single replay file per individual stage.

• Support full-game replays
• Add more metadata: Player name, timestamp, comment, score per stage, …
• Implement a new replay menu that shows more metadata: Shot type, starting difficulty / lives / bombs, the above new metadata
  • Implement sortability by all types of metadata
  • Implement incremental search in all metadata categories
• Implement scoreboard / replay hosting support code for Silent Selene
• Conversion from and to the old 秋霜りぷ*.DAT format, using file modification time as timestamp
  • Command-line tool for converting replays between formats

[nmlgc]

Received funding from Ember2528's Seihou subscription and will be done after #42.

[nmlgc]

Let's design the exact format for both Shuusou Gyoku and PC-98 Touhou! If there's anything you've ever wanted to see in a replay format, now's your chance to influence the design and feature set.

Container / Technicalities

• I like the general IFF idea of an arbitrary chunk structure.
• We probably should store all numbers as LEB128 to be ready for modders arbitrarily extending any limits? Then again, 32-bit frame counts ought to be enough for anybody. (2³² frames = 795.3 days per stage in Shuusou Gyoku and 881 days in PC-98 Touhou.)
• Strings are both length-prefixed and null-terminated for natural zero-copy use in any kind of engine.
• Given the presence of various UTF-8 fields, we might also want to consider an entirely plaintext format?
• Readers should treat checksums as blobs of arbitrary length and should not care about the algorithm that produced them. Seihou will use BLAKE3, PC-98 Touhou will use CRC32 for speed instead.
• Floating-point fields would cause bloat issues on PC-98, so we should avoid them if possible.

Metadata

Top-level

• Player name (arbitrary UTF-8)
• Description (arbitrary UTF-8) ("My first 1CC!")
• Game build number
• Checksum of game binary
• Game-specific configuration structure (Character/shot type, difficulty, starting lives/bombs, …)

Per-stage

• Stage number
• Checksum of script file
• Description (arbitrary UTF-8) ("I hate this boss")
• The list of per-frame inputs (obviously)

Game-specific metrics

The gameplay community has a lot of ideas for metrics and it seems highly likely that they'll come up with more of them in the future. Let's store every single one of them in an individual key-value format for consistency:

• Real-time amount of milliseconds spent playing the stage, used for calculating slowdown (RTms)
• Score at end of stage (STot)
• Score from cancels (SCan)
• Score from items (SItm)
• Score from graze (SGrz)
• Graze in stage (Graz)
• Number of items collected (ItC#)
• Number of max evades (EvX#)

Timeline chunks

These chunks list any notable events that happened on specific frames during a stage. Particularly interesting for validation reasons, as they capture minor unintended differences in gameplay that don't manifest in immediate desyncs or score differences.
One chunk per event type.

Examples:

• Lost a life (T_L-)
• Used a bomb (T_B-)
• Gained a life (T_L+) (also written for score-based extends)
• Gained a bomb (T_B+)
• Used the game's special mechanic (T_Mc)
• Collected a power/point item (T_It)
• Fired a gauge/boss attack at level N (T_Ga)
• Completed a boss phase (T_Ph)
• Pauses (logical game frame + length of pause) (Paus)

Readers could then investigate these per-metric chunks to determine whether a specific replay represents a NNN run, for example. To eliminate redundancy, these timeline chunks should be the only place where this information is found; we won't have something like a separate "total lives lost" field in the top-level header.

Handling dialog

In regular story-mode gameplay, Shuusou Gyoku doesn't freeze movement controls during dialog. In replay recording mode, however, pbg entirely disabled dialog.
And now we have a problem. We want to save full story-mode replays that may or may not have dialog, depending on the Config → Graphic → MsgWindow setting. However, players with enabled dialog always have an advantage as they can reposition VIVIT during dialog. The resulting gameplay can no longer be represented in the old 秋霜りぷ*.DAT format, which only stores a sequence of inputs. This ruins all my plans of converting new-format replays back to the old format and thus allowing easy validation against the original game.

Also: Including dialog sections in replays also means recording the key presses required to advance text boxes. Translators probably want to add or remove boxes, but replays should work identically across languages. (And translation revisions.)

The plan:

• We're going to record all inputs during dialog, just like Windows Touhou does it.
• However, these inputs go into a special chunk within the game-specific per-stage data.
• This chunk also stores the character position VIVIT is warped to at the end of dialog.
• Now, we can cover both cases:
  • If the input stream ends before dialog, we end dialog on the last input frame and warp VIVIT.
  • If dialog ends before the input stream, we just warp VIVIT.
• We forget about converting back to the old format.
• Validation against the original game will involve hacking a CLI into the original 秋霜玉.exe anyway. This CLI will read from the new replay format instead, ignore all inputs in the dialog sections, and warp VIVIT at the respective frames.

Open questions

• Compression Y/N? Shuusou Gyoku's old replays are compressed using the game's slightly suboptimal LZSS scheme. This comes down to two questions:

  • Do we care about file sizes? And even if we do, wouldn't it just be OK to rely on compression at the filesystem/OS level?
  • Do we want to encourage or discourage manual hex-edits, and why?

  Also, Shuusou Gyoku's current format simply stores the input for each frame in an array. We could change to storing run-length chunks instead (this input state was pressed for X frames), which would be less efficient than LZSS but more approachable for manipulation.

• Cryptographic signatures Y/N? We could automatically sign each replay with a player's asymmetric key pair. However:

  • Would only make sense with a Web of Trust infrastructure, and who would build that one?
  • Key management is a human problem
  • The Touhou community is very peaceful and non-threatening, any security measures are a waste of time and only make life harder for developers. (As exemplified by 13½ years of thpatch history.)

[Arandui]

Regarding file size: How big would a replay become in worst case? If it's still in around 100 KB (+/-20 KB), then it would be around the same size as replays in the Touhou games. And even bigger sizes wouldn't be that bad (for example replays from the Touhou fan game "Fantastic Danmaku Festival Part III" are around 180-220 KB). Other games like RefRain (sequel to Samidare, which has a lose connection to Touhou and Seihou because of the engine) are also around 80-100KB. The smallest I could find was the Devil Blade Reboot with around 12KB.
Only if it goes around 500 KB and more, then we might think about compression and if it goes near the MB area, we should compress.

Regarding cryptographic signatures: I don't think that we will need it. The Touhou community is already peacefull and since the Seihou community is much smaller, there should be far less danger.

I don't have any oppinion about hex-editing and I don't know any use-cases outside of cheating and maybe manualy fixing or correcting things.

This are my initial thoughts about the open questions. If I get a new idea or something else, I will comment here again.

[nmlgc]

Regarding file size: How big would a replay become in worst case?

The uncompressed raw input data would be (62.5 frames × 2 bytes × 60 seconds) = 7.5 KB per minute, which would translate to ~160-170 KB for the 20-ish minutes of a full 6-stage run… yeah, I'll go investigate the run-length idea.