diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 185 |
1 files changed, 80 insertions, 105 deletions
@@ -1,118 +1,93 @@ # FParkan -Open source проект с реализацией компонентов игрового движка игры **«Паркан: Железная Стратегия»**. - -## Описание - -Проект находится в активной разработке и включает: - -- библиотеки для работы с форматами игровых архивов; -- спецификации форматов и сопутствующую документацию. - -## Установка - -Проект находится в начальной стадии, подробная инструкция по установке пока отсутствует. - -## Документация - -- локально: каталог [`docs/`](docs) -- сайт: <https://fparkan.popov.link> - -## Библиотеки - -- [crates/fparkan-nres](crates/fparkan-nres) — strict/lossless модель архивов NRes. -- [crates/fparkan-rsli](crates/fparkan-rsli) — чтение, lookup и lossless roundtrip архивов RsLi. -- [crates/fparkan-msh](crates/fparkan-msh) — validated static MSH geometry. -- [crates/fparkan-runtime](crates/fparkan-runtime) — transactional mission loading и headless runtime foundation. -- [apps/fparkan-cli](apps/fparkan-cli) — CLI для архивов, графов и acceptance-отчетов. -- [apps/fparkan-viewer](apps/fparkan-viewer) — inspection-only CLI для archive/model/texture/map без live Vulkan draw path. -- [apps/fparkan-headless](apps/fparkan-headless) — headless runtime composition root. -- [apps/fparkan-game](apps/fparkan-game) — mission composition root: по умолчанию выдаёт planning report; opt-in `--backend static-vulkan` открывает native Vulkan окно и рисует terrain и все подготовленные MSH-компоненты выбранных mission roots. По умолчанию выбираются все roots; `--preview-roots N` оставляет bounded diagnostic scope. - -## Текущий статус рендера - -- `fparkan-vulkan-smoke` доказывает живой Stage 0 Vulkan triangle path с native window, swapchain и validation telemetry. -- `VulkanPlanningBackend` и default-режим `fparkan-game` подтверждают только deterministic command planning/capture, а не draw пикселей. `fparkan-game --backend static-vulkan` — узкий mission-to-native-Vulkan bridge: он объединяет terrain и подготовленные MSH-компоненты всех выбранных roots, применяет static TMA transforms и загружает первую MAT0 diffuse texture на каждый используемый selector с preview-local remap. Legacy D3D7 camera capture поддерживается; полный corpus, material phases, dynamic ownership/visibility и pixel parity ещё не подтверждены. -- `fparkan-viewer` пока является инспектором ассетов. `fparkan-vulkan-smoke` имеет live Stage 3 bridge для original `MSH`/`Texm`/`WEAR`/`MAT0` и geometry-only `Land.msh`; полноценный viewer, исходные terrain-material states, camera и pixel parity ещё не закрыты. -- Truth table и evidence-артефакты вынесены в [`docs/rendering/renderer_truth_table.md`](docs/rendering/renderer_truth_table.md) и [`docs/evidence/`](docs/evidence). - -## Тестирование - -Базовое тестирование проходит на синтетических тестах из репозитория: - -```bash -cargo xtask ci -``` - -Для дополнительного тестирования на реальных игровых ресурсах: - -- используйте оригинальную копию игры (диск или [GOG-версия](https://www.gog.com/en/game/parkan_iron_strategy)); -- разместите игровые каталоги в [`testdata/`](testdata); -- игровые ресурсы в репозиторий не включаются, так как защищены авторским правом. - -Локальный licensed gate использует некоммитимый manifest: - -```bash -cat > /private/tmp/fparkan-corpora.toml <<'EOF' -schema = 1 - -[[corpus]] -id = "part1-local" -kind = "part1" -root = "/absolute/path/to/IS" -expected_profile = "parkan-is-part1" - -[[corpus]] -id = "part2-local" -kind = "part2" -root = "/absolute/path/to/IS2" -expected_profile = "parkan-is-part2" -EOF - -FPARKAN_CORPORA_MANIFEST=/private/tmp/fparkan-corpora.toml \ - cargo xtask acceptance report --suite licensed --stage 5 +Открытый движок *Паркан: Железная стратегия* на 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' ``` -## Stage 0 Vulkan smoke - -Локальный Stage 0 smoke запускает реальный `winit` lifecycle и Vulkan triangle path с включёнными validation layers. Успешный прогон обязан: - -- отрисовать 300 кадров; -- выполнить как минимум один реальный resize; -- пересоздать swapchain после resize; -- завершиться без validation warnings/errors. - -Команда запуска: - -```bash -cargo run -p fparkan-vulkan-smoke --locked -- \ - --out target/fparkan/native-smoke/local.json \ - --timeout-seconds 120 +Окно работает в интерактивном режиме до закрытия и по умолчанию загружает все +корневые объекты миссии (`--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 ``` -Поддерживается только Windows. Перед запуском убедитесь, что установлен Vulkan runtime -от GPU vendor или LunarG Vulkan SDK и активный runtime предоставляет -`VK_LAYER_KHRONOS_validation`. Linux, macOS/MoltenVK и их smoke-пути не входят в -проектный scope. - -Для полного локального closure gate используйте: - -```bash -cargo xtask ci +Алгоритмы и форматы проверяются обычными 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 ``` -Windows native smoke — единственный platform acceptance path. Вопросы hosted CI -и других операционных систем намеренно находятся вне scope разработки. - -## Contributing & Support - -Проект активно поддерживается и открыт для contribution. Issues и pull requests можно создавать в обоих репозиториях: +## Книга и исходники -- **Primary development**: [valentineus/fparkan](https://code.popov.link/valentineus/fparkan) -- **GitHub mirror**: [valentineus/fparkan](https://github.com/valentineus/fparkan) +[Книга об устройстве движка](docs/index.md) объясняет форматы, математику, +загрузку мира и связь подсистем. Её можно читать прямо в репозитории; +`mkdocs.yml` задаёт представление на [сайте проекта](https://fparkan.popov.link). -Основная разработка ведётся в self-hosted репозитории. +`crates/` содержит форматы и игровые алгоритмы, `adapters/` — окно и Vulkan, +`apps/fparkan-game` — исполняемое приложение. ## Лицензия -Проект распространяется под лицензией **[GNU GPL v2](LICENSE.txt)**. +[GNU GPL v2](LICENSE.txt). |