Xaero's Minimap

Xaero's Minimap

This mod unfolds a detailed tactical map in the corner of your screen, displaying terrain, player movement, biomes, and various entity information in real-time. It grants you the ability to create "waypoints," guiding you back to locations you have visited with ease.

Warning: Do NOT use XaeroPlus with this mod!

Please be aware that XaeroPlus is not developed by me and has no official connection to this mod. This third-party plugin causes hard-to-trace, serious errors and even game crashes. Even more concerning, it is claimed to have ties to certain server-destroying groups, which could put your structures on servers at high risk.

Unlike many similar mods on the market, Xaero's Minimap focuses heavily on maintaining the vanilla Minecraft aesthetic, aiming to be a seamless part of the game interface rather than an abrupt add-on. Notably, it was the first map mod in Minecraft history to adopt a rotating square design. Among its extensive customization options, you can still choose the traditional circular map or set lock map rotation (using directional arrows to indicate orientation instead).

The radar system can accurately display surrounding entities—including players, mobs, and dropped items—as custom-colored dots or icons (usually heads). In addition to providing basic compass orientation, you can deploy your own waypoints, which will be synchronized and rendered both on the minimap and in the game world. Waypoints not only help you return to old locations or reach specific coordinates but also support teleportation. Furthermore, this mod has X-ray capabilities, allowing you to see structures above ground and the deep environment underground (i.e., Cave Mode).

This is just the tip of the iceberg of this mod's many features. To fully understand its potential, please read the "Minimap Features" section below. To adapt to the rules of multiplayer servers, this mod is available in two versions: Full and Fair-play, the latter being designed for fair PVP environments. This mod mainly runs on the client. Installing it on the server is not necessary, but it can unlock additional features such as "world recognition."

Feature Overview

• Perfectly replicates the visual style of vanilla Minecraft.
• Offers multiple minimap size options, including auto-adjustment mode.
• Features multi-level zooming for control over your field of view.
• Two map shapes to choose from: square or circular.
• Excellent performance optimization, with fluidity surpassing most competitors on the market.
• Through the "Change Position" setting, you can place the map in any corner of the screen. It even supports 1-pixel fine-tuning, which is especially practical when coexisting with other UI mods.
• Two block color modes: Vanilla Mode (using vanilla map colors) and Accurate Mode (using tile textures and biome colors directly). You can also enable biome coloring separately in vanilla mode.
• Supports custom keybinds (default is Z) to temporarily zoom in on the map for a clearer view of the surrounding environment. All keybindings are located in the standard control menu. Additionally, you can customize zoom behavior, such as centering the map or automatically switching to maximum zoom level.
• Through "Terrain Depth" and "Terrain Slope" settings, you can customize the map's shadow effects to enhance the sense of dimension.
• Perfectly compatible with Xaero's World Map. By default, it will directly call textures generated by the world map mod rather than reloading them, significantly improving performance when using both mods.
• Supports server-side configuration with an in-game UI. You can monitor and control players' permissions for using the mod on the server in real-time. Supports management based on level/permission systems (xaero.minimap.enforced_server_profile), compatible with FTB Ranks, Odyssey Roles, LuckPerms, and general permission APIs.
• Supports restricting minimap usage by binding it to specific items. For example, adding minimapItemId:minecraft:compass to the configuration file will make the minimap visible only when the player is holding or equipping a compass in their hotbar.
• Introduces a potion effect mechanism to control minimap function permissions for players on servers/maps. Currently supported effects include: xaerominimap:no_minimap (disable map), xaerominimap:no_entity_radar (disable radar), xaerominimap:no_waypoints (disable waypoints), xaerominimap:no_cave_maps (disable cave maps). These effects are neutral by default, but you can specify them as harmful by adding _harmful after the ID (e.g., xaerominimap:no_entity_radar_harmful).
• Has been translated into many languages, breaking down language barriers.
• Supports Lock North option, stopping the map from rotating and using an arrow to indicate the character's facing direction instead.
• Thanks to Auto-Cave Mode, it handles both surface and underground exploration with ease. This mode should also activate automatically when entering buildings. You can customize the "solid roof" size required to trigger cave mode. For example, setting a roof size of 3x3 or larger prevents accidental cave mode activation while cutting down trees.
• Waypoint System. Supports creating an almost unlimited number of waypoints. If you have teleport command permissions, you can teleport directly to a waypoint. These markers will be rendered in the game world and highlighted on the minimap. You can hide all or specific waypoints. Press B to create a new waypoint, press U to list all waypoints. In the list, you can manage single or multiple points, sort them, or view waypoints for other sub-worlds/dimensions.
• Local and Global Waypoint mechanism. To avoid screen clutter, you can create local waypoints limited by a "maximum render distance." This allows you to set a global waypoint for a large area, while having multiple local waypoints within that area. When you go beyond the render distance, only the global waypoint remains visible.
• Waypoint Set Management. You can organize waypoints by grouping them into different "sets" and switch the current set quickly using keybindings. All keybindings are in the standard control menu.
• Waypoint Sharing. You can share your waypoints with other players on the server in the game chat. This is done within the waypoint list (press U).
• Death Markers. Each time your character dies, the system automatically creates a skull-shaped waypoint at the location of death. The old death point will automatically convert to a regular waypoint; if you do not want to keep it, you can disable it via the "Keep old death points" setting.
• Supports displaying claims and allied players from the Open Parties and Claims mod.
• Toggable Chunk Grid. Grid lines will clearly mark the start and end positions of chunks.
• Toggable Slime Chunk mode. Chunks where slimes can spawn will be overlaid in green.
• Custom Light Overlay. You can set a light overlay, marking blocks within a specific light level range (default 0 to 7) with a custom color. This feature was originally for finding monster spawning grounds, but you can use it for any purpose.
• Multi-world detection in multiplayer games. If this mod is also installed on the server, each server world will have its own independent world map and independent waypoint "sub-worlds." If the server-side mod is not installed, a less reliable separation scheme based on the world spawn point is used. If the server has only a "single world," it is recommended to disable multi-world detection. This option is located in the Waypoint Menu (press U) -> Options interface.
• Entity/Mob Radar: Displays mobs on the map as yellow dots. Hostile and friendly mobs can be configured with different colors. It also supports displaying them as icons/heads. Please check the "Entity Radar" settings.
• Player Radar: Displays players on the map as white dots or player heads. Also supports displaying as icons/heads. Please check the "Entity Radar" settings.
• Item Radar: Displays dropped items on the map as red dots. Please check the "Entity Radar" settings.
• Displays all other entities (such as arrows and item frames) as purple dots, with support for disabling specific types of entities in the settings. Please check the "Entity Radar" settings.
• Provides an option in the "Entity Radar" settings to display entity names on the minimap.
• Supports zoom-in and zoom-out keys (default I and O) to efficiently adjust the zoom level to suit your use case.
• Displays Coordinates below the minimap.
• Displays Current Biome Name below the minimap. Disabled by default, needs to be enabled in settings (press Y).
• Displays Light Level below the minimap. Also disabled by default, needs to be enabled manually.
• Displays Current Game Time below the minimap. Disabled by default, supports 12-hour and 24-hour formats.
• Displays Current View Angle below the minimap. Disabled by default.
• Supports a one-key hide/unhide for all waypoint coordinates on the interface, which is very useful for streaming or video recording.
• Supports completely hiding/unhiding all server addresses mentioned in drop-down menus. default is set to "Partially Hidden," which provides sufficient privacy protection in most cases.
• Massive Setting Options. There are so many features that they cannot all be listed here. Please press the Y key in-game to open the settings interface and explore for yourself.
• Two mod versions: Full and Fair-play. The Full version has no feature restrictions. The Fair-play version does not display any entities or cave maps, making it more suitable for PVP combat against players who do not use a minimap.

FAQ

Why does the waypoint teleportation function not work for me?

There are many reasons for this. The mod executes teleportation by sending chat commands, with the default command being /tp @s x y z, so you must have the appropriate permissions. Vanilla /tp commands usually require administrator permissions (cheats enabled), but on non-vanilla servers, you may have separate command permissions through specific plugins. If the command does not match, you can change it in the "Default Teleport Command" option in the Minimap settings, or in the "Teleport Chat Command" option in the Waypoint menu (for specific servers). Non-vanilla teleport commands do not usually support selectors like @s, so you may need to remove it from the configured command. Additionally, Right-click teleportation on the World Map uses a different set of independent settings; please refer to the FAQ on the World Map description page for details.

If the "Teleport" button is greyed out and disabled, this also suggests several possibilities. The most common reason is that you are trying to use a waypoint that does not belong to the current "auto" sub-world, but belongs to the same dimension. If the current "auto" sub-world is not the one you should be using, please manually select the correct sub-world and click "Make Sub-world Auto" in the Waypoint menu options. This will swap the data for the two sub-worlds, allowing you to teleport to the waypoints now under the "auto" sub-world.

If the "auto" sub-world selection is correct but the button is still disabled, it is likely that the server or world has manually disabled the teleport function. Please check the teleport switch in the Waypoint menu options. If it is indeed disabled, you can only enable it by modifying the server-specific configuration file in the xaero/minimap (old version XaeroWaypoints) folder in your game directory. It is highly recommended to exit Minecraft before editing any configuration files and to make a habit of regular backups.

Why did my waypoints mysteriously disappear on a particular server?

Stay calm; your data is almost certainly not deleted. If you are also using the world map mod and the map has also been reset, please be sure to first follow the “Why did my world map ‘reset’ on a particular server?” section in the World Map description page FAQ for recovery. If you have completed that step, please continue reading.

First, press the U key to open the full Waypoint menu (if the U key does not work, please check the vanilla control settings). Browse the sub-worlds listed in the dropdown menu in the top right corner. All waypoint sub-worlds for the current server address should be listed here. If none of them contain data for the dimension you are currently in, then the server address has likely changed. Please find the old server address in the dropdown menu in the top left corner, select it, then execute Options -> Make World/Server Auto. At this point, you should be able to find the correct sub-world in the menu in the top right corner. If this sub-world is already marked as (auto), it means it has been automatically selected, and the problem should be resolved. If the one marked as (auto) is the incorrect sub-world, please continue reading.

<ins>Using the World Map mod?</ins>

One of the most common reasons an incorrect sub-world is automatically selected is failing to correctly use the world map mod in multiplayer (since version 1.6). Be sure to select the correct map for the current world before verifying, as this directly determines which waypoints are visible to you. The map selection menu is located at the bottom-left icon of the world map interface (unless opened by default). If the server environment allows, it is recommended to change the map selection mode to one of the automatic modes.

The map you currently have confirmed determines which waypoint sub-world is treated as "auto." This allows every created map to have independent data. At any time, you can view non-auto sub-worlds via the dropdown list in the top right corner of the Waypoint menu (press U). To bind any sub-world to the current map and set it as auto, select Options -> Make Sub-world Auto.

<ins>Not using the World Map mod?</ins>

If the incorrect sub-world is treated as (auto) and automatically selected, this is usually because a server plugin has changed the behavior of the vanilla compass, interfering with the mod's "multi-world" detection function (if this feature is enabled; it is off by default). In such cases, the compass usually points to the player's bed location rather than the world spawn point. If sleeping in another bed caused the waypoints to disappear, simply sleeping back in the original bed usually fixes the issue.

If this is due to a newly added plugin (and the plugin cannot be removed), you can recover your waypoints by following these steps:

1. Find the correct "sub-world" containing the data you need in the dropdown menu in the top-right corner of the waypoint interface (try Main World first).
2. Use Options -> Make Sub-world Auto.
3. Repeat this for every dimension (you must enter the corresponding dimension before performing this operation!).
4. If this is a simple single-world server (no lobby worlds, mini-game worlds, creative plot worlds, etc.), please disable "Multi-world Detection" in the same Options menu. You can re-enable it any time later if needed.

If in doubt, feel free to contact me!

How do I add custom entity icons or override default ones?

Prerequisite: Please ensure you have enabled entity icon/head display in Minimap Settings -> Entity Radar category, whether set to "Always" or "Player List". You must first know how to display them for this section to be meaningful to you.

Starting from mod version 21.6.0, you can override default entity icons with custom sprites/images by creating a resource pack (or including it in your own mod). Additionally, you can add or improve support for entity variants (where the same type of entity has different looks with different icons) by writing a simple mod or code. However, for most simple multi-variant entity types, this is usually unnecessary.

By default, the minimap mod uses the renderer/model bound to the entity to render all icons. This supports all vanilla mobs and simple bipedal/quadrupedal mobs where the head model parts are easily identifiable (e.g., head, ears, nose, etc.). If the mod cannot identify it, it will fall back to displaying a colored dot.

The relevant resource directory for overriding icons is located at /assets/xaerominimap/entity/icon/. You can find this path in the mod's jar file and extract the files for reference. The jar package contains an example file /assets/xaerominimap/entity/icon/definition/example_mod/example_entity.json, demonstrating how to override icons for modded entities. This file corresponds to a hypothetical entity type example_mod:example_entity. Please read the comments in example_entity.json carefully to understand its structure and create your own icon definition file.

Additionally, the /assets/xaerominimap/entity/icon/definition/minecraft/ directory contains multiple example files for vanilla entity types, which may contain additional explanations regarding default entity variant support. By default, entity variant support is very simple; the variant ID is simply the main texture resource location of the entity.

If you set the debugEntityVariantIds option to true in the minimap configuration file, the variant IDs of newly encountered entities (variants) will be printed in the chat and log/console.

Starting from version 21.8.0, you can also configure custom model-based rendering. Please read the comments in the example file /assets/xaerominimap/entity/icon/definition/example_mod/example_entity.json to get all the information you need.

If you want to see actual use cases of custom icons or use them directly, check out this wonderful project by babybluetit: https://www.curseforge.com/minecraft/texture-packs/xaeros-minimap-modded-support

How do I disable Cave Mode and/or Entity Radar on my server?

To achieve this, install this mod on the server (currently requires NeoForge/Forge/Fabric/Quilt server).

If your minimap version is at least 25.3.0, please set and use the "Minimap Server Settings" keybind to open the server settings interface. You can enforce almost any option there, including Cave Mode, Entity Radar, and even create custom Entity Radar categories.

In older versions of the mod, when you start the server, a new "common" configuration file is usually generated in the server directory's (not the world folder) config folder. In that file, you can find multiple options to disable specific mod features for players. Changes require a server restart.

Alternatively, if you cannot install this mod, you can send server/system messages to players upon login containing the following strings; these hidden codes will trigger the corresponding features:

§f§a§i§r§x§a§e§r§o - Force the client to disable Cave Mode (including world map) and Entity Radar (Fair-play mode).

§x§a§e§r§o§m§m§n§e§t§h§e§r§i§s§f§a§i§r - Allow Minimap Cave Mode to work in the Nether, even in Fair-play mode. The World Map has a nearly identical, separate code.

§n§o§m§i§n§i§m§a§p - Completely disable the Minimap.

§r§e§s§e§t§x§a§e§r§o - Reset all system message flags.

There is a third-party Spigot plugin that simplifies this (not made by me): XMMForceFairPlay And a third-party data pack with similar functionality (not made by me): Xaero's Map Server Utils Use any third-party plugins at your own risk.

How can a server with the mod installed allow vanilla client players to join?

Please locate the "common" configuration file in the config folder under the server directory (not the world folder), usually at config/xaero/minimap. There is an option allowing you to disable status effect registration; it is this status effect registration that prevents vanilla players from joining. Changes require a server restart. If you are using the World Map mod, please do the same.

Developer Guide

To hook your mod into this mod, first add the following repository to your build script:

repositories { 
    maven { 
        url "https://chocolateminecraft.com/maven" 
        name "Xaero's Maven" 
    } 
} 

If you are using Forge, ensure you have applied the Mixin gradle plugin (org.spongepowered.mixin) to your project, unless your version is 1.12.2.

Finally, add one or more of the following dependency declarations, replacing <minecraft version> and <mod version> with the actual values shown on the https://chocolateminecraft.com/maven/xaero/minimap page.

Forge (using official Mojang mappings before 1.21.1):

implementation "xaero.minimap:xaerominimap-forge-<minecraft version>:<mod version>:dev"//Intentionally not deobfuscated! 

Forge (using official Mojang mappings for 1.21.1 and later):

implementation "xaero.minimap:xaerominimap-forge-<minecraft version>:<mod version>" 

Forge (using other mappings):

implementation fg.deobf("xaero.lib:xaerolib-forge-<minecraft version>:+") 
implementation fg.deobf("xaero.minimap:xaerominimap-forge-<minecraft version>:<mod version>") 

Fabric:

modImplementation "xaero.minimap:xaerominimap-fabric-<minecraft version>:<mod version>" 

NeoForge:

implementation "xaero.minimap:xaerominimap-neoforge-<minecraft version>:<mod version>" 

In the "common" project of a multi-loader setup:

compileOnly "xaero.minimap:xaerominimap-common-<minecraft version>:<mod version>"