Web 地图服务器
基本信息
| 属性 | 值 |
|---|---|
| HTTP 服务器类 | journeymap.client.webmap.WebMap（WebMap.java:25） |
| 服务器框架 | Javalin 4.6.8（dependencies.gradle 的 shadowImplementation） |
| 静态前端 | info.journeymap:webmap-client:0.8-SNAPSHOT（同上，随 jar 一起 shadow 并重定位） |
| 路由数 | 9（8 个 GET + 1 个 POST） |
| 默认端口 | 8080 |
| 状态 | 默认关闭（jm.webmap.enable 默认 false） |
| 侧 | 仅客户端 |
功能
启用后 JourneyMap 会在本机起一个 HTTP 服务器，把地图切片、实体数据、配置等以 JSON / PNG 形式暴露给浏览器里的前端应用。WebMap 是单例（getInstance()，WebMap.java:35-42），start() / stop() 幂等（if (!started) 守卫，:46、:130）。
9 条路由
全部在 WebMap.initialise() 中以 Javalin 链式 API 注册（WebMap.java:109-117）：
| 方法 | 路径 | 处理类 | 参数 | 响应 | 源码 |
|---|---|---|---|---|---|
| GET | /data/{type} |
routes/Data |
路径参数 type + 查询参数 images.since |
JSON | :109 |
| GET | /logs |
routes/Logs |
— | 文件内容，缺失时 404 | :110 |
| GET | /properties |
routes/Properties |
— | WebMapProperties.toJsonString()，完整客户端配置 |
:111 |
| GET | /resources |
routes/Resource |
resource |
PNG，404/500 分支 | :112 |
| GET | /skin/{uuid} |
routes/Skin |
路径参数 uuid |
玩家皮肤 PNG | :113 |
| GET | /status |
routes/Status |
— | JSON | :114 |
| GET | /tiles/tile.png |
routes/Tiles |
x、y、z、dimension、mapTypeString |
地图切片 PNG | :115 |
| GET | /polygons |
routes/Polygons |
— | JSON | :116 |
| POST | /properties |
routes/Properties |
查询参数（key-value） | 应用配置改动 | :117 |
关键参数细节：
/data/{type}缺images.since时返回 400 并附说明（Data.java:32-33）/tiles/tile.png的 4 个参数都有默认值：x/z/dimension缺省0，y缺省null，mapTypeString缺省MapType.Name.day.name()（Tiles.java:31-35）POST /properties遍历ctx.queryParamMap().keySet()（Properties.java:34）逐项应用，布尔值用Boolean.parseBoolean解析（:43）
响应头
before(ctx -> ...) 中对所有响应统一追加（WebMap.java:105-108）：
Access-Control-Allow-Origin: *
Cache-Control: no-cache
静态资源的三种来源
initialise() 的配置 lambda（:59-103）按优先级决定前端资源从哪加载：
| 优先级 | 条件 | 来源 | 源码 |
|---|---|---|---|
| 1 | 系统属性 journeymap.webmap.assets_root 非空 |
该路径（Location.EXTERNAL）；若同时存在 ../src/main/resources/assets/journeymap/web/ 则额外再挂一份 |
:60-80 |
| 2 | 正常游戏环境 | 先把 jar 内 /assets/journeymap/web/ 复制到 <mcDir>/journeymap/web/（若不存在），再从该目录提供 |
:83-97 |
| 3 | 上述目录也不存在 | 直接从 jar classpath 提供（Location.CLASSPATH） |
:99-102 |
优先级 1 是开发环境用的（testFile 路径写死为 ../src/main/resources...，:61）。
数值
| 数值名 | 值 |
|---|---|
| 路由总数 | 9（8 GET + 1 POST） |
| 端口默认值 / 范围 | 8080 / 80–10000 |
| 端口占用回退 | ServerSocket(0) 申请随机空闲端口 |
| 静态资源来源分支数 | 3 |
| 统一响应头数 | 2 |
| Javalin 依赖版本 | 4.6.8 |
| 状态枚举 | webmap/enums/WebmapStatus.java |
交互
| 触发 | 行为 |
|---|---|
客户端启动且 enabled = true |
JourneymapClient.postInitialize() 调 WebMap.getInstance().start()（JourneymapClient.java:311） |
| 启动成功 | 日志 Webmap is now listening on port: {}（WebMap.java:51） |
| 配置端口被占用 | 静默改用随机端口，仅记 warn（见 Web 地图选项） |
| 浏览器轮询 | 前端按 browserPoll（默认 2000 ms，CoreProperties.java:60）轮询 /data/{type} |
| 关闭 | stop() 调 app.stop() 并置 started = false（WebMap.java:128-136） |
| 开发模式启动 | 设置 -Djourneymap.webmap.assets_root=<path> 走优先级 1 |
安全提示
内置 HTTP 服务器无任何身份验证，且显式允许任意跨域（Access-Control-Allow-Origin: *）。同一局域网内的任何设备都能读取地图切片、实体数据（/data/{type}）与完整客户端配置（GET /properties），并能通过 POST /properties 修改设置。请仅在本地或可信网络启用。
注意
POST /properties只能改WebMapProperties相关的键（Properties.java:17-21返回的正是JourneymapClient.getWebMapProperties().toJsonString()），不是全部 6 个配置文件。