OptiPortal

OptiPortal

OptiPortal 是一款专注于减少或消除传送门旅行时因区块加载导致卡顿的 Hytale 服务器优化插件。它会追踪传送点和传送门目的地，从实际传送中学习传送门链接，并在玩家抵达前预加载目的地区块，从而降低冷加载磁盘 I/O、避免突发区块加载峰值，并减少传送、传送点、复活及类似位置切换时的 TPS 和 MSPT 下降。

OptiPortal 通过 HOT、WARM 和 COLD 三级缓存来管理区域，持久化有用的缓存状态，并在服务器压力较大时自适应预加载行为，从而在不一直保持所有区块加载的情况下提升区块就绪度。它还提供实时诊断工具、逐区域调优、TTL 控制、备份以及热重载配置功能。

功能

• 在传送门旅行完成前预加载目的地区块
• 在运行时自动学习传送门之间的链接，并将其存储在 portal-links.json 中
• 维护三级缓存模型：HOT、WARM 和 COLD
• 支持 JSON、SQLITE、H2 和 MYSQL 存储后端
• 监听 warps.json 的实时更新
• 可选集成 Gravestones 插件
• 直接运行 /preload（无参数）时显示原生游戏内 UI
• 包含管理员命令，用于区域清理、链接管理、TTL 覆盖和运行时状态检查

核心概念

三级缓存

等级	用途
HOT	区块已加载并立即可用
WARM	区块保留在内存中，适用于高流量或固定目的地
COLD	区块不再驻留内存，但可持久化到磁盘以加快恢复速度

区域会根据活动情况自然降级。保活任务可以将重要区域更长时间地保持在原位。

传送门链接注册表

传送门配对是通过玩家的实际传送学习到的。一旦 OptiPortal 拥有足够的观察数据来信任某个链接，靠近该配对的一端就会预加载另一端。如果传送门的目的地后来发生变化，学习到的映射会在新的传送事件发生时自动更新。

负载感知预加载

当前实现包括：

• 基于地形密度的区块优先级
• 靠近 WorldPath 路线时的走廊优先级
• 速度感知的预测半径提升
• TPS 敏感型节流
• 垃圾回收感知的批量延迟
• 已加载区块压力回退
• 区块失败重试冷却
• 针对过载异步路径的熔断器

命令

所有命令均使用 /preload 前缀。

直接运行 /preload（无参数）会为世界内的玩家打开原生 UI 面板。

区域管理

命令	描述
/preload list	列出所有已知区域条目
`/preload strategy <WARM	PREDICTIVE>`
`/preload shape <ELLIPSOID	CYLINDER
/preload radius <id> <X> [Z]	设置区域半径，可选择单独的 Z 半径
/preload radiusxz <id> <rx> <rz>	传统非对称半径命令；推荐使用 radius
/preload activation <id> <distance>	覆盖单个区域的水平激活距离
/preload activation <id> reset	重置单个区域的激活距离
/preload setwarm <id> [radius]	强制将区域设为 WARM 并立即加载
/preload unsetwarm <id>	将区域恢复为 PREDICTIVE 并释放热区块
/preload preload <id>	立即触发预测性预加载
`/preload ttl <days	-1
/preload zone <id>	显示单区域诊断详情
/preload delete <id>	删除区域并执行完整清理
/preload flush	重新计算区域 RAM 值并将所有当前区域条目写回存储

诊断

命令	描述
/preload ram	显示缓存 RAM 估算值
/preload status	显示异步健康状态、熔断器状态、TPS、区块数量和区域等级总数
/preload links	列出已确认和待定的传送门链接
/preload links remove <id>	移除某个传送门的已确认链接
/preload links clear-pending	清除未确认的候选链接
/preload help	在聊天中打印命令帮助

维护

命令	描述
/preload refresh warps	立即重新读取 warps.json
/preload reload	在支持的情况下热重载 config.json
`/preload migrate <JSON	SQLITE
/preload backup list	列出 WAL 备份
/preload backup restore <date>	恢复备份并建议重启

集成

传送点

OptiPortal 会读取 warps.json 并将传送点目的地注册为预加载区域。监视器可以自动刷新，/preload refresh warps 会强制立即重新读取。

如果你的传送点数据使用不同的属性名称，可以通过 warps.* 设置来配置字段名称。

墓碑

启用后，OptiPortal 可以监视墓碑数据并在死亡或恢复位置附近进行预加载。此集成是可选的，取决于是否安装了 Gravestones 插件。

存储后端

后端	配置值	备注
JSON	JSON	设置最简单，人类可读的平面文件
SQLite	SQLITE	单文件 SQL 数据库，提供良好的默认升级路径
H2	H2	嵌入式 SQL 后端，拥有更强的数据库工具支持
MySQL	MYSQL	适用于共享或远程设置的外部数据库

JSON 存储使用 WAL 安全的原子写入和备份恢复。SQL 后端支持相同的区域模型，同时提升了在更大或更繁忙服务器上的性能。

热重载

/preload reload 可以应用 config.json 的大部分设置而无需重启，包括许多激活、衰减、保活、缓存、监视器、UI 和指标设置。

对于在启动时连接核心基础设施的设置，仍然需要完全重启服务器，例如：

• backend
• startupLoadStrategy
• rebuildFromChunksOnCorruption
• scheduledRebuildIntervalHours
• mysql.*
• cache.cacheDirectory
• cache.maxCacheAgeDays
• immuneToSimulationReduction
• updateChecker.enabled
• integrations.gravestone.pluginId
• metrics.bstatsPluginId

如果 config.json 包含无效的 JSON，则重载会被拒绝，当前运行时配置保持不变。

重要配置区域

完整的默认配置文件位于 [src/main/resources/config.json](/i:/OptiPortal - Copy - Copy/OptiPortal safe/PreloadPlugin3/src/main/resources/config.json)。

管理员通常首先关心的设置包括：

• backend
• defaults.strategy
• defaults.warmRadius
• activation.distance
• activation.distanceVertical
• activation.predictiveRadius
• keepalive.*
• decay.*
• ttl.*
• warps.*
• integrations.gravestone.*
• portalLinks.confidenceThreshold

运行时说明

• 传送门链接与区域存储分开保存，位于 portal-links.json 中
• 冷缓存数据可以持久化到 preload-cache/ 目录
• 可以通过 /preload backup ... 列出和恢复 WAL 备份
• /preload status 是确认负载节流或异步基础设施是否影响行为的最快捷方式

测试服务器

CPU: E5-1650v4 RAM: 48GB 存储: NVMe 操作系统: Proxmox LXC / Ubuntu