Table of Contents

Creating the .jar.pack (LEGACY ONLY - SEE ABOVE)

Customizing the Bootstrapper
Recompiling
Distributing Executables

.exe Wrapper
.app Wrapper
Linux Package
Creating Installers

Pushing Launcher Updates

The bootstrap is a separate program used to self-update the launcher. Following these instructions will generate the bootstrap program.

What The Boostrapper Does

When the boostrapper loads, it picks a folder to store the launcher's files and modpacks (here's the code).
If the launcher has already been downloaded (it checks in the launcher/ folder), the boostrapper will run the launcher.
If not:
1. A latest.json file from your website is fetched (you make this file below).
2. The URL to the launcher in the latest.json file is used to download the real launcher.
3. The launcher is run.

How does update work? The boostrap doesn't actually update: the launcher does. The next time the boostrapper is launched, the bootstrapper uses the newest downloaded version.

latest.json

One of the sample files is latest.json. In it, it contains a link to a copy of the launcher for download, as well as the latest launcher version.

The file looks like:

{
    "version": "4.0.1",
    "url": "http://example.com/versions/4.0.1.jar"
}

The version should correspond to the version in build.gradle (in the source code). Change "4.0.1" to whatever version is in build.gradle at the moment.

You can also change the version to build.gradle to whatever you want. Unlike the package/modpack version, this version must be a proper version string (X.Y.Z), and you should always increase it. Note that 1.1.10 is greater than 1.1.9, and 1.2.0 is greater than both 1.1.9 and 1.1.10.

Backwards compatibility

Older versions of the launcher required the launcher JAR to be compressed with the pack200 compression tool. However, this tool was deprecated in Java 11 and removed completely in Java 14. This poses a problem for us, because until recently the bootstrapper and launcher both assume the launcher download will be packed - but will fail to unpack it if the user has a Java version above 14.

If you have previously been distributing packed launchers, it's recommended to provide one last packed update for old clients - update to a launcher version past daa955fa and, crucially, change the location that it looks towards for updates (you should also update your bootstrapper for new users). For example, create a new update JSON at https://example.com/latest-v2.json and only update that file with new launcher updates from now on. This allows you to maintain basic support for old clients while ensuring new users with new Java versions can use the launcher.

The current version of the launcher & bootstrapper ignore the previously-introduced packed key completely, and will always write a filename ending in .jar. The bootstrapper can no longer decompress pack200 files and will consider any .jar.pack files non-working.

Creating the .jar.pack (LEGACY ONLY - SEE ABOVE)

⚠️ THIS IS ONLY REQUIRED FOR LEGACY DISTRIBUTION AND DOES NOT APPLY FOR NEW LAUNCHERS ⚠️

Take the launcher file and run it through the pack200 tool that comes with the JDK. Upload this to the website and also change the URL in latest.json (also on your site).

pack200 --no-gzip launcher.jar.pack launcher-X.Y.Z.jar

(That command makes launcher.jar.pack from launcher-X.Y.Z.jar in the same folder.)

Customizing the Bootstrapper

Inside the folder launcher-bootstrap/src/main/resources/com/skcraft/launcher/ will be:

lang/, which contains language files you should change
bootstrap.properties, which contain important settings you must change
bootstrapper_icon.png, which is the bootstrapper icon

The properties file is one of the most important. It looks like:

homeFolderWindows=Example Launcher
homeFolder=.examplelauncher
launcherClass=com.skcraft.launcher.Launcher
latestUrl=http://example.com/latest.json

"homeFolderWindows" is the folder in "My Documents" (i.e. C:\Users\Name\Documents\Example Launcher)
"homeFolder" is the folder in the user's home folder (i.e. /home/user/.examplelauncher)
"launcherClass" does not need to be changed unless you are using the Fancy Launcher
"latestUrl" should point to latest.json on your website

Recompiling

Recompile the entire launcher again (using gradlew clean build).
Double click the .jar file in launcher-bootstrap/build/libs to make sure it works.
Check your home folder (BSD/Linux/Mac OS X users) or My Documents (Windows users) to see the folder name that you used.

If everything works, you are done! Give players a copy of the bootstrapper .jar file.

Distributing Executables

While you can provide the .jar for download, it comes with two downfalls: (1) the file will be useless if Java is not already installed; and (2) your launcher will have no program icon.

There are two ways to solve the problem:

Create .exe and .app wrappers for Windows and Mac OS X.
Create an installer that automatically installs Java and sets up shortcuts.

Since most of your players will have Java installed already (they are, after all, Minecraft players), releasing just a .jar is perfectly reasonable as well.

.exe Wrapper

There are several tools that create an .exe from a .jar:

The author has personal experience with launch4j and can recommend it, but the other options may work even better.

Warning: Later versions of Internet Explorer and Google Chrome will mark an executable as untrustworthy unless (1) it has been downloaded thousands of times, (2) it has been downloaded from a trusted website, or (3) it has been been digitally signed using a "code signing certificate" that costs money. To run an untrusted executable, the user has to find a hidden "ignore this warning" button.

Signing the executable is the easiest solution to this problem, but it does come with monetary costs. If you want to instead rely on your executable accruing many downloads, make sure to use the bootstrapper (and not the launcher) for your executable. Why? Every time you release a new .exe, you start over with a new download count, but that's not a problem with the bootstrapper program that you never update.

With the bootstrapper, you can still release as many launcher updates as you want.

.app Wrapper

Apple provides tools to create .app bundles of .jar files.

Windows users without access to Mac OS X can create .zip.app bundles using Maven, Ant and Gradle, but this is outside the scope of the article. Since the launcher is already built using Gradle, modifying the build files to also produce .zip.apps is perhaps the easiest approach. Be aware, however, that the Gradle plugin for building these Mac OS X applications is pretty limited compared to its Maven plugin counterpart, and did not even work for the author.

Linux Package

It is possible to build a Linux package for every Linux distribution that you are interested in, but this is outside the scope of the article. It is easiest to just provide the .jar for Linux users.

There are other good options, such as AppImage.

Creating Installers

If you prefer creating an installer, there are many options available to you. The author has no experience with creating an installer for Java applications, and so the following is only general advice.

Some tools can target Windows, Mac OS X, and Linux all in one go. Other tools can only create an installer for one platform. When looking for an installer, look out for its support of Java applications. For example, support for running .jar files is important, as well as the ability to automatically download and install the JRE.

Windows has a built-in installer framework called Windows Installer, whose files are often identified with an .msi extension. Some Windows-targeted installer builders use this framework, while others don't.

Some of these tools involve going through a bunch of wizards. Others involve writing install scripts/configuration files by hand.

Windows target:
- NSIS is a popular free Windows-target installer builder, although it requires editing NSIS scripts.
- WiX is a popular .msi-based (Windows-target) installer builder, but it has a large learning curve.
Multi-platform target:
- IzPack is an open source installer builder that is built on Java.
- install4j is a commercial installer builder specifically for Java applications.
- InstallBuilder is a commercial installer builder.
- Advanced Installer is a popular commercial installer builder.
- InstallShield is a popular commercial installer builder.

By no means is this an exhaustive list.

Pushing Launcher Updates

Whenever you want to push an update:

Update the version in build.gradle (NOTE: Unlike the versions for modpacks, this version should actually be a proper version like #.#.# or #.#, or #).
Recompile the launcher.
Upload the new launcher .jar.
Update the version number and URL in latest.json.

You never should need to update the bootstrapper.

Launcher Wiki

Tutorial

Launcher Features:

Customization:

Additional Reading:

Find the launcher useful?

Donate to obw, the current maintainer:

Donate to sk89q, the original maintainer:

Need help? See Getting Help.