# Rift Ranked — Tier Tagger installation

Compatibility note: this guide documents the existing v1.1.1 release, which
still appears in Minecraft as Emerald Tier Tagger and uses its original
mineral icons. The website now uses the Rift Ranked hierarchy. Download
filenames, commands and the Mod Menu entry below are intentionally unchanged.

Client-side tags using the Rift Ranked leaderboard, with optional
Mod Menu settings and compact Minecraft-inspired pixel icons:

`[#1] [High Diamond] PlayerName [High Lapis · Sword]`

The main tier appears left of the name, the highest individual subtier appears
right, and the number is the **overall leaderboard position**, not the point total.
This example shows text mode. By default, mineral and kit names use item icons.
Minerals retain an **L / M / H** letter for Low / Mid / High; Emerald has no
division. Labels use the website's colors and item icons retain their own
colors. Tags also appear in the Tab player list.
Unranked players keep their normal names. Names, server formatting and vanilla
name-tag visibility are preserved; this mod does not reveal hidden players.

## Install

1. Install Fabric Loader for the Minecraft version you play.
2. Install Fabric API for that same Minecraft version.
3. Put **one** matching Emerald Tier Tagger JAR in that instance's `mods` folder.
4. Start the game. No site login or server-side mod is required.
5. For the settings screen, also install the matching **Mod Menu** version.

| Minecraft | Mod JAR | Java | Loader |
| --- | --- | --- | --- |
| 1.21.11 | `emerald-tier-tagger-1.1.1+mc1.21.11.jar` | 21+ | 0.18.1+ |
| 26.2 | `emerald-tier-tagger-1.1.1+mc26.2.jar` | 25+ | 0.19.3+ |

Replace an older Emerald Tier Tagger JAR; do not keep both versions installed.
Existing layout preferences are retained when upgrading.

Fabric: https://fabricmc.net/use/installer/

Fabric API: https://modrinth.com/mod/fabric-api

Mod Menu: https://modrinth.com/mod/modmenu

Built against Mod Menu **17.0.1** for 1.21.11 and **20.0.3** for 26.2.
Mod Menu is optional; the commands still work without it. Cloth Config is not
required.

## Configure in game

Open **Mods → Emerald Tier Tagger → Configure**. The screen includes a live
sample, independent tier/kit icon toggles, side swapping, rank position,
highest-kit visibility, the master tag switch, ranking refresh, and reset
defaults. Changes save immediately; Done or Escape returns to Mod Menu.

Turn **Tier icons** off for full mineral/division names. Turn **Kit icons** off
for full kit names. Both can be changed separately. **Highest kit** controls
whether the kit appears at all.

Icons use original static sprites bundled with this mod through its own bitmap
font. They are independent of resource-pack replacements for Minecraft item
textures, so animated gold/iron items cannot squash the icons into narrow strips.
No external icon pack is needed. Sword uses a diamond sword, UHC a golden apple,
SpearMace a single crossed spear-and-mace emblem,
Pot a potion, NethPot a netherite helmet and potion, and HT Cart a TNT minecart.

These commands run locally. No admin/operator permission is needed.

| Command | Action |
| --- | --- |
| `/emeraldtiers` | Connection status and command help |
| `/emeraldtiers swap` | Swap main tier and highest subtier sides |
| `/emeraldtiers position` | Show/hide the overall position number |
| `/emeraldtiers kit` | Show/hide the highest subtier's kit |
| `/emeraldtiers tiericons` | Switch mineral icons/full tier names |
| `/emeraldtiers kiticons` | Switch kit icons/full kit names |
| `/emeraldtiers enabled` | Enable/disable all added tags |
| `/emeraldtiers refresh` | Request a fresh leaderboard; 15-second cooldown |

All six setting commands also accept `true` or `false`, for example
`/emeraldtiers swap true`. Defaults and changes are stored in
`config/emerald-tier-tagger.json`. Edit that file while the game is closed.

```json
{
  "enabled": true,
  "swapSides": false,
  "showOverallPosition": true,
  "showHighestKit": true,
  "useTierIcons": true,
  "useKitIcons": true
}
```

## Data and ranking rules

The mod downloads one public leaderboard snapshot at startup and every five
minutes, using HTTPS. Refreshes run in a background thread; rendering never
waits for a network request. The server may cache a snapshot for 60 seconds.
It sends no Minecraft account token, password, current server address, or list
of players in your world. The endpoint receives a normal HTTP request and IP
address, like a website visit.

https://emerald-tiers.emerald-rankings.workers.dev/api/mod/tiers

The endpoint reuses the website's calculation: Main Tier counts twice, six
subtiers count once each, and overall points have a 200-point ceiling. Equal
scores share leaderboard positions. Highest-subtier ties use this stable kit
order: Sword, UHC, SpearMace, Pot, NethPot, HT Cart. A missing main tier or
subtier is simply omitted.

Java UUID matching takes priority, so recorded tiers follow renamed players.
Case-insensitive name matching is a fallback, including the standard `.`
Floodgate prefix for Bedrock players visible from a Java client. Custom server
prefixes/nicknames without a matching UUID may not resolve. Tags are cosmetic,
not proof of account ownership or an anti-cheat feature.

On a connection failure, the current session retains its last valid data for
up to 24 hours. On a fresh offline launch, no extra tags appear until a fetch
succeeds. `/emeraldtiers` reports connection status.

## OpenGL / Vulkan

This mod changes only the text components passed to Minecraft's normal
name-tag and player-list rendering. It creates no shaders, graphics buffers,
OpenGL calls or Vulkan calls.

- **1.21.11:** designed for vanilla OpenGL and VulkanMod 0.6.8 for 1.21.11.
- **26.2:** designed for both built-in OpenGL and Vulkan renderers.

Both versions are compiled against their exact Minecraft/Fabric APIs. The
name-tag hook is independent of the graphics backend. Compatibility checks
inspect the matching methods and VulkanMod's entity-renderer mixin. Actual
in-game visual testing on both backends is still needed. Another mod that
replaces the entire name-tag renderer can require additional integration.

## Build from source

Use JDK 25 to build either project. The 1.21.11 JAR targets Java 21 bytecode.
The Gradle wrapper downloads Gradle 9.5.1 from its official distribution.

```powershell
cd mc-1.21.11
.\gradlew.bat build
cd ..\mc-26.2
.\gradlew.bat build
```

macOS/Linux: use `sh gradlew build` in each folder. Output is under `build/libs`.
Install the regular JAR, not the `-sources.jar`. `build` runs `verifyTags`,
which validates identity matching, colors/labels, side swapping, positions,
all icon/text combinations, font resources, configuration migration, and
rejection of incompatible API schemas.

Version 1.1.1 fixes animated item-pack distortion for every tag icon, and combines
SpearMace into one crossed-weapons glyph. All icon and text settings still apply.

Website endpoint source is maintained separately in the Rift Ranked site
repository. The mod archive includes no Minecraft code, mappings, Fabric API,
Mod Menu, vanilla item textures, or VulkanMod. Those projects retain their own
licenses. This is an independent
community project, not affiliated with Mojang or Microsoft.