### Quick Start Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/README.md

A quick start guide demonstrating how to obtain the API instance, get a world, create a layer, add markers, and register the layer.

```APIDOC
## Quick Start

To get started with the squaremap API:

```java
// 1. Obtain the API instance
Squaremap squaremap = SquaremapProvider.get();

// 2. Get a world
Optional<MapWorld> world = squaremap.getWorldIfEnabled(
    WorldIdentifier.parse("minecraft:overworld")
);

// 3. Create a layer
SimpleLayerProvider layer = SimpleLayerProvider.builder("My Layer")
    .layerPriority(5)
    .build();

// 4. Add markers to the layer
layer.addMarker(
    Key.of("my_marker"),
    Marker.circle(Point.of(100, 200), 50)
        .markerOptions(MarkerOptions.builder()
            .strokeColor(Color.RED)
            .clickTooltip("My Marker")
            .build())
);

// 5. Register the layer
world.ifPresent(mapWorld -> 
    mapWorld.layerRegistry().register(Key.of("my_layer"), layer)
);
```
```

--------------------------------

### Complete Example: Setting up Custom Map Layers

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/MapWorld.md

A comprehensive example demonstrating the setup of custom map layers and markers for a specific world. Includes error handling for layer registration.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.Color;
import java.util.Optional;

public class SquaremapIntegration {
    
    public void setupMapLayers() {
        Squaremap squaremap = SquaremapProvider.get();
        
        // Get the overworld
        Optional<MapWorld> world = squaremap.getWorldIfEnabled(
            WorldIdentifier.parse("minecraft:overworld")
        );
        
        if (!world.isPresent()) return;
        
        MapWorld mapWorld = world.get();
        Registry<LayerProvider> layerRegistry = mapWorld.layerRegistry();
        
        // Create a custom layer
        SimpleLayerProvider customLayer = SimpleLayerProvider.builder("Shops")
            .layerPriority(5)
            .build();
        
        // Add markers to the layer
        customLayer.addMarker(
            Key.of("shop_baker"),
            Marker.icon(Point.of(1000, 2000), Key.of("shop_icon"), 32)
                .markerOptions(MarkerOptions.builder()
                    .clickTooltip("Baker's Shop")
                    .build())
        );
        
        // Register the layer with the world
        try {
            layerRegistry.register(Key.of("shops_layer"), customLayer);
            System.out.println("Registered shops layer in " + mapWorld.identifier().asString());
        } catch (IllegalArgumentException e) {
            System.err.println("Failed to register layer: " + e.getMessage());
        }
    }
}
```

--------------------------------

### Complete Layer Setup Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/SimpleLayerProvider.md

Demonstrates how to create and register multiple SimpleLayerProvider instances with markers for settlements and trails. This example shows marker customization including colors, tooltips, and shapes.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.Color;
import java.util.*;

public class LayerSetup {
    
    public void createLayers(MapWorld world) {
        Registry<LayerProvider> layerRegistry = world.layerRegistry();
        
        // Create a simple settlements layer
        SimpleLayerProvider settlements = SimpleLayerProvider.builder("Settlements")
            .layerPriority(10)
            .build();
        
        settlements.addMarker(
            Key.of("village_1"),
            Marker.circle(Point.of(100, 100), 75)
                .markerOptions(MarkerOptions.builder()
                    .strokeColor(Color.GREEN)
                    .fillColor(Color.GREEN)
                    .fillOpacity(0.2)
                    .clickTooltip("Village #1")
                    .build())
        );
        
        settlements.addMarker(
            Key.of("village_2"),
            Marker.circle(Point.of(500, 500), 75)
                .markerOptions(MarkerOptions.builder()
                    .strokeColor(Color.GREEN)
                    .fillColor(Color.GREEN)
                    .fillOpacity(0.2)
                    .clickTooltip("Village #2")
                    .build())
        );
        
        layerRegistry.register(Key.of("settlements"), settlements);
        
        // Create a trails layer
        SimpleLayerProvider trails = SimpleLayerProvider.builder("Trails")
            .layerPriority(5)
            .build();
        
        trails.addMarker(
            Key.of("trail_main"),
            Marker.polyline(
                Point.of(0, 0),
                Point.of(100, 100),
                Point.of(200, 150),
                Point.of(300, 100)
            ).markerOptions(MarkerOptions.builder()
                .strokeColor(Color.ORANGE)
                .strokeWeight(2)
                .hoverTooltip("Main Trail")
                .build())
        );
        
        layerRegistry.register(Key.of("trails"), trails);
    }
}
```

--------------------------------

### Install Certbot for SSL

Source: https://github.com/jpenilla/squaremap/wiki/Internal-vs-External-Web-Server

Installs Certbot and initiates the SSL certificate setup process for either Apache or NGINX.

```sh
sudo apt-get update
sudo apt-get install certbot
sudo certbot --YOUR_WEBSERVER
```

--------------------------------

### Complete Marker Styling Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/MarkerOptions.md

A comprehensive example showcasing various MarkerOptions configurations for different marker types (circle, rectangle, polygon) including stroke, fill, opacity, and tooltips. This example also demonstrates registering a custom layer with the MapWorld.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.Color;

public class MarkerOptionsExample {
    
    public void demonstrateOptions(MapWorld world) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Styled Markers")
            .build();
        
        // Red circle with semi-transparent fill
        Marker red = Marker.circle(Point.of(100, 100), 50)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.RED)
                .strokeWeight(3)
                .fill(true)
                .fillColor(Color.RED)
                .fillOpacity(0.3)
                .clickTooltip("Red Zone")
                .build());
        
        // Blue outline only, no fill
        Marker blueOutline = Marker.rectangle(Point.of(200, 200), Point.of(300, 300))
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.BLUE)
                .strokeWeight(2)
                .fill(false)
                .hoverTooltip("Blue Rectangle")
                .build());
        
        // Green with custom opacity
        Marker transparent = Marker.circle(Point.of(400, 400), 75)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.GREEN)
                .strokeOpacity(0.5)
                .fill(true)
                .fillColor(Color.GREEN)
                .fillOpacity(0.1)
                .clickTooltip("Low Opacity Green")
                .build());
        
        // Yellow thick border
        Marker thick = Marker.polygon(
            Point.of(500, 500),
            Point.of(600, 500),
            Point.of(600, 600),
            Point.of(500, 600)
        ).markerOptions(MarkerOptions.builder()
            .strokeColor(Color.YELLOW)
            .strokeWeight(8)
            .fill(false)
            .clickTooltip("Thick Border")
            .build());
        
        layer.addMarker(Key.of("red"), red);
        layer.addMarker(Key.of("blue"), blueOutline);
        layer.addMarker(Key.of("green"), transparent);
        layer.addMarker(Key.of("yellow"), thick);
        
        world.layerRegistry().register(Key.of("styled"), layer);
    }
    
    public void updateMarkerStyle(Marker marker) {
        // Get current options and modify
        MarkerOptions current = marker.markerOptions();
        MarkerOptions updated = current.asBuilder()
            .strokeWeight(5)
            .fillOpacity(0.5)
            .build();
        
        marker.markerOptions(updated);
    }
}
```

--------------------------------

### Quick Start: Registering a Custom Layer and Adding Markers

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/README.md

This snippet demonstrates the basic steps to obtain the Squaremap API instance, get a world, create a custom layer, add markers to it, and register the layer with the world. It's a foundational example for integrating custom map data.

```java
import java.util.Optional;

import org.bukkit.Color;
import org.bukkit.util.Vector;

import xyz.jpenilla.squaremap.api.Key;
import xyz.jpenilla.squaremap.api.MapWorld;
import xyz.jpenilla.squaremap.api.Squaremap;
import xyz.jpenilla.squaremap.api.SquaremapProvider;
import xyz.jpenilla.squaremap.api.WorldIdentifier;
import xyz.jpenilla.squaremap.api.marker.Marker;
import xyz.jpenilla.squaremap.api.marker.MarkerOptions;
import xyz.jpenilla.squaremap.api.marker.SimpleLayerProvider;

// 1. Obtain the API instance
Squaremap squaremap = SquaremapProvider.get();

// 2. Get a world
Optional<MapWorld> world = squaremap.getWorldIfEnabled(
    WorldIdentifier.parse("minecraft:overworld")
);

// 3. Create a layer
SimpleLayerProvider layer = SimpleLayerProvider.builder("My Layer")
    .layerPriority(5)
    .build();

// 4. Add markers to the layer
layer.addMarker(
    Key.of("my_marker"),
    Marker.circle(Point.of(100, 200), 50)
        .markerOptions(MarkerOptions.builder()
            .strokeColor(Color.RED)
            .clickTooltip("My Marker")
            .build())
);

// 5. Register the layer
world.ifPresent(mapWorld -> 
    mapWorld.layerRegistry().register(Key.of("my_layer"), layer)
);
```

--------------------------------

### Dynamic Layer Provider Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/LayerProvider.md

Implement LayerProvider to create a layer with markers that can change dynamically. This example shows how to generate markers based on a collection of player names.

```java
public class DynamicLayerProvider implements LayerProvider {
    private final Collection<String> playerNames;
    
    @Override
    public String getLabel() {
        return "Online Players";
    }
    
    @Override
    public int layerPriority() {
        return 1;
    }
    
    @Override
    public Collection<Marker> getMarkers() {
        Collection<Marker> markers = new ArrayList<>();
        for (String playerName : playerNames) {
            // Query player location and create marker
            Marker playerMarker = Marker.circle(
                Point.of(100, 200),
                10
            ).markerOptions(MarkerOptions.builder()
                .clickTooltip(playerName)
                .build());
            markers.add(playerMarker);
        }
        return markers;
    }
}
```

--------------------------------

### Complete Icon Marker Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/Icon.md

Demonstrates registering custom icons, creating markers with tooltips, adding them to a layer, and registering the layer with a map world. This example requires Squaremap API, BufferedImage, File, and ImageIO imports.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.image.BufferedImage;
import java.io.File;
import javax.imageio.ImageIO;

public class IconMarkerExample {
    
    public void setupIcons(Squaremap squaremap) throws Exception {
        // Load custom icon images
        BufferedImage shopIcon = ImageIO.read(new File("icons/shop.png"));
        BufferedImage homeIcon = ImageIO.read(new File("icons/home.png"));
        
        // Register icons
        Registry<BufferedImage> iconRegistry = squaremap.iconRegistry();
        Key shopKey = Key.of("example_shop");
        Key homeKey = Key.of("example_home");
        
        iconRegistry.register(shopKey, shopIcon);
        iconRegistry.register(homeKey, homeIcon);
        
        // Create and position icons
        Icon shopMarker = Marker.icon(Point.of(100, 100), shopKey, 32, 32);
        shopMarker.markerOptions(MarkerOptions.builder()
            .clickTooltip("Village Shop")
            .build());
        
        Icon homeMarker = Marker.icon(Point.of(200, 200), homeKey, 32, 32);
        homeMarker.markerOptions(MarkerOptions.builder()
            .clickTooltip("Player Home")
            .build());
        
        // Add to layer
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Locations")
            .layerPriority(5)
            .build();
        
        layer.addMarker(Key.of("shop_1"), shopMarker);
        layer.addMarker(Key.of("home_1"), homeMarker);
        
        // Register layer
        WorldIdentifier worldId = WorldIdentifier.parse("minecraft:overworld");
        Optional<MapWorld> world = squaremap.getWorldIfEnabled(worldId);
        world.ifPresent(mapWorld -> 
            mapWorld.layerRegistry().register(Key.of("locations"), layer)
        );
    }
    
    public void customizeIcon() {
        // Create icon with custom anchor
        Icon customIcon = Marker.icon(
            Point.of(500, 500),
            Point.of(0, -32), // Popup opens at top
            Point.of(16, 32), // Anchor at bottom center
            Key.of("custom_icon"),
            32,
            32
        );
        
        // Update icon properties
        customIcon.sizeX(48);
        customIcon.sizeZ(48);
        customIcon.point(Point.of(600, 600));
    }
}

```

--------------------------------

### Complete Player Visibility Management Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/PlayerManager.md

A comprehensive example demonstrating how to use the PlayerManager to hide, show, and toggle player visibility, both temporarily and permanently. This class requires Squaremap and PlayerManager instances.

```java
import xyz.jpenilla.squaremap.api.*;
import java.util.UUID;

public class PlayerVisibilityManager {
    
    private final Squaremap squaremap;
    private final PlayerManager playerManager;
    
    public PlayerVisibilityManager() {
        this.squaremap = SquaremapProvider.get();
        this.playerManager = squaremap.playerManager();
    }
    
    public void hidePlayerTemporarily(UUID playerUUID) {
        playerManager.hide(playerUUID);
        System.out.println("Player hidden temporarily");
    }
    
    public void hidePlayerPermanently(UUID playerUUID) {
        playerManager.hide(playerUUID, true);
        System.out.println("Player hidden permanently");
    }
    
    public void showPlayerTemporarily(UUID playerUUID) {
        playerManager.show(playerUUID);
        System.out.println("Player shown temporarily");
    }
    
    public void showPlayerPermanently(UUID playerUUID) {
        playerManager.show(playerUUID, true);
        System.out.println("Player shown permanently");
    }
    
    public void togglePlayerVisibility(UUID playerUUID, boolean persistent) {
        if (playerManager.hidden(playerUUID)) {
            playerManager.show(playerUUID, persistent);
            System.out.println("Player now visible");
        } else {
            playerManager.hide(playerUUID, persistent);
            System.out.println("Player now hidden");
        }
    }
    
    public void listPlayerStatus(UUID playerUUID) {
        String status = playerManager.hidden(playerUUID) ? "HIDDEN" : "VISIBLE";
        System.out.println("Player " + playerUUID + " is " + status);
    }
}
```

--------------------------------

### Complete Pair Example Class

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Pair.md

A comprehensive example demonstrating the creation and usage of Pair objects, including iterating through registries and processing world data within a Squaremap context.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.util.*;

public class PairExample {
    
    public void processPairs(MapWorld world) {
        Registry<LayerProvider> layerRegistry = world.layerRegistry();
        
        // Collect all layer pairs
        List<Pair<Key, LayerProvider>> allLayers = new ArrayList<>();
        for (Pair<Key, LayerProvider> entry : layerRegistry.entries()) {
            allLayers.add(entry);
        }
        
        // Print information about each layer
        System.out.println("Registered layers:");
        for (Pair<Key, LayerProvider> pair : allLayers) {
            Key layerKey = pair.left();
            LayerProvider provider = pair.right();
            System.out.println("  " + layerKey.getKey() + ": " + provider.getLabel());
        }
    }
    
    public void mapWorldPairs(Squaremap squaremap) {
        // Create pairs of world identifiers and map worlds
        List<Pair<WorldIdentifier, MapWorld>> worldPairs = new ArrayList<>();
        
        for (MapWorld world : squaremap.mapWorlds()) {
            WorldIdentifier id = world.identifier();
            worldPairs.add(Pair.of(id, world));
        }
        
        // Process pairs
        for (Pair<WorldIdentifier, MapWorld> pair : worldPairs) {
            WorldIdentifier worldId = pair.left();
            MapWorld world = pair.right();
            System.out.println("World: " + worldId.asString() 
                + " has " + world.layerRegistry().entries().iterator().hasNext() 
                + " layers");
        }
    }
}
```

--------------------------------

### Complete Rectangle Marker Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/Rectangle.md

This example demonstrates how to create and configure multiple rectangle markers with different styling options and add them to a map layer. It also shows how to update an existing rectangle's dimensions.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.Color;

public class RectangleMarkerExample {
    
    public void setupBuildings(MapWorld world) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Buildings")
            .layerPriority(8)
            .build();
        
        // House
        Rectangle house = Marker.rectangle(
            Point.of(100, 100),
            Point.of(130, 130)
        ).markerOptions(MarkerOptions.builder()
            .strokeColor(Color.ORANGE)
            .fillColor(Color.ORANGE)
            .fillOpacity(0.25)
            .clickTooltip("Small House")
            .build());
        
        // Large building
        Rectangle building = Marker.rectangle(
            Point.of(200, 200),
            Point.of(300, 350)
        ).markerOptions(MarkerOptions.builder()
            .strokeColor(Color.GRAY)
            .fillColor(Color.GRAY)
            .fillOpacity(0.2)
            .clickTooltip("Large Building")
            .build());
        
        // Farm area
        Rectangle farm = Marker.rectangle(
            Point.of(500, 500),
            Point.of(750, 700)
        ).markerOptions(MarkerOptions.builder()
            .strokeColor(Color.GREEN)
            .strokeWeight(2)
            .fill(false)
            .clickTooltip("Farm Area")
            .build());
        
        layer.addMarker(Key.of("house_1"), house);
        layer.addMarker(Key.of("building_1"), building);
        layer.addMarker(Key.of("farm_1"), farm);
        
        world.layerRegistry().register(Key.of("buildings"), layer);
    }
    
    public void updateRectangle(Rectangle rect) {
        // Expand the rectangle
        Point p1 = rect.point1();
        Point p2 = rect.point2();
        
        rect.points(
            Point.of(p1.x() - 10, p1.z() - 10),
            Point.of(p2.x() + 10, p2.z() + 10)
        );
    }
}
```

--------------------------------

### Invalid Key Examples

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Key.md

Shows examples of strings that will cause an IllegalArgumentException when used to create a Key, due to disallowed characters like spaces and colons.

```java
Key.of("marker 1");      // Throws: spaces not allowed
Key.of("marker:1");      // Throws: colons not allowed
Key.of("marker/1");      // Throws: slashes not allowed
Key.of("marker@1");      // Throws: @ not allowed
```

--------------------------------

### Start Full Map Render

Source: https://github.com/jpenilla/squaremap/wiki/Commands-and-Permissions

Initiates a full render for a specified world, starting from the spawn point and expanding outwards. Progress is logged in the server console. Players can omit the world parameter to use their current world.

```minecraft-command
/map fullrender [world]
```

--------------------------------

### Examples of Stripping Various HTML Content

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/HtmlStripper.md

Provides examples of how HtmlStripper handles different types of HTML, including basic formatting, malicious scripts, and mixed content.

```java
HtmlStripper stripper = HtmlStripper.htmlStripper();

// Remove tags from formatted text
stripper.stripHtml("<b>Bold</b> text");           // Output: "Bold text"
stripper.stripHtml("<i>Italic</i>");              // Output: "Italic"
stripper.stripHtml("<span class='x'>Test</span>");// Output: "Test"

// Remove malicious scripts
stripper.stripHtml("<script>alert('xss')</script>"); // Output: "alert('xss')"
stripper.stripHtml("<img src=x onerror=alert(1)>");   // Output: ""

// Handle mixed content
stripper.stripHtml("Normal <b>bold</b> <script>evil</script> more"); 
// Output: "Normal bold evil more"
```

--------------------------------

### Example Pair Creation

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Pair.md

Demonstrates creating Pair instances with different generic types for various Squaremap API components.

```java
Pair<String, Integer> pair1 = Pair.of("count", 42);
Pair<Key, Marker> pair2 = Pair.of(Key.of("marker_1"), marker);
Pair<WorldIdentifier, MapWorld> pair3 = Pair.of(worldId, mapWorld);
```

--------------------------------

### Valid Key Examples

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Key.md

Illustrates various valid characters and conventions for creating Key instances, including numbers, uppercase letters, hyphens, periods, and plugin prefixes.

```java
Key.of("marker_1");              // Numbers are allowed
Key.of("MY_KEY");                // Uppercase is allowed
Key.of("my-key");                // Hyphens are allowed
Key.of("my.key");                // Periods are allowed
Key.of("myplugin_marker_1");     // Plugin prefix convention
```

--------------------------------

### Common Task: Working with Custom Icons

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/README.md

This example illustrates how to load a custom icon from an image file, register it with Squaremap's icon registry, and then use it to create an icon marker on the map.

```java
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;
import javax.imageio.ImageIO;

import xyz.jpenilla.squaremap.api.Key;
import xyz.jpenilla.squaremap.api.Squaremap;
import xyz.jpenilla.squaremap.api.SquaremapProvider;
import xyz.jpenilla.squaremap.api.marker.Marker;

// Load and register an image
BufferedImage icon = ImageIO.read(new File("icon.png"));
Squaremap squaremap = SquaremapProvider.get();
squaremap.iconRegistry().register(Key.of("my_icon"), icon);

// Use in marker
Marker iconMarker = Marker.icon(Point.of(100, 100), Key.of("my_icon"), 32);
```

--------------------------------

### Complete Circle Marker Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/Circle.md

Demonstrates the creation and registration of multiple circle markers with different styles and tooltips within a Squaremap layer. Also shows how to update existing circle properties.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.Color;
import java.util.Optional;

public class CircleMarkerExample {
    
    public void setupCircles(Squaremap squaremap) {
        WorldIdentifier worldId = WorldIdentifier.parse("minecraft:overworld");
        Optional<MapWorld> world = squaremap.getWorldIfEnabled(worldId);
        
        if (!world.isPresent()) return;
        
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Danger Zones")
            .layerPriority(10)
            .build();
        
        // Large danger zone
        Circle dangerZone = Marker.circle(Point.of(0, 0), 100)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.RED)
                .fillColor(Color.RED)
                .fillOpacity(0.2)
                .strokeWeight(3)
                .clickTooltip("Danger Zone - High Level Mobs")
                .build());
        
        layer.addMarker(Key.of("danger_zone_1"), dangerZone);
        
        // Medium warning zone
        Circle warningZone = Marker.circle(Point.of(500, 500), 75)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.ORANGE)
                .fillColor(Color.ORANGE)
                .fillOpacity(0.1)
                .clickTooltip("Warning Zone - Moderate Level Mobs")
                .build());
        
        layer.addMarker(Key.of("warning_zone_1"), warningZone);
        
        // Safe zone
        Circle safeZone = Marker.circle(Point.of(1000, 1000), 50)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.GREEN)
                .fillColor(Color.GREEN)
                .fillOpacity(0.15)
                .clickTooltip("Safe Zone - No Mobs")
                .build());
        
        layer.addMarker(Key.of("safe_zone_1"), safeZone);
        
        world.get().layerRegistry().register(Key.of("zones"), layer);
    }
    
    public void updateCircle(Circle circle) {
        // Expand the circle
        circle.radius(circle.radius() * 1.5);
        
        // Move the circle
        Point currentCenter = circle.center();
        circle.center(Point.of(currentCenter.x() + 100, currentCenter.z() + 100));
    }
    
    public void dynamicCircles(MapWorld world, List<Integer> radiusValues) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Dynamic Circles")
            .build();
        
        Point baseCenter = Point.of(500, 500);
        
        for (int i = 0; i < radiusValues.size(); i++) {
            Circle circle = Marker.circle(baseCenter, radiusValues.get(i))
                .markerOptions(MarkerOptions.builder()
                    .strokeColor(new Color(0, 100 + i * 30, 255 - i * 30))
                    .fillOpacity(0.1)
                    .clickTooltip("Radius: " + radiusValues.get(i))
                    .build());
            
            layer.addMarker(Key.of("dynamic_circle_" + i), circle);
        }
        
        world.layerRegistry().register(Key.of("dynamic"), layer);
    }
}
```

--------------------------------

### asString()

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/WorldIdentifier.md

Gets the complete string representation in the format 'namespace:value'.

```APIDOC
## asString()

### Description
Gets the complete string representation in the format `namespace:value`.

### Method
```java
String asString()
```

### Parameters
No parameters.

### Returns
`String` - The complete identifier string.

### Example
```java
WorldIdentifier id = WorldIdentifier.parse("minecraft:overworld");
System.out.println(id.asString()); // Output: "minecraft:overworld"
```
```

--------------------------------

### HtmlStripper.htmlStripper()

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/HtmlStripper.md

Gets an instance of the HtmlStripper. This is a static factory method to obtain the stripper.

```APIDOC
## htmlStripper()

### Description
Gets an `HtmlStripper` instance. This is a static factory method.

### Method
Java Static Method

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters Table
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| — | — | — | No parameters |

### Response
#### Success Response
- **Return Value** (`HtmlStripper`) - An HtmlStripper instance.

### Request Example
```java
HtmlStripper stripper = HtmlStripper.htmlStripper();
```
```

--------------------------------

### Iterating Through All Registered Entries

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Registry.md

This example demonstrates how to iterate over all key-value pairs stored within a registry. It is useful for inspecting all registered items, such as layers, and accessing their properties.

```java
Registry<LayerProvider> layerRegistry = // ...

for (Pair<Key, LayerProvider> entry : layerRegistry.entries()) {
    Key key = entry.left();
    LayerProvider provider = entry.right();
    System.out.println("Layer: " + key + " -> " + provider.getLabel());
}
```

--------------------------------

### Get Key String

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Key.md

Retrieves the original string representation of the Key instance.

```java
Key key = Key.of("myplugin_marker");
System.out.println(key.getKey()); // Output: "myplugin_marker"
```

--------------------------------

### Complete IPolygon Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/IPolygon.md

Demonstrates the full lifecycle of creating, modifying, and processing polygons using the IPolygon interface. Includes setting boundaries, adding holes, and handling different polygon types.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.util.Arrays;
import java.util.List;

public class IPolygonExample {
    
    public void processPolygon(IPolygon polygon) {
        // Get boundary
        List<Point> boundary = polygon.mainPolygon();
        System.out.println("Boundary vertices: " + boundary.size());
        
        // Get holes
        List<List<Point>> holes = polygon.negativeSpace();
        System.out.println("Number of holes: " + holes.size());
        
        // Modify boundary
        List<Point> newBoundary = Arrays.asList(
            Point.of(0, 0), Point.of(200, 0),
            Point.of(200, 200), Point.of(0, 200)
        );
        polygon.mainPolygon(newBoundary);
    }
    
    public void addHole(IPolygon polygon) {
        List<Point> hole = Arrays.asList(
            Point.of(50, 50), Point.of(150, 50),
            Point.of(150, 150), Point.of(50, 150)
        );
        
        List<List<Point>> currentHoles = new java.util.ArrayList<>(polygon.negativeSpace());
        currentHoles.add(hole);
        polygon.negativeSpace(currentHoles);
    }
    
    public void processAnyPolygon(Marker marker) {
        if (marker instanceof IPolygon) {
            IPolygon poly = (IPolygon) marker;
            
            // Can work with both Polygon and MultiPolygonPart
            List<Point> boundary = poly.mainPolygon();
            System.out.println("Processing polygon with " + boundary.size() + " vertices");
        }
    }
    
    public void setupExample(MapWorld world) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Complex Shapes")
            .build();
        
        // Create two different polygon types
        Polygon simplePolygon = Marker.polygon(
            Point.of(0, 0), Point.of(100, 0),
            Point.of(100, 100), Point.of(0, 100)
        );
        
        MultiPolygon multiPolygon = Marker.multiPolygon(
            MultiPolygon.part(
                Point.of(200, 0), Point.of(300, 0),
                Point.of(300, 100), Point.of(200, 100)
            )
        );
        
        // Process both using the interface
        processPolygon(simplePolygon);
        processPolygon(multiPolygon.subPolygons().get(0));
        
        // Add holes to both
        addHole(simplePolygon);
        addHole(multiPolygon.subPolygons().get(0));
        
        layer.addMarker(Key.of("simple"), simplePolygon);
        layer.addMarker(Key.of("multi"), multiPolygon);
        
        world.layerRegistry().register(Key.of("complex"), layer);
    }
}
```

--------------------------------

### Add Styled Markers

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/README.md

Example of creating a styled circle marker with custom options like color, fill, and tooltip.

```APIDOC
## Add Styled Markers

```java
Marker circle = Marker.circle(Point.of(0, 0), 50)
    .markerOptions(MarkerOptions.builder()
        .strokeColor(Color.RED)
        .fillColor(Color.RED)
        .fillOpacity(0.3)
        .clickTooltip("Danger Zone")
        .build());
```
```

--------------------------------

### Example fluids-export.yml

Source: https://github.com/jpenilla/squaremap/wiki/Modded-Fluids-Setup-(Forge-Fabric)

This file is automatically generated on the client and lists fluid block IDs with their corresponding color codes. It serves as a source for server-side configuration.

```yaml
# Automatically generated list of fluid colors. You may want to copy this into your server's advanced.yml.

immersiveengineering:ethanol_fluid_block: '#D3D3CEB3'
mekanism:hydrogen: '#D4D4D4E8'
immersiveengineering:redstone_acid_fluid_block: '#E42424B3'
bigreactors:rossinite_fluid: '#B10000B4'
bigreactors:redfrigium_fluid: '#AE7C85B4'
mekanism:steam: '#D4D4D4E8'
thermal:ender_fluid: '#08304AFF'
ad_astra:fuel: '#9A8B54B2'
create:honey: '#E7A026FF'
create:chocolate: '#9D483BFF'
pneumaticcraft:oil: '#232323F3'
mekanismgenerators:deuterium: '#D42929E8'
mekanism:ethene: '#C2A9CFE8'
ad_astra:oil: '#312936E5'
bigreactors:steam: '#B1B1B1B4'
```

--------------------------------

### Example advanced.yml color overrides

Source: https://github.com/jpenilla/squaremap/wiki/Modded-Fluids-Setup-(Forge-Fabric)

This shows how to integrate the fluid color overrides from `fluids-export.yml` into the server's `advanced.yml` file under the `color-overrides.blocks` section.

```yaml
# ...
world-settings:
    default:
        # ...
        color-overrides:
            # ...
            blocks:
                # ...
                immersiveengineering:ethanol_fluid_block: '#D3D3CEB3'
                mekanism:hydrogen: '#D4D4D4E8'
immersiveengineering:redstone_acid_fluid_block: '#E42424B3'
bigreactors:rossinite_fluid: '#B10000B4'
bigreactors:redfrigium_fluid: '#AE7C85B4'
mekanism:steam: '#D4D4D4E8'
thermal:ender_fluid: '#08304AFF'
ad_astra:fuel: '#9A8B54B2'
create:honey: '#E7A026FF'
create:chocolate: '#9D483BFF'
pneumaticcraft:oil: '#232323F3'
mekanismgenerators:deuterium: '#D42929E8'
mekanism:ethene: '#C2A9CFE8'
ad_astra:oil: '#312936E5'
bigreactors:steam: '#B1B1B1B4'
```

--------------------------------

### Generic Type Examples for Pair

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Pair.md

Illustrates the flexibility of the Pair class by showing its instantiation with various common generic type combinations used within the Squaremap API.

```java
// String key, marker value
Pair<Key, Marker> keyMarker = Pair.of(Key.of("m1"), marker);

// String key, layer value
Pair<Key, LayerProvider> keyLayer = Pair.of(Key.of("l1"), layer);

// World identifier, map world value
Pair<WorldIdentifier, MapWorld> worldPair = Pair.of(
    WorldIdentifier.parse("minecraft:overworld"),
    mapWorld
);

// Icon key, buffered image value
Pair<Key, BufferedImage> iconPair = Pair.of(Key.of("icon"), image);
```

--------------------------------

### Demonstrate Fill Rules with Self-Intersecting Polygon

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/types.md

This example demonstrates the visual difference between the EVENODD and NONZERO fill rules using a self-intersecting polygon. EVENODD is generally recommended for most Squaremap use cases.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.util.Arrays;
import java.util.List;

public class FillRuleExample {
    
    public void demonstrateFillRules(MapWorld world) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Fill Rules")
            .build();
        
        // Self-intersecting polygon - demonstrates fill rule difference
        List<Point> selfIntersecting = Arrays.asList(
            Point.of(0, 0),
            Point.of(100, 100),
            Point.of(100, 0),
            Point.of(0, 100)
        );
        
        // With EVENODD rule
        Polygon evenOddPolygon = Marker.polygon(selfIntersecting)
            .markerOptions(MarkerOptions.builder()
                .fillRule(MarkerOptions.FillRule.EVENODD)
                .fillColor(Color.BLUE)
                .fillOpacity(0.3)
                .clickTooltip("Even-Odd Fill Rule")
                .build());
        
        // With NONZERO rule
        Polygon nonzeroPolygon = Marker.polygon(selfIntersecting)
            .markerOptions(MarkerOptions.builder()
                .fillRule(MarkerOptions.FillRule.NONZERO)
                .fillColor(Color.RED)
                .fillOpacity(0.3)
                .clickTooltip("Non-Zero Fill Rule")
                .build());
        
        layer.addMarker(Key.of("evenodd"), evenOddPolygon);
        layer.addMarker(Key.of("nonzero"), nonzeroPolygon);
        
        world.layerRegistry().register(Key.of("fill_rules"), layer);
    }
}
```

--------------------------------

### Complete Polyline Marker Example

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/Polyline.md

Demonstrates setting up a layer with both a single main trail and multiple disconnected secondary trails using Polyline markers. Includes styling options like stroke color and weight.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.awt.Color;
import java.util.Arrays;
import java.util.List;

public class PolylineMarkerExample {
    
    public void setupTrails(MapWorld world) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Trails")
            .layerPriority(7)
            .build();
        
        // Main trail
        Polyline mainTrail = Marker.polyline(
            Point.of(0, 0),
            Point.of(100, 50),
            Point.of(200, 100),
            Point.of(300, 80)
        ).markerOptions(MarkerOptions.builder()
            .strokeColor(Color.ORANGE)
            .strokeWeight(3)
            .clickTooltip("Main Trail")
            .build());
        
        layer.addMarker(Key.of("trail_main"), mainTrail);
        
        // Multiple disconnected trails
        List<Point> trailA = Arrays.asList(
            Point.of(400, 400),
            Point.of(450, 450),
            Point.of(500, 400)
        );
        List<Point> trailB = Arrays.asList(
            Point.of(600, 600),
            Point.of(650, 580),
            Point.of(700, 620)
        );
        
        Polyline multiTrail = Marker.multiPolyline(trailA, trailB)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.BLUE)
                .strokeWeight(2)
                .clickTooltip("Secondary Trails")
                .build());
        
        layer.addMarker(Key.of("trail_multi"), multiTrail);
        
        world.layerRegistry().register(Key.of("trails"), layer);
    }
    
    public void updatePolyline(Polyline polyline) {
        // Add more points to the line
        List<Point> currentPoints = new java.util.ArrayList<>(polyline.points().get(0));
        currentPoints.add(Point.of(400, 150));
        polyline.points(currentPoints);
    }
}
```

--------------------------------

### IPolygon.mainPolygon() - Get Boundary

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/IPolygon.md

Gets the mutable list of points that make up the outer polygon boundary.

```APIDOC
## IPolygon.mainPolygon() - Get Boundary

### Description
Gets the mutable list of points that make up the outer polygon boundary.

### Method
GET

### Endpoint
IPolygon

### Parameters
None

### Response
#### Success Response (200)
- **mainPolygon** (List<Point>) - The polygon's outer boundary points.

### Response Example
{
  "mainPolygon": [
    {"x": 0, "y": 0},
    {"x": 100, "y": 0},
    {"x": 100, "y": 100},
    {"x": 0, "y": 100}
  ]
}
```

--------------------------------

### Get Layer Registry and Add Custom Markers

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/MapWorld.md

Demonstrates how to retrieve the layer registry for a world and register a custom layer with markers. This is useful for adding dynamic or static data points to the map.

```java
Squaremap squaremap = SquaremapProvider.get();
WorldIdentifier worldId = WorldIdentifier.parse("minecraft:overworld");
Optional<MapWorld> mapWorld = squaremap.getWorldIfEnabled(worldId);

mapWorld.ifPresent(world -> {
    Registry<LayerProvider> layerRegistry = world.layerRegistry();
    
    // Create a simple layer
    SimpleLayerProvider layer = SimpleLayerProvider.builder("My Custom Layer")
        .layerPriority(10)
        .build();
    
    // Add a marker to the layer
    layer.addMarker(
        Key.of("myplugin_marker_1"),
        Marker.circle(Point.of(100, 200), 50)
            .markerOptions(MarkerOptions.builder()
                .strokeColor(Color.RED)
                .build())
    );
    
    // Register the layer
    layerRegistry.register(Key.of("myplugin_layer"), layer);
});
```

--------------------------------

### IPolygon.negativeSpace() - Get Holes

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/IPolygon.md

Gets the mutable list of polygons that represent holes (negative space) in this polygon.

```APIDOC
## IPolygon.negativeSpace() - Get Holes

### Description
Gets the mutable list of polygons that represent holes (negative space) in this polygon.

### Method
GET

### Endpoint
IPolygon

### Parameters
None

### Response
#### Success Response (200)
- **negativeSpace** (List<List<Point>>) - The hole boundaries.

### Response Example
{
  "negativeSpace": [
    [
      {"x": 25, "y": 25},
      {"x": 75, "y": 25},
      {"x": 75, "y": 75},
      {"x": 25, "y": 75}
    ]
  ]
}
```

--------------------------------

### Key Best Practices

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Key.md

Provides guidance on naming conventions for Keys, including using plugin namespaces, descriptive names, consistent formatting, and preferring lowercase.

```java
// 1. Use plugin namespace to avoid conflicts
Key markerKey = Key.of("myplugin_important_marker");

// 2. Use descriptive names
Key villageLayer = Key.of("myplugin_villages");

// 3. Use consistent naming conventions
Key npcMarker1 = Key.of("myplugin_npc_001");
Key npcMarker2 = Key.of("myplugin_npc_002");

// 4. Keep keys lowercase (by convention)
Key properKey = Key.of("myplugin_my_marker");    // Good
Key improperKey = Key.of("MyPlugin_MyMarker");   // Works but unconventional
```

--------------------------------

### build()

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/SimpleLayerProvider.md

Builds and returns the configured SimpleLayerProvider instance.

```APIDOC
## build()

### Description
Builds and returns the configured `SimpleLayerProvider` instance.

### Method
```java
SimpleLayerProvider build()
```

### Returns
`SimpleLayerProvider` — The built layer provider.
```

--------------------------------

### Register and Retrieve from Registries

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/README.md

Interact with registries to manage layers and icons. Register new entries using `register(key, value)`, retrieve them with `get(key)`, and iterate through all entries.

```java
Registry<LayerProvider> layerRegistry = mapWorld.layerRegistry();
Registry<BufferedImage> iconRegistry = squaremap.iconRegistry();

// Register
layerRegistry.register(key, layer);

// Retrieve
LayerProvider layer = layerRegistry.get(key);

// List all
for (Pair<Key, LayerProvider> entry : layerRegistry.entries()) {
    Key k = entry.left();
    LayerProvider v = entry.right();
}
```

--------------------------------

### Key API Usage for Markers and Layers

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/Key.md

This example demonstrates how to create consistently named keys for markers and layers, add markers to a layer using these keys, register the layer, and manage markers by key. It highlights the importance of unique keys for identification and manipulation.

```java
import xyz.jpenilla.squaremap.api.*;
import xyz.jpenilla.squaremap.api.marker.*;
import java.util.*;

public class KeyExample {
    
    public void setupMarkers(MapWorld world) {
        SimpleLayerProvider layer = SimpleLayerProvider.builder("Points of Interest")
            .build();
        
        // Create consistently named keys
        Key[] poiKeys = new Key[5];
        for (int i = 1; i <= 5; i++) {
            poiKeys[i-1] = Key.of("myplugin_poi_" + String.format("%03d", i));
        }
        
        // Add markers with keys
        for (int i = 0; i < poiKeys.length; i++) {
            Marker marker = Marker.circle(
                Point.of(100 * (i+1), 100 * (i+1)),
                30
            ).markerOptions(MarkerOptions.builder()
                .clickTooltip("POI #" + (i+1))
                .build());
            
            layer.addMarker(poiKeys[i], marker);
        }
        
        // Use consistent key for layer registration
        Key layerKey = Key.of("myplugin_pois");
        world.layerRegistry().register(layerKey, layer);
        
        // Later, check if a specific marker exists
        if (layer.hasMarker(poiKeys[0])) {
            Marker removed = layer.removeMarker(poiKeys[0]);
            System.out.println("Removed first POI marker");
        }
    }
}
```

--------------------------------

### value()

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/WorldIdentifier.md

Gets the value string of this identifier.

```APIDOC
## value()

### Description
Gets the value string of this identifier.

### Method
```java
String value()
```

### Parameters
No parameters.

### Returns
`String` - The value string.

### Example
```java
WorldIdentifier id = WorldIdentifier.parse("minecraft:overworld");
System.out.println(id.value()); // Output: "overworld"
```
```

--------------------------------

### namespace()

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/WorldIdentifier.md

Gets the namespace string of this identifier.

```APIDOC
## namespace()

### Description
Gets the namespace string of this identifier.

### Method
```java
String namespace()
```

### Parameters
No parameters.

### Returns
`String` - The namespace string.

### Example
```java
WorldIdentifier id = WorldIdentifier.parse("minecraft:overworld");
System.out.println(id.namespace()); // Output: "minecraft"
```
```

--------------------------------

### Create and Modify MarkerOptions

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/MarkerOptions.md

Demonstrates how to create a MarkerOptions object and then use its asBuilder() method to create a new builder for modifications.

```java
MarkerOptions original = MarkerOptions.builder()
    .strokeColor(Color.RED)
    .build();

MarkerOptions modified = original.asBuilder()
    .strokeWeight(5)
    .build();
```

--------------------------------

### Get Circle Radius

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/Circle.md

Retrieves the current radius of a Circle marker.

```java
Circle circle = Marker.circle(Point.of(100, 100), 50);
System.out.println("Radius: " + circle.radius());
```

--------------------------------

### Get Circle Center

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/Circle.md

Retrieves the center point of an existing Circle marker.

```java
Circle circle = Marker.circle(Point.of(100, 100), 50);
Point center = circle.center();
System.out.println("Center: " + center.x() + ", " + center.z());
```

--------------------------------

### Common Task: Registering a Custom Layer with Options

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/README.md

This snippet shows how to create and register a custom layer with specific options like priority, default visibility, and control visibility. It also includes an example of adding an icon marker to the layer.

```java
SimpleLayerProvider layer = SimpleLayerProvider.builder("Shops")
    .layerPriority(10)
    .defaultHidden(false)
    .showControls(true)
    .build();

// Add markers
layer.addMarker(Key.of("shop_1"), Marker.icon(Point.of(100, 200), Key.of("shop_icon"), 32));

// Register
mapWorld.layerRegistry().register(Key.of("shops"), layer);
```

--------------------------------

### Create a SimpleLayerProvider

Source: https://github.com/jpenilla/squaremap/wiki/API-Basics

Build a custom layer provider with specified display options. Use this to define the appearance and behavior of a new map layer.

```java
SimpleLayerProvider provider = SimpleLayerProvider.builder("Layer Label")
  .showControls(true)
  .defaultHidden(false)
  .layerPriority(5);
  .zIndex(250);
  .build();
```

--------------------------------

### Get Default MarkerOptions

Source: https://github.com/jpenilla/squaremap/blob/master/_autodocs/api-reference/markers/MarkerOptions.md

Retrieve the default MarkerOptions instance to use as a base or for comparison.

```java
MarkerOptions defaults = MarkerOptions.defaultOptions();
```