---

# AstraCore — что делает каждый файл кода

Документ описывает исходники из `src/main/java` и `src/test/java` текущего рабочего дерева. Это справочник по назначению файлов, а не подтверждение того, что вся функциональность уже проверена в запущенной игре.

## Как устроен проект в целом

- **Запуск мода и события:** `AstraCore` подключает команды, сетевые сообщения, хранение, интеграцию чанков и игровые сервисы.
- **Планета:** поверхность и слои генерируются детерминированно из seed и параметров. В проекте есть два представления чанков: карта из шести граней куб-сферы и полноценные декартовы воксели вокруг центра. Интеграция с обычными Overworld-чанками использует прежде всего декартов путь `PlanetVoxel*`.
- **Сохранение:** каталог планет, окна их размещения и данные вокселей хранятся внутри одного save через `SubworldStorageManager` и `SubworldRegionStore`; отдельный `ServerLevel` для граней не создаётся.
- **Игрок:** `PlanetGravityService` отвечает за серверную гравитацию и ввод; клиентские контроллеры предсказывают движение и отображают радиальную ориентацию. Сценарный облёт `/astracore planet fly` — отдельный маршрут, не обычное ручное движение.
- **Статус камеры:** код локальных yaw/pitch и их переноса между радиалями уже есть, но Mixin в `Entity.turn(DD)V` пока не подтверждён запуском игры/сервера.

## Исходники мода — `src/main/java`

### Корень, клиент, команды и сеть

- `src/main/java/dev/astracore/AstraCore.java` — главный класс NeoForge-мода. Создаёт и регистрирует серверные сервисы, команды, интеграцию чанков, управление хранилищем и регистрацию сетевых payload.
- `src/main/java/dev/astracore/client/PlanetFlightClientController.java` — клиентская часть экспериментального scripted-облёта: принимает стартовые параметры, двигает игрока по маршруту на сфере, направляет взгляд и восстанавливает физику при остановке.
- `src/main/java/dev/astracore/client/PlanetGravityClientController.java` — локальное предсказание радиальной гравитации и движения; отправляет клавиатурный ввод серверу, применяет касательное ускорение, обновляет вид игрока, рендер-ориентацию и состояние контакта с поверхностью.
- `src/main/java/dev/astracore/command/PlanetCommands.java` — команды `/astracore planet create`, `fly`, `stop`, `status`. Создание проверяет место в Overworld, сохраняет планету и окно мира, безопасно удерживает игрока на время материализации чанков и затем переносит его к стартовой точке.
- `src/main/java/dev/astracore/mixin/EntityRadialFrameMixin.java` — вмешивается в методы Minecraft `Entity`: для игрока в активном поле задаёт радиальный bounding-box/позицию глаз и перехватывает поворот камеры. Новый перехват `turn(DD)V` пока не проверен в runtime.
- `src/main/java/dev/astracore/network/AstraCoreNetwork.java` — регистрирует сетевые сообщения и маршрутизирует их клиентским контроллерам или серверному обработчику движения. Клиентские классы загружаются только на клиенте.
- `src/main/java/dev/astracore/network/PlanetFlightStartPayload.java` — передаёт клиенту начальные параметры scripted-облёта: центр, радиус, адрес на поверхности, высоту, направление и скорость; проверяет корректность данных и кодирует/декодирует пакет.
- `src/main/java/dev/astracore/network/PlanetFlightStopPayload.java` — пустой сигнал сервер → клиент о завершении scripted-облёта.
- `src/main/java/dev/astracore/network/PlanetGravityPayload.java` — описывает активное поле гравитации для клиента: ID планеты, центр, радиус и силу; также имеет вариант сообщения об остановке.
- `src/main/java/dev/astracore/network/PlanetMovementInputPayload.java` — передаёт серверу нормированные оси клавиатурного ввода вперёд/вбок.

### Физика и система координат игрока

- `src/main/java/dev/astracore/physics/Deep.java` — координата большого космоса без фиксированного предела `long`: целая часть хранится через `BigInteger`, дробная — отдельно, чтобы малые перемещения не терялись на огромных расстояниях.
- `src/main/java/dev/astracore/physics/RadialGravityModel.java` — чистая математика сферической гравитации: направление к центру, обратный квадрат вне планеты, линейное ослабление внутри, радиаль от центра и поправка направления прыжка.
- `src/main/java/dev/astracore/physics/RadialGroundContact.java` — проверяет контакт игрока с поверхностью пробой в направлении центра планеты и трактует его как приземление.
- `src/main/java/dev/astracore/physics/RadialMovementModel.java` — переводит клавиатурные оси «вперёд/влево» в касательную плоскость сферы относительно радиальной вертикали.
- `src/main/java/dev/astracore/physics/RadialPlayerCollisionModel.java` — рассчитывает консервативный axis-aligned AABB, который охватывает тело игрока, ориентированное по радиальной нормали; это не точный повёрнутый OBB.
- `src/main/java/dev/astracore/physics/RadialPlayerFieldState.java` — хранит для активного игрока центр его радиального поля, чтобы клиентские Mixin и рендер могли узнать, относительно какой планеты считать ориентацию.
- `src/main/java/dev/astracore/physics/RadialPlayerFrame.java` — строит ортонормированный базис «вправо/вверх/вперёд» и кватернион поворота модели игрока под заданную радиаль и направление взгляда.
- `src/main/java/dev/astracore/physics/RadialPlayerViewState.java` — клиентское состояние камеры игрока: активирует локальную систему взгляда, обновляет её при изменении радиали и обрабатывает повороты мыши.
- `src/main/java/dev/astracore/physics/RadialViewModel.java` — независимая от Minecraft математика yaw/pitch вокруг локального верха, ограничение pitch, перенос направления кратчайшим поворотом при переходе между радиалями и конвертация в углы мира.

### Планета, поверхность и материалы

- `src/main/java/dev/astracore/planet/BiomeType.java` — перечень внутренних типов биомов планеты и связанных с ними vanilla biome ID.
- `src/main/java/dev/astracore/planet/ColumnInfo.java` — рассчитанные данные одной вертикальной колонки: направление на сфере, высота поверхности и тип биома.
- `src/main/java/dev/astracore/planet/CubeFace.java` — задаёт шесть граней куб-сферы и их согласованные нормали/локальные оси; умеет находить грань по нормали.
- `src/main/java/dev/astracore/planet/CubeSphereMap.java` — переводит адреса на шести квадратных гранях в направления на сфере, нормализует координаты через рёбра/углы и выполняет переходы соседних ячеек.
- `src/main/java/dev/astracore/planet/DepthModel.java` — переводит локальную высоту `Y` планеты в радиус и внутреннюю зону (поверхность, переход, ад, мантия, ядро), а также определяет доступный этаж.
- `src/main/java/dev/astracore/planet/DepthParams.java` — параметры вертикальных слоёв планеты: границы, толщина и проверки допустимой конфигурации.
- `src/main/java/dev/astracore/planet/DepthZone.java` — типы вертикальных зон и признак, доступна ли зона игроку.
- `src/main/java/dev/astracore/planet/DungeonKind.java` — категории детерминированно размещаемых подземелий.
- `src/main/java/dev/astracore/planet/DungeonPlacer.java` — находит кандидатов подземелий по 3D-сетке ячеек; расположение зависит от seed и не привязано к швам граней.
- `src/main/java/dev/astracore/planet/DungeonSite.java` — неизменяемая запись о типе, ID и координатах сгенерированной площадки подземелья.
- `src/main/java/dev/astracore/planet/HellGenerator.java` — генерирует материалы и полости в адском внутреннем слое планеты по детерминированному шуму.
- `src/main/java/dev/astracore/planet/Material.java` — внутренний enum материалов планеты и соответствующих vanilla block ID; позволяет генератору работать без прямой записи в Minecraft-чанк.
- `src/main/java/dev/astracore/planet/Noise3.java` — детерминированные хеши и 3D-шумовые функции (Perlin, fBm, ridged, сглаживание) для рельефа и распределения материалов.
- `src/main/java/dev/astracore/planet/PlanetBlockGenerator.java` — выбирает материал для указанной колонки/высоты: поверхность и биомные слои, камень, deepslate, руды, пещеры, адский слой, мантию и ядро.
- `src/main/java/dev/astracore/planet/PlanetChunkSection.java` — неизменяемый массив материалов для одной секции `16×16×16` в face-based представлении планеты.
- `src/main/java/dev/astracore/planet/PlanetChunkSectionAssembler.java` — заполняет одну face-based секцию материалами, полученными из генератора планеты.
- `src/main/java/dev/astracore/planet/PlanetClimate.java` — по направлению на сферу и высоте вычисляет детерминированные показатели температуры/влажности и классификацию биома.
- `src/main/java/dev/astracore/planet/PlanetDefinition.java` — сохраняемое описание одной планеты: ID, размер граней, точный центр, параметры поверхности и слоёв.
- `src/main/java/dev/astracore/planet/PlanetFaceChunkAddress.java` — устойчивый логический адрес чанка по ID планеты, грани и индексам чанка на грани.
- `src/main/java/dev/astracore/planet/PlanetFlightController.java` — состояние экспериментального полёта по одной великой окружности; ограничивает маршрут одним полным кругом и выдаёт позицию/направление каждого шага.
- `src/main/java/dev/astracore/planet/PlanetParams.java` — параметры формы и шума поверхности: базовый радиус, континенты, холмы, горы, детали и уровень моря.
- `src/main/java/dev/astracore/planet/PlanetSubworldChunk.java` — контейнер вертикального набора face-based секций одного логического чанка планеты.
- `src/main/java/dev/astracore/planet/PlanetSurfaceMotion.java` — непрерывное движение по сферической поверхности: геодезическая траектория, перенос направления вдоль пути, высота над сферой и преобразование обратно в адрес куб-сферы.
- `src/main/java/dev/astracore/planet/PlanetSurfaceSampler.java` — интерфейс семплера радиального смещения поверхности; связывает numeric ID планеты с существующим общим интерфейсом высот.
- `src/main/java/dev/astracore/planet/PlanetTerrain.java` — собирает карту граней, генератор поверхности, климат и размещение подземелий в общий фасад для блоков и семплирования поверхности.
- `src/main/java/dev/astracore/planet/PlanetVoxelChunk.java` — контейнер декартовых секций одного объёмного чанка планеты.
- `src/main/java/dev/astracore/planet/PlanetVoxelChunkAddress.java` — signed X/Z-адрес декартового voxel-чанка; вертикальные секции этого чанка адресуются отдельно.
- `src/main/java/dev/astracore/planet/PlanetVoxelGenerator.java` — генерирует реальный 3D объём вокруг центра: определяет поверхность по радиусу, возвращает воздух снаружи и материал внутренней зоны внутри.
- `src/main/java/dev/astracore/planet/PlanetVoxelSection.java` — неизменяемые `16×16×16` материалы декартовой секции вокруг центра планеты.
- `src/main/java/dev/astracore/planet/PlanetVoxelSectionAssembler.java` — собирает декартовую секцию voxel-объёма; может быстро заполнить секции, заведомо находящиеся снаружи сферы воздухом.
- `src/main/java/dev/astracore/planet/ProceduralSurfaceSampler.java` — детерминированно вычисляет радиальные перепады поверхности: океан/материки, холмы, горы и мелкий рельеф.
- `src/main/java/dev/astracore/planet/SurfaceAddress.java` — адрес точки на грани куб-сферы с целой координатой блока и дробной частью внутри блока.
- `src/main/java/dev/astracore/planet/SurfaceTransition.java` — результат перехода координаты через шов грани; также преобразует локальные оси направления при переходе.

### Общие интерфейсы terrain

- `src/main/java/dev/astracore/terrain/SurfaceHeightSampler.java` — небольшой общий интерфейс для получения высоты поверхности по seed, ID планеты и единичному направлению; отделяет потребителей высоты от конкретного алгоритма шума.

### Координаты мира, сохранение и интеграция с чанками

- `src/main/java/dev/astracore/world/CosmicChunkAddress.java` — адрес чанка и вертикальной секции в неограниченных целочисленных координатах; умеет переводить точку `Deep` в чанк и локальное смещение блока.
- `src/main/java/dev/astracore/world/LocalChunkFrame.java` — обратимое преобразование между глобальными космическими адресами и ограниченными координатами обычных Minecraft-чанков; само по себе не телепортирует игрока.
- `src/main/java/dev/astracore/world/LocalChunkWindowAllocator.java` — выдаёт игрокам непересекающиеся локальные окна чанков и умеет перебазировать окно, сохраняя локальную позицию игрока.
- `src/main/java/dev/astracore/world/PlanetCatalogCodec.java` — сериализует/десериализует версии NBT-каталога с параметрами планет и проверяет корректность полей.
- `src/main/java/dev/astracore/world/PlanetCatalogStore.java` — атомарно сохраняет каталог определений планет внутри основного save и предоставляет операции загрузки/добавления/удаления/поиска.
- `src/main/java/dev/astracore/world/PlanetChunkAddressMapper.java` — переводит локальные Overworld-чанки вокруг точки-якоря и касательного курса в адреса face-based чанков планеты.
- `src/main/java/dev/astracore/world/PlanetChunkMaterializer.java` — соединяет face-based хранилище секций с ещё не опубликованным `ChunkAccess`: определяет диапазон секций и записывает данные.
- `src/main/java/dev/astracore/world/PlanetChunkSectionWriter.java` — преобразует внутренний `Material` в `BlockState` Minecraft и пишет face-based секцию в выбранный chunk section.
- `src/main/java/dev/astracore/world/PlanetFlightSessionService.java` — серверный владелец сессий scripted-облёта: отключает обычную физику на время маршрута, обновляет позицию/взгляд, отправляет клиенту старт/стоп и восстанавливает состояние.
- `src/main/java/dev/astracore/world/PlanetGravityService.java` — серверная авторитетная гравитация: выбирает ближайшую планету в радиусе влияния, применяет радиальное ускорение, обрабатывает прыжок и один раз за тик использует сохранённый ввод клиента.
- `src/main/java/dev/astracore/world/PlanetRuntime.java` — собирает все генераторы, адресаторы и оба репозитория секций для одного определения планеты; это центральный объект, через который игровые системы получают функции конкретной планеты.
- `src/main/java/dev/astracore/world/PlanetRuntimeRegistry.java` — держит runtime-представления планет текущего save и синхронизирует их с сохранённым каталогом.
- `src/main/java/dev/astracore/world/PlanetSectionFrame.java` — обратимое преобразование между вертикальными индексами секций планеты и локальными Minecraft-секциями.
- `src/main/java/dev/astracore/world/PlanetSubworldChunkCodec.java` — кодирует/декодирует face-based секции как palette NBT для хранения.
- `src/main/java/dev/astracore/world/PlanetSubworldChunkRepository.java` — загружает face-based чанк из хранилища и асинхронно создаёт только отсутствующие секции; запросы одного адреса сериализуются.
- `src/main/java/dev/astracore/world/PlanetVoxelChunkCodec.java` — palette-кодек NBT для декартовых voxel-чанков и их секций.
- `src/main/java/dev/astracore/world/PlanetVoxelChunkMaterializer.java` — получает декартовые voxel-секции из генератора/репозитория и записывает их в секции Minecraft-чанка.
- `src/main/java/dev/astracore/world/PlanetVoxelSectionWriter.java` — записывает декартовую секцию в локальную секцию чанка, используя общий переводчик материалов.
- `src/main/java/dev/astracore/world/PlanetVoxelSubworldChunkRepository.java` — сохраняет/загружает voxel-чанки и генерирует только недостающие вертикальные секции.
- `src/main/java/dev/astracore/world/PlanetVoxelWorldWindow.java` — сопоставляет локальные координаты Overworld с координатами вокруг центра планеты; вычисляет пересечения чанков/секций со сферой и обрезает диапазон высот по build height.
- `src/main/java/dev/astracore/world/PlanetWorldChunkIntegration.java` — подключает voxel-данные к обычному циклу Overworld-чанков: ставит работу в очередь, материализует чанки, сохраняет маркер окна и отправляет обновлённый чанк клиентам. Не создаёт отдельное измерение.
- `src/main/java/dev/astracore/world/PlanetWorldWindowStore.java` — сохраняет внутри save соответствие ID планеты и её локального окна Overworld; проверяет пересечения и дубликаты окон.
- `src/main/java/dev/astracore/world/SphericalPlanetGeometry.java` — чистая сферическая геометрия: центр в точной координате `Deep`, signed altitude и единичное радиальное направление.
- `src/main/java/dev/astracore/world/SubworldRegionStore.java` — асинхронное дисковое хранилище NBT-чанков внутри одного save; разбивает очень большие логические адреса на bounded Anvil-регионы/шарды.
- `src/main/java/dev/astracore/world/SubworldStorageManager.java` — открывает и закрывает планетарные хранилища на жизненном цикле сервера, находит корень основного save и предоставляет доступ к сторам и runtime-реестру.

## Тесты — `src/test/java`

Тестовые файлы проверяют математику, сериализацию, генераторы и адаптеры. Их успешное выполнение само по себе не доказывает корректную работу в реальном клиенте Minecraft.

### Сеть и физика

- `src/test/java/dev/astracore/network/PlanetFlightPayloadTest.java` — round-trip стартового payload облёта и отсутствие полей у stop-payload.
- `src/test/java/dev/astracore/network/PlanetMovementInputPayloadTest.java` — допустимый диапазон конечных осей движения и отказ на NaN/Infinity/значениях вне диапазона.
- `src/test/java/dev/astracore/physics/DeepTest.java` — точность больших координат, carry дробной части, отрицательные переходы, отсутствие переполнений и атомарность при ошибочном вводе.
- `src/test/java/dev/astracore/physics/RadialGravityModelTest.java` — направление/величина поля снаружи и внутри сферы, устойчивость в центре, нормаль поверхности и радиальный прыжок.
- `src/test/java/dev/astracore/physics/RadialMovementModelTest.java` — касательное движение на полюсе/экваторе, диагональный ввод, fallback направления и обработка ошибочных данных.
- `src/test/java/dev/astracore/physics/RadialPlayerCollisionModelTest.java` — ванильные размеры на полюсе, поворот габарита на экваторе, охват восьми углов и проверка входных размеров.
- `src/test/java/dev/astracore/physics/RadialPlayerFrameTest.java` — правильная ориентация модели игрока на полюсах, экваторе и наклонной радиали; ортонормальность базиса.
- `src/test/java/dev/astracore/physics/RadialViewModelTest.java` — локальные yaw/pitch, перенос взгляда между радиалями, round-trip углов и устойчивость возле полюса.

### Генерация, поверхность и полёт

- `src/test/java/dev/astracore/planet/CubeSphereMapTest.java` — преобразование граней/углов, соседство через швы, полный обход, большие и отрицательные адреса, дробные координаты и устойчивость нормализации.
- `src/test/java/dev/astracore/planet/DepthModelTest.java` — границы вертикальных слоёв, доступность этажей и валидация конфигурации планеты.
- `src/test/java/dev/astracore/planet/Noise3Test.java` — детерминизм шума/seed, диапазоны вспомогательных функций и некорректные входы.
- `src/test/java/dev/astracore/planet/PlanetBlockGeneratorTest.java` — пригодность параметров планеты, материал ядра/мантии/ада/коры, пещеры, детерминизм и неизменяемость возвращаемых данных.
- `src/test/java/dev/astracore/planet/PlanetChunkSectionAssemblerTest.java` — сборка face-based секций, крайние чанки и блоки, адреса, выравнивание по 16 и переполнение Y.
- `src/test/java/dev/astracore/planet/PlanetFlightControllerTest.java` — полный круг по великой окружности, переходы между гранями, точная остановка после круга и запрет обратного ввода.
- `src/test/java/dev/astracore/planet/PlanetSurfaceMotionTest.java` — непрерывность позиции/курса на рёбрах и углах, параллельный перенос направления, высота и большой центр.
- `src/test/java/dev/astracore/planet/PlanetSurfaceSamplerTest.java` — соответствие общему интерфейсу высот, стабильное преобразование ID и отклонение недопустимых параметров.
- `src/test/java/dev/astracore/planet/PlanetTerrainTest.java` — повторяемость, отличие seed, непрерывность швов, разнообразие рельефа/биомов и детерминизм подземелий.
- `src/test/java/dev/astracore/planet/PlanetVoxelGeneratorTest.java` — сплошное радиальное тело с корой/адом/мантией/ядром, воздух вне поверхности и корректная верхняя граница радиуса.
- `src/test/java/dev/astracore/planet/PlanetVoxelSectionAssemblerTest.java` — быстрое заполнение внешних секций воздухом, секция ядра и настоящая граница воздух/поверхность.
- `src/test/java/dev/astracore/planet/PlanetVoxelVolumeAcceptanceTest.java` — крупная выборочная проверка 3D объёма планеты: присутствуют воздух, поверхность, мантия и твёрдое ядро.

### Адреса, сохранение и интеграция мира

- `src/test/java/dev/astracore/world/CosmicChunkAddressTest.java` — корректные адреса блоков, отрицательные координаты, границы секций и значения далеко за пределами vanilla-диапазона.
- `src/test/java/dev/astracore/world/LocalChunkFrameTest.java` — обратимость глобальных/локальных координат, большие смещения, ошибки переполнения и сохранение глобальной позиции при локальном rebase.
- `src/test/java/dev/astracore/world/LocalChunkWindowAllocatorTest.java` — непересекающиеся окна, rebase, освобождение/повторное использование слотов и исчерпание ёмкости.
- `src/test/java/dev/astracore/world/PlanetCatalogStoreTest.java` — запись и чтение определения планеты из того же save, удаление без удаления чанков и защита копии центра.
- `src/test/java/dev/astracore/world/PlanetChunkAddressMapperTest.java` — перевод чанков около всех швов граней и стабильность адреса якорного чанка.
- `src/test/java/dev/astracore/world/PlanetRuntimeRegistryTest.java` — восстановление runtime планеты по каталогу после загрузки save.
- `src/test/java/dev/astracore/world/PlanetRuntimeTest.java` — сборка генератора с same-save репозиторием, создание и сохранение Cartesian core sections и защита от адреса другой планеты.
- `src/test/java/dev/astracore/world/PlanetSectionFrameTest.java` — round-trip локальных и планетарных секций и проверки высоты мира.
- `src/test/java/dev/astracore/world/PlanetSubworldChunkCodecTest.java` — round-trip palette-кодека, порядок секций и отклонение повреждённых palette-индексов.
- `src/test/java/dev/astracore/world/PlanetSubworldChunkRepositoryTest.java` — объединение конкурентных запросов секций и отсутствие повторной генерации сохранённых секций.
- `src/test/java/dev/astracore/world/PlanetVoxelSubworldChunkRepositoryTest.java` — сохранение и восстановление signed Cartesian voxel-чанков в том же save.
- `src/test/java/dev/astracore/world/PlanetVoxelWorldWindowTest.java` — преобразование чанков/секций Overworld в планетарные координаты, пересечение сферы и обрезка по build height.
- `src/test/java/dev/astracore/world/PlanetWorldWindowStoreTest.java` — постоянное хранение окон, отказ при перекрытии/дубликатах и корректное удаление.
- `src/test/java/dev/astracore/world/SphericalPlanetGeometryTest.java` — радиальная геометрия, signed altitude, отрицательные/астрономические координаты, центр и defensive copy.
- `src/test/java/dev/astracore/world/SubworldRegionStoreTest.java` — запись/чтение в одном save, Anvil-шардинг больших адресов и сохранение face-based и voxel-данных.

## Конфигурация и сборка

- `src/main/resources/astracore.mixins.json` — обязательная конфигурация Mixin: включает `EntityRadialFrameMixin`, задаёт Java 21 и требование минимум одного совпадения для инъекций.
- `src/main/resources/META-INF/neoforge.mods.toml` — манифест мода: ID, версия, описание, конфигурация Mixin и обязательные версии Minecraft/NeoForge.
- `build.gradle` — Gradle-сборка Java 21 и NeoForge, запуск client/server, подключение JUnit и обработка metadata-ресурсов.
- `settings.gradle` — имя Gradle-проекта и репозитории, откуда берутся плагины.
- `gradle.properties` — параметры Gradle, версия AstraCore и целевые версии Minecraft/NeoForge.
- `gradlew` — скрипт-запускатель Gradle Wrapper; это инструмент сборки, не игровая логика мода.

## С чего начать чтение

Если нужно проследить путь создания планеты: `AstraCore` → `PlanetCommands` → `SubworldStorageManager` → `PlanetRuntime` → `PlanetVoxelGenerator` → `PlanetVoxelSectionAssembler` → `PlanetVoxelSubworldChunkRepository` / `SubworldRegionStore` → `PlanetWorldChunkIntegration`.

Если нужно понять притяжение и движение игрока: `PlanetGravityService` → `PlanetGravityPayload` / `PlanetMovementInputPayload` → `PlanetGravityClientController` → классы `Radial*` в `physics`.