Super Metroid Auto Tracker - Real-time Speedrun Tracking

game development kotlin super metroid speedrunning on December 5, 2025

A real-time item, boss, and location tracker for Super Metroid with automatic speedrun splits. Supports multiple connection methods including RetroArch Network Commands and SNI (SNES Classic/SD2SNES).

The source code can be found on GitHub.

Features

  • Multi-Platform Support: Works with RetroArch (any platform) and SNI-compatible devices (SD2SNES, SNES Classic, etc.)
  • Automatic Item & Boss Tracking: Real-time detection of all items, beams, suits, and boss defeats
  • Auto-Splits: Automatic speedrun splits for KPDR Any% route with best possible time calculation
  • Customizable UI:
    • Adjustable icon sizes (16x16 to 256x256)
    • Multiple themes (Dark, Light, Matrix Green, etc.)
    • Show/hide individual icons
    • Configurable split display modes (icons, names, or both)
  • Room Name Display: Shows current area and room name
  • Run Statistics: Personal best tracking with best possible time derived from best segments across all runs
  • Persistent Storage: All settings, icon configurations, and run history saved to ~/.smtracker/

Installation

Download Pre-built Executables (Recommended)

  1. Go to the Releases page or download from GitHub Actions
  2. Download the appropriate file for your platform:
    • macOS: SuperMetroidAutoTracker-macOS.dmg
    • Windows: SuperMetroidAutoTracker-Windows.msi
    • Linux: SuperMetroidAutoTracker-Linux.deb

Installation

  • macOS: Double-click the .dmg file and drag to Applications
  • Windows: Double-click the .msi file and follow the installer
  • Linux: sudo dpkg -i SuperMetroidAutoTracker-Linux.deb

Prerequisites

  • No Java installation required (bundled in all builds)
  • One of the following:
    • RetroArch with network commands enabled, OR
    • SNI with a compatible device (SD2SNES, SNES Classic, etc.)

Usage

Basic Operation

  1. Start RetroArch (or SNI) and load Super Metroid
  2. Launch Super Metroid Auto Tracker
  3. The application will automatically detect and connect to the best available connection method
  4. Start playing - items and bosses will be tracked automatically!

Keyboard Shortcuts

  • Spacebar: Start/pause the run timer
  • R: Reset the current run (requires confirmation)

How It Works

Connection Methods

The tracker supports multiple connection methods and automatically detects the best available option:

  1. SNI (SNES Network Access) - Preferred method

    • Connects to SNI server at localhost:8191 (default)
    • Works with SD2SNES, SNES Classic, and other SNI-compatible devices
    • Uses gRPC for efficient communication

  2. RetroArch Network Commands - Fallback method

    • Connects via UDP to RetroArch at localhost:55355 (default)
    • Works with any platform running RetroArch
    • Compatible with all SNES cores

Memory Reading Process

  1. Automatically detects available connection methods on startup
  2. Connects to the preferred adapter (SNI first, then RetroArch)
  3. Polls game memory at regular intervals (default: 500ms)
  4. Parses raw memory values into structured game state
  5. Applies stability checks to prevent erratic updates
  6. Updates the UI with the latest verified game state

Building and Testing

Building from Source

  1. Clone the repository

  2. Build and run the application with a single command:

    ./gradlew build && ./gradlew run

    Or build and run separately:

    ./gradlew build
./gradlew run

  3. Create a distribution package:

    ./gradlew packageDmg

For more detailed build instructions and platform-specific installers, see the GitHub repository.

Data Storage

The tracker stores all data in ~/.smtracker/:

  • smtracker.json - Application settings and preferences
  • icon-config.json - Icon visibility and ordering
  • splits-data.json - Current run and personal bests (legacy format)
  • runs/ - Individual run files for detailed history
  • run-summaries.json - Best splits and statistics (derived from runs)

Built with Kotlin and Jetpack Compose, the tracker provides real-time memory reading, cross-platform support, and has been tested extensively with the Super Metroid speedrunning community. Perfect for speedrunners who want automatic split detection or casual players who enjoy tracking their collection progress through Zebes!


Projects

Site

Games

Tags