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.jar
from the releases tab and install a Java version โฅ 8. - Run the launcher with
java -jar headlessmc-launcher.jar
in your terminal. You can also use thehmc.sh/bat
scripts for convenience. - You need to specify which Java installations HeadlessMc can use to run the game.
Open the file
HeadlessMC/config.properties
and 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/Java
will already get detected automatically. - Execute
config -refresh
and 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
login
command 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
, andneoforge
commands, e.g.fabric 1.21
. - With
versions
you can list your downloaded Minecraft versions. - With
help
you 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-lwjgl
flag.
The hmc-specifics are mods
that you can place inside your .minecraft/mods folder.
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
.
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.
HeadlessMc also has a preconfigured docker image,
which comes with Java 8, 17 and 21 installed.
Pull it via docker pull 3arthqu4ke/headlessmc
and run it with docker run -i -t -p 3arthqu4ke/headlessmc
.
Inside the container you can use the hmc
command anywhere.
HeadlessMc achieves headless mode by patching the LWJGL library: every of its functions is rewritten to do nothing, or to return stub values. 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. 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. Additional configs can be added to the HeadlessMc/configs
folder. For available
information see the HmcProperties, the
LauncherProperties, the
RuntimeProperties or the
LwjglProperties.
Look here for more in-depth documentation about the project.
Some cool libraries we use:
HeadlessMc is licensed under the MIT License.