diff options
| author | Valentin Popov <valentin@popov.link> | 2026-09-06 04:22:12 +0300 |
|---|---|---|
| committer | Valentin Popov <valentin@popov.link> | 2026-09-06 04:22:12 +0300 |
| commit | aa51f3574d3d4d4e0fa59653eedd718fceb5d1bd (patch) | |
| tree | 9a43f6a3f3c86767e4e2b7316051562d96789f06 /README.md | |
| parent | da03e77f53bb33b2fe203ac45578289953a1b524 (diff) | |
| download | fparkan-aa51f3574d3d4d4e0fa59653eedd718fceb5d1bd.tar.xz fparkan-aa51f3574d3d4d4e0fa59653eedd718fceb5d1bd.zip | |
chore: simplify project to engine docs and tests
Remove planning and acceptance scaffolding while retaining the native Vulkan mission preview, format readers, runtime algorithms, and ordinary Rust tests. Keep the book aligned with the runnable project and validate checked-in shaders without generated tool metadata.
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). |
