Skip to content
BranchesTags

Repository files navigation

Location Manager

A Minecraft Paper plugin for managing shared waypoints using lodestones, signs, and tracking compasses.

Players create locations by placing a sign on a lodestone and waxing it with honeycomb. Locations are visible to all players through a GUI browser and can be navigated to with tracking compasses that show distance in the action bar.

Features

  • Lodestone + sign registration with wax-to-confirm flow
  • Multi-dimension support - Overworld and Nether locations linked by tag:name
  • Tracking compass with real-time distance in action bar
  • Compass needle updates when changing dimensions
  • Item frame icons - use banners, player heads, or any item as location icon in the GUI
  • Per-player item frame glowing when holding a compass (via ProtocolLib)
  • GUI browser with pagination and filters
  • Tag system - organize locations with custom tags
  • SQLite persistence with multi-dimension coordinate storage

Requirements

  • Paper or Purpur 1.21+
  • Java 21

Optional Dependencies

Plugin Version Purpose
Pl3xMap 1.21.11-544+ Web map markers with per-location icons (block textures, player heads, custom banners)
ProtocolLib 5.4.0+ Per-player item frame glowing when holding a compass

Both are soft-dependencies - the plugin works without them but enables extra features when present.

Installation

  1. Download basemanager-x.x.x.jar from Releases
  2. Place in your server's plugins/ folder
  3. (Optional) Install Pl3xMap for web map markers
  4. (Optional) Install ProtocolLib for item frame glowing
  5. Restart the server

Location Lifecycle

flowchart TD
    Start([Player places a Lodestone]) --> PlaceSign[Place sign on lodestone]
    PlaceSign --> SetTag["Line 1: Tag (e.g. team name)"]
    SetTag --> SetName["Lines 2-4: Location name"]
    SetName --> Decorate["Add item frame icon on lodestone\nand/or build structure above\nwith player heads as members"]
    Decorate --> Wax

    Wax["Wax sign with honeycomb"] --> CheckDup{Same tag:name\nexists?}
    CheckDup -->|No| Create[New location created]
    CheckDup -->|Yes, other dimension| Link["Coords added to\nexisting location"]
    CheckDup -->|Yes, same dimension| Block[Blocked - duplicate]

    Create --> ScanHeads["Structure scanned\nPlayer heads → members"]
    Link --> ScanHeads
    ScanHeads --> Registered((Location\nRegistered))

    Registered --> Use
    Registered --> Edit
    Registered --> Delete

    subgraph Use [Usage]
        GUI["GUI Browser\n/loc"]
        Compass["Tracking Compass\nwith action bar"]
        Glow["Item frame glows\nfor compass holder"]
        GUI --> Compass
        Compass --> Glow
    end

    subgraph Edit ["Editing (name, icon, or members)"]
        BreakSignEdit["Break the sign"] --> Modify["Update sign, icon,\nor head structure"]
        Modify --> ReWax["Wax sign"]
        ReWax --> ScanHeads
    end

    subgraph Delete [Deletion]
        BreakLodestone["Break lodestone"] --> Removed
        BreakSign["Break sign"] --> Removed
        Removed((Location\nDeleted))
    end

    style Registered fill:#4a9,stroke:#333,color:#fff
    style Removed fill:#c44,stroke:#333,color:#fff
    style Block fill:#c44,stroke:#333,color:#fff
Loading

Since signs are waxed (locked) after registration, editing requires breaking the sign to delete the location, then placing a new sign with updated details and waxing again. The lodestone and item frame can stay in place.

Cross-Dimension Compass

Locations can span multiple dimensions. To link Overworld and Nether, register a lodestone in each dimension using the same tag and name. The compass then automatically switches between them:

  • In Overworld: Compass points to the Overworld coordinates, action bar shows distance
  • Enter Nether portal: Compass needle updates to point to the Nether coordinates
  • Return to Overworld: Compass switches back to Overworld coordinates
  • No coords in current dimension: Compass spins freely, action bar shows "No base here"

Auto-dispose only triggers in the origin dimension (where you got the compass). Walking past a Nether portal won't accidentally consume your compass.

flowchart TD
    subgraph Setup ["Setup: same tag + name in both dimensions"]
        OW_Setup["Overworld lodestone\n[WOLVES] Main Base\n→ wax"] --> Linked((WOLVES:Main Base\nlinked location))
        NE_Setup["Nether lodestone\n[WOLVES] Main Base\n→ wax"] --> Linked
    end

    Linked --> Compass["Get compass"]

    Compass --> OW_Use["In Overworld\nPoints to OW coords"]
    OW_Use -->|Enter Nether| NE_Use["In Nether\nPoints to Nether coords"]
    NE_Use -->|Return to Overworld| OW_Use
    NE_Use -->|No Nether coords| Spin["Compass spins\n'No base here'"]

    style Linked fill:#4a9,stroke:#333,color:#fff
Loading

Icon Behavior

The location icon (displayed in the GUI) is taken from the item frame on the lodestone at the time of waxing. When a location spans multiple dimensions:

  • The icon is set when first registered (first wax with an item frame)
  • Waxing a second lodestone (in another dimension) with a different item frame overwrites the icon
  • The last waxed lodestone's item frame wins
  • If no item frame is present during waxing, the existing icon is kept

Pl3xMap Integration

When Pl3xMap is installed, locations appear as markers on the web map. The plugin automatically downloads and renders the correct icon for each location.

Setup

  1. Install Pl3xMap on your server
  2. BaseManager detects it automatically on startup (check for Pl3xMap found - map markers enabled. in the console)
  3. Configure in config.yml under pl3xmap:
pl3xmap:
  enabled: true
  layer-label: "Bases"        # Label in the Pl3xMap layer control
  public-only: true           # Only show public locations
  icon-size: 24               # Icon size for square icons (blocks, heads)
  banner-icon-width: 24       # Banner width in pixels (height = 2x width)
  tooltip: |                  # HTML tooltip template
    <div style="text-align:center;">
      <b style="font-size:13px;color:#f5a623;">{name}</b>
      <br><span style="color:#aaa;font-size:11px;">{tag}</span>
      <br><span style="font-size:11px;">{coords}</span>
      <br><span style="color:#8bc34a;font-size:11px;">{owner}</span>
    </div>

Supported Icon Types on the Map

The map marker icon is determined by the location's icon item (set via item frame on lodestone or /loc icon command):

Icon Type How it's set Rendering Map Size
Block/Item texture /loc icon <tag> <name> <material> or item frame with any block/item Texture downloaded from Minecraft asset CDN icon-size x icon-size (square)
Player head Item frame with a player head Skin face cropped from Mojang API (8x8 region, scaled to 16x16) icon-size x icon-size (square)
Custom banner Item frame with a decorated banner All pattern layers (up to 6) rendered via Java2D: base color fill + per-layer texture colorization and alpha compositing banner-icon-width x banner-icon-width * 2 (1:2 ratio)
Default No icon set, or icon type not recognized Built-in icon.png from plugin resources icon-size x icon-size (square)

Banner rendering supports all 42 Minecraft 1.21 pattern types and all 16 dye colors. Pattern textures and rendered banners are cached in plugins/BaseManager/icons/.

How Banner Rendering Works

  1. Base color extracted from the banner material (e.g. MAGENTA_BANNER → magenta fill)
  2. For each pattern layer, the 64x64 entity texture is downloaded and the front face is cropped (20x40 pixels)
  3. Each mask is colorized by multiplying pixel RGB with the layer's dye color
  4. Layers are composited onto the canvas using alpha blending
  5. The final image is registered with Pl3xMap's icon registry

Sign Format

+------------------+
| [WOLVES]         |  <- Line 1: Tag (with or without brackets, empty = "BASE")
| Main Base        |  <- Line 2: Name part 1
| North            |  <- Line 3: Name part 2 (optional)
|                  |  <- Line 4: Name part 3 (optional)
+------------------+

Result: Tag = WOLVES, Name = Main Base North

  • Lines 2-4 are joined with spaces, empty lines ignored
  • Tag is case-insensitive, stored uppercase
  • Any tag is allowed (no whitelist)

Commands

Command Description Permission
/loc Open GUI browser basemanager.use (all)
/loc save <tag> <name> Save current location basemanager.admin (op)
/loc delete <tag> <name> Delete a location basemanager.admin (op)
/loc compass <tag> <name> Get tracking compass basemanager.admin (op)
/loc icon <tag> <name> <material> Set location icon basemanager.admin (op)
/loc list List all locations basemanager.admin (op)
/loc reload Reload configuration basemanager.reload (op)

Aliases: /base, /b, /location

Permissions

Permission Description Default
basemanager.use Open the location GUI All players
basemanager.admin Use management commands OP
basemanager.reload Reload configuration OP

Configuration

# Compass settings
compass:
  auto-dispose-on-arrival: true   # Remove compass when arriving
  arrival-radius: 10              # Blocks distance for arrival trigger
  show-distance-actionbar: true   # Show distance while holding compass
  actionbar-update-ticks: 20      # Update interval (20 = 1 second)

# Location limits
limits:
  max-locations-per-player: 50    # 0 = unlimited
  min-name-length: 2
  max-name-length: 32

# Database
database:
  file: storage.db                # SQLite file in plugin folder

# Lodestone registration
lodestone:
  enabled: true
  allowed-tags: []                # Empty = any tag allowed

# Pl3xMap web map integration
pl3xmap:
  enabled: true                   # Enable/disable map markers
  layer-label: "Bases"            # Layer name in Pl3xMap controls
  public-only: true               # Only show public locations
  icon-size: 24                   # Square icon size (blocks, heads)
  banner-icon-width: 24           # Banner width (height = 2x)

Dependencies

Dependency Version Scope Purpose
Paper API 1.21-R0.1 provided Minecraft server API
Pl3xMap 1.21.11-544 provided (optional) Web map marker API
ProtocolLib 5.4.0 provided (optional) Packet-level entity manipulation
Commodore 2.2 shaded Brigadier command completions
AnvilGUI 1.10.11 shaded Anvil-based search input

Test-only: JUnit 5 (5.11.0), MockBukkit (4.14.0), Mockito (5.14.0).

Building

# Build the plugin
./mvnw clean package

# Run tests
./mvnw test

# Full verification (compile + test + lint + spotbugs)
./mvnw clean verify

The built JAR is at target/basemanager-x.x.x.jar.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages