{"id":19569537,"url":"https://github.com/3arthqu4ke/headlessmc","last_synced_at":"2025-04-13T02:12:03.359Z","repository":{"id":38009381,"uuid":"480523771","full_name":"3arthqu4ke/headlessmc","owner":"3arthqu4ke","description":"Minecraft on the command line","archived":false,"fork":false,"pushed_at":"2025-02-04T09:54:44.000Z","size":2086,"stargazers_count":211,"open_issues_count":17,"forks_count":21,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T05:05:25.894Z","etag":null,"topics":["bytecode","cli","headless","launcher","lwjgl","minecraft","minecraft-launcher"],"latest_commit_sha":null,"homepage":"https://3arthqu4ke.github.io/headlessmc/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/3arthqu4ke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-11T19:31:53.000Z","updated_at":"2025-04-01T18:02:46.000Z","dependencies_parsed_at":"2023-11-13T12:29:53.656Z","dependency_job_id":"a4391cd1-0ff8-4947-b8a9-3e81d74f0472","html_url":"https://github.com/3arthqu4ke/headlessmc","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3arthqu4ke%2Fheadlessmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3arthqu4ke%2Fheadlessmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3arthqu4ke%2Fheadlessmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3arthqu4ke%2Fheadlessmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/3arthqu4ke","download_url":"https://codeload.github.com/3arthqu4ke/headlessmc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654089,"owners_count":21140236,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bytecode","cli","headless","launcher","lwjgl","minecraft","minecraft-launcher"],"created_at":"2024-11-11T06:10:27.076Z","updated_at":"2025-04-13T02:12:03.331Z","avatar_url":"https://github.com/3arthqu4ke.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--suppress HtmlDeprecatedAttribute --\u003e\n\u003ch1 align=\"center\" style=\"font-weight: normal;\"\u003e\u003cb\u003eHeadlessMc\u003c/b\u003e\u003c/h1\u003e\n\u003cp align=\"center\"\u003eA command line launcher for Minecraft Java Edition.\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"headlessmc-web/page/logo.png\" alt=\"logo\" style=\"width:200px;\"\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/3arthqu4ke/mc-runtime-test\"\u003eMc-Runtime-Test\u003c/a\u003e | HMC | \u003ca href=\"https://github.com/3arthqu4ke/hmc-specifics\"\u003eHMC-Specifics\u003c/a\u003e | \u003ca href=\"https://github.com/3arthqu4ke/hmc-optimizations\"\u003eHMC-Optimizations\u003c/a\u003e\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/6a86b3e62d3b47909de670b09737f8fd)](https://app.codacy.com/gh/3arthqu4ke/headlessmc/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![GitHub All Releases](https://img.shields.io/github/downloads/3arthqu4ke/HeadlessMc/total.svg)](https://github.com/3arthqu4ke/HeadlessMc/releases)\n![](https://github.com/3arthqu4ke/HeadlessMc/actions/workflows/gradle-publish.yml/badge.svg)\n![GitHub](https://img.shields.io/github/license/3arthqu4ke/HeadlessMc)\n[![Docker Image Size](https://badgen.net/docker/size/3arthqu4ke/headlessmc?icon=docker\u0026label=image%20size)](https://hub.docker.com/r/3arthqu4ke/headlessmc/)\n![Github last-commit](https://img.shields.io/github/last-commit/3arthqu4ke/HeadlessMc)\n\n\u003c/div\u003e\n\n\u003e [!WARNING]\n\u003e NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.\n\u003e \n\u003e HeadlessMc will not allow you to play without having bought Minecraft! \n\u003e Accounts will always be validated.\n\u003e Offline accounts can only be used to run the game headlessly in CI/CD pipelines.\n\nHeadlessMc (HMC) allows you to launch Minecraft Java Edition from the command line.\nIt can also modify the game while and before running it.\nThis feature can be used to make the Minecraft client run in headless mode, \nwithout displaying a UI, controlled by the command line.\nHeadlessMc also patches the Log4J vulnerability \nand can be used\nto test the game in your CI/CD pipeline with [mc-runtime-test](https://github.com/3arthqu4ke/mc-runtime-test).\n\n## How to use\n\n1. Download the `headlessmc-launcher.jar` from the releases tab and install a Java version \u0026geq; 8.\n    - If you want additional features such as plugins and launching the game inside the same JVM, use the `headlessmc-launcher-wrapper.jar` instead.\n    - You do not need to install java if you download one of the GraalVM executables instead.\n2. Run the launcher with `java -jar headlessmc-launcher.jar` in your terminal.\n    - Or e.g. `./headlessmc-launcher-linux` if you use a GraalVM executable.\n3. HeadlessMc will generally not allow you to start the game without an account. \nLogin to your Minecraft account by executing the `login` command and follow the instructions.\n4. Launch the game with `launch \u003cmodloader\u003e:\u003cversion\u003e`, e.g. `launch fabric:1.21.4 -lwjgl`.\nThe `lwjgl` flag will make the game run in headless mode.\n\n### HeadlessMc-Specifics\n\nThe [hmc-specifics](https://github.com/3arthqu4ke/hmc-specifics) are mods\nthat you can place inside your .minecraft/mods folder.\nTogether with HeadlessMc they allow you to control the game via the command line, e.g.\nby sending chat messages and commands with `msg \"\u003cmessage\u003e\"`,\nvisualizing the menus displayed by Minecraft via `gui` and clicking through menus via `click`.\n\n### Docker \n\nA preconfigured [docker image](https://hub.docker.com/r/3arthqu4ke/headlessmc/) exists,\nwhich comes with Java 8, 17 and 21 installed.\nPull it via `docker pull 3arthqu4ke/headlessmc:latest`\nand run it with `docker run -it 3arthqu4ke/headlessmc:latest`.\nInside the container you can use the `hmc` command anywhere.\n\n### Android\n\nHeadlessMc can run inside Termux.\n* Download Termux from F-Droid, NOT from the PlayStore.\n* Install Java: `apt update \u0026\u0026 apt upgrade $ apt install openjdk-\u003cversion\u003e`\n* Download the headlessmc-launcher-wrapper.jar into Termux.\n* Disable JLine, as we could not get it to work on Termux for now,\n  by adding `hmc.jline.enabled=false` to the HeadlessMC/config.properties.\n* Now you can use HeadlessMc like you would on Desktop or Docker.\n\n### Web\n\nHeadlessMc can run inside the browser, kinda.\nFirst, there is CheerpJ, a WebAssembly JVM,\nbut it does not support all features we need to launch the game.\nThe CheerpJ instance can be tried out [here](https://3arthqu4ke.github.io/headlessmc/).\nSecondly, there is [container2wasm](https://github.com/headlesshq/hmc-container2wasm),\nwhich can translate the HeadlessMc Docker container\nto WebAssembly and the run it inside the browser, but this is extremely slow.\n\n### Optimizations \n\nHeadlessMc achieves headless mode by patching the LWJGL library: \nevery of its functions is rewritten to do nothing, or to return stub values\n(you can read more about this [here](headlessmc-lwjgl/README.md)).\nThis has the advantage of being independent of Minecraft versions,\nbut comes with some overhead.\nA Minecraft version dependent approach are the [hmc-optimizations](https://github.com/3arthqu4ke/hmc-optimizations),\nanother set of mods which patch Minecraft itself to skip all rendering code.\nAdditionally HeadlessMc also comes with the `hmc.assets.dummy` property,\nwhich replaces all assets with small dummy textures and sounds,\nwhich allows for a smaller memory footprint and much less downloads before launch.\nYou can also achieve headless mode without patching lwjgl by running headlessmc with a virtual framebuffer like\n[Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml).\n\n### Configuring HeadlessMc\n- HeadlessMc stores its configuration in `HeadlessMC/config.properties`.\n- On Windows and Linux Java versions in certain folders get detected automatically\n  and HeadlessMc can download missing Java distributions.\n  But you can also specify which Java installations HeadlessMc can use to run the game.\n  Open the file `HeadlessMC/config.properties` and add a key called `hmc.java.versions`,\n  with a `;` seperated list of java versions HeadlessMc can use, like this:\n    ```properties\n    hmc.java.versions=C:/Program Files/Java/jre-\u003cversion\u003e/bin/java;C:/Program Files/Java/jdk-\u003cversion\u003e/bin/java\n    ```\n- Restart HeadlessMc or use `config -refresh` and then `java -refresh`, HeadlessMc should now know which Java versions to use.\n\nProperties can also be passed as SystemProperties from the command line.\nFor available properties see the [HmcProperties](headlessmc-api/src/main/java/me/earth/headlessmc/api/config/HmcProperties.java), the\n[LauncherProperties](headlessmc-launcher/src/main/java/me/earth/headlessmc/launcher/LauncherProperties.java), the\n[JLineProperties](headlessmc-jline/src/main/java/me/earth/headlessmc/jline/JLineProperties.java), the\n[LoggingProperties](headlessmc-logging/src/main/java/me/earth/headlessmc/logging/LoggingProperties.java), the\n[RuntimeProperties](headlessmc-runtime/src/main/java/me/earth/headlessmc/runtime/RuntimeProperties.java) or the\n[LwjglProperties](headlessmc-lwjgl/src/main/java/me/earth/headlessmc/lwjgl/LwjglProperties.java).\n\nYou can e.g. set `hmc.gamedir` to run the game inside another directory.\n\n### In-Memory launching and GraalVM\n\nWith the `-inmemory` flag HeadlessMc can even launch the game inside the same\nJVM that is running HeadlessMc itself.\nMaking it possible to really run Minecraft anywhere, where a JVM can run.\n\nThis is not possible on GraalVM.\nAdditionally, HeadlessMc's plugin system and instrumentation process\nare also difficult to realize in GraalVM.\n\nBut we provide GraalVM images, that are basically a launcher for HeadlessMc itself:\nThey find/download a suitable Java distribution and run HeadlessMc on it,\nwithout the user having to install Java.\n\n### A Note on command arguments\n\nArguments passed to commands have to be separated using spaces. If you want to pass an Argument which contains spaces\nyou need to escape it using quotation marks, like this:\n`\"argument with spaces\"`.\nQuotation marks and backslashes can be escaped by using a backslash.\nSo `msg \"A text with spaces\"` will send the chat message `A text with spaces`,\nwhile `msg \"\\\"A text with spaces\\\"\" additional space`\nwill send the chat message `\"A text with spaces\"` and the argument `additional space` will be dropped.\n\n## Building, Developing and Contributing\n\nSimply run `./gradlew build` or import the [build.gradle](build.gradle)\ninto an IDE of your choice, and you should be good to go.\n\nIn order to keep compatibility with older Java and Minecraft versions\nHeadlessMc uses Java language level 8. It can be\nbuilt with any JDK \u0026geq; 8, but language features \u003e 8 can't be used. \nHeadlessMc uses [project lombok](https://github.com/projectlombok/lombok)\nto eliminate Java boilerplate.\n\nThe (sparse) javadoc can be found [here](https://3arthqu4ke.github.io/headlessmc/javadoc/).\n\nContributions are welcome!\n\n### Plugins\n\nYou can also write Plugins for HeadlessMc.\nPlugins can run through the `headlessmc-launcher-wrapper`,\nwhich launches the `headlessmc-launcher` on another classloader.\nYou can find a small example [here](headlessmc-launcher-wrapper/src/testPlugin).\n\n## License and Libraries\n\nSome cool libraries we use:\n\n*   [MinecraftAuth by RaphiMC](https://github.com/RaphiMC/MinecraftAuth)\n*   [Deencapsulation by xxDark](https://github.com/xxDark/deencapsulation)\n*   [Forge-CLI by TeamKun](https://github.com/TeamKun/ForgeCLI), which we [customized](https://github.com/3arthqu4ke/ForgeCLI).\n\nHeadlessMc is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3arthqu4ke%2Fheadlessmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F3arthqu4ke%2Fheadlessmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3arthqu4ke%2Fheadlessmc/lists"}