心态 | 世界网络地图

心态 | 世界网络地图

1.20.1 模组:在浏览器中显示带玩家标记的实时2D世界地图,并在区块加载时自动渲染。

管理

World Web Map - Minecraft 1.20.1 服务器网页地图模组

适用于 Forge 和 Fabric 的 Minecraft 1.20.1 服务器端网页地图模组。

World Web Map 会渲染你的 Minecraft 世界的 2D 俯视地图,并在浏览器中提供访问:

http://server-ip:8123

无需客户端模组。玩家只需要一个浏览器。


版本与要求

加载器 版本 Minecraft 加载器版本 额外依赖 Java Jar
Forge 0.2.1 1.20.1 Forge 47.x,已在 47.2.0 上测试 无 17 forgewebmap-0.2.1.jar
Fabric 0.2.1 1.20.1 Fabric Loader 0.15.11+ Fabric API 0.92.2+1.20.1 17 fabricwebmap-0.2.1.jar

功能

  • 带高度阴影的 2D 俯视地图。
  • 实时玩家标记及名称,每 2 秒更新一次。
  • 在光标下或移动端中心点显示生物群系名称。
  • 支持主世界、下界和末地的维度切换器。
  • 玩家探索时自动渲染,并对区块加载进行防抖处理。
  • 稳健的合成机制,使之前渲染的像素在重新渲染后仍能保留。
  • PNG 瓦片写入为原子操作,未变化时跳过写入。
  • 基于 Leaflet 1.9.4 的浏览器界面,支持缩放、平移、深色样式和移动端控件。

命令

所有命令都需要管理员等级 2。Forge 和 Fabric 的语法相同。

命令 描述
/webmap status 显示 Web 服务器状态、队列大小、工作线程数和已渲染瓦片数
/webmap render <tileX> <tileZ> 渲染一个主世界瓦片;瓦片坐标为 floor(blockCoord / 256)
/webmap render-area <minX> <minZ> <maxX> <maxZ> 将矩形主世界区域加入队列,最多 10,000 个瓦片
/webmap fullrender <radius> 渲染出生点周围的方形区域,半径以瓦片为单位
/webmap stoprender 清空渲染队列
/webmap reload 重新加载配置;如果绑定地址或端口发生变化,则重启 Web 服务器

瓦片坐标:

tileX = floor(blockX / 256)
tileZ = floor(blockZ / 256)

示例:

/webmap render 0 0

这会渲染方块 0..255 x 0..255。


配置与存储

方面 Forge Fabric
配置文件 config/forgewebmap-common.properties config/fabricwebmap-common.properties
瓦片路径 world/forgewebmap/tiles/ world/fabricwebmap/tiles/
静态 Web 文件 打包在模组 jar 的 /web/ 下 打包在模组 jar 的 /web/ 下

配置会在首次运行时自动创建。

键 默认值 描述
enabled true 启用模组
bindAddress 0.0.0.0 HTTP 绑定地址;使用 127.0.0.1 仅限本地访问
port 8123 HTTP 端口
tileSize 256 瓦片大小,以方块和像素为单位
renderThreads 1 后台 PNG 渲染工作线程数
maxTilesPerTick 1 每个渲染间隔采样的最大瓦片数
ticksBetweenRenders 20 队列处理步骤之间的服务器刻数
enablePlayerMarkers true 在地图上显示玩家
enableAutoRender true 区块加载时将瓦片渲染加入队列
chunkRenderDebounceMs 5000 最后一次区块加载事件后延迟多久再渲染该瓦片
renderRadiusAroundPlayers 4 保留用于玩家半径渲染行为
saveTilesInsideWorldFolder true 将瓦片存储在世界文件夹下
tilesDirectory 加载器特定 相对瓦片输出目录
logRenderProgress true 每渲染 50 个瓦片记录一次日志

瓦片布局:

world/<loader-webmap>/tiles/
├── overworld/
│   └── 0/
│       ├── 0_0.png
│       └── ...
├── the_nether/
│   └── 0/
└── the_end/
    └── 0/

API 端点

方法 路径 描述
GET / Web 地图前端
GET /app.js 前端 JavaScript
GET /style.css 前端 CSS
GET /tiles/{dim}/{zoom}/{x}/{z}.png PNG 地图瓦片
GET /api/status 模组状态、队列大小、工作线程数、已渲染瓦片数
GET /api/players 在线玩家及其名称、维度、坐标和偏航角
GET /api/config 瓦片大小、缩放范围和可用维度
GET /api/biome?dim=overworld&x=100&z=200 生物群系显示名称和注册表 ID

加载器差异

方面 Forge Fabric
模组入口点 @Mod 类 ModInitializer.onInitialize()
生命周期钩子 Forge 服务器事件 ServerLifecycleEvents
刻钩子 TickEvent.ServerTickEvent ServerTickEvents.END_SERVER_TICK
区块加载钩子 ChunkEvent.Load ServerChunkEvents.CHUNK_LOAD
命令钩子 RegisterCommandsEvent CommandRegistrationCallback.EVENT
日志记录 Forge LogUtils SLF4J LoggerFactory

两个加载器的行为意图完全一致。


已知限制

  • 仅支持 2D:尚无 3D、等距或洞穴地图。
  • 简单的方块颜色调色板:尚无资源包纹理或生物群系着色。
  • 渲染命令目前仅针对主世界,尽管瓦片存储支持全部三种原版维度。
  • fullrender 渲染出生点周围的方形区域,而非所有现有区域文件。
  • 未加载或未生成的区块会保持透明,直到被渲染/生成;在重新渲染期间,之前渲染的像素会被保留。
  • 无身份验证,也无 HTTPS;任何能通过网络访问端口 8123 的人都可以查看地图。
  • 仅原生渲染缩放级别 0;Leaflet 会在视觉上缩放其他缩放级别。