# squaremap puts a live top-down map of a Minecraft server in a browser

> squaremap is an MIT-licensed Java plugin and mod that renders your Minecraft world as a vanilla-style 2D map in any web browser, with player markers showing rotation, health and armor, on Paper, Fabric, NeoForge and Sponge. It ships as a plugin jar with a Leaflet front end, and it publishes a small API for other plugins to draw on the map.

**jpenilla/squaremap** — squaremap is a minimalistic and lightweight world map viewer for Minecraft servers, using the vanilla map rendering style

- Repository: https://github.com/jpenilla/squaremap
- Website: https://modrinth.com/plugin/squaremap
- Stars: 520 · Forks: 83
- Language: Java
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jpenilla-squaremap

## What the plugin does and where it runs

squaremap is described as a minimalistic and lightweight live world map viewer for Minecraft servers, and the mechanism is that it hooks into your server as a plugin or mod on a supported platform, then generates and manages a live map of your server that you can view in any web browser. The word live is the important part, because the alternative is a map that is rendered on demand by the player's own client, and the reason an operator wants this instead is that it works for any visitor to a browser, including one who will never install anything. The feature list is short and concrete: ultra fast render times with the promise that you get your map rendered today rather than next week, a simple vanilla-like top-down 2D view designed for navigation, and player markers that show yaw rotation, health and armor, so you can see where someone is and which way they are facing.

## The four supported platforms, and why they matter

The supported platforms are Paper, Fabric, NeoForge and Sponge, and the mod-based ones carry an extra requirement, with Fabric requiring the Fabric API. The topic list in the repository also names the packaging formats, a fabric-mod, a minecraft-mod, a paper-plugin, a neoforge-mod and a sponge-plugin, which tells you this is a single codebase that ships as several artefacts rather than one project per platform. The repository layout matches that, with separate fabric/, neoforge/, paper/ and sponge/ directories alongside common/ for the shared code, api/ for the public interface, build-logic/ for the Gradle convention plugins, and web/ for the front end. It is a fairly large build for a plugin, but that is the cost of one codebase covering four loaders rather than four near-duplicate projects.

## The front end and the addons

The web side is Leaflet, and the README notes that the front end is kept up to date and that Leaflet itself is licensed under the 2-clause BSD licence, separately from the plugin's own MIT licence. Two things follow from that. First, the browser page is not a custom map engine, which is why the plugin can claim lightweight rendering, because the heavy lifting of drawing tiles is a well-optimised library rather than something this project maintains. Second, the addons and integrations directory in the wiki is where squaremap earns its keep for a server that already runs a plugin ecosystem, because the integration point is that a plugin declares markers or shapes and squaremap renders them. The wiki also holds the installation and default configuration pages, so the actual setup instructions live outside the repository.

## The API, and how another plugin draws on the map

squaremap provides simple APIs to draw markers, shapes and icons on rendered maps, and the Javadocs are hosted on the Maven repository alongside the binaries, so an IDE should download them automatically. Releases are published to Maven Central, which means the dependency is a normal library reference rather than something you have to shade or install by hand. The Maven coordinates are:

```xml
<dependency>
    <groupId>xyz.jpenilla</groupId>
    <artifactId>squaremap-api</artifactId>
    <version>1.4.3</version>
    <scope>provided</scope>
</dependency>
```

and the Gradle form is:

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    compileOnly("xyz.jpenilla", "squaremap-api", "1.4.3")
}
```

The provided scope in the Maven form and compileOnly in the Gradle form both say the same thing: the API classes are supplied by the squaremap plugin at runtime, so your plugin should not bundle them. Snapshot builds are available on the Sonatype snapshots repository, which is where you would look if you need to build against a change that has not been released yet.

## Building it from source

Building has two halves, and the README separates them clearly. The prerequisites are an up-to-date JDK, meaning Java 21 or later, and Bun installed for building the web UI, and the first step is to run bun install in the web directory to pull in the web UI dependencies. The plugin itself is built by invoking the build task with Gradle:

```bash
./gradlew build
```

The web UI is built automatically and included in the plugin jar by Gradle when the plugin is built, so the Bun step is a prerequisite rather than a separate deliverable. There is a development convenience on top of that. When you use the various run tasks, such as :squaremap-paper:runServer, Gradle passes the squaremap.devFrontend=true and squaremap.frontendPath properties, with the path being an absolute path to the web directory, and the plugin then runs the Vite dev server and proxies requests to it, which is what makes hot module reloading work while you work on the front end.

## Where squaremap is the wrong choice

Three cases. The first is a server that wants a three-dimensional world view or a heightmap, because squaremap is explicitly a simple vanilla-like top-down 2D view designed for navigation, and the plugins that do render heightmaps are a different project with a different cost. The second is an operator who cannot run a separate web build step, since the front end is a Bun project that has to be compiled and then bundled into the jar, which makes the build heavier than a pure Java plugin even though the result is a single jar at runtime. The third is a server on a platform outside the four listed, because adding a loader means writing and maintaining another integration rather than a configuration change. Against the heavier mapping plugins, the difference in approach is that squaremap renders server-side into tiles the browser fetches, so the cost falls on the server and the client stays light, and the price of that trade is the 2D top-down view with no height information.

## Conclusion

squaremap is a good fit for a server that wants a browsable map of its world without asking players to install a client mod, and for an operator who has been running a heavier mapping plugin and wants the render to be fast and the page to be small. It is a poor fit if you need the 3D or heightmap views that the heavier plugins provide, since the whole design is a simple vanilla-like top-down 2D view for navigation. Check three things before you install it: that your server platform is on the supported list, since Paper, Fabric with the Fabric API, NeoForge and Sponge are named and each needs its own build, and that your web UI dependencies can be built with Bun, because the front end is compiled separately and then packaged into the plugin jar; and that you read the configuration page rather than assuming defaults, since the setup and configuration both live in the project wiki rather than in the README.

## FAQ

### What is squaremap?

It is a minimalistic and lightweight live world map viewer for Minecraft servers, written in Java, that hooks into the server as a plugin or mod on a supported platform and generates a map of your server viewable in any web browser. It uses the vanilla map rendering style.

### Which Minecraft platforms does squaremap support?

Paper, Fabric, NeoForge and Sponge, with Fabric additionally requiring the Fabric API. The repository ships separate directories for each of those loaders alongside common/ for the shared code, and downloads come from Modrinth.

### How do I add squaremap markers from another plugin?

squaremap provides simple APIs to draw markers, shapes and icons on rendered maps, with Javadocs hosted on the Maven repository alongside the binaries. You depend on the squaremap-api artifact with a provided or compileOnly scope, since the classes are supplied by the plugin at runtime.

### How do I build squaremap from source?

You need an up-to-date JDK, meaning Java 21 or later, and Bun. Run bun install in the web directory to install the web UI dependencies, then run ./gradlew build, which also builds the web UI and includes it in the plugin jar.

### What does squaremap show about players?

Player markers showing yaw rotation, health and armor. The map itself is a simple vanilla-like top down 2D view designed for navigation, and the front end is Leaflet, which is licensed under the 2-clause BSD licence while squaremap itself is MIT licensed.

## Sources

- [Issues](https://github.com/jpenilla/squaremap/issues)
- [jpenilla/squaremap on GitHub](https://github.com/jpenilla/squaremap)
- [Project website](https://modrinth.com/plugin/squaremap)
- [README](https://github.com/jpenilla/squaremap/blob/master/README.md)
- [Releases](https://github.com/jpenilla/squaremap/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jpenilla-squaremap