ReadStar

ReadStar — мод астрономии для NeoForge

Мод для неба Minecraft, основанный на реальной небесной механике и данных звёздных каталогов: планетарные орбитальные системы, звёздные каталоги, рендеринг с учётом FOV и синхронизируемая с сервером конфигурация небесных тел.

Автор: FrozenStream

Возможности

• Реальный звёздный каталог — более 12 000 настоящих звёзд из Gaia DR3 (цвет) + BSC5 (резерв для ярких звёзд), с индивидуальной яркостью и свечением каждой звезды
• Реальная небесная механика — кеплеровская орбитальная система с неограниченной глубиной вложенности
• Атмосферное рассеяние — вычисление цвета и свечения атмосферы на основе HSV с наложением на всё небо и звёздным гало
• Рендеринг комет — двуххвостовая структура из пылевого и ионного хвостов на кривых Безье с динамическим колебанием
• Рендеринг с учётом FOV — кастомный шейдер сохраняет постоянный экранный размер звёзд при изменении FOV
• Настройка без кода — добавьте 8 фаз луны любому телу, просто положив PNG-файлы
• Синхронизация с сервером — конфигурация небесных тел управляется на стороне сервера и автоматически синхронизируется со всеми клиентами

Быстрый старт

./gradlew build          # Сборка
./gradlew runClient      # Запуск клиента
./gradlew runData        # Генерация данных (конфигурация атласа)
./gradlew runServer      # Запуск сервера

Небесная система задаётся через датапак в data/readstar/celestial/system.json, а звёздный каталог — через ресурспак в assets/readstar/custom/stars/stars.json.

Изменения конфигурации вступают в силу по F3+T. Изменения датапака требуют /reload или перезапуска.

Конфигурация

Файл конфигурации: run/config/readstar-common.toml

Рендеринг с учётом FOV

Звёзды используют кастомный шейдер, который разделяет каждую точку на позицию и смещение:

Формула: FovCompensation = tan(fov/2) / tan(35°) × strength + (1 - strength)

Шейдер: worldPos = Position + Offset × FovCompensation

Индивидуальная яркость звёзд

На основе Vmag с независимыми порогами затухания:

Квады свечения только для Vmag < 2.0: < 0.5 → высокое / < 1.5 → среднее / < 2.0 → низкое.

Датапак — Небесная система

Путь: data/readstar/celestial/system.json

Разместите в `saves//datapacks//data/readstar/celestial/system.jsonили в серверномworld/datapacks/`.

Структура

{
  "System": {
    "<name>": {
      "mass": <double>,
      "radius": <double>,
      "luminance": <int>,
      "unstableDirtySnowball": <bool>,
      "hasAtmosphere": <bool>,
      "atmosphereHSV": <int>,
      "starHSV": <int>,
      "axis": [<x>, <y>, <z>],
      "orbit": {
        "semiMajorAxis": <double>,
        "eccentricity": <double>,
        "inclination": <double>,
        "argumentOfPeriapsis": <double>,
        "longitudeOfAscendingNode": <double>,
        "initialMeanAnomaly": <double>
      },
      "children": { "<name>": { ... } }
    }
  }
}

### Справочник полей

| Поле | Описание |
|-------|-------------|
| `mass` | Масса (кг). 0 = фиксировано на позиции родителя |
| `radius` | Радиус (м). Видимый размер = `max(1.024, radius / distance × factor)` |
| `luminance` | Собственная светимость 0~15. >0 = звезда; дочерние тела автоматически определяют `hostStar` вверх по иерархии |
| `unstableDirtySnowball` | Флаг кометы. `true` отрисовывает структуру с двумя хвостами |
| `hasAtmosphere` | Есть атмосфера (управляет отрисовкой оверлея и свечения) |
| `atmosphereHSV` | Цвет атмосферы в HSV, упакованный int (H<<16 \| S<<8 \| V). H=оттенок, S=насыщенность, V=плотность (0~255) |
| `starHSV` | Собственный цвет тела, та же кодировка. Светящееся = излучение, несветящееся = отражение поверхности |
| `axis` | Ось вращения. Нулевой вектор по умолчанию `(0,0,-1)` |
| `orbit.semiMajorAxis` | Большая полуось (м). 0 = нет орбиты |
| `orbit.eccentricity` | Эксцентриситет. 0 = круговая |
| `orbit.inclination` | Наклон орбиты (радианы) |
| `orbit.argumentOfPeriapsis` | Аргумент перицентра (радианы) |
| `orbit.longitudeOfAscendingNode` | Долгота восходящего узла (радианы) |
| `orbit.initialMeanAnomaly` | Начальная средняя аномалия (радианы) |

Имена нечувствительны к регистру. `children: {}` = нет дочерних тел. Глубина вложенности не ограничена.

### Полный пример

Солнце → Земля + Марс → Луна. Реальные данные Солнечной системы.

```json
{
  "System": {
    "Sun": {
      "mass": 1.989e30, "radius": 6.957e8, "luminance": 15,
      "unstableDirtySnowball": false, "hasAtmosphere": false, "atmosphereHSV": 0, "starHSV": 2172671,
      "axis": [0, 0, 0],
      "orbit": { "semiMajorAxis": 0, "eccentricity": 0, "inclination": 0, "argumentOfPeriapsis": 0, "longitudeOfAscendingNode": 0, "initialMeanAnomaly": 0 },
      "children": {
        "Earth": {
          "mass": 5.972e24, "radius": 6.371e6, "luminance": 0,
          "unstableDirtySnowball": false, "hasAtmosphere": true, "atmosphereHSV": 9738751, "starHSV": 9732275,
          "axis": [0, 0, 0],
          "orbit": { "semiMajorAxis": 1.496e11, "eccentricity": 0.0167, "inclination": 0, "argumentOfPeriapsis": 1.796, "longitudeOfAscendingNode": 0, "initialMeanAnomaly": 6.240 },
          "children": {
            "Moon": {
              "mass": 7.342e22, "radius": 1.737e6, "luminance": 0,
              "unstableDirtySnowball": false, "hasAtmosphere": false, "atmosphereHSV": 0, "starHSV": 1707468,
              "axis": [0, 0, 0.5],
              "orbit": { "semiMajorAxis": 3.844e8, "eccentricity": 0.0549, "inclination": 0.0899, "argumentOfPeriapsis": 0, "longitudeOfAscendingNode": 0, "initialMeanAnomaly": 0 },
              "children": {}
            }
          }
        },
        "Mars": {
          "mass": 6.417e23, "radius": 3.390e6, "luminance": 0,
          "unstableDirtySnowball": false, "hasAtmosphere": true, "atmosphereHSV": 1336835, "starHSV": 1356697,
          "axis": [0, 0, 0],
          "orbit": { "semiMajorAxis": 2.279e11, "eccentricity": 0.0934, "inclination": 0.0323, "argumentOfPeriapsis": 0, "longitudeOfAscendingNode": 0.865, "initialMeanAnomaly": 0 },
          "children": {}
        }
      }
    }
  }
}

Наследование и время

• hostStar: рекурсивно определяется вверх до ближайшего предка с luminance > 0
• Позиция = parent.position + orbit(parent.mass, gameTime)
• Корень фиксирован в (0, 0, 0)
• gameTime управляет орбитальным движением; daylightTime (0~24000) управляет вращением/зенитом
• Фазы Луны вычисляются автоматически из геометрии наблюдатель-спутник-звезда

Система атмосферы

Каждое тело может задать цвет атмосферы (HSV) и собственный цвет (HSV), оба как упакованные int:

atmosphereHSV / starHSV = (H << 16) | (S << 8) | V

Примеры значений:

Упаковка/распаковка через CelestialBody.packHSV(h, s, v) и getHueFloat/getSaturationFloat/getValueFloat.

Вычисление свечения (computeGlowColor): цвет гало = звёздный свет × атмосферное рассеяние. Оттенок смещается к атмосфере; насыщенность и яркость слегка повышаются.

Слои рендеринга:

1. renderSkyDisc       → ванильный фон неба биома
2. Тела + звёзды       → светящиеся / несветящиеся + каталог звёзд
3. renderAtmosphereOverlay → полупрозрачная атмосфера на всё небо (затухает ночью)

Текстуры небесных тел

Текстуры тел организованы по категориям, автоматически обнаруживаются атласом celestial.json:

assets/<namespace>/textures/environment/celestial/
├── luminous/<name>.png       # Светящиеся тела (одно изображение, без фаз)
├── non-luminous/<name>/      # Несветящиеся тела (8 PNG-фаз луны)
└── halo.png                  # Текстура свечения (серый радиальный спад)

Светящимся телам нужен один PNG в luminous/. Несветящимся телам нужно 8 PNG-фаз луны в `non-luminous//. readstar:luminous/white_sun.png` — заглушка, замените своей.

Ресурспак

Каталог звёзд

Путь: assets/readstar/custom/stars/stars.json

Источники данных

Каталоги звёзд автоматически генерируются скриптами в .data/:

Конвейер цвета: предпочтительно эффективная температура Gaia GSP-Phot → планковское абсолютно чёрное тело → sRGB; запасной вариант — отображение цветового индекса bp_rp. 12 ярчайших звёзд (Сириус, Вега и т. д.) сохраняют данные BSC5 из-за насыщения детектора Gaia.

Формат JSON

{
  "Stars": [
    {
      "name": "Sirius",
      "position": [-0.1875, -0.2876, 0.9392],
      "Vmag": -1.46,
      "color": 4294967295
    }
  ]
}

Пользовательские текстуры луны

Ключевая особенность: добавьте 8 фаз луны любому небесному телу, просто разместив PNG-файлы — без единой строчки кода.

Каталог

assets/<namespace>/textures/environment/celestial/non-luminous/<body-name>/

• `должен совпадать с именем вsystem.json` в нижнем регистре
• Требуется ровно 8 PNG с фиксированными именами файлов:

Требования

Пример: Jupiter

assets/readstar/textures/environment/celestial/non-luminous/jupiter/
├── full_moon.png
├── waning_gibbous.png
├── third_quarter.png
├── waning_crescent.png
├── new_moon.png
├── waxing_crescent.png
├── first_quarter.png
└── waxing_gibbous.png

Также задай орбиту Jupiter в system.json (см. пример выше).

Как это работает

1. PNG-файлы в textures/environment/celestial/ автоматически обнаруживаются атласной системой Minecraft
2. ReadstarSkyRenderer сканирует подкаталоги moons/ и строит GPU-буферы по группам
3. Сопоставление во время выполнения по body.name

Другие моды могут переопределять текстуры через приоритет ресурспаков.

Спрайты и атлас

Атлас звёзд

assets/readstar/atlases/star.json объявляет источник readstar:star. Во время выполнения все значения color из stars.json тонируют базовые трафареты попиксельно:

Каждый цвет → 4 спрайта: color_{c}, glow_low_{c}, glow_med_{c}, glow_high_{c}.

Требования: RGBA 32-бит, 32×32, чёрные края, яркость свечения подавлена ×0.35.

Небесный атлас

assets/readstar/atlases/celestial.json использует источник minecraft:directory, автоматически сканируя все пространства имён в textures/environment/celestial/.

Сетевая синхронизация

Сервер загружает data/readstar/celestial/*.json и рассылает через пакет readstar:planet_system. Клиент перестраивает небесное дерево в CelestialBodyManager.initializeFromJson().

Сборка и устранение неполадок

./gradlew build          # Сборка JAR
./gradlew runData        # Генерация данных (конфиг атласа)
./gradlew runClient      # Запуск клиента
./gradlew runServer      # Запуск сервера

Вывод: build/libs/readstar-*.jar

© 2026 FrozenStream. Лицензия MIT.