LeanCore

LeanCore：Hytale 服务器的内存治理器

LeanCore 专为降低 Hytale 服务器的 JVM 堆内存占用而构建。当玩家探索世界时，他们接触过的每个区域都会将对应的区块和实体保留在内存中，而游戏引擎释放这些资源的速度很慢，因此即使玩家早已离开，堆内存占用也会持续攀升并居高不下。LeanCore 通过模拟玩家的当前位置、即将前往的位置以及他们实际会返回的地图区域，来决定哪些内容应保持加载、哪些应被释放。它能释放多少内存取决于你的世界，并且区块卸载功能只有在运行 /leancore probe 后才会激活。

仅涉及服务器堆内存。它从不影响客户端的 FPS、GPU 或 TPS，也永远不会卸载玩家仍可见的区块。

使用与未使用 LeanCore 的对比

在同一个单人游戏中，服务器内存随时间的变化。没有此模组时，你访问过的每个区域都会保留在内存中，堆内存只会持续攀升直到你重启服务器。有了 LeanCore，闲置区域会冷却并释放内存，因此内存在高负载时上升，随后又会回落。

长时间游戏会话中的服务器内存使用情况  （柱状越高 = 内存占用越多）

未使用 LeanCore   ▁▂▃▄▅▆▇███████████   持续攀升至极限，然后你重启服务器
使用 LeanCore      ▂▄▆▄▂▄▆▄▂▄▆▄▂▄▆▄▂▄   上下波动，保持在可控范围内

LeanCore 的决策方式

每个操作都由两个信号驱动：当前内存的紧张程度，以及某个区域是否仍然需要。内存压力级别决定了操作的强度；而针对每个区域的检查则决定释放哪些区域是安全的。

压力驱动的操作

                           每个游戏刻
                                │
                 读取堆内存百分比  +  区块压力
                                │
              与当前服务器的历史数据对比排名
                                │
        ┌───────────────┬───────┴───────┬───────────────┐
        ▼               ▼               ▼               ▼
     舒适             注意             紧张              危急
    保持全视距       温和修剪         卸载远处          最大程度修剪 +
    无操作            + 降级闲置区域   休眠区域          卸载 + 垃圾回收
                                                         + 网络钩子

保留或释放一个区域

   每个闲置区域
        │
        ▼
   玩家在其内/附近，或被固定？     ──► 热区   保留，从不触及
        │ 否
        ▼
   在当前或预测视距内？           ──► 保留   会导致区块突然出现
        │ 否
        ▼
   闲置时间足够长变为休眠？       ──► 温区   保留，仍在冷却中
        │ 是
        ▼
   排名：距离远 + 不太可能返回 + 内置内容少
        │
        ▼
   释放   每次通过有限制，仅卸载无人可见的区块，
          并且如果卸载产生不良后果会进行回滚

LeanCore 的思考方式

它不是一个定时卸载区块的计时器。它会维护一个你世界的小型活动模型，并基于此做出决策。以下部分是其实际的逻辑。

1. 压力是相对于你自己的服务器而言的

在一个主机上 70% 的堆内存算是宽松的，而在另一个主机上可能接近卡顿的边缘，因此 LeanCore 并没有硬编码阈值。它会持续采样堆内存比率，根据你自己服务器的历史数据构建一个滚动分布，并将当前读数归类到不同的层级中：

同一个百分比在宽松的主机上可能显示为“舒适”，而在紧张的主机上则可能显示为“紧张”。以下所有操作都与此层级成比例地缩放。

2. 地图被分组为带有温度的区域

LeanCore 不会对单个区块进行推理。它将地图分组为区域（区块的小块），并跟踪每个区域的温度：

热区 -> 温区 -> 休眠区 -> 冻结区

当有任何玩家在区域内或附近时，该区域为热区；当所有玩家都离开后，它会按照你设定的计时器开始冷却。只有那些同时满足休眠区或冻结区且远离所有玩家的区域才会成为候选。这区分了“这里20分钟没人来过”和“玩家刚出去一会儿”的情况。

3. 距离是真实测量的

当检查一个区域距离玩家有多远时，它测量的是到该区域最近区块边缘的距离，而不是其中心（点到矩形，而非点到点）。使用中心距离会高估大型区域的距离，可能导致模组卸载你旁边紧邻的区块。

硬性规则：任何位于任何玩家视距加上一个额外宽松区域范围内的区域，永远不会成为卸载候选。这条界限是回收内存和导致区块突然弹出之间的区别。

4. 它会观察移动，从而保护你即将前往的地方

仅靠位置坐标是不够的。一个向新地形冲刺的玩家需要该地形在到达之前就被保留，否则加载器会跟不上，你会撞上一堵空区块墙。LeanCore 为每个玩家运行一个运动模型：平滑后的速度、估算的加速度、一个置信度值，以及一个数秒后的预测位置。这个预测点成为第二个锚点，因此一个移动玩家前方的扇形区域会被提前保护。当前视距和预测视距都是不允许卸载的区域。

一个可选的电影般视距增强功能，可以为快速移动的玩家扩大视距。默认是关闭的：每刻重写客户端视距半径会导致区块加载混乱，并在当前引擎上可能引起卡顿。在专用主机或拥有充足 CPU 和磁盘余量的强大机器上，额外的流式加载更容易被吸收，因此在那里启用是合理的；在嵌入式或受限的配置上请保持关闭。

5. 它会学习哪些区域对你来说真正重要

你的基地、你的矿洞、它们之间的路径：你会不断返回。而为了追逐一只怪物而跨越的一个地点，你可能再也不会看到。LeanCore 为每个区域维护一个重复使用距离和存活模型：它变热的频率和新近度，转化为一个回访得分，从而拉伸或缩短该区域的冷却时间。

当内存紧张且必须卸载某些东西时，驱逐会同时根据两个信号进行排名：

• 距离玩家有多远，以及
• 被回访的可能性有多低。

既远又被遗忘的区域优先处理。虽然远但属于你日常活动路线的区域会被保留。如果关闭重复使用模型，逻辑会简化为单纯的基于距离的判断，因此行为保持可预测。

6. 它会考虑玩家身份

一个搬运材料的建筑工、一个深藏地下的矿工、以及一个跨越生物群系的探索者，对内存的压力是不同的。一个在线分类器（活动感知）会观察破坏、放置、合成、战斗和移动行为，并通过一个基于近期活动的 Softmax 函数为每个玩家打上标签：

矿工 伐木工 农夫 建筑工 战斗者 探索者

这为一个需求模型提供数据，该模型在全局预算内为每个玩家设置一个保留权重，以便决策偏向于那些真正需要这些区块的玩家。在更大的主机上，一个策略赌博机会探索哪种视距策略在每个上下文中效果最好，一个留置组作为对照组保持不受影响，并且一个错误切割追踪器加上奖励反馈机制，允许模组撤回一个损害了高需求玩家的切割，而不是重复犯同样的错误。

7. 它会谨慎地操作，并且在正确的线程上执行

对于一个内存模组来说，有两种失败模式很重要：破坏世界状态，以及过于激进地卸载。LeanCore 对两者都进行了保护：

• 世界线程亲和性：对区块存储、区块追踪器或视距半径的每次读取或写入，都在所属世界的线程上运行。后台调度器仅负责协调。
• 探针门控：区块卸载保持关闭状态，直到一次性能力探针（/leancore probe）确认引擎钩子正常工作。
• 限制清扫次数：每次通过最多卸载一定数量的区块，因此永远不会导致无节制的批量卸载。
• 可见性检查：它只释放任何玩家的追踪器当前都看不到的区块。
• 先修剪再丢弃，并支持回滚：在负载下，它会先修剪视距再卸载，并且当层级历史记录显示某个更改产生了反效果时会进行回滚。

运行时配置文件

LeanCore 会根据主机自动调整自身规模，依据玩家数量，无需手动切换：

精简模式读取两个压力信号（堆内存层级和区块饱和度，即已加载区块相对于视距预算的比例），并仅在玩家离开足够长时间后才回收远处的休眠区域。

它明确不做什么

• 影响客户端 FPS、GPU 或渲染性能。它仅作用于服务器堆内存。 显然，优化内存使用有时可能有助于稳定甚至提升 FPS。但这不能保证！
• 改变 TPS 或模拟行为。
• 提供令人意外的默认设置：单人模式是保守的，电影级视距增强需要手动开启。

功能特性

• 自适应内存层级（舒适、注意、紧张、危急）从你服务器的历史数据中学习
• 区域休眠状态，包含热区、温区、休眠区、冻结区状态，你的自定义计时器，以及区域固定功能
• 预测性保留：运动模型保护当前和预测的视距
• 重复使用距离和存活模型：基于回访历史的每个区域冷却时间和驱逐顺序
• 视距半径修剪：在堆内存或区块压力下进行，不会低于你的下限，并在错误修剪时支持回滚
• 探针门控、限制次数的区块卸载，仅释放无人可见的区块
• 活动感知分类器和在全局预算内的每个玩家需求权重
• 策略赌博机、留置组和奖励反馈（在标准和完整配置下）
• 跨重启持久化的学习数据（gzip 快照，带修剪和过期时间）
• 始终开启的诊断：服务器日志本身就能解释模组执行了哪些操作及其原因
• 会话节省量报告、管理员 HUD（可选开启）、热力图、区域固定、可选的危急状态网络钩子

安装

1. 从文件标签页下载最新的 LeanCore JAR 文件
2. 将其放入服务器文件夹中的 mods/ 目录（Windows 系统为 %AppData%\Hytale\UserData\Mods\）
3. 启动服务器。配置文件创建在 mods/durkz_LeanCore/LeanCore.json
4. 如果你依赖区块卸载功能，运行 /leancore probe
5. 启动大约一分钟后，运行 /leancore status

命令

主命令：/leancore

/leancore status
/leancore memory
/leancore savings
/leancore zones
/leancore learn
/leancore learn player
/leancore probe
/leancore hud on|off|status
/leancore heatmap [limit]
/leancore zone pin|unpin|pins

管理员命令、权限和完整的配置参考：DurkzPRG 文档 发现 Bug？问题反馈

建议

• 单人或本地游戏：保持 localHostMode: AUTO。精简模式治理器和学习默认开启。
• 专用主机或与朋友联机：根据需要启用 governEnabled、learningEnabled 和 unloadEnabled，并在策略性卸载前运行 /leancore probe。
• 游戏 15 分钟后，查阅 /leancore savings 以查看真实的堆内存变化和治理器活动情况。

许可证： MIT