A command line launcher for Minecraft Java Edition.
Mc-Runtime-Test | HMC | HMC-Specifics | HMC-Optimizations
Warning
NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.
HeadlessMc will not allow you to play without having bought Minecraft! Accounts will always be validated. Offline accounts can only be used to run the game headlessly in CI/CD pipelines.
HeadlessMc (HMC) allows you to launch Minecraft Java Edition from the command line. It can also modify the game while and before running it. This feature can be used to make the Minecraft client run in headless mode, without displaying a UI, controlled by the command line. HeadlessMc also patches the Log4J vulnerability and can be used to test the game in your CI/CD pipeline with mc-runtime-test.
- Download the
headlessmc-launcher.jarfrom the releases tab and install a Java version ≥ 8.- If you want additional features such as plugins and launching the game inside the same JVM, use the
headlessmc-launcher-wrapper.jarinstead.
- If you want additional features such as plugins and launching the game inside the same JVM, use the
- Run the launcher with
java -jar headlessmc-launcher.jarin your terminal. You can also use thehmc.sh/batscripts for convenience. - You need to specify which Java installations HeadlessMc can use to run the game.
Open the file
HeadlessMC/config.propertiesand add a key calledhmc.java.versions, with a;seperated list of java versions HeadlessMc can use, like this:On Windows Java versions inhmc.java.versions=C:/Program Files/Java/jre-<version>/bin/java;C:/Program Files/Java/jdk-<version>/bin/java
Program Files/Javawill already get detected automatically. - Execute
config -refreshand thenjava -refresh, HeadlessMc should now know which Java versions to use. - HeadlessMc will generally not allow you to start the game without an account.
Login to your Minecraft account by executing the
logincommand and follow the instructions. - You can download Minecraft Vanilla versions with the download command, e.g.
download 1.21. - After downloading a Vanilla version you can also install modloaders
with the
forge,fabric, andneoforgecommands, e.g.fabric 1.21. - With
versionsyou can list your downloaded Minecraft versions. - With
helpyou can list other available commands. - If you are ready to launch the game execute
launch <version>. If you want to start the game in headless mode add the-lwjglflag.
The hmc-specifics are mods
that you can place inside your .minecraft/mods folder.
Together with HeadlessMc they allow you to control the game via the command line, e.g.
by sending chat messages and commands with msg "<message>",
visualizing the menus displayed by Minecraft via gui and clicking through menus via click.
A preconfigured docker image exists,
which comes with Java 8, 17 and 21 installed.
Pull it via docker pull 3arthqu4ke/headlessmc:latest
and run it with docker run -it 3arthqu4ke/headlessmc:latest.
Inside the container you can use the hmc command anywhere.
HeadlessMc can run inside Termux.
- Download Termux from F-Droid, NOT from the PlayStore.
- Install Java:
apt update && apt upgrade $ apt install openjdk-<version> - Download the headlessmc-launcher-wrapper.jar into Termux.
- Disable JLine, as we could not get it to work on Termux for now,
by adding
hmc.jline.enabled=falseto the HeadlessMC/config.properties. - Now you can use HeadlessMc like you would on Desktop or Docker.
HeadlessMc can run inside the browser, kinda. First, there is CheerpJ, a WebAssembly JVM, but it does not support all features we need to launch the game. The CheerpJ instance can be tried out here. Secondly, there is container2wasm, which can translate the HeadlessMc Docker container to WebAssembly and the run it inside the browser, but this is extremely slow.
HeadlessMc achieves headless mode by patching the LWJGL library:
every of its functions is rewritten to do nothing, or to return stub values
(you can read more about this here).
This has the advantage of being independent of Minecraft versions,
but comes with some overhead.
A Minecraft version dependent approach are the hmc-optimizations,
another set of mods which patch Minecraft itself to skip all rendering code.
Additionally HeadlessMc also comes with the hmc.assets.dummy property,
which replaces all assets with small dummy textures and sounds,
which allows for a smaller memory footprint and much less downloads before launch.
You can also achieve headless mode without patching lwjgl by running headlessmc with a virtual framebuffer like
Xvfb.
HeadlessMc can be configured using properties. These can be passed as SystemProperties from the command line or via the
HeadlessMc/config.properties file.
For available properties see the HmcProperties, the
LauncherProperties, the
JLineProperties, the
LoggingProperties, the
RuntimeProperties or the
LwjglProperties.
You can e.g. set hmc.gamedir to run the game inside another directory.
Arguments passed to commands have to be separated using spaces. If you want to pass an Argument which contains spaces
you need to escape it using quotation marks, like this:
"argument with spaces".
Quotation marks and backslashes can be escaped by using a backslash.
So msg "A text with spaces" will send the chat message A text with spaces,
while msg "\"A text with spaces\"" additional space
will send the chat message "A text with spaces" and the argument additional space will be dropped.
Simply run ./gradlew build or import the build.gradle
into an IDE of your choice, and you should be good to go.
In order to keep compatibility with older Java and Minecraft versions HeadlessMc uses Java language level 8. It can be built with any JDK ≥ 8, but language features > 8 can't be used. HeadlessMc uses project lombok to eliminate Java boilerplate.
The (sparse) javadoc can be found here.
Contributions are welcome!
You can also write Plugins for HeadlessMc.
Plugins can run through the headlessmc-launcher-wrapper,
which launches the headlessmc-launcher on another classloader.
You can find a small example here.
Some cool libraries we use:
HeadlessMc is licensed under the MIT License.