LeanCore

Установка, команды, конфиг и права для LeanCore.

---

Обзор

LeanCore это серверный governor памяти для Hytale. Он смотрит на heap, оставшийся после каждой сборки мусора (плюс old gen после GC и тренд роста), и действует по этим данным: урезает дальность обзора и радиус симуляции при реальной нагрузке, держит недавно посещённые чанки загруженными, пока есть свободный heap (обратный путь не читается с диска), и тормозит стриминг чанков, когда памяти мало. Движок и так выгружает любой чанк, за которым не следит ни один игрок, примерно через 7,5 секунды; LeanCore никогда не удаляет чанки сам. Соло встроенный мир работает в профиле LITE; STANDARD и FULL добавляют полные пути governor, если включены. Включает Activity Sense, отчёт о heap за сессию (/leancore savings), выделенный bootstrap, всегда включённую диагностику [diag], снапшот обучения v9 и безопасный dispatch в потоке мира. Требуется сервер Hytale >=0.7.0. Не трогает FPS, GPU и TPS клиента.

---

Установка

1. Скачайте LeanCore-1.8.0.jar со вкладки Files на CurseForge
2. Положите JAR в папку mods/ сервера
3. Запустите сервер. Конфиг создаётся в mods/durkz_LeanCore/LeanCore.json
4. Выдайте персоналу доступ к HUD/админке (см. Права ниже)
5. Выполните /leancore memory и /leancore status примерно через минуту

Одиночная игра / локальный хост: используйте группы hudViewerGroups / hudAdminGroups по умолчанию (OP, Admin) или выдайте права через /perm.

---

Профили встроенного хоста

Игроки	Профиль	Тик	Что работает
1 (соло локально)	LITE	30с (60с в простое), нагрузка каждые 5с	Lite governor, адаптивный обзор, удержание, lite обучение
1 + embeddedStandardProfile	STANDARD	15с	Локальная проверка govern/learning без 5с тика FULL
2–8 (друзья)	STANDARD	15с	Классификатор; govern/learning/HUD, если включены в конфиге
9+ (плотный локальный)	FULL	5с	Полный runtime по конфигу
Выделенная JVM	FULL	5с	Полный runtime по конфигу

Конфиг: localHostMode: "AUTO" (по умолчанию). "PASSIVE" полностью отключает фоновый runtime. На выделенной JVM ставьте dedicatedServerMode: true.

Лог запуска (соло): LeanCore 1.8.0 setup (localHostMode=AUTO). и Runtime started profile=LITE. Заходит друг → profile LITE -> STANDARD.

---

Уровни памяти

Уровень	Heap после GC (по умолчанию)	Что делает LeanCore
COMFORT	ниже watchHeapRatio (0.70)	полный обзор, удержание чанков работает
WATCH	от 0.70	мягкая урезка обзора, удержанные чанки отпускаются
TIGHT	от tightHeapRatio (0.82)	сильнее урезка, меньше радиус симуляции, тормоз чанков
CRITICAL	от criticalHeapRatio (0.90)	максимальная урезка, сильнее тормоз, опциональный webhook

Old gen тоже читается после GC, так что мёртвые данные чанков, ждущие сборки, не учитываются. Сырой heap сам по себе даёт CRITICAL только на 97%. Растущий живой набор может поднять уровень раньше. Изменениям нужны два замера для подтверждения, смены policy разнесены по policyChangeMinIntervalSec, а возврат обзора отменяется, если heap растёт сразу после него. Урезка никогда не отменяется только потому, что heap продолжил расти.

---

Удержание чанков

Когда чанк выходит из обзора всех игроков, движок выгружает его примерно через 7,5 секунды, как бы ни выглядел heap. Пока уровень COMFORT и heap после GC ниже chunkRetentionMaxPostGcRatio (0.50), LeanCore берёт на такие чанки keep-loaded ссылку движка, в пределах бюджета, рассчитанного из этого запаса (chunkRetentionMbPerChunk, ограничено chunkRetentionMaxChunks). Движок перестаёт тикать удержанные чанки.

• Игрок возвращается: чанк уже загружен, с диска ничего не читается.
• Любой уровень выше COMFORT: всё отпускается при следующей проверке (каждые 2с).
• Удержанный чанк отпускается через chunkRetentionMaxHoldSeconds (600).
• Сначала берутся чанки ближе всего к игроку онлайн, и ничего дальше chunkRetentionMaxDistanceBlocks (1024) не удерживается. При превышении бюджета первыми отпускаются самые дальние, по 64 за проверку, чтобы короткий скачок heap не сбросил весь путь. След того, кто ушёл из области, остаётся последним.
• Не больше 64 новых чанков за проверку, чтобы замер heap успевал, и ни одного, когда heap после GC ближе чем на 5% к потолку.

LeanCore никогда не удаляет чанки; отпустить значит только убрать ссылку, дальше движок выгружает как обычно. /leancore status показывает retention held=… budget=….

---

Тормоз чанков

На TIGHT и CRITICAL скорость отправки чанков каждому игроку ограничивается до chunkRateBrakeTightPerSecond (512) и chunkRateBrakeCriticalPerSecond (192) секций в секунду; COMFORT и WATCH возвращают скорость самого движка. Только снижает, никогда не повышает. Пропускается, пока загружен QuantumHy или включён chunkThroughputGovernanceEnabled.

---

Работа с QuantumHy

Когда стоят оба мода, QuantumHy забирает дальность обзора клиента и скорость отправки чанков (своё сглаживание против фризов). LeanCore оставляет себе память: уровни, радиус симуляции и удержание чанков. QuantumHy читает уровень LeanCore и сужает радиус рендера на TIGHT или CRITICAL. Тормоз чанков LeanCore выключен, пока загружен QuantumHy. chunkThroughputGovernanceEnabled: true отдаёт скорость отправки LeanCore.

---

Возможности

• Профили runtime: LITE, STANDARD, FULL на встроенном и выделенном хосте
• Уровни по реальному heap: COMFORT, WATCH, TIGHT, CRITICAL по heap после GC, old gen после GC и тренду; откат, если возврат обзора навредил
• Удержание чанков (1.8): свободный heap держит недавно покинутые чанки
• Тормоз чанков (1.8): замедляет стриминг на TIGHT/CRITICAL; выключен с QuantumHy
• Урезка дальности обзора (LITE) и радиуса симуляции при реальной нагрузке, никогда ниже liteMinClientViewRadius
• Кинематографический буст обзора (motionViewRadiusBoostEnabled, опционально): увеличивает дальность для быстро движущихся; выключен по умолчанию (перезапись дальности обзора каждый тик дёргает загрузку чанков на текущем движке)
• Диагностика всегда включена (diagnosticLogEnabled): сводки при старте/остановке и логи решений [diag] по профилю
• Данные обучения: окна heap (60с / 15м / 24ч), модель спроса, статистика повторного посещения зон; сохраняются между перезапусками (schema v9)
• Activity Sense: онлайн softmax-классификатор (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
• Session savings: /leancore savings показывает пик/базу/дельту heap JVM и активность governor
• Выделенный bootstrap: разовый пресет при первом запуске на выделенном сервере
• HUD админа (/leancore hud on): маленький оверлей heap/уровня. Выключен по умолчанию.
• Heatmap, zone pin, опциональный webhook на CRITICAL

---

Команды

Основная команда: /leancore

Команда	Доступ	Описание
/leancore status	Все	Профиль, уровень, строка нагрузки (heap после GC, old gen, аллокации, время GC, тренд), строка удержания
/leancore memory	Все	Снимок heap, уровень, footprint
/leancore savings	Все	Heap JVM за сессию и состояние governor
/leancore zones	Все	Счётчики зон
/leancore learn	Все	Диагностика обучения
/leancore learn player	Все	Признаки спроса, posterior, EMA активности
/leancore probe	Все	Проверка возможностей API (S1–S5), только диагностика
/leancore hud on	Зрители HUD	Включить опциональный оверлей памяти
/leancore hud off	Зрители HUD	Выключить оверлей
/leancore hud status	Зрители HUD	Доступ к HUD и его состояние
/leancore heatmap [limit]	Персонал	Heatmap зон
/leancore zone pin	Персонал	Закрепить текущую зону как HOT
/leancore zone unpin	Персонал	Открепить текущую зону
/leancore zone pins	Персонал	Список закреплённых зон

/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

---

Права

LeanCore использует узлы прав и/или списки групп в конфиге. Любой из путей даёт доступ.

Право	Описание
durkz.leancore.hud	Включать и видеть опциональный HUD памяти (/leancore hud …)
durkz.leancore.admin	Heatmap, zone pin/unpin/pins и инструменты HUD админа

• Зрители HUD: группы в hudViewerGroups и/или durkz.leancore.hud
• Heatmap и zone pin (админ): hudAdminGroups и/или durkz.leancore.admin

Группы в конфиге (по умолчанию)

"hudViewerGroups": ["OP", "Admin"],
"hudAdminGroups": ["OP", "Admin"]

Быстрая настройка через /perm в Hytale

/perm group add OP durkz.leancore.admin

---

Конфигурация (LeanCore.json)

Путь: mods/durkz_LeanCore/LeanCore.json

Ключ	По умолчанию	Описание
enabled	true	Главный выключатель
localHostMode	AUTO	AUTO, PASSIVE или FULL на встроенном хосте
governEnabled	false	Governor STANDARD/FULL
learningEnabled	false	Обучение STANDARD/FULL
embeddedStandardProfile	false	Соло встроенный → STANDARD вместо LITE
dedicatedServerMode	false	Принудительно профиль FULL
dedicatedViewRadiusGraceSeconds	600	Выделенный хост: без урезки обзора столько секунд после старта
watchHeapRatio	0.70	Порог WATCH, heap после GC
tightHeapRatio	0.82	Порог TIGHT, heap после GC
criticalHeapRatio	0.90	Порог CRITICAL, heap после GC
liteMemoryGovernorEnabled	true	Lite governor в соло
liteLearningEnabled	true	Модель спроса + сохранение в соло
liteViewRadiusEnabled	true	Адаптивный обзор в соло
liteMinClientViewRadius	8	Никогда не урезать обзор ниже этого
liteViewPressureThreshold	0.85	Потолок в COMFORT при высокой насыщенности чанками
chunkRetentionEnabled	true	Держать недавно покинутые чанки, пока есть свободный heap
chunkRetentionMaxPostGcRatio	0.50	Потолок heap после GC (всегда ниже watchHeapRatio). Новые чанки перестают браться на 5% ниже; выше него сначала отпускаются дальние, по 64 за проверку
chunkRetentionMbPerChunk	1.0	Оценка heap на удержанный чанк для бюджета
chunkRetentionMaxChunks	2048	Жёсткий предел удержанных чанков
chunkRetentionMaxHoldSeconds	600	Отпустить удержанный чанк через это время
chunkRetentionMaxDistanceBlocks	1024	Удерживать от ближних к дальним; ничего дальше этого расстояния от игрока онлайн
chunkRateBrakeEnabled	true	Тормозить стриминг чанков на TIGHT/CRITICAL
chunkRateBrakeTightPerSecond	512	Предел секций/с на игрока на TIGHT
chunkRateBrakeCriticalPerSecond	192	Предел секций/с на игрока на CRITICAL
chunkThroughputGovernanceEnabled	false	Отдать скорость отправки throughput LeanCore по уровням (QuantumHy тогда уступает)
motionModelEnabled	true	Модель движения для каждого игрока
zoneReuseModelEnabled	true	Модель повторного посещения + выживания по зонам
motionViewRadiusBoostEnabled	false	Опциональный кинематографический буст обзора
diagnosticLogEnabled	true	Всегда включённые логи [diag] сессии/решений
checkForUpdates	true	Уведомлять операторов/админов о новом JAR
gcHintEnabled	false	Экспериментальный толчок GC в простое LITE

Не используются с 1.8.0, оставлены, чтобы старые конфиги загружались: unloadEnabled, liteUnloadEnabled, liteUnloadIdleSeconds, unloadProbeGateEnabled, probePassedAtMs.

Снапшот обучения: mods/durkz_LeanCore/learning.state.gz (schema v9, gzip).

Состояние HUD по игрокам: mods/durkz_LeanCore/hud.state.

---

Рекомендуется

• Соло / локально: оставьте localHostMode: AUTO. LITE governor, удержание и обучение включены.
• Выделенный или с друзьями: включите governEnabled и learningEnabled. Больше heap значит больше места для удержания.
• С QuantumHy: ставьте оба и оставьте chunkThroughputGovernanceEnabled выключенным.
• На выделенных хостах смотрите /leancore savings через 15+ минут, чтобы увидеть дельту heap и счётчики governor.

---

Как проверить, что работает

1. В логе должно быть LeanCore 1.8.0 setup (localHostMode=AUTO). и profile=LITE в соло
2. /leancore status: profile LITE, строка pressure= и строка retention on held=… budget=…
3. Отойдите от спавна и остановитесь: held растёт, пока уровень остаётся COMFORT
4. Заходит друг → лог profile LITE -> STANDARD
5. Добудьте руду → /leancore learn player показывает posterior=MINER и demand/viewScale

Важен heap JVM сервера, а не FPS или GPU клиента.

---

Лицензия

MIT License. Copyright (c) 2026 DurkzPRG