promotional bannermobile promotional banner
premium banner

Custom Markers - Core

This plugin is designed as a flexible base for modifying player markers on the map and navbar through endpoints. It aims to be accessible, modular, and easy to extend, providing a dynamic foundation for custom implementations.

Description

Custom Marker Core

A Hytale server plugin that replaces player map/navbar markers with customizable markers, supports per-player overrides, and allows downloading marker PNGs from URLs.

Overview

Custom Marker Core provides:

  • Toggle between custom and vanilla player markers
  • Global default marker selection
  • Per-player marker overrides
  • Marker download from URL (PNG only)
  • Public Java API for other plugins
  • Automatic cleanup of custom markers when players disconnect

Current Runtime Behavior

  • /cm on enables custom marker mode.
  • /cm off restores original Hytale markers.
  • The local player's own custom marker is intentionally not shown (prevents duplicate self marker).
  • Custom markers are produced by a world MarkerProvider.
  • On player disconnect, the plugin removes that player's custom marker from all worlds.

Default internal values:

  • customMarkersEnabled = false on startup
  • Default marker image: blue
  • Default custom image size: 24
  • Size clamp: 8..64

Commands

Base command: /cm

Implemented and working

  • /cm help
  • /cm info
  • /cm refresh
  • /cm on
  • /cm off
  • /cm default list
  • /cm default set <name>
  • /cm marker url <url> [filename]

Important command notes

  • Help text still includes some legacy lines (/cm set url, /cm endpoints), but the actual URL command is:
    • /cm marker url <url> [filename]
  • /cm endpoints is not registered in the main command collection.
  • /cm ui is currently not exposed as an active subcommand.

Typical Usage Flow

  1. Enable custom markers:
    • /cm on
  2. List available marker names:
    • /cm default list
  3. Set default marker:
    • /cm default set black
    • or /cm default set custom1
  4. Download a PNG marker from URL:
  5. Apply downloaded marker:
    • /cm default set icon
  6. Force refresh:
    • /cm refresh
  7. Revert to vanilla:
    • /cm off

Marker Name Resolution

/cm default set <name> accepts:

  • Built-in color names:
    • black, blue, cyan, green, orange, pink, purple, red, yellow
  • Custom file names without extension:
    • custom1 resolves to custom1.png

External Asset Directories

The plugin searches marker directories and prefers folders that actually contain PNGs.

Primary candidates:

  • mods/sulf-marker-core/Common/UI/WorldMap/MapMarkers
  • mods/sulf's_Custom Marker Core/Common/UI/WorldMap/MapMarkers
  • <pluginDataDir>/Common/UI/WorldMap/MapMarkers

Expected structure:

  • .../MapMarkers/Custom/*.png for custom markers
  • .../MapMarkers/Colors/*.png for color markers

For compatibility, the plugin may also copy custom PNGs into:

  • .../MapMarkers/*.png

URL Download Rules

For URL-based marker downloads:

  • PNG header is strictly validated
  • Max file size: 10 MB
  • Redirects enabled
  • Timeouts:
    • Connect: 8s
    • Read: 15s
  • Filename is sanitized (or auto-generated if omitted)
  • Image is resized to a square using current marker size (8..64)
  • Saved under Custom/ and mirrored in root marker directory for resolution

Public Java API (CORE)

Access:

CustomMarkerCoreApi api = CustomMarkerCoreApi.get();
if (api == null) return;

Marker mode and refresh

api.setCustomMarkersEnabled(boolean enabled);
api.refreshMarkers();

Default marker control

api.setDefaultMarkerImage(String imagePath);
api.setDefaultMarkerColor(String color);

api.setDefaultMarkerImageFromUrl(String url);
api.setDefaultMarkerImageFromUrl(String url, String fileName);
api.setDefaultMarkerImageFromUrl(String url, String fileName, Integer size);

Per-player marker control

api.setPlayerMarkerImages(Map<UUID, String> markerImages);
api.setPlayerMarkerImage(UUID playerUuid, String imagePath);
api.setPlayerMarkerColor(UUID playerUuid, String color);

api.setPlayerMarkerImageFromUrl(UUID playerUuid, String url);
api.setPlayerMarkerImageFromUrl(UUID playerUuid, String url, String fileName);
api.setPlayerMarkerImageFromUrl(UUID playerUuid, String url, String fileName, Integer size);

api.clearPlayerMarkerImage(UUID playerUuid);

Size and listing

int size = api.getCustomMarkerSize();
api.setCustomMarkerSize(int size);

List<String> colors = api.getMarkerColorList();
List<String> downloaded = api.getMarkerList();

World/Event Integration

The plugin hooks into server lifecycle/events:

  • Registers a marker provider on AddWorldEvent
  • Applies marker mode logic on PlayerConnectEvent
  • Removes disconnected players' custom markers on PlayerDisconnectEvent

Quick Troubleshooting

If custom markers are not visible:

  1. Enable custom mode:
    • /cm on
  2. Verify marker list:
    • /cm default list
  3. Set a known marker:
    • /cm default set blue
  4. Force refresh:
    • /cm refresh
  5. Confirm PNG exists in external marker folder:
    • .../MapMarkers/Custom
  6. Reconnect client if assets appear stale

If URL download fails:

  • Ensure direct PNG URL
  • Ensure file is valid PNG
  • Ensure file size under 10 MB
  • Retry with explicit filename:
    • /cm marker url <url> myicon.png