# Installation

> Add the xis-mvui API to your Gradle build, declare the xis_mvui dependency in your mod metadata and run a dev client with the library.

URL: https://xichil.dev/docs/xis-mvui/v1/getting-started/installation/ · Updated: 2026-11-06 · Applies to: Fabric, Quilt, Legacy Fabric, Forge, NeoForge, MC 1.7.10 - 26.3

By the end of this page your mod compiles against the API, declares its dependency on the library, and
starts in a dev client with the library loaded.

## Prerequisites

- A mod project that builds with Gradle.
- Java 8 or newer as the compile target. The API is compiled for Java 8, so it works on every Minecraft
  version from 1.7.10 to 26.3.

## Steps

### 1. Add the repository and the API

The API jar is `dev.xichil.mvui:xis-mvui-api` on `https://maven.xichil.dev`. Add it as `compileOnly`:

```kotlin title="build.gradle.kts"
repositories {
    maven("https://maven.xichil.dev")
}

dependencies {
    compileOnly("dev.xichil.mvui:xis-mvui-api:1.0.0")
    // Optional: FakeHost, to test your menus in JUnit without Minecraft.
    testImplementation(testFixtures("dev.xichil.mvui:xis-mvui-api:1.0.0"))
}
```

```groovy title="build.gradle"
repositories {
    maven { url 'https://maven.xichil.dev' }
}

dependencies {
    compileOnly 'dev.xichil.mvui:xis-mvui-api:1.0.0'
    testImplementation testFixtures('dev.xichil.mvui:xis-mvui-api:1.0.0')
}
```

> **Warning:** Don't bundle, shade or jar-in-jar the API. The library's mod jar already contains it, and players install
> that jar next to your mod, so bundling it would put a second copy of the API on the class path.

The API has no dependencies of its own and contains no Minecraft classes, so it compiles in any source set,
including code that is shared between loaders (see [Build one mod for every loader](https://xichil.dev/docs/xis-mvui/v1/guides/multiversion-mod/index.md)).

### 2. Declare the dependency

Tell the loader that your mod needs the library mod, whose id is `xis_mvui`:

#### Fabric, Quilt, Legacy Fabric

In `fabric.mod.json`:

```json title="fabric.mod.json"
{
  "depends": {
    "xis_mvui": ">=1.0.0"
  }
}
```

Quilt reads `fabric.mod.json` too. With Mod Menu installed, the mod list's Config button opens your menu with
nothing else to set up.

#### Forge, NeoForge

Forge 1.13.2 and newer, and NeoForge: a dependency entry in `META-INF/mods.toml` (NeoForge 1.20.5 and newer read
`META-INF/neoforge.mods.toml`). Replace `mymod` with your mod id.

```toml title="META-INF/mods.toml"
[[dependencies.mymod]]
modId = "xis_mvui"
mandatory = true
versionRange = "[1.0.0,)"
ordering = "NONE"
side = "CLIENT"
```

```toml title="META-INF/neoforge.mods.toml"
[[dependencies.mymod]]
modId = "xis_mvui"
type = "required"
versionRange = "[1.0.0,)"
ordering = "NONE"
side = "CLIENT"
```

Forge 1.7.10 to 1.12.2 have no `mods.toml`. Put the dependency in your `@Mod` annotation instead:

```java
@Mod(modid = "mymod", dependencies = "required-after:xis_mvui")
```

Use `MultiversionUi.MOD_ID` in place of the string if you like: `"required-after:" + MultiversionUi.MOD_ID`.

### 3. Run a dev client with the library

Your dev client needs the library's mod jar for its loader family. Each one is on the same Maven repository:

| Artifact | Dev client |
| --- | --- |
| `dev.xichil.mvui:xis-mvui-fabric:1.0.0` | Fabric and Quilt, 1.14 – 26.3 |
| `dev.xichil.mvui:xis-mvui-legacyfabric:1.0.0` | Legacy Fabric, 1.7.10 – 1.13.2 |
| `dev.xichil.mvui:xis-mvui-forge-1.7.10:1.0.0` | Forge 1.7.10 |
| `dev.xichil.mvui:xis-mvui-forge-1.8-1.12:1.0.0` | Forge 1.8 – 1.12.2 |
| `dev.xichil.mvui:xis-mvui-modlauncher:1.0.0` | Forge 1.13.2 – 26.3, NeoForge 1.20.1 – 26.3 |

Add it to the dev client the way your build tool adds a mod at runtime only, for example Fabric Loom's
`modLocalRuntime`:

```kotlin title="build.gradle.kts"
dependencies {
    modLocalRuntime("dev.xichil.mvui:xis-mvui-fabric:1.0.0")
}
```

Alternatively, put the release jar in the dev client's `mods` folder.

### 4. Check that it loaded

Start the dev client. The library writes one line to the log when it picks its backend, starting with
`[Xi's Multiversion UI Lib]`:

```text
[Xi's Multiversion UI Lib] UI backend <backend> for <loader> <version>
```

If the line says `No UI backend for …` instead, that combination of loader and Minecraft version isn't
supported. The game and your mod still run; there are just no menus.

## Next steps

- [Your first menu](https://xichil.dev/docs/xis-mvui/v1/getting-started/first-menu/index.md): build a screen and register it.
- [Build one mod for every loader](https://xichil.dev/docs/xis-mvui/v1/guides/multiversion-mod/index.md): if you ship for several loaders or versions.