Everything the launcher does.

MinecraftInstaller.versionCatalog() loads the official manifest from VERSION_MANIFEST and returns every safe release, snapshot, special, and legacy version ID, together with the latest release ID. The desktop version selector loads the full official manifest list (900+ IDs) and remains editable for typed version IDs. Any version ID listed in Mojang's official version manifest can be selected.

• Releases — official stable versions of Minecraft Java Edition.
• Snapshots — development builds published in the official manifest.
• Special — manifest entries outside the release and snapshot tracks.
• Legacy — historical versions that use old launch metadata, including legacy minecraftArguments strings and legacy library rules.
• Latest release ID — returned by the catalog and used as the default selection when no explicit version is chosen.

Modern argument arrays and legacy minecraftArguments are both supported at launch, so a legacy version selected from the same catalog launches like a modern one. The catalog is also exposed to your own code through the programmatic API.

1. 1
   Version metadata. Resolve and download the official version JSON for the selected ID into versions/<id>/<id>.json, verified against the official manifest.
2. 2
   Client jar. Download the client jar into versions/<id>/<id>.jar, checked against the SHA-1 and size published in the metadata.
3. 3
   Rule-matched libraries. Select and download every library whose rules allow it on this OS and architecture, including platform-matched native classifiers, into libraries/.
4. 4
   Asset index. Download the asset index for the metadata's asset ID into assets/indexes/.
5. 5
   Assets. Download every asset object from the official asset CDN into assets/objects/, stored under their SHA-1 prefix.
6. 6
   Log configuration. Download the official log4j configuration into assets/log_configs/.
7. 7
   Natives directories. Extract platform-matched native classifiers safely into the natives subdirectories referenced by the metadata, honoring metadata exclusion paths.
8. 8
   Java runtime. Install the official Java runtime component declared by the version's metadata under runtimes/.

An existing installation is reused instead of being re-downloaded. existing(version) rebuilds an Installation from files already on disk and returns null when the metadata, client jar, or runtime is missing; isInstalled(version) is exactly existing(version) != null.

• SHA-1 plus size. Downloads with a published SHA-1 and size are checked against both. Legacy library downloads without those fields are restricted to HTTPS and rejected if empty; published legacy checksums are still checked.
• .part files. Downloads are written to a .part file and moved into place only after verification, so a partial file never masquerades as an installed one.
• HTTPS only. Only HTTPS sources are accepted; a metadata-provided non-HTTPS URL is refused with an actionable error.
• Path-escape rejection. Paths from official metadata are rejected when they would escape their target directory, so a malicious metadata path cannot write outside the game directory.
• Legacy library rules. Old-format libraries are handled with their own ruleset: HTTPS required, empty downloads rejected, published checksums still enforced.
• HTTP/1.1 with four attempts and backoff. Transfers use HTTP/1.1 with up to four attempts and backoff, because the asset CDN resets concurrent HTTP/2 streams.
• Resume, not restart. Verified files are kept, so an interrupted install resumes from where it stopped when the same command is re-run rather than restarting from zero.

• The runtime is written under runtimes/<component>/<version>, where the component and version come from the version's runtime metadata via the official runtime manifest (JAVA_RUNTIME_MANIFEST).
• Executable bits are applied to the runtime binaries, which matters on macOS and Linux.
• Symbolic links are validated against the runtime root, so a link cannot point outside it.
• A .ct-runtime-complete marker is written only after the whole runtime verifies; an incomplete runtime is never treated as installed.
• A Java executable override in settings.properties replaces the runtime executable through Installation.withRuntimeExecutable(Path) — see Java override.

1. 1
   Choose the sign-in method. The default built-in method signs in with the Microsoft account email and needs no setup; MicrosoftAuthenticator.signInDirect(status) requests the device code from the Live Connect endpoints at login.live.com with the built-in client ID. The classic custom method uses a configured Azure public client ID; MicrosoftAuthenticator.signIn(clientId, status) runs the device code flow against the Microsoft consumers tenant.
2. 2
   Device code flow. Both methods report the user code and verification address through the consumer, open the browser, and poll for the token at the interval the service returns.
3. 3
   Xbox Live, XSTS, and Minecraft exchanges. The Microsoft token is exchanged through Xbox Live, then XSTS, then the Minecraft services, producing the game identity.
4. 4
   Profile ownership check. A profile check confirms the account owns Minecraft Java Edition. The profile endpoint returning 404 yields the error This Microsoft account does not own Minecraft Java Edition.

Failures are reported as IOException with an actionable message, including the mapped XSTS cases such as This Microsoft account has no Xbox profile (sign in at xbox.com once, then retry) and a region restriction. The returned Account carries user type msa.

• d= prefix rule. The d= ticket prefix is applied only for the built-in launcher client ID; a third-party application sends its token unmodified.
• Sign-in method selection. The chosen method is persisted as microsoft.loginMode (builtIn or custom). The Azure client ID field is enabled only while the custom method is selected, and its stored value survives switching back and forth.
• Offline profiles. Account.offline(String) validates the name against [A-Za-z0-9_]{3,16} and throws IllegalArgumentException otherwise. The access token is 0 and the user type is legacy. Offline profiles derive a stable UUID from the name, matching the convention used by other launchers, and cannot join online-mode servers.
• Token redaction. Never log, persist, or transmit accessToken. The desktop launcher redacts it from any echoed command, and access tokens are never written to disk — a Microsoft sign-in lasts for the current launcher session.

The built-in method needs no Azure application at all. A custom Azure application must be a public client with the device code flow enabled, allowed to use the XboxLive.signin and offline_access scopes. Setup details in sign-in configuration; the security model in security.

The command is assembled in this exact order:

1. 1
   runtimeExecutable — the official Java runtime binary, or the override applied with withRuntimeExecutable(Path).
2. 2
   User JVM arguments — heap bounds and the user's own JVM arguments.
3. 3
   Log configuration argument — pointing at the downloaded official log4j configuration.
4. 4
   arguments.jvm — from the version metadata, with rules evaluated and placeholders substituted.
5. 5
   Main class — the metadata's main class.
6. 6
   arguments.game — from the version metadata, with rules evaluated and placeholders substituted.

• Rule evaluation. RuleEvaluator.allows(JsonObject, RuleFeatures) treats an element without rules as allowed; otherwise the last matching rule wins, and an element with no matching rule is denied. Rules are evaluated against the OS (windows, osx, or linux, derived from os.name), the architecture (os.arch, with isArm() and is64Bit() predicates), and the feature flags.
• Feature flags. RuleFeatures(demoUser, customResolution, quickPlaysSupport, quickPlaySingleplayer, quickPlayMultiplayer, quickPlayRealms) carries the quick play fields as well as has_custom_resolution (from a custom resolution) and is_demo_user (from demo mode). RuleFeatures.none() disables all of them.
• Unknown placeholder hard failure. An unknown placeholder such as ${unknown} is a hard failure — buildCommand throws IOException for unsupported placeholders — instead of a silently dropped argument, so a metadata change surfaces immediately. The error reads Official metadata requested an unsupported launch value: ${...}.
• No shell. The process starts through ProcessBuilder with the game directory as the working directory and no shell, so no argument is re-parsed or expanded.
• Launch log. launch(...) appends game output to <game directory>/logs/ct-client-launch.log and forwards every line to the provided consumer. The CT-Main version reaches the game as launcher_version; the brand ct-client is passed as launcher_name.

buildCommand supports modern argument arrays and legacy minecraftArguments, and generates a missing classpath when the metadata does not provide one.

• Fabric auto-selection. CT detects fabric.mod.json in the game mods/ folder and automatically uses the sole installed Fabric profile matching the selected Minecraft version. If no profile matches, install Fabric Loader into the same game directory; if several match, select one explicitly.
• Forge and NeoForge profiles. Install them with their official or community installer, choosing the same game directory configured in CT. Refresh the profile list and select the desired installed profile.
• Vanilla parent install. CT installs the profile's required vanilla Minecraft parent version when it is missing.

What CT does not do:

• It does not download or repair loader files — loader installation and loader-library repair remain the responsibility of that loader's installer.
• It does not load Fabric, Forge, or NeoForge mods through its own API; the external loader loads its mods.
• It does not run loader-profile launches from the command line — profile launching is currently desktop-only, and the CLI continues to install and launch vanilla versions.

Profile setup instructions live in mods; the design rationale in architecture.

• Discovery. CT Loader looks for mod JARs in the mods directory inside the configured game directory — ~/.ct-client/game/mods with the default settings. CT creates the directory automatically on launch.
• ct.mod.json. Each JAR must contain a ct.mod.json file at its root with schemaVersion, id, name, version, one or more entrypoints, and an optional depends array. An entrypoint is a public class with a public no-argument constructor that implements com.ct.module.ctloader.CTMod.
• Dependency checks. The depends array contains required CT mod IDs. CT checks that each dependency is installed, rejects duplicate IDs and dependency cycles, and initializes dependencies first.
• Failure behavior. A malformed mod or failed entrypoint stops launch with an error in the CT output.

• 200,000-character history. The console keeps a 200,000-character history limit, trimming the oldest output as new lines arrive so memory stays bounded.
• Auto-scroll. The console auto-scrolls to the newest line as output streams.
• Dual output. Game output goes to the console window and to <game directory>/logs/ct-client-launch.log, appended per launch.
• Startup check. The desktop launcher checks the local installation on startup and reports the result in the console; launch installs the game first if it is not installed yet.

The same output is available programmatically — every install and launch call takes a Consumer<String> status consumer. See the class reference.

• Header. Shows the CT brand icon, product name, a v3.0.0.1 badge, account state, and sign-in actions.
• Settings cards. Grouped cards for Minecraft profile, memory, window size, directories, the Microsoft sign-in method and client ID, and JVM flags with uppercase caption labels, arranged in two columns so launcher output stays visible at the default window size.
• Sign-in method selector. The Microsoft sign-in row switches between the built-in sign-in and the custom Azure client ID; the client ID field below it is enabled only for the custom method.
• Custom-drawn controls. Custom-drawn buttons, rounded text fields, a custom version selector, memory steppers that step by 512 MB through custom arrow buttons, checkboxes with accent glyphs, a slim animated progress bar, and a rounded console panel.
• Footer. Provides Install / Verify and Launch selected version actions above a status line with an animated progress indicator. Launch stays disabled until an account is selected.
• Version selector. Loads the full official manifest list (900+ IDs) and remains editable for typed version IDs.
• States. Disabled, hover, focus, and busy states are drawn by the custom components; the window was rendered and inspected at the default size on macOS with all controls drawing the CT theme.

Version selection, offline profiles, installation and verification, Fabric mod detection and profile routing, and game launching work exactly as in v2.2.0.1; Microsoft sign-in now works without any setup. Release notes in release.

The first three hosts are needed for installation; the Microsoft hosts are needed for sign-in only, with the built-in method using login.live.com and the custom method using login.microsoftonline.com. Game downloads are always HTTPS-only — see verification. How the downloaded files are laid out on disk is described in architecture, and what CT refuses to do with them in security.