[SBW] Projectile Chunk Loading

[SBW] PROJECTILE CHUNK LOADING — ОПИСАНИЕ + ГАЙД (EN + RU)
===========================================================

====================================================================
PART 1 — ENGLISH (description + guide)
====================================================================

# [SBW] Projectile Chunk Loading

**Server-side addon for Superb Warfare + PointBlank (FCL): keeps your rockets, shells, bullets and drones flying across unloaded chunks without freezing.**

## The problem

Long-range weapons in **Superb Warfare** and **PointBlank (FCL)** fire projectiles that fly far beyond the loaded area:

- SBW natively force-loads chunks for only **4 projectile classes** (guided missiles, medium rockets, cannon and mortar shells). Everything else — **NURS rockets, auto-cannon rounds, bombs, RPG rockets, 7.62/12.7 bullets** — freezes the moment it reaches the edge of the loaded terrain and never comes back.
- **PointBlank/FCL launcher rockets** (RPG-7V2, RPG-26, M72, AT4, SMAW, Carl Gustaf) have the same problem.
- **FPV/Mavic drones** (uncomplicated-fpv) lose their signal link silently when flying out of the loaded area.

Meanwhile, SBW/pointblank projectiles only tick in chunks with `distance <= simulation-distance`. Vanilla chunk loading is driven by players — nobody is standing where the shell is about to land.

## What this mod does

A single hook on the vanilla `ServerLevel.addFreshEntity` feeds every new projectile into a **public tracker API**. For each tracked projectile the mod:

1. **Classifies** it by speed (bullets / rockets / heavy shells / bombs) — one time, cached per class.
2. **Rasterizes a corridor of chunks** along its trajectory (DDA, configurable width) with **adaptive lookahead** (`speed × interval × multiplier`) so the projectile never outflies the loaded path.
3. **Keeps those chunks entity-ticking** via vanilla region tickets at the correct level (`min(3, simulation-distance)`), so the projectile actually moves through them.
4. **Releases everything automatically**: refcounted shared tickets (100 bullets in the same chunk = 1 ticket), TTL expiry (~5 s after last refresh), smart-update (the corridor is only recomputed when course/speed actually change).

## Features

- **Drop-in**: throw the jar into the server's `mods/` folder. No integration, no configuration required.
- **Covers everything that inherits the base classes**: SBW projectiles + FCP, VVP and DragonRise vehicles, pointblank `ProjectileLike` entities, uncomplicated-fpv FPV/Mavic drones — **future addons are covered automatically, no new mixins needed**.
- **Public API** (`ProjectileTracker.register(entity[, profile])`): any mod can register its own projectiles without mixins.
- **Cheap**: a timing wheel processes one bucket per tick — no per-tick scan of every projectile; corridor recalculations are skipped when nothing changed.
- **Safe by default**:
  - tickets are only placed when the chunk is genuinely not entity-ticking (`smartChunkLoading`),
  - world-border protection (no chunk generation behind the border),
  - hard limits, all configurable via `<world>/serverconfig/sbwchunkload-server.toml`: max tracked projectiles (300), max active tickets (512), max track distance (2000 blocks), max track age (1200 ticks), stationary drop (landed grenades / stuck rockets release their ticket),
  - drones are tracked **only while airborne**.
- **Debug command**: `/sbwchunkload status` (permission 2) shows tracked counts and drop reasons; `/sbwchunkload config` prints the effective settings.

## Made for PWP

This mod was built specifically for **PWP** — a tactical squad-shooter Minecraft server: Squad-style gameplay with tickets, capture points, squads, FOBs, supply logistics, a full vehicle fleet and drone warfare. When artillery, vehicle autocannons and FPV drones are the core of the gameplay, projectiles freezing at the chunk border is not an edge case — it is the whole match. PWP is powered by Superb Warfare, PointBlank, uncomplicated-fpv and other combat mods, and this addon is what makes long-range combat actually work there.

Join the PWP community on Discord: https://discord.gg/4SMwkQMEAP

## Requirements

- Minecraft **Forge 1.20.1**
- **Superb Warfare** 0.8.9+ (required)
- **PointBlank** 1.11+ (required)
- For drone support: **uncomplicated-fpv** (which brings its own GeckoLib requirement)

## Installation

Put the jar into the server's `mods/` folder. That's it — clients do **not** need this mod (it is server-side only; installing it on clients is harmless but pointless).

## Configuration

Everything is configurable via `<world>/serverconfig/sbwchunkload-server.toml` (created on first server start):

- `enabled`, `trackSbwProjectiles`, `trackPointblankProjectiles`, `trackDrones`
- `smartChunkLoading`, `adaptiveLookahead`, `predictionMultiplier`, `corridorWidth`, `ticketIntervalTicks`, `ticketTTLTicks`
- per-profile intervals & lookaheads: `bullet.*`, `rocket.*`, `heavy.*`, `ballistic.*`, `drone.*`
- hard limits: `maxTrackedProjectiles`, `maxActiveTickets`, `maxTrackDistanceBlocks`, `maxTrackAgeTicks`, `stationaryThresholdUpdates`
- `debug` (periodic statistics log)

Most values are reloaded on the fly by Forge (serverconfig reload) — no restart needed.

## FAQ

**My shells still freeze.** Check the server's `simulation-distance` (server.properties). Tickets are placed at level `min(3, simulationDistance)` — entities only tick in chunks with `distance <= simulationDistance`, so on a server with simulation-distance 2 the effect stops beyond 32 blocks from any player. Raise it to 4+ for meaningful long-range fire.

**TPS impact?** Minimal: one bucket of work per tick, corridor recomputation only on course/speed changes, shared tickets per chunk, and everything is released ~5 s after the projectile is gone.

**Drones still lose connection?** The mod keeps drone chunks ticking while the drone is airborne; a landed drone releases its tickets by design (a grounded drone must not act as a chunk loader).

**Does it work in singleplayer?** Yes — the integrated server is a server.

## License

All Rights Reserved. Not open source.

====================================================================
PART 2 — РУССКАЯ ВЕРСИЯ (описание + гайд)
====================================================================

# [SBW] Projectile Chunk Loading

**Серверный аддон для Superb Warfare + PointBlank (FCL): не даёт снарядам, пулям и дронам «замерзать» на границе прогруженных чанков.**

## Проблема

Дальнобойное оружие в **Superb Warfare** и **PointBlank (FCL)** стреляет снарядами, летящими далеко за пределы прогруза:

- SBW грузит чанки по траектории только для **4 классов снарядов** (ПТУРы, средние ракеты, снаряды пушек и миномётов). Всё остальное — **НУРС, снаряды автопушек, бомбы, РПГ, пули 7.62/12.7** — замирает на границе прогруза и больше никуда не летит.
- **Ракеты труб PointBlank/FCL** (РПГ-7В2, РПГ-26, M72, AT4, SMAW, Карл Густав) — та же беда.
- **Дроны** (uncomplicated-fpv FPV/Mavic) молча теряют связь с оператором, когда вылетают за пределы прогруза.

При этом снаряды SBW/pointblank тикаются только в чанках с `distance <= simulation-distance`, а чанки грузятся только вокруг игроков — у точки падения снаряда никто не стоит.

## Что делает мод

Один хук на ванильный `ServerLevel.addFreshEntity` ловит каждый новый снаряд и передаёт его в **публичный трекер**. Для каждого снаряда мод:

1. **Определяет тип по скорости** (пуля / ракета / тяжёлый снаряд / бомба) — 1 раз, кэшируется по классу.
2. **Растеризует коридор чанков** по траектории (DDA, ширина настраивается) с **адаптивным упреждением** (`скорость × интервал × множитель`) — снаряд не может обогнать прогретый коридор.
3. **Держит эти чанки в entity-ticking** через ванильные region tickets на правильном уровне (`min(3, simulation-distance)`) — снаряд реально летит через них.
4. **Всё освобождается само**: тикеты общие с рефкаунтом (100 пуль в одном чанке = 1 тикет), TTL (~5 сек после последнего продления), smart-update (коридор пересчитывается, только если курс/скорость реально изменились).

## Возможности

- **Drop-in**: кинул jar в `mods/` сервера — работает, настройки не обязательны.
- **Покрывает всё, что наследует базовые классы**: снаряды SBW + техника аддонов FCP/VVP/DragonRise, ProjectileLike-сущности pointblank, дроны uncomplicated-fpv. **Будущие аддоны подхватываются автоматически, без новых миксинов.**
- **Публичный API** (`ProjectileTracker.register(entity[, profile])`) — любой мод может регистрировать свои снаряды без миксинов.
- **Дёшево**: TimingWheel обрабатывает 1 бакет в тик — нет перебора всех снарядов каждый тик; пересчёт коридора пропускается, если ничего не изменилось.
- **Безопасно по умолчанию**:
  - тикеты только там, где чанк реально НЕ тикается (`smartChunkLoading`),
  - защита от world border (генерация за границей мира не запускается),
  - жёсткие лимиты, все настраиваются в `<мир>/serverconfig/sbwchunkload-server.toml`: 300 снарядов, 512 тикетов, 2000 блоков дальности, 1200 тиков жизни трека, снятие лежащих гранат/зависших ракет,
  - дроны трекаются **только в воздухе**.
- **Команда отладки**: `/sbwchunkload status` (permission 2) — счётчики и причины снятия; `/sbwchunkload config` — текущие настройки.

## Сделано для PWP

Мод сделан специально для **PWP** — тактического шутера «Squad в Minecraft»: тикеты, точки захвата, отряды, фобы, логистика снабжения, парк техники и дрон-война. Когда артиллерия, автопушки техники и FPV-дроны — основа геймплея, замерзание снарядов на границе чанков это не краевой случай, а вся карта боя. PWP работает на Superb Warfare, PointBlank, uncomplicated-fpv и других боевых модах — этот аддон делает дальний бой реально рабочим.

Дискорд PWP: https://discord.gg/4SMwkQMEAP

## Требования

- Minecraft **Forge 1.20.1**
- **Superb Warfare** 0.8.9+ (обязательно)
- **PointBlank** 1.11+ (обязательно)
- Для дронов: **uncomplicated-fpv** (тянет за собой GeckoLib)

## Установка

Положи jar в папку `mods/` сервера. Всё — клиентам мод НЕ нужен (серверный; на клиенте безвреден, но бессмыслен).

## Конфиг

Всё настраивается в `<мир>/serverconfig/sbwchunkload-server.toml` (создаётся при первом запуске):

- `enabled`, `trackSbwProjectiles`, `trackPointblankProjectiles`, `trackDrones`
- `smartChunkLoading`, `adaptiveLookahead`, `predictionMultiplier`, `corridorWidth`, `ticketIntervalTicks`, `ticketTTLTicks`
- профильные интервалы и упреждения: `bullet.*`, `rocket.*`, `heavy.*`, `ballistic.*`, `drone.*`
- лимиты: `maxTrackedProjectiles`, `maxActiveTickets`, `maxTrackDistanceBlocks`, `maxTrackAgeTicks`, `stationaryThresholdUpdates`
- `debug` (периодический лог статистики)

Большинство значений перечитываются на лету (Forge serverconfig reload) — рестарт не нужен.

## FAQ

**Снаряды всё ещё замерзают.** Проверь `simulation-distance` в server.properties. Тикеты ставятся на уровне `min(3, simulationDistance)` — сущности тикаются только в чанках с `distance <= simulationDistance`, поэтому при simulation-distance=2 эффект обрывается уже на 32 блоках от игрока. Ставь 4+.

**Влияние на TPS?** Минимальное: 1 бакет работы в тик, пересчёт коридора только при смене курса/скорости, общие тикеты на чанк, всё освобождается ~5 сек после исчезновения снаряда.

**Дрон всё равно теряет связь?** Чанки дрона держатся, пока он В ВОЗДУХЕ. Приземлившийся дрон отпускает тикеты намеренно (наземный дрон не должен быть чанк-лоадером).

**Работает в одиночной игре?** Да — встроенный сервер это тоже сервер.

## Лицензия

All Rights Reserved. Не open source.