Heihachi

A Python-based Discord bot (using the discord.py library) that provides an interface to query Tekken 8 frame date from Wavu Wiki.

The heihachi project was originally started by TLNBS2405 for Tekken 7 (under the name mokujin). I started contributing significantly to its Tekken 8 iteration, to complement my existing (and ongoing) contributions to Wavu Wiki.

My first contribution to the codebase was in order to handle a difference in how Wavu Wiki represented certain data, vs. how heihachi assumed it to be. Specifically, Wavu Wiki stores the values for the frame advantage on hit and counterhit fields not as an integer, as might be intuitive, but as a string. This is so that it can link to the character’s combo page if the move leads to a combo (or minicombo) on hit (or counterhit). This was not handled correctly by heihachi, with it printing the entire UR instead. My PR modified it to correctly detect the URL, convert it into Markdown, and display it in the Discord embed, with a neat tooltip as well depending on whether the link was to the Combo or Minicombo section.

The codebase ended up being quite easy to understand and modify. The primary factor was that it was written in Python, a language I’m fairly comfortable with. The secondary factor was its smaller size - it totaled only about 864 lines of Python.¹ Given my then enthusiasm about filling out the frame data for all Tekken 8 characters on Wavu Wiki, and a desire to see it be useful, and become the authority for frame data in the community, I set about increasing my contribution to the project.

The first improvement I spotted was a refactor of the way that character-specific commands were handled. Discord allows bots to register commands that recognize a specific keyword (Discord even autocompletes it in chat), and respond to further user data in a custom way. heihachi used these to implement commands for each Tekken 8 character, allowing users to simply type /[character] in the chat box, have Discord quickly autocomplete it to their desired character, and then continue typing /[character] [move query] to query a move’s frame data. Commands are registered as functions, and heihachi implemented it via hardcoded function for each character.

Since this seemed like tedious repetition of what were essentially identical functions, for each character in the game (nearly 30), and of which there could be more in the future (in the form of DLC), I thought it obvious to abstract it out into a single function that simply received the list of all game characters, and implemented each Discord command. I was able to do this by writing a factory function that created a new function object per game character, greatly simplifying the codebase.

Next, I identified more potential areas for refactors, this time with the entire architecture. The existing project was reading frame data from Wavu Wiki, storing it as JSON files, then reading the JSON files to actually serve the frame data. There had also been some issues with interconversion from strings to Markdown, which suggesting the use of stricter typing to help prevent future errors. It seemed natural to separate the reading of frame data, to enable reading data from multiple sources (Wavu Wiki, JSON files or others), the processing and querying of that data, as a sort of ad-hoc in-memory database, and the serving of that data, whether to Discord as embeds or to anywhere else (as a REST API, for e.g.). I contributed these architectural overhauls, along with some more features and a better dev workflow and tests, in another PR.

As it stands, heihachi is primarily used as a Discord bot to query frame data from the multiple Tekken community Discords in existence (over 1,680 as per TLNBS2405). However, it could be so much more. Though Wavu Wiki is the original source of the frame data, it does not provide an efficient interface to query or display that data, only doing so through the constrained API and user interface provided by MediaWiki. Unshackling that data from Wavu Wiki, could allow a lot more experimentation to be done.

One idea is to replace the existing ad-hoc “database”² with a serious OLAP database, such as DuckDB. This would presumably make the ad-hoc queries used to search for and retrieve frame data faster, due to the implementation of indexes for retrieval, and query planning when executing queries.³ It would also make it more convenient to interface with heihachi since SQL is a more established language.

The next idea is to support a natural language search interface, perhaps using LLMs. Imagine asking queries of the form - “Is Jin’s f+4 safe on block?”, “What moves can Claudio use to punish Reina’s wind god fist?”, “What lows does Lidia have from Horse stance?” or “What are Feng’s fast Heat Engagers?” These are the kinds of questions players actually have, for which they consult frame data tables and do the calculation themselves to find the answer to their questions. Enabling natural language Q&A over frame data would make interfacing with frame data a lot faster and easier for both newcomers and veterans alike.

Finally, the actual UX for presenting frame data on Wavu Wiki isn’t the best. Investigating alternate means of presenting the data in a web interface, as an app on a mobile screen or otherwise⁴, would contribute greatly towards achieving better frame data presentation on all mediums where it is currently done so.

I’m already working on replacing the internal dictionary-based “database” with DuckDB, although progress is slow, and I’m unsure how fuzzy string search could be imnplemented. Utilizing LLMs is likely a far more involved project, requiring more research on how they can be used on custom data sources and schemas. The alternate frame data UX is also a WIP, as a simple website built using Svelte.