How to Use ImageOnMap on a Minecraft Server

Overview

Minecraft builds already have paintings, signs, banners, plants, and plenty of other decoration options. ImageOnMap adds a more direct choice: turn an online image into an in-game map, then place it in item frames. That can be custom artwork, a server logo, a diagram for a minigame lobby, or a picture that absolutely should not have taken twelve item frames but somehow did.

ImageOnMap works on plugin-based server software such as Spigot, Paper, Purpur, and similar forks. After installation, players can run commands that fetch an image URL and convert it into one or more maps. Larger images can be split across multiple maps, which lets you create wall-sized displays when a single map is too small.

This guide covers downloading ImageOnMap, installing it through your server panel, creating maps from image URLs, managing saved maps, adjusting permissions, changing configuration settings, and fixing common problems.

Downloading ImageOnMap

1. Open the ImageOnMap plugin page on Spigot.
2. Click Download Now near the top-right area of the page.

1. Save the plugin `.jar` somewhere easy to find, such as your desktop or downloads folder.

Use a plugin build that matches your Minecraft version. Servers on Minecraft 1.17 and newer should generally use the latest available ImageOnMap release. Minecraft 1.14 through 1.16 servers need the 4.1 build, Minecraft 1.13 needs 4.0-pre1, and older servers may require 3.1 for proper support. To find those older files, use the Version History section on the plugin page and download the matching release.

Installing the Plugin

Before uploading ImageOnMap, make sure your server is running Spigot, Paper, Purpur, or another plugin-compatible server type. Vanilla Minecraft does not load Bukkit-style plugins. In your server panel, use the version selector to choose the server type and Minecraft version you want, then restart once so the server can generate its folders.

After the server files exist, install ImageOnMap with these steps:

1. Open your server panel and connect via FTP.

1. Enter your password, then log in.

1. Open the `plugins` folder.
2. Click Upload and drag the ImageOnMap `.jar` file into the upload area.

1. Wait until the upload reaches 100 percent.
2. Return to the main server page and restart the server.

Once the restart finishes, ImageOnMap should create its own plugin folder and load its default settings.

First Use

By default, ImageOnMap is designed so players can start creating image maps quickly. On many setups, standard players can use the main commands immediately. If your server needs stricter control, such as only letting staff create or delete maps, configure permissions with a plugin like LuckPerms.

Before running commands, prepare a direct image URL. ImageOnMap needs a link to the image file itself, not a webpage that contains the image. Good links usually end in `.png`, `.jpg`, or `.jpeg`. Avoid unsupported formats such as `.webp`, and avoid extremely long links with extra tracking strings whenever possible.

Choosing a Valid Image URL

Find the image you want to place on a map, then copy its direct file URL. If you created the image yourself, upload it to a service that provides direct image links. Imgur and similar image hosts are common choices, though any reliable host can work if the URL points straight to a supported image file.

If a command fails, the URL is one of the first things to check. A link ending in a valid file extension is a much better candidate than a long page URL full of symbols, redirects, and mystery parameters.

Creating Image Maps

ImageOnMap provides two common command styles:

• `/tomap [URL] [resize]`
• `/maptool new [URL] [resize]`

For Minecraft 1.17 and newer, `/maptool new` is usually the better option. Both commands use the same basic idea: provide the image URL, then define how large the map display should be.

For example:

`/maptool new https://example.com/image.png resize 1 1`

That creates a one-map version of the image. The `resize 1 1` part means the output should fit into a single map. For larger displays, increase the numbers:

`/maptool new https://example.com/image.png resize 4 4`

That creates a 4 by 4 map display, requiring 16 item frames. Bigger displays can look sharper, but they also use more item frames and more map data. Use large sizes carefully on busy servers, since a giant wall of maps can affect performance in crowded areas.

ImageOnMap also supports resizing modes such as `resize-stretched` and `resize-covered`. These can help with certain image shapes, but the normal `resize` option is usually easier to predict.

Placing and Removing Displays

After generating a map set, place item frames in the same layout as the map size you created. For a 3 by 3 display, place 9 item frames. For a 4 by 4 display, place 16 item frames.

To apply the image, right-click the bottom-left item frame with the generated map. ImageOnMap should fill the connected item frames with the correct pieces of the image. To remove the display, shift + left-click the map area.

Managing Saved Maps

Use `/maps` to open the ImageOnMap management menu. From there, players can view saved maps and select the one they need. Right-clicking a map entry reveals extra actions, such as renaming, deleting, or taking individual parts from a larger image.

This menu is convenient, but it is also a reason to think about permissions. If every player can manage every map, someone may remove or rename displays they should not control. That is not a technical disaster, but it can become an administrative headache with better graphics.

Permissions and Access Control

Server owners often limit ImageOnMap when players create too many displays or when maps are used in protected builds. LuckPerms is a good way to control who can create, manage, or delete image maps.

Check the ImageOnMap documentation or plugin page for the current permission nodes for your installed version. Then assign the permissions to groups such as owner, admin, builder, or trusted players. If you want to remove default access, deny the relevant nodes for regular players and grant them only to the groups that should use the plugin.

Editing the Configuration

ImageOnMap settings are stored in its plugin folder. Use the configuration file to adjust limits such as map size, allowed behavior, and other plugin options. Follow the file's existing YAML formatting closely. YAML is picky, and it will complain about spacing like it has a clipboard and a grudge.

1. Connect via FTP in your server panel and log in.
2. Go to `plugins/ImageOnMap`.

1. Find `config.yml` and click Edit.

1. Make your changes, then click Save.

1. Restart the server so the new settings load.

Common Problems

If ImageOnMap does not load, first confirm that the server is running Spigot, Paper, Purpur, or another plugin-compatible server type. Also check that the plugin build matches your Minecraft version. A plugin made for newer versions may not work correctly on an older server, and older builds may break on newer releases.

If the plugin file was uploaded incorrectly, delete the failed upload from the `plugins` folder, upload the `.jar` again, wait for the transfer to finish, then restart the server.

If image generation fails in chat, inspect the URL. It should point directly to a supported image file such as PNG or JPG. Remove unnecessary query strings when possible, and confirm the link can be opened in a browser without signing in.

If only large images fail, try a smaller resize value first. A 1 by 1 or 2 by 2 test can confirm whether the plugin and URL work before creating a much larger wall display. For version-specific errors, switch to the ImageOnMap build recommended for your Minecraft version: 4.1 for 1.14 through 1.16, 4.0-pre1 for 1.13, 3.1 for older versions, or the latest release for modern servers.

Useful Links

• ImageOnMap on Spigot
• How to add plugins to a Minecraft server
• LuckPerms setup guide
• Minecraft server operator guide