SpeedrunUtils

A Minecraft Fabric mod for managing speedruns with built-in timer, blindness mechanics, and run tracking.

Note: This mod is still in development and is (mostly) generated by AI.

Note: This mod is meant to be installed server-only, but can be installed on a client (untested).

Preview

Requirements

• Minecraft 1.21.11
• Fabric Loader >= 0.18.4
• Fabric API
• Java 21+

Installation

1. Install Fabric Loader
2. Install Fabric API
3. Place the mod JAR in your mods folder

Features

Gameplay Flow

1. Server Start: All players join with blindness effect applied
2. Run Start: Any player runs /startrun to begin the countdown
3. Speedrun: Players complete the game while the timer runs
4. Completion: Timer automatically stops when a player exits through the End portal after defeating the Ender Dragon

Automatic Features

• Blindness on Join: Players automatically receive blindness when joining before a run starts or during a pause
• Time Freezing: Time is frozen before the run starts and during pauses, and unfrozen when the run starts/resumes
• Player Freezing: Players are completely frozen in place (movement and interactions) before the run starts and during pauses using packet-based freezing that prevents all client actions including breaking blocks, placing blocks, attacking, and moving
• Timer Display: Action bar shows elapsed time at the bottom of the screen, updating 20 times per second (each tick)
• Splits: Automatically records key milestones, broadcasts them to chat, and shows them on a sidebar scoreboard during the run
• Auto-Complete Detection: Run automatically completes when the Ender Dragon is defeated & a player teleports through the End portal back to the Overworld (after the credits screen)
• Run Tracking: All runs are logged to speedruns.txt with:
  • Date and time
  • Player names
  • Final time (formatted as HH:MM:SS.mmm or MM:SS.mmm)
  • Completion status
  • Splits (when recorded)

Splits

Splits are recorded automatically while a run is RUNNING. Each split is:

• Broadcast to all players as a chat message
• Added to a sidebar scoreboard titled Speedrun Splits
• Reflected next to the timer as the latest split in the action bar
• Saved under a Splits: section in speedruns.txt when the run is saved

Current split list

• First Iron: Get the "Acquire Hardware" advancement (smelt/obtain an iron ingot)
• Entered Nether: First time a player enters the Nether during the run
• Entered Nether Fortress: Get the "A Terrible Fortress" advancement (enter a nether fortress)
• First Blaze Rod: First blaze rod retrieved by any player during the run
• Blaze Rods Done: Server-wide total blaze rods across all online players reaches 7
• First Ender Pearl: First ender pearl retrieved by any player during the run
• Ender Pearls Done: Server-wide total ender pearls across all online players reaches 14
• First Ender Eye: First time an Eye of Ender is crafted
• Stronghold Found: Get the "Eye Spy" advancement (enter a stronghold)
• Entered End: First time a player enters the End during the run

Commands

/startrun

• Permission Level: 0 (all players)
• Description: Starts a speedrun with a 3-second countdown
• Behavior:
  • Can only be run once per speedrun (before the run starts)
  • Displays a 3-second countdown to all players
  • Removes blindness effect from all players
  • Unfreezes time
  • Starts the scoreboard timer
  • Plays sound effects for countdown and start

/pauserun

• Permission Level: 0 (all players)
• Description: Pauses the current speedrun
• Behavior:
  • Stops the timer
  • Freezes time
  • Applies blindness to all players
  • Shows "Run already paused!" if the run is already paused

/resumerun

• Permission Level: 0 (all players)
• Description: Resumes a paused speedrun
• Behavior:
  • Continues the timer
  • Unfreezes time
  • Removes blindness from all players
  • Shows an error message if the run is not paused

/stoprun

• Permission Level: 0 (all players)
• Description: Stops the current speedrun and clears the timer
• Behavior:
  • Stops the run (if one is active)
  • Clears the timer
  • Unfreezes time
  • Removes blindness from all players (in case the run was paused)
  • Broadcasts: "Run stopped. Timer cleared."

/newrun

• Permission Level: 0 (all players)
• Description: Saves the current run and prepares for a new speedrun
• Behavior:
  • Stops the run (if one is active)
  • Saves the current run data to speedruns.txt in the server root
  • Records: timestamp, player names, time, and completion status
  • Resets the run state
  • Freezes time
  • Applies blindness to all players
  • Notifies players about server restart for world regeneration

Building

The built JAR will be in build/libs/

on Windows

.\gradlew.bat build

on Linux

./gradlew build

Code Quality

The project uses Checkstyle to maintain code quality and consistent formatting standards.

Checking

Run the following command:

java -jar checkstyle-13.0.0-all.jar -c checkstyle.xml src

CI

This project is configured with GitHub Actions to automatically run Checkstyle on every push to any branch.