How it works

What it doesn't solve

This plugin doesn't provide full feature support for VoxelMap, JourneyMap and Xaero mods.

That being said, MapModCompanion doesn't provide the following features:

• Updating maps from the server,
• and sharing them between players;
• Custom waypoints and markers;
• Admin menu;
• Limiting or changing client features (#2), like:
• • disabling mob or player visibility;
• • disabling mini map whatsoever.

If you want full support, you may want to switch to Forge/Fabric and then install these mods on the server side. If you do this, you will lose Bukkit plugins support. Well, unless you're experienced enough to switch to something like Banner or Cardboard and willing to contribute to these projects.

What it does solve

In Bungeecord/Velocity-style networks that consist of multiple servers, players may face an issue with mods like VoxelMap, JourneyMap, along with Xaero's Minimap and WorldMap. These mods sometimes struggle to accurately identify the current world of the player. This causes data from one dimension to erroneously appear in another. For instance:

1. When accessing a saved map, a player might see chunks from a dimension they are not currently in.
2. Waypoints that don't belong to the player's current dimension might become visible.

Developers behind these mapping mods are aware of these issues. To solve the problem, these mods communicate with their counterparts on the server.

The issue is that all the mods mentioned above use Forge or Fabric APIs. They are not compatible with Bukkit (Spigot/Paper) servers, so you can't install these mods there. Without their matching server-side parts, the map mods have to use alternative algorithms to tell one world apart from another. And these algorithms sometimes fail.

MapModCompanion is built using the Bukkit API and it knows how to interact with JourneyMap, VoxelMap and Xaero's mods.

More technical explanation

MapModCompanion communicates with compatible mods using Plugin channels.

world_id channel

Recent versions of JourneyMap and VoxelMap have been utilizing the worldinfo:world_id channel to query the world's identifier where the player is currently located. If a server-side mod to this query is installed, it replies the client with the necessary identifier.

Even though both VoxelMap and JourneyMap use the same channel, the structure of their packets differs across versions. The creator of this plugin, turikhay, suggested to the VoxelMap developers (accept Discord invite first, link to the first message) that they adopt a unified standard. Since one of the releases for 1.19.2, VoxelMap for Fabric has been using the same format as JourneyMap.

Xaero's mods

Xaero's mods (both Minimap and WorldMap) utilize their own channels to send world information using a structure called LevelMapProperties. At the time of writing, this structure's contains only one field, id, which serves a similar purpose to that of the worldinfo:world_id.

Xaero's mods don't follow the standard request-response pattern commonly used in such scenarios. The server side of the mod sends the world identifier to the client as soon as the client starts listening to this channel. Due to limitations, when we're behind the proxy we can't tell which channels the client has registered, so we send the LevelMapProperties packet to all clients.

Why you should install the plugin on the proxy side

Although the plugin works well when installed only on downstream servers, we recommend installing it on the proxy side as well.

The algorithm used to determine the world identifier is prone to collisions. Sometimes, two worlds within the same server network may end up having the same identifiers. This could happen, for instance, if the same level.dat is used to create worlds on different servers. To prevent this from becoming an issue for players (and therefore, server administrators), I've developed a separate plugin for BungeeCord/Velocity. Its principle is simple: it "mixes" the server name to the id that was sent from the downstream server. This effectively reduces the collision probability to zero.

If a downstream server is running on the Fabric or Forge platform and has mentioned mapping mods already installed, the plugin shouldn't cause any issues. The plugin will simply pass through data it doesn't understand "as is".