DOCSEARCHbyAlgolia
Submit Docs

squaremap Documentation

repository·master·Indexed 19 days ago

https://github.com/jpenilla/squaremap

A lightweight, high-performance live world map viewer for Minecraft servers. Compatible with Paper, Fabric, NeoForge, and Sponge, it provides a 2D top-down web view with real-time player tracking. Includes a developer API (squaremap-api) for drawing markers and shapes, and a comprehensive set of administrative commands for managing map rendering, visibility, and configuration.

Tokens
6.9K
Snippets
25
Records
35
Agent score
67%

What's inside squaremap

  1. What is squaremap

    master
    squaremap is a minimalistic and lightweight live world map viewer for Minecraft servers. It functions as a plugin or mod that hooks into your server to generate and manage a live, viewable map in any web browser. It features ultra-fast rendering, a 2D top-down view designed for navigation, and player markers that display yaw rotation, health, and armor.

  3. Add squaremap-api to your project

    master

    To use the squaremap API in your own plugin or mod, add the squaremap-api dependency to your build configuration. Releases are published to Maven Central.

    Note: The scope should be provided (Maven) or compileOnly (Gradle) because the API is provided by the squaremap plugin at runtime.

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

    Gradle

    repositories {
    mavenCentral()
}

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

  4. Set up a development environment for squaremap

    master

    To develop squaremap or its web UI, ensure you have the following prerequisites:

    1. JDK: An up-to-date JDK (Java 21 or later).
    2. Bun: Installed on your system for building the web UI.
    3. Web Dependencies: Run bun install inside the web directory.

    Building the Plugin

    Use the Gradle build task:

    ./gradlew build

    Developing the Web UI

    The web UI is automatically built and included in the plugin JAR by Gradle. For local development with Hot Module Reloading (HMR), use the Gradle run tasks (e.g., :squaremap-paper:runServer). Gradle will automatically pass the following system properties to the server:

    • squaremap.devFrontend=true
    • squaremap.frontendPath=<absolute path to ./web>

    When these properties are present, the plugin proxies requests to the Vite dev server.

    # Build the plugin
./gradlew build

# Install web dependencies
cd web && bun install

  5. Understand the Player data model

    master

    The Player class represents a player on the map. It manages the player's state (name, UUID, world, position, armor, health, and display name) and handles the visual representation of the player via a Leaflet marker and a nameplate tooltip.

    Key behaviors:

    • Marker Management: Automatically creates, updates, or removes a Leaflet marker based on the player's position and whether the current world's player_tracker is enabled.
    • Nameplates: Generates and updates a nameplate tooltip that can display the player's head, display name, health, and armor, depending on the world configuration.
    • Synchronization: The update(player) method is the primary way to sync the internal state with new data received from the server.
    • Cross-world visibility: If a player is in a different world than the one currently being viewed, their associated UI elements (like links in a player list) are marked with the other-world CSS class.

  6. How Squaremap manages coordinate systems

    master

    Squaremap uses a custom coordinate system where map positions are defined by x and z (typical of Minecraft-style maps) rather than standard Latitude and Longitude.

    To bridge this with the underlying Leaflet engine, the SquaremapMap class performs coordinate transformations:

    • toLatLng(x, z): Converts pixel coordinates to Leaflet's LatLng. It uses pixelsToMeters to handle the scale.
    • toPoint(latlng): Converts a Leaflet LatLng back into pixel coordinates.
    • setScale(zoom): Calculates the scale factor based on the current zoom level using the formula 1 / Math.pow(2, zoom). This scale is essential for all coordinate conversions.

  7. Understand the World data model

    master

    The World class represents a specific Minecraft world (e.g., Overworld, Nether, or The End) within the Squaremap web client. It manages world-specific settings, tile layer updates, and marker layers.

    Key responsibilities include:

    • Configuration: Loading world settings like zoom levels, spawn points, and update intervals from tiles/{world_name}/settings.json.
    • Lifecycle Management: Using load() to initialize the map view and unload() to clean up layers and player markers.
    • Dynamic Updates: The tick() method handles periodic refreshing of map tiles and markers based on tiles_update_interval and marker_update_interval.
    • Visuals: Automatically sets the map background based on the world type (nether, the_end, or normal).

  8. Use the squaremap API to draw on maps

    master
    squaremap provides APIs for drawing markers, shapes, icons, and other elements on rendered maps. Javadocs are hosted on the Maven repository alongside the binaries and are typically automatically downloaded by your IDE when you add the dependency.

  10. Manage player markers with `removeMarker()`

    master

    The removeMarker() method cleans up the player's visual presence on the map. It removes the Leaflet marker from the map and the playersLayer, and deletes the marker from the internal S.playerList.markers registry using the player's uuid.

    playerInstance.removeMarker();

  11. Unload a world and clean up resources

    master

    Call unload() to remove the current world's data from the map. This method:

    • Clears all player markers from S.playerList.
    • Iterates through all managed markerLayers, removes them from the S.layerControl UI, and removes them from the Leaflet map instance.
    • Deletes the layers from the internal markerLayers Map.
    world.unload();

  12. Manage map overlays with LayerControl

    master

    The LayerControl class provides a mechanism to manage Leaflet layers as overlays, including persistent visibility settings using localStorage. It integrates with the global S.map instance.

    Key Methods

    • addOverlay(name, layer, hide): Adds a Leaflet layer to the map controls with a specific name. If hide is true, the layer is added to the control but not immediately rendered on the map. Visibility is checked against localStorage using the key hide_${layer.id}.
    • removeOverlay(layer): Removes a layer from the map controls and the map itself.
    • hideLayer(layer): Persistently hides a layer by setting hide_${layer.id} to "true" in localStorage.
    • showLayer(layer): Persistently shows a layer by setting hide_${layer.id} to "false" in localStorage.

    Note: Visibility state is persisted in the browser's localStorage based on the id property of the Leaflet layer.

    // Example usage of LayerControl methods
const lc = new LayerControl();
// ... init logic ...

const myLayer = L.layerGroup();
myLayer.id = 'custom_layer_id';

// Add an overlay that is hidden by default
lc.addOverlay('My Custom Layer', myLayer, true);

// Persistently hide the layer
lc.hideLayer(myLayer);

// Persistently show the layer
lc.showLayer(myLayer);