The add-on API for the Mosaic Minecraft client.
xyz.mosaicmod:mosaic-sdk
Work in progress. This is published so the contract is visible and reviewable, not because it is finished. The API will still change and breaking changes before 1.0 should be expected.
The Mosaic client itself is not open source yet. This repository is only the public surface that add-ons compile against; the client implementing it is still being built in private. Until it ships there is nothing to load an add-on into, so treat this as a preview of the API rather than something to build a released add-on on top of.
A plain Java 21 library with zero dependencies. It contains no Minecraft, Fabric, Loom, Stonecutter or Dear ImGui code and never imports a client class. That separation is the whole point: the client stays free to change its rendering, platform and persistence internals without breaking anything built against this.
An add-on is a JAR in .minecraft/mosaic/addons/ with a mosaic-addon.json at its root and a
class implementing MosaicAddon.
- docs/ADDONS.md — the full guide: project setup, manifest, features, settings, events, keybinds, HUD, commands, notifications
- example/ — a working reference add-on
- docs/adr/ — why these contracts live here instead of in the client
An add-on is arbitrary code running in the game process, with the same access to files, network and JVM state as the client. The SDK is an API, not a security boundary, and Mosaic does not claim otherwise.
./gradlew build # compile, test, javadoc
./gradlew publishToMavenLocal # consume from a local client checkout