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

Enable custom markers:
- /cm on
List available marker names:
- /cm default list
Set default marker:
- /cm default set black
- or /cm default set custom1
Download a PNG marker from URL:
- /cm marker url https://example.com/icon.png --filename=icon
Apply downloaded marker:
- /cm default set icon
Force refresh:
- /cm refresh
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:

Enable custom mode:
- /cm on
Verify marker list:
- /cm default list
Set a known marker:
- /cm default set blue
Force refresh:
- /cm refresh
Confirm PNG exists in external marker folder:
- .../MapMarkers/Custom
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

Custom Markers - Core