ModSelector

A small JavaFX desktop app for searching and downloading Minecraft mods from Modrinth. Filter by loader, game version, category, and environment; queue up the mods you want; and download them straight into your mods folder.

Features

• Live search of Modrinth with debounced input and pagination
• Filters for mod loader (Fabric, Forge, …), Minecraft version, category, and environment (client / server / any)
• Download queue — stage multiple mods and download them in one batch
• Integrity checked — every download is verified against the SHA-512 hash reported by the Modrinth API before it's kept
• Settings — default download directory, one-click auto-detect of your .minecraft/mods folder, optional close-on-complete, and a configurable search delay

Requirements

• Java 11 or newer
• Maven 3.6+

Build & Run

mvn clean javafx:run

To produce a runnable fat jar (target/modselector.jar):

mvn clean package
java -jar target/modselector.jar

Standalone executable

To build a self-contained application image that bundles its own Java runtime (end users don't need Java installed):

./package.sh

This produces:

• a native launcher at dist/ModSelector/bin/ModSelector (run it directly), and
• a compressed, shareable archive dist/ModSelector-<version>-<platform>.tar.gz (~75 MB).

The script trims the bundled runtime (removes CDS archives and compile-time files) before archiving. For maximum compression (~50 MB), it prints an xz one-liner at the end.

The image is platform-specific — run package.sh on the OS you want to target (Linux → Linux image, Windows → .exe, macOS → .app). It requires a JDK 17+ (for jpackage) and Maven to build.

Building for all platforms

jpackage cannot cross-compile, so each OS must be built on that OS. The .github/workflows/release.yml workflow does this automatically on GitHub Actions runners (Linux, Windows, macOS Intel + Apple Silicon). Push a tag like v1.0.0 and it builds all four and attaches them to the GitHub Release; or trigger it manually ("Run workflow") to get downloadable build artifacts without a release.

Note: on Red Hat / Fedora OpenJDK, jpackage's default trimmed runtime can fail because the distro modifies java.security; package.sh automatically falls back to bundling the full JDK (then trims it back down).

Tech stack

• JavaFX — UI
• OkHttp — HTTP client
• Gson — JSON parsing
• JSVG — SVG icon rendering
• TwelveMonkeys ImageIO — WebP support

Notes

This project is not affiliated with Modrinth. It uses the public Modrinth API and requires no API key. Please be mindful of Modrinth's API usage guidelines.

License

Released under the MIT License.

The bundled Inter font is licensed separately under the SIL Open Font License 1.1 (OFL.txt).