ULTRASTATS

ULTRAKILL doesn't track run stats, this fix.

ULTRASTATS

ULTRASTATS is an all-in-one stat tracking, performance analysis, and data collection mod for ULTRAKILL.

Whether you speedrun, high round Cybergrind, play custom levels, or just want a better record of how you play, ULTRASTATS saves your run data and allows you to browse it in-game.

ULTRASTATS currently supports:

• Campaign run logging
• Cybergrind run logging
• Custom level run logging through Angry Level Loader
• A SQLite backed database for faster filtering, sorting, migration, and future analysis
• An in-game main menu UI with INFO, STATS, and PLOTS tabs
• A STATS tab for browsing saved runs without opening the raw database
• A FILTERS window for narrowing down the displayed runs
• An ANALYSIS window for averages, best values, standard deviations, and other useful summaries
• PluginConfigurator options for data storage, logging preferences, menu behavior, UI defaults, and startup notices

Current Version

This plugin is currently on v0.1.2.

v0.1.0 is the first SQLite based release of ULTRASTATS. Older versions stored runs in many .jsonl files spread across difficulty, mode, campaign, and custom-level folders. New versions store runs in one database file:

ultrastats.db

Old .jsonl data can be migrated automatically. See Updating From Older Versions before deleting any old ULTRASTATS files.

Screenshots

These are from v0.0.15, the layout may be slightly different now.

Cybergrind stats:

Campaign stats:

Custom level stats:

The exact columns shown depend on the selected mode and filters. ULTRASTATS converts stored values into readable dates, times, waves, ranks, flags, level names, and difficulty names whenever possible.

Features

Run logging

• Saves Campaign, Cybergrind, and Custom level runs
• Stores all new run data in a SQLite database
• Uses a queue/save flow designed to reduce endscreen overhead
• Uses backup data from the game's stats display when FinalRank endscreen data is unusable
• Supports custom difficulties instead of clamping difficulty values to only the base game range
• Lets you enable or disable Campaign, Cybergrind, and Custom logging independently
• Can optionally let you discard a pending endscreen run with a configurable key

In-game UI

• Adds a main menu button that opens the ULTRASTATS UI
• Includes INFO, STATS, and PLOTS tabs
• Lets you choose which tab opens by default
• Lets you choose the main menu button corner
• Lets you choose the default STATS difficulty
• Lets you browse runs by mode, difficulty, save slot, layer, bundle, and level
• Includes a separate FILTERS window for more detailed filtering
• Includes a separate ANALYSIS window for summaries of the currently displayed runs
• Uses rank/flag coloring to make special runs easier to notice
• Avoids showing the user's full OS username in displayed source paths

Data and analysis

• Stores runs in ultrastats.db
• Automatically creates the database when needed
• Can migrate older .jsonl data into SQLite
• Keeps old .jsonl files after migration instead of deleting them automatically
• Stores campaign/custom ranks in a compact encoded format
• Stores run flags as bit flags instead of many separate boolean columns
• Removes redundant points earned logging because points can be derived from other saved values
• Keeps custom level support optional so ULTRASTATS still works without Angry Level Loader

Requirements

Required:

• BepInEx
• PluginConfigurator

Optional:

• Angry Level Loader for custom level support

If Angry Level Loader is not installed, ULTRASTATS still works for Campaign and Cybergrind. Custom level logging is simply unavailable.

Installation

If you already have a working ULTRAKILL mod setup, install ULTRASTATS like any other BepInEx plugin.

Quick install

1. Install BepInEx for ULTRAKILL.
2. Install PluginConfigurator.
3. Drop the ULTRASTATS plugin files into:

   ULTRAKILL\BepInEx\plugins\

1. Launch ULTRAKILL.
2. Confirm the mod loaded by checking the BepInEx console or log.

Optional custom level support

To enable custom level logging, also install:

• Angry Level Loader

Updating From Older Versions

v0.1.0 changes the storage backend from .jsonl files to SQLite.

What changed?

Older ULTRASTATS versions saved runs in a folder structure with separate files for different difficulties, modes, campaign levels, and custom levels. v0.1.0 stores new runs in one database file named:

ultrastats.db

This makes filtering and sorting much faster and makes future analysis features easier to build.

Automatic migration

When ULTRASTATS starts:

• If ultrastats.db already exists, ULTRASTATS uses it.
• If no ultrastats.db exists but the old .jsonl file structure exists, ULTRASTATS will create a new database and import the old runs.
• Imported runs are assigned database IDs based on chronological order.
• Old .jsonl files are not deleted automatically.

Do not delete your old ULTRASTATS folders until you have launched the game, opened the STATS tab, and confirmed that your old runs appear correctly.

If both old files and ultrastats.db exist

If ULTRASTATS detects both the new database and the old file structure, it may show a startup notice