Repository navigation
Installation and Compatibility
| Matcha release | Required Minecraft | Notes |
|---|---|---|
| 1.03 | 26.2 | Supported by the same Companion JAR |
| 1.12 | 26.2 | Supported by the same Companion JAR |
| 1.12.5 | 26.2 | Uses upstream's recommended 1.12.3 resource assets |
| 1.12.7-beta | 26.3 | Targets this specific upstream beta |
Support for nearby version numbers, other betas, or additional Minecraft versions is not implied. A future Matcha release can change item components, models, translations or data structures, so it must be checked before being added.
- Install the supported Minecraft version, Fabric Loader 0.19.5 or newer, and Java 25 or newer.
- Install Fabric API, YetAnotherConfigLib (YACL), Mod Menu, and MezzConfig GUI, each for your Minecraft version.
- Put one Companion JAR in the client's
modsfolder. Remove older Companion copies. - Install supported Matcha gameplay data using its official Fabric mod JAR or a world datapack ZIP/folder.
- Open Companion settings to confirm the detected version after entering the world.
JEI and its MezzConfig library are included. MezzConfig GUI supplies JEI settings screens and is still an external required dependency. YACL builds Companion settings screens; Mod Menu provides access from the mod list. These dependencies are installed separately.
Do not install a second full Matcha resource pack just to obtain its artwork: the Companion already includes it. A separate full pack can override the Companion's optional visual choices. With the official Matcha mod, the fixed client resource pack is replaced by Companion-controlled artwork; the gameplay data is preserved.
World datapack: put the supported ZIP/folder in the world's datapacks directory and enable it using Minecraft's normal datapack controls. Its metadata identifies the Matcha version, so merely renaming the ZIP does not select a different version.
Official mod: install the supported official Matcha mod in the appropriate mods directory. The Companion recognises its supported version automatically. It does not turn an unsupported Matcha mod into a supported one.
Both present: an enabled Matcha world datapack takes detection priority over the installed Matcha mod. This selects Companion compatibility; Minecraft still controls which gameplay packs are loaded. Avoid enabling conflicting gameplay installations and assuming the Companion merges them.
The current world determines the gameplay catalogue and matching assets. Joining a different supported world updates the selection without restarting Minecraft. Leaving a world clears its gameplay selection, preventing the old catalogue from carrying over into a vanilla or unsupported world. Asset reloads can take a moment after world transitions settle.
Visual settings and personal presets belong to the client installation. Automatic profile selection is per world; the individual visual preferences are not separate configuration files for each world.
From 1.4.2, enabled interface visuals are available on the first title screen. A supported installed Matcha mod supplies the menu artwork version; otherwise the latest supported profile for the running Minecraft version supplies it. This is presentation only, and does not claim to have detected a world's Matcha gameplay.
Required translations and font glyphs remain available independently of optional visual settings. Selecting Vanilla visuals does not intentionally expose translation keys in welcome or difficulty messages.
Install Matcha gameplay data on the server. Each player wanting the Companion installs it and its dependencies on their own client. Clients cannot read the server's datapack ZIP directly, so remote detection uses an unambiguous supported signature in synced Matcha content. Unknown or ambiguous content leaves the gameplay catalogue inactive instead of guessing or retaining the previous world's selection.
JEI recipe discovery is verified in singleplayer. Multiplayer results depend on which recipe information the server supplies; the Companion cannot make unavailable server recipes discoverable by itself.
Guide for Companion 1.4.2 · Downloads · Report a Companion issue