TLModded Starter

A clean, dependency-free, FOSS starter for TLauncher. It uses a Java 21+ runtime already installed on the computer and starts TLauncher with TLModLoader enabled by default.

Repository target: https://github.com/TLauncherModding/tlmodded-starter

Important behaviour

• No TLauncher JRE downloads. The starter never reads or installs the javaRepo entry from TLauncher's application descriptor.
• It first tries the configured Java path, the current Java process, java.home, JAVA_HOME, JDK_HOME, PATH, and common vendor/package-manager locations.
• The Java finder supports Windows, macOS, Linux, BSD, Solaris/illumos/Tribblix, AIX, z/OS, Haiku, ArcaOS/OS/2, Amiga, UnixWare/OpenServer, HP-UX, QNX, IBM i, Android/Termux, and unknown Unix-like systems.
• Every candidate is validated by running java -version; Java 21 is the default minimum.
• When the starter itself is launched under Java 8–20, it locates Java 21+ and relaunches the core with that executable.
• On Java 21+, the current executable is obtained with reflective ProcessHandle access when available.
• If no suitable runtime is found, a localised Swing dialog explains the requirement and lets the user browse to java or java.exe.
• Existing TLauncher installations under the normal tlauncher/starter folder are preserved and used without reinstalling them.
• Existing classpaths are checked for platform-mismatched OpenJFX native JARs. For example, Linux will not launch with a javafx-graphics-*-win.jar; the starter downloads and SHA-1 verifies the corresponding Linux classifier, excludes the Windows JAR from the runtime classpath, and saves the repaired classpath.
• JavaFX is optional. When no JavaFX JARs are installed, no supported native classifier exists for the current operating system/CPU, or platform repair cannot be completed, the starter launches TLauncher without JavaFX instead of refusing to start.
• A fresh installation downloads the TLauncher application JAR, dependency manifest, and resource manifest from the configured TLauncher repositories, validates size and SHA-1, and deliberately skips the runtime manifest.
• Updates for this starter, TLauncher, and TLModLoader are optional. Every prompt offers Update now, Later, 30 days, and Never. Headless runs never accept an update automatically.
• User-facing strings are supplied in English (UK), Spanish (Mexico), and Russian.

Build

mvn -Pdev package
java -jar target/tlmodded-starter-0.1.4.jar --self-test

The classes target Java 8 bytecode so the first-stage runtime finder can run on older Java installations. Normal startup work and TLauncher itself are required to run under Java 21+.

Run

java -jar target/tlmodded-starter-0.1.4.jar

Useful options:

--config <file>   Use another properties file
--java <binary>   Select a Java 21+ executable
--no-updates      Skip optional update checks for this run
--offline         Do not access the network
--no-javafx       Force this run to exclude JavaFX
--diagnose        Print paths and Java detection only
--self-test       Run internal tests
--                Pass the remaining arguments to TLauncher

Running without JavaFX

Use the following option to force one launch without JavaFX:

java -jar target/tlmodded-starter-0.1.4.jar --no-javafx

--no-javafx removes every javafx-*.jar entry and JavaFX-specific module-opening argument from the active TLauncher command. It also sets -Dtlmodded.noJavaFx=true, allowing TLModLoader modules to detect that JavaFX is unavailable. The setting is only for that run: it does not delete JavaFX files and does not overwrite the complete saved TLauncher classpath.

The starter also falls back to this mode automatically when:

• the installation contains no JavaFX JARs;
• the current operating system or CPU has no recognised OpenJFX native classifier;
• a required platform-specific JavaFX replacement cannot be obtained or verified; or
• JavaFX 21 is present on macOS older than macOS 11.

Running without JavaFX can cause slight issues. TLauncher may use a simpler Swing fallback instead of its JavaFX browser/content panel, some embedded web content may be unavailable, and launcher-level modules or themes that directly require JavaFX may lose features or fail to load. The main launcher controls and game-starting functions may still work, making this mode useful on unusual operating systems, limited graphics environments, and older macOS releases. In particular, the JavaFX 21 release notes require macOS 11 or later, so this mode may be necessary on macOS Mojave 10.14 or macOS Catalina 10.15. Apple lists Mojave as 10.14 and Catalina as 10.15 in its macOS version reference.

Configuration location

• macOS: ~/Library/Application Support/tlauncher/tlmodded-starter.properties
• Windows: %APPDATA%\.tlauncher\tlmodded-starter.properties
• Other systems: ~/.tlauncher/tlmodded-starter.properties

The TLauncher starter files remain in the compatible starter subdirectory:

• macOS: ~/Library/Application Support/tlauncher/starter
• Windows: %APPDATA%\.tlauncher\starter
• Other systems: ~/.tlauncher/starter

The properties file is created with documented defaults on first run. Important settings include:

java.path=
java.minimumMajor=21

tlauncher.version=latest
tlauncher.repositoryBases=https://repo.tlauncher.org/tlauncher-sources/prod/release/tlauncher/,https://repo.fastrepo.org/tlauncher-sources/prod/release/tlauncher/
tlauncher.jar=
tlauncher.classpath=
tlauncher.jvmArgs=
tlauncher.appArgs=
tlauncher.javafxRepositoryBases=https://repo1.maven.org/maven2/

tlmodloader.enabled=true
tlmodloader.version=1.0.1
tlmodloader.url=https://repo1.maven.org/maven2/com/asbestosstar/tlmodloader/${version}/tlmodloader-${version}.jar
tlmodloader.wrapperMainClass=com.asbestosstar.tlmodloader.TLLaunchWrapper
tlmodloader.mavenCentralBase=https://repo1.maven.org/maven2/
tlmodloader.fabricMavenBase=https://maven.fabricmc.net/
tlmodloader.asm.version=9.10.1
tlmodloader.spongeMixin.version=0.17.2+mixin.0.8.7
tlmodloader.mixinExtras.version=0.5.4
tlmodloader.accessWidener.version=2.1.0
tlmodloader.sha256=

updates.enabled=true

tlauncher.jar and tlauncher.classpath provide an explicit escape hatch for unusual or manually managed installations.

The only TLModLoader toggle is tlmodloader.enabled. When enabled, the starter always uses com.asbestosstar.tlmodloader.TLLaunchWrapper as the application main class.

TLModLoader and launcher-level modding

TLModLoader is not a Java agent and it is not a normal Minecraft mod loader. It is a launcher-level extension system. A normal Minecraft mod is loaded after a particular Minecraft instance starts and usually changes the game itself. A TLModLoader module runs inside the TLauncher process, before or while the launcher initialises, so it can extend or patch the launcher rather than only one game version.

The starter follows the supplied TLModLoader installer design:

1. Download the configured TLModLoader JAR.
2. Download ASM, Sponge Mixin, MixinExtras, and Access Widener versions required by TLModLoader.
3. Insert those JARs into the TLauncher application classpath.
4. Launch com.asbestosstar.tlmodloader.TLLaunchWrapper instead of TLauncher's original main class.
5. Allow the wrapper and installed launcher modules to prepare their transformations and extensions before control reaches TLauncher's original entry point.

The resulting command has this form:

java <TLauncher JVM arguments> -cp <TLauncher app>:<TLModLoader>:<TLModLoader libraries>:<TLauncher libraries> com.asbestosstar.tlmodloader.TLLaunchWrapper <TLauncher arguments>

The original TLauncher main class remains recorded and is used whenever tlmodloader.enabled=false. This starter performs the equivalent classpath and main-class substitution at launch time rather than permanently rewriting TLauncher's appConfig.json and dependencies.json.

Why launcher-level mods are useful

Because TLModLoader starts before TLauncher's normal main class, launcher modules can work at the same level as the launcher code they are extending. This creates an independent extension point for community features that do not need to wait for the TLauncher developers to accept, prioritise, or maintain them.

Launcher-level modules can be used to build features such as:

• New modpack formats. Add importers, exporters, converters, manifests, dependency rules, instance layouts, migration tools, and compatibility with formats used by other launchers or modding communities.
• Additional mod loaders. Add detection, installation, version resolution, launch arguments, metadata handling, and update support for new, experimental, legacy, or otherwise unsupported Minecraft mod loaders.
• Authentication integrations. Add modular support for legitimate account and identity providers, self-hosted authentication systems, development environments, and organisation-specific sign-in workflows without hard-coding every provider into the base launcher.
• Themes and user-interface extensions. Replace or extend screens, navigation, controls, styling, icons, accessibility options, localisation, instance management, and other parts of the launcher experience.
• Debugging and diagnostic tools. Add launch tracing, dependency inspection, crash collection, log analysis, class-loading diagnostics, network diagnostics, profile inspection, developer consoles, and tools for investigating launcher or game-startup failures.
• New operating-system support. Patch path handling, native-library selection, process launching, file permissions, desktop integration, package-manager behaviour, and platform-specific assumptions for operating systems not supported well by the upstream launcher.
• New CPU-architecture support. Extend architecture detection and runtime/native selection for platforms such as ARM, POWER, SPARC, s390x, RISC-V, and other architectures where the required Java and native components are available.
• Modding website integrations. Add browsing, searching, downloading, updating, publishing, account linking, collections, ratings, and metadata support for community mod, modpack, resource-pack, shader, and server websites.
• Compatibility and bug patches. Correct launcher defects, work around regressions, restore support for older services or formats, and ship targeted fixes without maintaining a complete fork of TLauncher.
• Automation and advanced workflows. Add custom instance templates, deployment rules, development profiles, testing tools, server presets, offline workflows, content policies, or organisation-specific launcher behaviour.

Authentication modules are intended for authorised providers and user-controlled systems. TLModLoader is not intended to bypass service-side authentication, licensing, access controls, or the rules of third-party services.

Modular instead of a permanent fork

A traditional fork requires maintaining a complete modified copy of the launcher. TLModLoader instead allows each feature or patch to be packaged as an independent launcher module. A user can install only the capabilities they need, module authors can release updates independently, and one module can be disabled or replaced without rebuilding the entire launcher.

This modular model is especially useful for experimental or specialised work:

• A new modpack format can be developed without coupling it to an authentication provider.
• An operating-system compatibility module can be maintained separately from themes or website integrations.
• A temporary bug fix can be removed after upstream resolves the issue.
• Multiple communities can distribute different extension sets while using the same base TLauncher installation.
• Organisations can maintain private modules for their own infrastructure without creating a public launcher fork.

TLModLoader turns TLauncher from a fixed application into a launcher platform that users and module authors can extend. The upstream feature roadmap no longer defines the limit of what the local launcher can do.

The goal is to give users full control over their local TLauncher installation regardless of which features the upstream developers choose to add. Upstream TLauncher can continue to update normally, while TLModLoader supplies an independent extension layer for community features, compatibility work, experiments, and patches.

Control and responsibility

Launcher modules execute inside the TLauncher JVM and can potentially access the same files, network connections, process-launching facilities, and launcher state as TLauncher itself. Install modules only from authors and sources you trust. A launcher update can also change internal classes or behaviour used by a module, so module compatibility should be tested and versions should be pinned when reliability matters.

Set tlmodloader.sha256 to pin the wrapper JAR. Optional per-library hashes use keys such as tlmodloader.dependency.asm.sha256.

Existing installations

The starter checks, in order:

1. tlauncher.jar and tlauncher.classpath from this project's configuration.
2. A prior tlmodded-install.properties generated by this starter.
3. Existing original-TLauncher-*.jar and dependencies/**/*.jar files in the standard TLauncher starter folder.
4. A fresh manifest-based installation, only when the prior choices are absent.

Existing starter.json is not overwritten. Update placeholders passed to TLauncher set requireUpdate=false; update decisions remain with this starter's optional prompt.

Platform-specific JavaFX repair

TLauncher uses OpenJFX classifier JARs that contain operating-system-specific native libraries. A classifier for another operating system can allow Java classes to load but still fail when JavaFX tries to create its graphics pipeline. A typical example is javafx-graphics-21.0.11-win.jar appearing on a Linux classpath, which produces Error initializing QuantumRenderer: no suitable pipeline found.

Before launching, TLModded Starter examines every classified javafx-* JAR in the resolved TLauncher classpath. On Windows, Linux, and macOS it:

1. Determines the required OpenJFX classifier from the operating system and CPU architecture, including linux-aarch64, mac-aarch64, and win-aarch64 where applicable.
2. Keeps JARs already matching the current platform.
3. Replaces foreign classifiers in the runtime classpath with the matching classifier of the same OpenJFX artifact and version.
4. Downloads a missing replacement from tlauncher.javafxRepositoryBases and verifies its Maven .sha1 before using it.
5. Saves the corrected classpath in tlmodded-install.properties, so later launches do not reuse the stale foreign classifier.

The incompatible file is left on disk because it may belong to another installation or platform, but it is not placed on the active classpath. Offline startup uses the matching JAR when it is already present. If the matching JavaFX runtime is unavailable, the starter now falls back to a transient no-JavaFX launch rather than aborting startup. Use --no-javafx to select that behaviour immediately and skip JavaFX repair for the run.

Security model

• Only HTTP and HTTPS URLs are accepted; HTTPS is used by default.
• Repository target paths are normalised and rejected if they escape the TLauncher work directory.
• TLauncher files are checked against the size and SHA-1 supplied by its manifest.
• TLModLoader can be SHA-256 pinned through configuration.
• Downloads use a temporary .part file and an atomic move where the file system supports it.
• No telemetry, advertisements, account collection, or bundled runtime management is implemented.

Project status

This is an independent compatibility project and is not an official TLauncher distribution. TLauncher and TLModLoader retain their respective names, licences, and ownership.