fparkan/README.md

# FParkan

Открытый движок *Паркан: Железная стратегия* на Rust и Vulkan. Он читает
ресурсы установленной оригинальной игры. Сейчас приложение показывает
интерактивную сцену выбранной карты: terrain, все доступные MSH-компоненты
объектов, материалы, динамические тени, небо, погоду, lightning FX и звуковые
события. Это просмотр карты с полной графической сценой; прохождение миссии и
игровое поведение юнитов пока не запускаются, а модели показываются в статической
позе, заданной сохранёнными настройками узлов прототипа.

## Запуск

Нужны Rust и драйвер видеокарты с поддержкой Vulkan. Игровые файлы в
репозиторий не входят.

```powershell
cargo run --release -p fparkan-game -- `
  --root 'C:\GOG Games\Parkan - Iron Strategy' `
  --mission 'MISSIONS\Autodemo.00\data.tma'
```

Окно работает в интерактивном режиме до закрытия и по умолчанию загружает все
корневые объекты миссии (`--preview-roots N` ограничивает их число только для
диагностики).
`WASD` перемещают камеру относительно её направления, `E/Q` поднимают и
опускают её, `Shift` ускоряет, `Ctrl` замедляет движение. Удержание правой
кнопки мыши включает relative-look; движение мыши вращает yaw/pitch. При
потере фокуса обзор отключается и нажатые клавиши сбрасываются. `Esc`
отпускает обзор или закрывает окно.

В каталоге миссии ищется `sky.ske`. Если файл найден, приложение читает её
расписание и `sky.wea`; связанные MAT0/WEAR-материалы и
`effects.rlb/env_lightning` загружаются из ресурсов игры. Без `sky.ske`
окружение отключено; если файл есть, отсутствие `sky.wea`, `env_lightning` или
связанного материала считается ошибкой. Параметр `--atmosphere-seconds N`
задаёт начальное время; по умолчанию используется начало расписания. Когда
окружение загружено, небо, солнце и
луна, flares, молнии, дождь и снег, point lights, динамические тени и связанные
звуковые события обновляются в каждом кадре.

`--frames N` ограничивает запуск числом кадров для smoke/readback-проверок;
значение `0` означает бесконечный интерактивный запуск. `--legacy-camera-capture`
читает сохранённый захват камеры и запускает воспроизводимый режим без
free-flight управления. `--static-animation-frame <u16>` задаёт один кадр для
всех узлов. Если параметр не указан, приложение берёт сохранённые настройки
узлов из явной ссылки прототипа на `.ctl`; для узлов без такой настройки
используется кадр `0`. Статическая поза не запускает игровой Control, AI или
полное поведение юнитов.
`--static-material-phase <u16>` выбирает фиксированную фазу материала.
`--readback-out target/frame.raw` сохраняет последний кадр GPU. `--validation`
включает Vulkan validation layers и завершает запуск с ошибкой при предупреждении
или ошибке. Readback сохраняет байты в формате surface без преобразования;
размер — `width × height × 4`. Порядок каналов и encoding определяются значением
`readback_format` в выводе; на текущем GPU обычно используется
`VK_FORMAT_R8G8B8A8_UNORM`.

## Разработка

```text
cargo fmt --all -- --check
cargo test --workspace
cargo check --workspace
```

Алгоритмы и форматы проверяются обычными Rust-тестами рядом с кодом.
Тесты с оригинальными ресурсами помечены `#[ignore]`; пути к двум частям
установки задаются через `FPARKAN_CORPUS_PART1_ROOT` и
`FPARKAN_CORPUS_PART2_ROOT`. Зависимости разрешает Cargo, локальный
`Cargo.lock` не хранится в Git.

Готовые SPIR-V шейдеры находятся рядом с исходниками GLSL.
Vulkan SDK нужен только для их пересборки и проверки с `--validation`.
При доступных в PATH инструментах SDK:

```powershell
glslangValidator -V adapters/fparkan-render-vulkan/shaders/triangle.vert -o adapters/fparkan-render-vulkan/shaders/triangle.vert.spv
glslangValidator -V adapters/fparkan-render-vulkan/shaders/triangle.frag -o adapters/fparkan-render-vulkan/shaders/triangle.frag.spv
spirv-val adapters/fparkan-render-vulkan/shaders/triangle.vert.spv
spirv-val adapters/fparkan-render-vulkan/shaders/triangle.frag.spv
```

## Книга и исходники

[Книга об устройстве движка](docs/index.md) объясняет форматы, математику,
загрузку мира и связь подсистем. Её можно читать прямо в репозитории;
`mkdocs.yml` задаёт представление на [сайте проекта](https://fparkan.popov.link).

`crates/` содержит форматы и игровые алгоритмы, `adapters/` — окно и Vulkan,
`apps/fparkan-game` — исполняемое приложение.

## Лицензия

[GNU GPL v2](LICENSE.txt).