自定义标记 - 核心

自定义标记 - 核心

此插件旨在作为一个灵活的基础，用于通过端点修改地图和导航栏上的玩家标记。它力求易于访问、模块化且易于扩展，为自定义实现提供动态基础。

早期插件

自定义标记 - 核心预览查看大图

Custom Marker Core

一款 Hytale 服务器插件，可将玩家地图/导航栏标记替换为可自定义的标记，支持按玩家覆盖，并允许从 URL 下载标记 PNG 图片。

概述

Custom Marker Core 提供：

  • 在自定义和原版玩家标记之间切换
  • 全局默认标记选择
  • 按玩家标记覆盖
  • 从 URL 下载标记（仅限 PNG）
  • 面向其他插件的公共 Java API
  • 玩家断开连接时自动清理自定义标记

当前运行时行为

  • /cm on 启用自定义标记模式。
  • /cm off 恢复原始 Hytale 标记。
  • 本地玩家自己的自定义标记有意不显示（防止重复的自身标记）。
  • 自定义标记由一个世界 MarkerProvider 生成。
  • 当玩家断开连接时，插件会从所有世界移除该玩家的自定义标记。

默认内部值：

  • 启动时 customMarkersEnabled = false
  • 默认标记图片：blue
  • 默认自定义图片大小：24
  • 大小限制：8..64

命令

基础命令：/cm

已实现并正常工作的命令

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

重要命令说明

  • 帮助文本仍包含一些旧的行（/cm set url、/cm endpoints），但实际 URL 命令是：
    • /cm marker url <url> [filename]
  • /cm endpoints 未注册到主命令集合中。
  • /cm ui 当前未作为活跃子命令暴露。

典型使用流程

  1. 启用自定义标记：
    • /cm on
  2. 列出可用的标记名称：
    • /cm default list
  3. 设置默认标记：
    • /cm default set black
    • 或 /cm default set custom1
  4. 从 URL 下载 PNG 标记：
    • /cm marker url <a href="/linkout/remoteUrl?https%253a%252f%252fexample.com%252ficon.png" target="_blank" rel="nofollow">https://example.com/icon.png</a> --filename=icon
  5. 应用已下载的标记：
    • /cm default set icon
  6. 强制刷新：
    • /cm refresh
  7. 恢复至原版：
    • /cm off

标记名称解析

/cm default set <name> 接受：

  • 内置颜色名称：
    • black、blue、cyan、green、orange、pink、purple、red、yellow
  • 不含扩展名的自定义文件名：
    • custom1 解析为 custom1.png

外部资源目录

插件会搜索标记目录，并优先选择实际包含 PNG 的文件夹。

主要候选目录：

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

预期结构：

  • .../MapMarkers/Custom/*.png 用于自定义标记
  • .../MapMarkers/Colors/*.png 用于颜色标记

为了兼容性，插件也可能将自定义 PNG 复制到：

  • .../MapMarkers/*.png

URL 下载规则

对于基于 URL 的标记下载：

  • PNG 文件头经过严格验证
  • 最大文件大小：10 MB
  • 允许重定向
  • 超时：
    • 连接：8s
    • 读取：15s
  • 文件名会被清理（如果省略则自动生成）
  • 图片会调整为当前标记大小的正方形（8..64）
  • 保存在 Custom/ 目录下，并在根标记目录中镜像一份以利于解析

公共 Java API (CORE)

访问方式：

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

标记模式与刷新

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

默认标记控制

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);

按玩家标记控制

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);

大小与列表

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

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

世界/事件集成

插件挂接到服务器生命周期/事件：

  • 在 AddWorldEvent 上注册标记提供器
  • 在 PlayerConnectEvent 上应用标记模式逻辑
  • 在 PlayerDisconnectEvent 上移除已断开玩家的自定义标记

快速故障排除

如果自定义标记不可见：

  1. 启用自定义模式：
    • /cm on
  2. 验证标记列表：
    • /cm default list
  3. 设置一个已知标记：
    • /cm default set blue
  4. 强制刷新：
    • /cm refresh
  5. 确认 PNG 存在于外部标记文件夹中：
    • .../MapMarkers/Custom
  6. 如果资源看起来陈旧，请重新连接客户端

如果 URL 下载失败：

  • 确保是直接的 PNG URL
  • 确保文件是有效的 PNG
  • 确保文件大小小于 10 MB
  • 使用明确的文件名重试：
    • /cm marker url <url> myicon.png