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:
   • /cm marker url https://example.com/icon.png --filename=icon
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