About KOdex

KOdex (knock-out + index) publishes Glicko-2 ratings and complete historical records for combat robots competing under NHRL's rulesets. It has per-weight-class leaderboards, per-bot records and rating trajectories, badges, event analysis, and a matchup what-if tool.

The KOdex idea happened while I was making a TUI tool in python using the BrettZone API, as a little stream companion while watching events at home. The cache of data that was pulled was fun to play around with, and playing around with it kind of eventually spiralled out into being a really, really rough version of the basic features you see here.

The scope for KOdex became a lot more ambitious, and my partner Steph was integral in helping hammer out a stack that would support the project rapidly scaling vision, as elegantly as possible. This project uses a ton of primitives from other well established projects so we can focus more on the mechanics.

As with a lot of ambitious solo dev projects, this one makes ample use of agentic coding tools for a number of different specific purposes. I always encourage anyone to be extremely skeptical of any outputs produced by large language models, and to never rely on agentic tooling if you do not already understand what good output looks like. Every line of code and structural decision generated by agentic tools has been reviewed and critically examined by a human author. At time of writing, the website is over 16,000 lines of code, and the database tools are about 7,800 lines of code.

Additionally, the Mythos/Fable project by Anthropic has shown that these tools are now capable of creating highly sophisticated cybersecurity threats at an unprecedented pace. Every step will be taken to leverage agents defensively, to ensure the security, resiliency, and availability of this platform.

I sympathize with people who are overall resistant to any form of AI/LLM/ML touching the projects they use and products they enjoy. If somebody with more free-time than I have would like to stand up a comparable platform that does not use agents for anything, I can contribute some of my painful lessons learned about NHRL's various data endpoints that might help that project move along more smoothly. You're very much encouraged to reach out!

This site lives in a small private git repo that a couple of people have access to. Hosting is currently deployed over Railway, replicated on US East and US West. It uses S3 buckets for image cacheing to be respectful of BrettZone's servers, and a Postgres database holds all of the data. At this point I'm locally cacheing all of NHRL's data they make available while I actively develop in a containerized Postgres on my local system, and performing test runs against that instead of slamming NHRL's endpoints for hours every day. This system will likely mature into a slightly different shape over time.

The best way you can contribute is to find things that look wrong, render weirdly, or are just flat out incorrect. I try to never patch incorrect data. I would like for data to ingest, sanitize, and normalize into my databases programmatically, in case a big recovery ever needs to take place. So sometimes it may take longer than expected to fix incorrect data. I ask for your patience in that process! You're encouraged to share your ideas with me. Constructive critique is way more generative than complaints that don't offer solutions, so I would prefer that, if applicable, you come ready with an idea about what "good" or "better" looks like, and we can figure things out. :3

I'd like to thank all of my builder friends who contributed active critical feedback during this project. There were some pretty big philosophical design decisions that went into what information counts towards rankings, and how information should best be displayed on the site. Builders also, obviously, have an intuitive and strong memory of their bots' performances. This has caught a lot of inaccuracies in my dataset that would have been way more painful to root out otherwise. You all have my gratitude and I hope this site becomes everything you imagined it could be while contributing.

Thank you for using KOdex and I hope you really like the platform. I hope it is useful to you, makes sense, and you feel like you can trust it. I look forward to continuing building out KOdex with all of your help to see what we can make together for this silly little sport. :3

Glicko-2 here scores head-to-head competitive results between bots at events where competitors are trying. Opens, qualifiers, invitationals, Pro-tour, and World Finals all count towards the rating.

KOdex ratings do not reflect novelty fights, exhibitions, or any formats where the stakes are low and the competitive intent is unclear. We want to keep ratings focused on areas that are meaningful to builders.

For exactly how the ratings, scopes, projections, and records are computed, and where the numbers are exact versus approximate, see How it works.

Invitations are still real, full-effort fights between real bots, and we have no reason to believe drivers give anything less than their all at them. Glicko-2 ratings benefit from having a gluttony of datapoints behind them.

KOdex computes its Glicko-2 ratings independently from NHRL-ruleset competition data. That competition data is sourced from NHRL's own endpoints, brought in through an upstream data pipeline. The ratings themselves are KOdex's own computations. Postgres is pretty cool.

Bot photos don't come from a documented BrettZone API. KOdex pulls them using BrettZone's public URL format and caches them in an S3 bucket, which keeps repeat requests off BrettZone's servers and lets us convert each one into a lighter thumbnail that serves quickly.

Judges' scorecards don't seem to live in BrettZone yet, so KOdex sources those by scraping the relevant pages on nhrlportal.io. That isn't a documented API either, so it is best-effort and may change as the upstream data evolves.

Bot weapon types come from the outstanding work of Aaron Harnish, whose NHRL Data Analysis project hand-categorized thousands of NHRL robots into a two-tier weapon taxonomy: broad weapon classes and the specific weapon types within them. KOdex builds its weapon typing directly on Aaron's taxonomy and his per-bot classifications. Enormous credit and thanks to him. This layer would not exist without his effort, and any weapon-aware feature on KOdex stands on that foundation.

These ratings are intended to be authoritative for NHRL matchups only, and they update in real time during events as results come in. Ratings for different weight classes and different scopes are computed in separate pools and are not directly comparable across those boundaries.

The Havoc Registry (havocrundown.com) is a complementary, all-tournaments resource that covers NHRL and other tournaments, so its rankings are weighted across the whole sport. It also documents builders and teams. KOdex is only concerned with bot records for NHRL, so these are parallel resources with different scopes.

Visit The Havoc Registry

KOdex is an independent project and is not affiliated with, endorsed by, or sponsored by NHRL. It is built by a fan of the sport, literal white-name, using NHRL's publicly available data. KOdex doesn't claim to author or own any of the underlying data and it does not seek to supplant or compete with NHRL's very cool presentation of its data via BrettZone or the statsbook.

KOdex is built with a bunch of open-source software that makes it easy for a solo dev to ship shiny things. That software includes Next.js, React, Tailwind CSS, and shadcn/ui, among others. See the licenses page for third-party software and asset attributions.