HeadlessMc Documentation

HeadlessMc (HMC) is a command line launcher for Minecraft Java Edition. It is designed to manage clients, servers, and mods from the command line.

A key feature is the ability to run the Minecraft client in 'headless mode' (without a graphical screen), which is useful for automated testing in CI/CD pipelines (e.g., using mc-runtime-test).

Running HeadlessMc in a browser is experimental and limited:

• CheerpJ: A WebAssembly JVM approach. A demo is available at https://headlesshq.github.io/headlessmc/, but it does not support all features required for full game launching.
• container2wasm: Translates the Docker container to WebAssembly. This method is functional but extremely slow.

The gui command only shows structured UI elements (buttons, text fields). To see text that is rendered directly on the screen but not part of a formal GUI element (such as potion effects, coordinates, or floating text), use the render command. It outputs a list of text strings and their x, y coordinates.

> render
{x=97.0, y=6.0, text=Crafting}
{x=358.0, y=62.0, text=Regeneration II}

HeadlessMc-Web is launched via the headlessmc-launcher-wrapper. The process follows these steps:

1. The wrapper calls a custom main function provided by the CheerpJ-Plugin.
2. This custom main function creates a JFrame.
3. Input and output are redirected to the JFrame to provide a functional console within the browser.
4. The HeadlessMc-Launcher is then launched normally.

The headlessmc-lwjgl transformer intercepts calls to org.lwjgl classes. It replaces method bodies with a redirection to the RedirectionApi.

When a method is called, the transformer executes a call structured like this:

public <type> method(<arg>... args) {
    return (<type>) RedirectionApi.invoke(this, "<owner>;method(<arg>)<type>", <type>.class, args);
}

By default, the RedirectionApi returns default values for most data types. For interfaces, it uses java.lang.reflect.Proxy to provide an implementation.

HeadlessMc provides two primary ways to run Minecraft without a graphical interface:

1. LWJGL Patching (Default): HeadlessMc patches the LWJGL library, rewriting its functions to do nothing or return stub values. This method is independent of Minecraft versions but carries some overhead.
2. Optimization Mods (hmc-optimizations): A set of mods that patch Minecraft itself to skip rendering code. This is version-dependent but potentially more efficient.
3. Virtual Framebuffer: You can run HeadlessMc using a virtual framebuffer like Xvfb to avoid patching LWJGL.

Additionally, using the hmc.assets.dummy property helps reduce the memory footprint by replacing assets with dummy files.

HeadlessMc uses a specific syntax for commands, flags, and arguments:

• Arguments: Separated by spaces. To pass an argument containing spaces, surround it with quotation marks ". You can escape characters using a backslash \.
• Flags (on/off switches): Use a single hyphen - (e.g., -flag1).
• Options (key-value pairs): Use two hyphens -- (e.g., --option1 "Value").
• Auto-completion: You can press TAB to complete commands and see available options.
• Help: Use the help command to list all available commands or get details on a specific command.

# Example of argument handling
> "some command"
# Read as: ['some command']

# Example of flags vs options
> command -flag1 -flag2 --option1 "Some option" --option2 1234

HeadlessMc is not an official Minecraft product and is not associated with Mojang or Microsoft.

Important Usage Constraints:

• Account Validation: All accounts will always be validated. You cannot play Minecraft without having purchased it.
• Offline Accounts: Offline accounts are strictly limited to running the game headlessly within CI/CD pipelines.

MC-Runtime-Test supports the Minecraft Game-Test Framework. Upon joining a world, the action automatically executes the /test runall command.

Note for Forge/NeoForge: Discovery of GameTests on Forge and NeoForge may currently require additional setup or modifications to register structure templates correctly.

To ensure a minimum number of GameTests are executed, you can pass a JVM argument via the headlessmc-command input using the following property: -DMcRuntimeGameTestMinExpectedGameTests=1

# Example usage of the JVM argument via headlessmc-command
headlessmc-command: '--jvm "-DMcRuntimeGameTestMinExpectedGameTests=1"'

The Meteor Plugin provides integration between the HeadlessMC launcher and hmc-specifics.

Key features include:

• Meteor Commands: Adds a command to hmc-specifics to execute Meteor commands within the game.
• Launcher Integration: Acts as a plugin for the HeadlessMC launcher, adding a command to download the latest version of Meteor.

The plugin can be found at: https://github.com/3arthqu4ke/hmc-meteor