HynfinityWebMap

WebMap

在线演示： https://hynfinity.com/map

Hytale 服务端版本 2026.03.26 或更高版本

为你的 Hytale 服务器提供实时网页地图。在浏览器中查看你的世界，实时追踪玩家，并将地图嵌入到你的社区网站中。

快速开始

1. 从 Releases 下载最新的 WebMap-*.jar 文件
2. 将其放入服务器的 mods/ 目录
3. 启动服务器
4. 在浏览器中打开 http://你的服务器IP:8080

功能

世界地图

• 以 PNG 瓦片形式呈现 Hytale 原生地图渲染
• 可配置的金字塔结构，每个缩放级别采用平均降采样
• 后台预热器预渲染全部已探索区域，让首位访客无需等待瓦片
• 游戏内修改（放置/破坏）数秒内更新网页地图——玩家编辑过的每个瓦片都会重新渲染，且仅将实际改变的瓦片写入磁盘（基于每个瓦片的内容哈希跳过冗余写入）
• 磁盘瓦片缓存，重复访问使用浏览器缓存

玩家追踪

• 每个玩家使用真实的游戏内头部头像渲染，根据玩家的自定义外观从服务器角色资源中合成
• 每个标记上方的方向箭头显示玩家注视方向（偏航角）
• 玩家列表抽屉显示实时坐标；点击可居中或跟随视角
• 自动跟随功能可耐受临时隐形（如蹲下），并在玩家重新出现时恢复
• 位置通过服务器推送事件（SSE）实时推送

实时聊天

公共聊天消息会被实时中继到网页地图上一个可折叠的聊天面板。玩家标记上方也会显示一个持续 5 秒的对话气泡。玩家可通过 /webmap chat 命令选择退出。桌面端默认打开面板，移动端默认折叠。

可分享的 URL

每个视图都可通 URL 哈希重现——世界、位置、缩放和跟随的玩家都被编码。复制 URL 可分享精确的视图，或重新加载以恢复你上次的位置。

#world=overworld&x=-128.5&z=42&zoom=0&follow=<uuid>

多世界

从顶栏切换世界。每个世界有自己的瓦片缓存和脏瓦片追踪器，因此一个世界的编辑不会触发另一个世界的重新渲染。

网站嵌入

<iframe src="http://你的服务器IP:8080" width="100%" height="600"></iframe>

REST API

端点	返回内容
GET /api/worlds	世界列表 + 元数据（比例尺、边界、玩家数量、缩放范围）
GET /api/players	所有世界中当前的玩家位置（快照）
GET /api/players/stream	玩家位置的实时 SSE 流
GET /api/tiles/{world}/{z}/{x}/{y}.png	给定缩放级别的地图瓦片
GET /api/players/{uuid}/head.png	渲染的头部 PNG（离线或头部禁用时返回 404）
GET /api/claims/{world}	领地覆盖数据（SimpleClaims 禁用时返回 404）
GET /api/markers/{world}	地图标记/兴趣点（标记禁用时返回 404）
GET /api/shops/{world}	包含交易的 BarterShop 数据（BarterShop 禁用时返回 404）
GET /api/marker-icons/{name}.png	标记图标图片（内置 + 管理员覆盖）

命令

命令	描述	权限
/webmap status	服务器状态、SSE 客户端数量、缓存和预热摘要	—
/webmap reload	重新加载 config.json	com.hynfinity.webmap.admin.reload
/webmap cache stats	瓦片数量和磁盘使用情况	—
/webmap cache status	详细的缓存和正在进行的预热进度	—
/webmap cache clear	清空瓦片缓存	com.hynfinity.webmap.admin
/webmap cache warm	触发立即后台预热	com.hynfinity.webmap.admin
/webmap cache regen	清空缓存然后立即预热（完整重新渲染）	com.hynfinity.webmap.admin
/webmap cache stop	取消正在运行的预热/重新渲染	com.hynfinity.webmap.admin
/webmap hide	在地图上隐藏自己	—
/webmap show	在地图上显示自己	—
/webmap chat	切换是否将聊天消息中继到网页地图	—

别名：/wm, /map。除非明确设置了权限，非管理员命令不受限制。

配置

配置文件在首次运行时创建于插件数据文件夹。

{
  "configVersion": 4,
  "httpPort": 8080,
  "httpHost": "0.0.0.0",
  "basePath": "/",
  "threadPoolSize": 4,
  "tileCacheDirectory": "tile-cache",
  "tileCacheMaxEntries": 10000,
  "playerUpdateIntervalSeconds": 3,
  "tileRefreshIntervalSeconds": 300,
  "worldListMode": "whitelist",
  "enabledWorlds": [],
  "showPlayerAltitude": false,
  "showPlayersByDefault": true,
  "allowPlayerToggleVisibility": true,
  "hidePlayersWhenCrouching": true,
  "corsOrigin": "*",
  "minZoom": -3,
  "maxZoom": 4,
  "maxNativeZoom": 0,
  "prewarmEnabled": true,
  "prewarmStartupDelaySeconds": 10,
  "prewarmIntervalMinutes": 30,
  "prewarmThrottleMillis": 50,
  "showPlayerHeads": true,
  "showPlayerDirection": true,
  "characterAssetsPath": "",
  "playerHeadCacheMaxEntries": 500,
  "playerHeadSize": 32,
  "playerHeadProviderUrl": "https://hyvatar-worker.bodyagavril.workers.dev/?username={username}",
  "simpleClaimsEnabled": false,
  "simpleClaimsShowByDefault": true,
  "simpleClaimsFillOpacity": 0.25,
  "simpleClaimsRefreshSeconds": 30,
  "markersEnabled": false,
  "markersShowByDefault": true,
  "markersRefreshSeconds": 60,
  "markersFilterMode": "none",
  "markersFilterPatterns": [],
  "barterShopEnabled": false,
  "renderQuality": "medium",
  "notifyAdminsOnGeneration": true,
  "chatRelayEnabled": true,
  "showChatBubbles": true,
  "hstatsEnabled": true
}

HTTP 服务器

设置项	默认值	描述
httpPort	8080	网页服务器端口
httpHost	0.0.0.0	绑定地址
basePath	/	URL 前缀（例如，在反向代理后设置为 /map）
threadPoolSize	4	HTTP 工作线程池大小
corsOrigin	*	Access-Control-Allow-Origin 头的值

瓦片和缩放

设置项	默认值	描述
tileCacheDirectory	tile-cache	缓存目录（相对于插件数据文件夹）
tileCacheMaxEntries	10000	磁盘瓦片的 LRU 上限
tileRefreshIntervalSeconds	300	随每个瓦片发送的 Cache-Control max-age
minZoom	-3	客户端可缩放到的最远距离（更负的值 = 更宽的视野）
maxZoom	4	客户端可放大的最近距离
maxNativeZoom	0	服务端渲染的最高缩放级别；在此之上客户端进行放大
prewarmEnabled	true	在后台预渲染金字塔
prewarmStartupDelaySeconds	10	启动后首次预热运行的延迟
prewarmIntervalMinutes	30	定期预热间隔
prewarmThrottleMillis	50	预热期间瓦片渲染之间的休眠时间（保持游戏正常运行）
renderQuality	"medium"	瓦片 PNG 分辨率："low"（32 像素）、"medium"（96 像素）、"high"（192 像素）。更改此设置并重新加载将清空瓦片缓存
notifyAdminsOnGeneration	true	当管理员触发预热或重新渲染时，向管理员发送游戏内进度消息（每约 10%）

玩家

设置项	默认值	描述
playerUpdateIntervalSeconds	3	位置轮询和广播的频率
showPlayerAltitude	false	在 UI 中包含 Y 坐标
showPlayersByDefault	true	玩家默认是否在地图上可见
allowPlayerToggleVisibility	true	允许使用 /webmap hide 和 /webmap show
hidePlayersWhenCrouching	true	自动隐藏蹲下的玩家
showPlayerDirection	true	在每个标记上方绘制方向箭头

玩家头部

设置项	默认值	描述
showPlayerHeads	true	在地图上渲染每个玩家的游戏内头部
characterAssetsPath	""	Hytale 角色资源路径；为空则自动发现
playerHeadCacheMaxEntries	500	渲染后头部 PNG 的 LRU 上限
playerHeadSize	32	输出边长（像素，范围 8–256）
playerHeadProviderUrl	(hyvatar)	外部头部提供器 URL；留空则仅使用本地合成器。{username} 在运行时被替换

实时聊天

设置项	默认值	描述
chatRelayEnabled	true	将公共聊天消息实时中继到网页地图聊天面板
showChatBubbles	true	玩家发送聊天消息时，在其标记上方显示对话气泡（5 秒后自动消失）

玩家可以使用 /webmap chat 命令单独选择退出聊天中继。

分析

设置项	默认值	描述
hstatsEnabled	true	向 HStats 报告匿名服务器统计数据（操作系统、Java 版本、CPU 核心数、在线玩家数量——不含用户名或 IP）

SimpleClaims 集成

默认关闭。 启用后，WebMap 通过反射从 SimpleClaims 插件读取领地数据，并将每个被认领的区块在地图上绘制为可点击的矩形。点击矩形会弹出一个窗口，显示队伍名称、所有者、成员数量、PvP 标志和方块保护标志。

如果未安装 SimpleClaims，插件会正常加载，集成保持休眠状态——/api/claims/{world} 返回 404，顶栏切换按钮被隐藏。矩形位于基础瓦片已显示内容的上面，因此如果 SimpleClaims 也在瓦片中烘焙了自己的色调，两者都将保持可见。

设置项	默认值	描述
simpleClaimsEnabled	false	总开关。关闭时，/api/claims/{world} 返回 404，前端隐藏图层控件
simpleClaimsShowByDefault	true	页面加载时覆盖层是否可见（用户可随时从顶栏切换）
simpleClaimsFillOpacity	0.25	每个领地矩形的填充不透明度（0 = 仅描边，1 = 完全不透明）
simpleClaimsRefreshSeconds	30	前端重新获取领地数据的频率，使游戏内新领地无需重新加载即可显示在地图上

端点 GET /api/claims/{world} 为每个队伍返回一条记录，包含完整的区块列表，格式为 [[chunkX, chunkZ], ...] 对。每个区块大小为 32 × 32 方块（Hytale 的原生区块大小）。

地图标记（兴趣点）

默认关闭。 启用后，WebMap 在地图上显示 Hytale 原生的兴趣点——出生点、被遗忘的神殿、传送门、共享玩家标记以及由其他模组添加的任何标记。图标是真实的 Hytale 标记图片，内置于插件 JAR 中，并在启动时从已安装的模组 JAR 中自动提取。

当有玩家在线时，标记从 Hytale 的 WorldMapManager 标记提供器中收集。磁盘缓存可在玩家断开连接和服务器重启之间保留标记，确保地图永远不会为空。

如果未安装任何支持标记的模组，则仅显示出生点。

设置项	默认值	描述
markersEnabled	false	总开关。关闭时，/api/markers/{world} 返回 404，顶栏按钮被隐藏
markersShowByDefault	true	页面加载时标记图层是否可见
markersRefreshSeconds	60	前端重新获取标记的频率
markersFilterMode	"none"	"none"（显示全部）、"whitelist"（仅显示匹配的）或 "blacklist"（隐藏匹配的）
markersFilterPatterns	[]	与每个标记的 ID 和图片名称匹配的正则表达式模式。示例：["Temple", "Spawn"] 仅白名单显示神殿和出生点标记

管理员可以将自定义图标 PNG 文件放置在 {dataFolder}/marker-icons/ 目录下，以覆盖内置图标。文件通过名称匹配（例如 Spawn.png、Temple_Gateway.png）。

BarterShop 集成

默认关闭。 启用后，WebMap 直接从磁盘上的 JSON 文件读取来自 Makapar 的 Barter Shops 的商店数据。点击地图上的商店标记会显示一个"查看商店"按钮，该按钮打开一个详细面板，显示该商店提供的所有交易（出售/需求的物品及数量）。

如果未安装 BarterShop，集成保持休眠状态——按钮被隐藏，/api/shops/{world} 返回 404。插件对 BarterShop 没有编译时依赖——它直接读取纯 JSON 文件。

设置项	默认值	描述
barterShopEnabled	false	地图上商店详细面板的总开关

世界

设置项	默认值	描述
worldListMode	whitelist	"whitelist"（空列表 = 所有世界可见）或 "blacklist"
enabledWorlds	[]	根据模式的白名单或黑名单

反向代理

要在 nginx 后通过 https://play.example.com/map 提供地图服务：

1. 在配置中设置 "basePath": "/map"
2. 添加 location 块：

location /map/ {
    proxy_pass http://localhost:8080/map/;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
}

常见问题

如何从其他设备访问地图？ 使用服务器的 IP 而不是 localhost：http://192.168.1.100:8080。

为什么有些区域显示为空白？ 只有已探索的区块才会被 Hytale 的地图系统渲染。未访问的区块会显示为空白，直到有玩家走进它们。

在移动设备上能用吗？ 可以。UI 具有横向顶栏和右侧抽屉，可在窄视口上滑入。

如何启用 HTTPS？ 使用反向代理（nginx、Caddy 等）来处理 TLS 终止。该插件仅提供 HTTP 服务。

玩家建造了某个东西，但地图仍显示旧地形。 更新管道会在后台每几秒重新渲染脏瓦片。如果约 10 秒后瓦片仍未刷新，请检查 /webmap status——处理器将报告有多少基础瓦片和缩放的瓦片待处理。手动执行 /webmap cache warm 会强制进行一次整个世界范围的运行。