diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 142 |
1 files changed, 42 insertions, 100 deletions
@@ -1,118 +1,60 @@ # FParkan -Open source проект с реализацией компонентов игрового движка игры **«Паркан: Железная Стратегия»**. +Открытый движок *Паркан: Железная стратегия* на Rust и Vulkan. Он читает +ресурсы установленной оригинальной игры. Сейчас приложение загружает миссию +и показывает её ландшафт и модели в статическом окне Vulkan. -## Описание +## Запуск -Проект находится в активной разработке и включает: +Нужны Rust и драйвер видеокарты с поддержкой Vulkan. Игровые файлы в +репозиторий не входят. -- библиотеки для работы с форматами игровых архивов; -- спецификации форматов и сопутствующую документацию. - -## Установка - -Проект находится в начальной стадии, подробная инструкция по установке пока отсутствует. - -## Документация - -- локально: каталог [`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 +```powershell +cargo run -p fparkan-game -- ` + --root 'C:\GOG Games\Parkan - Iron Strategy' ` + --mission 'MISSIONS\Autodemo.00\data.tma' --frames 240 ``` -Для дополнительного тестирования на реальных игровых ресурсах: - -- используйте оригинальную копию игры (диск или [GOG-версия](https://www.gog.com/en/game/parkan_iron_strategy)); -- разместите игровые каталоги в [`testdata/`](testdata); -- игровые ресурсы в репозиторий не включаются, так как защищены авторским правом. - -Локальный licensed gate использует некоммитимый manifest: +`--frames` задаёт число кадров. `--preview-roots N` ограничивает число объектов, +`--legacy-camera-capture` читает сохранённую матрицу камеры, +`--static-animation-frame` и `--static-material-phase` выбирают позу и фазу +материала. `--readback-out target/frame.raw` сохраняет последний кадр GPU. +Без сохранённой камеры используется вид карты сверху. -```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 -``` - -## 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 +```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). |