EasyWebMap
Hytale 服务器的实时网页地图。在浏览器中查看您的世界，支持实时玩家追踪、方向箭头和点击定位功能。可通过 iframe 嵌入您的网站，或使用 REST API 构建自定义工具。采用 Hytale 原生地图渲染技术。
EasyWebMap
专为欧洲 Hytale 生存服务器 play.hyfyve.net 构建
为你的 Hytale 服务器提供实时网页地图。在浏览器中查看你的世界，实时追踪玩家，并轻松集成到你的社区网站。
快速开始
- 从发布页面下载最新的
EasyWebMap.jar - 将其放入服务器的
mods文件夹 - 重启你的服务器
- 在浏览器中打开
http://localhost:8080
你能做什么
实时世界地图
- 在网页浏览器中查看整个世界的渲染图
- 地形随着玩家建造或破坏方块自动更新
- 自由缩放和平移
- 使用 Hytale 原生的地图渲染（与游戏内地图相同）
实时玩家追踪
- 在地图上看到所有在线玩家，并带有箭头标记
- 箭头会旋转，显示玩家面对的方向
- 点击侧边栏中的任何玩家，跳转到他们的位置
- 玩家位置通过 WebSocket 每秒更新一次
网站集成
使用 iframe 将地图直接嵌入你的社区网站：
<iframe src="http://your-server-ip:8080" width="100%" height="600"></iframe>
或者从你的服务器网站、Discord 或论坛链接到它。
REST API
使用内置 API 构建自定义工具：
| 端点 | 返回内容 |
|---|---|
GET /api/worlds |
可用世界列表 |
GET /api/players/{world} |
世界中所有玩家（名称、位置、方向） |
GET /api/tiles/{world}/{z}/{x}/{y}.png |
地图瓦片图像 |
WS /ws |
实时玩家位置更新 |
示例：获取玩家位置
const response = await fetch('http://your-server:8080/api/players/world');
const players = await response.json();
// [{ name: "Steve", x: 100, y: 64, z: -200, yaw: 1.57 }, ...]
示例：用于实时更新的 WebSocket
const ws = new WebSocket('ws://your-server:8080/ws');
ws.onmessage = (e) => {
const data = JSON.parse(e.data);
console.log(data.worlds); // 按世界划分的所有玩家位置
};
多世界支持
- 使用下拉菜单在世界之间切换
- 配置哪些世界可见
- 每个世界都有自己的瓦片缓存
命令
| 命令 | 功能 |
|---|---|
/easywebmap status |
显示连接数、缓存信息、SSL 状态和服务器状态 |
/easywebmap reload |
重新加载配置文件 |
/easywebmap clearcache |
清除所有缓存（内存 + 磁盘） |
/easywebmap pregenerate <radius> |
在当前位置周围预生成瓦片 |
/easywebmap renewssl |
强制立即更新 SSL 证书 |
所有命令都需要 easywebmap.admin 权限。
使用 Let's Encrypt 的 HTTPS（免费 SSL）
EasyWebMap 可以自动从 Let's Encrypt 获取和更新 SSL 证书。无需手动管理证书！
快速设置
将你的域名指向你的服务器 - 确保
map.yourserver.com（或你选择的任何域名）指向你服务器的 IP 地址。打开端口 80 - Let's Encrypt 需要通过连接端口 80 来验证你拥有该域名。确保你的防火墙允许此操作。
添加到你的 config.json：
{
"enableHttps": true,
"httpsPort": 8443,
"domain": "map.yourserver.com",
"acmeEmail": "admin@yourserver.com"
}
- 重启你的服务器 - 插件将自动：
- 向 Let's Encrypt 注册
- 为你的域名请求证书
- 开始在 8443 端口上提供 HTTPS 服务
就是这样！你的地图现在可以在 https://map.yourserver.com:8443 上访问
工作原理
启用 HTTPS 后，插件会：
- 在 Let's Encrypt 创建一个账号（存储在
ssl/account.key中） - 为你的域名请求证书
- 在端口 80 上响应 Let's Encrypt 的 HTTP-01 验证挑战
- 将证书存储在
ssl/domain.crt中，密钥存储在ssl/domain.key中 - 启动 HTTPS 服务器
- 每天检查证书是否需要更新（在到期前 30 天续期）
- 无需重启即可自动重新加载证书
HTTPS 配置选项
| 设置 | 默认值 | 功能 |
|---|---|---|
enableHttps |
false | 启用/禁用 HTTPS |
httpsPort |
8443 | HTTPS 端口（如果有权限，可使用 443） |
domain |
"" | 你的域名（HTTPS 必需） |
acmeEmail |
"" | 用于 Let's Encrypt 通知的邮箱（可选但推荐） |
useProductionAcme |
true | 设置为 false 用于测试（使用测试服务器，避免速率限制） |
SSL 命令
| 命令 | 功能 |
|---|---|
/easywebmap status |
显示 HTTPS 状态、域名和证书到期日期 |
/easywebmap renewssl |
强制立即更新证书 |
要求
- 域名 - 你需要一个指向你服务器的域名（IP 地址无法与 Let's Encrypt 配合使用）
- 端口 80 可访问 - Let's Encrypt 通过 HTTP 在端口 80 上验证域名所有权
- 端口 8443（或 443）可访问 - 用于提供 HTTPS 流量
先进行测试
在正式上线前，使用 Let's Encrypt 的测试服务器进行测试，以避免速率限制：
{
"enableHttps": true,
"domain": "map.yourserver.com",
"useProductionAcme": false
}
测试服务器会颁发浏览器不信任的测试证书，但这可以证明一切正常工作。验证后，将 useProductionAcme 设置回 true 并重启。
使用 443 端口（标准 HTTPS）
默认情况下，HTTPS 运行在 8443 端口。如果你想使用标准的 HTTPS 端口（443）：
{
"httpsPort": 443
}
注意：绑定到 443 端口可能需要以 root/管理员身份运行服务器，或使用反向代理。
在反向代理后面运行
如果你使用 nginx 或 Apache 作为反向代理，可以让代理处理 SSL，EasyWebMap 仅使用 HTTP。示例 nginx 配置：
server {
listen 443 ssl;
server_name map.yourserver.com;
ssl_certificate /etc/letsencrypt/live/map.yourserver.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/map.yourserver.com/privkey.pem;
location / {
proxy_pass http://localhost:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}
配置
配置文件：mods/cryptobench_EasyWebMap/config.json
{
"httpPort": 8080,
"updateIntervalMs": 1000,
"tileCacheSize": 20000,
"enabledWorlds": [],
"tileSize": 256,
"maxZoom": 4,
"renderExploredChunksOnly": true,
"chunkIndexCacheMs": 30000,
"useDiskCache": true,
"tileRefreshRadius": 5,
"tileRefreshIntervalMs": 60000,
"enableHttps": false,
"httpsPort": 8443,
"domain": "",
"acmeEmail": "",
"useProductionAcme": true
}
| 设置 | 默认值 | 功能 |
|---|---|---|
httpPort |
8080 | 网络服务器端口 |
updateIntervalMs |
1000 | 玩家更新频率（毫秒） |
tileCacheSize |
20000 | 内存中最多缓存的瓦片数（约 200MB，每瓦片 10KB） |
enabledWorlds |
[] | 世界白名单（空 = 全部） |
renderExploredChunksOnly |
true | 仅渲染玩家探索过的区块（防止卡顿/滥用） |
chunkIndexCacheMs |
30000 | 已探索区块索引的缓存时间（毫秒） |
useDiskCache |
true | 将瓦片保存到磁盘，以便在重启后持久化 |
tileRefreshRadius |
5 | 玩家必须在 N 个区块内，瓦片才会刷新 |
tileRefreshIntervalMs |
60000 | 瓦片刷新的最小间隔时间（毫秒） |
enableHttps |
false | 启用 Let's Encrypt 自动 HTTPS |
httpsPort |
8443 | HTTPS 连接端口 |
domain |
"" | 你的 SSL 证书域名 |
acmeEmail |
"" | 用于 Let's Encrypt 通知的邮箱 |
useProductionAcme |
true | 使用生产环境 Let's Encrypt（false = 测试环境） |
区块索引缓存（chunkIndexCacheMs）
当 renderExploredChunksOnly 启用时，插件需要检查哪些区块已被探索。这需要从磁盘读取索引。为避免每次瓦片请求都读取磁盘，索引会被缓存。
权衡：
- 较低的值（例如 5000ms）：新探索的区域在地图上显示更快，但磁盘读取更多
- 较高的值（例如 60000ms）：磁盘读取更少，但新探索的区域需要更长时间才能显示
实际意义：
| 缓存时间 | 磁盘读取次数 | 地图新鲜度 |
|---|---|---|
| 5000（5秒） | 约每分钟 12 次/世界 | 新区块在 5 秒内可见 |
| 30000（30秒） | 约每分钟 2 次/世界 | 新区块在 30 秒内可见 |
| 60000（1分钟） | 约每分钟 1 次/世界 | 新区块在 1 分钟内可见 |
示例场景： 玩家探索了一个新区域。如果 chunkIndexCacheMs: 30000，新的区块在缓存过期前（最多 30 秒）不会出现在网页地图上。在此期间，瓦片将显示为空。
注意： 这仅影响新探索的区块。已探索的区块始终可见。如有需要，/easywebmap clearcache 命令可以立即清除此缓存。
磁盘缓存与智能刷新
插件使用智能缓存系统来最小化服务器负载：
磁盘缓存：瓦片作为 PNG 文件保存到
mods/cryptobench_EasyWebMap/tilecache/。这些文件在服务器重启后仍然存在，因此重启后的第一个访问者不会触发大量瓦片生成。智能刷新：仅在以下情况下重新生成瓦片：
- 瓦片的时间早于
tileRefreshIntervalMs（默认：60 秒），且 - 玩家在
tileRefreshRadius区块内（默认：5 个区块）
- 瓦片的时间早于
为什么这很重要：
- 如果附近没有玩家，地形不可能发生变化，因此缓存的瓦片始终有效
- 这意味着 99% 的瓦片请求会立即从缓存中提供，服务器负载为零
- 只有活跃游玩的区域才会重新生成，且最多每分钟一次
流程：
瓦片请求 → 内存缓存？ → 立即提供
↓ 否
磁盘缓存？ → 足够新？ → 从磁盘提供
↓ 否 ↓ 旧
生成新的 玩家在附近？ → 否：提供过期版本（地形未变化）
↓ 是
重新生成瓦片
预生成
使用 /easywebmap pregenerate <radius> 预热缓存：
- 在你的位置周围的正方形区域内生成瓦片
- 跳过已缓存的瓦片和未探索的区块
- 在后台运行，瓦片之间延迟 50ms 以避免卡顿
- 示例：
/easywebmap pregenerate 50最多生成 10,201 个瓦片 - 没有最大限制 - 根据需要设置（较大的数值需要更多时间）
常见用例
公开服务器地图 - 让玩家看到每个人在哪里探索
网站小部件 - 嵌入到你的服务器主页，显示实时活动
直播叠加 - 在你的 Twitch/YouTube 直播中显示地图
Discord 机器人 - 使用 API 发布玩家位置或截图
管理工具 - 监控你服务器上的玩家活动
常见问题
问：如何从另一台电脑访问地图？
使用你服务器的 IP 而不是 localhost：http://192.168.1.100:8080
问：如何将其嵌入到我的网站？
使用 iframe：<iframe src="http://your-server:8080" width="800" height="600"></iframe>
问：我可以隐藏某些世界吗？
可以，在配置的 enabledWorlds 中添加特定的世界名称。空数组表示显示所有世界。
问：如何将其放在反向代理后面？
将 nginx/Apache 指向 8080 端口。WebSocket 路径为 /ws。
问：为什么地图上的某些区域显示为空？
默认情况下，仅渲染探索过的区块（renderExploredChunksOnly: true）。这可以防止服务器卡顿和用户滚动到未探索区域导致的滥用。如果希望渲染所有区块（不推荐用于公共服务器），可以在配置中将其设置为 false。
问：用户会利用地图使我的服务器卡顿吗？
使用默认设置不会。renderExploredChunksOnly 选项（默认启用）阻止渲染未探索的区块，因此滚动不会触发区块生成。
问：如何启用 HTTPS？
在配置中添加 "enableHttps": true 和 "domain": "your-domain.com"。插件会自动从 Let's Encrypt 获取免费的 SSL 证书。详情请参见上面的 HTTPS 部分。
问：为什么我的 SSL 证书不工作？ 常见问题：
- 域名未指向你服务器的 IP 地址
- 端口 80 被防火墙阻止（Let's Encrypt 需要通过此端口进行验证）
- 其他服务正在使用端口 80 请检查服务器日志以获取具体的错误信息。
问：我需要手动更新证书吗？ 不需要！插件每天自动检查，并在证书到期前 30 天更新。你无需手动操作。
问：我可以使用自己的 SSL 证书代替 Let's Encrypt 吗？ 目前仅支持自动 Let's Encrypt 证书。如果你需要使用自己的证书，请将 EasyWebMap 放在处理 SSL 的反向代理（nginx/Apache）后面。
问：如果 Let's Encrypt 不可用或受速率限制怎么办？ 插件将继续正常提供 HTTP 服务。它会重试证书请求并记录任何错误。一旦 Let's Encrypt 恢复可用，证书将自动获取。
从源代码构建
mvn clean package
cp target/EasyWebMap-1.0.0.jar /path/to/Server/mods/
需要 Java 25+ 和 Maven 3.8+。
许可证
MIT - 随心所欲！
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表，这里同步展示。