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.
2026-09-06 05:22:12 +04:00
parent da03e77f53
commit aa51f3574d
167 changed files with 667 additions and 23705 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
 ```

-Для дополнительного тестирования на реальных игровых ресурсах:
+`--frames` задаёт число кадров. `--preview-roots N` ограничивает число объектов,
+`--legacy-camera-capture` читает сохранённую матрицу камеры,
+`--static-animation-frame` и `--static-material-phase` выбирают позу и фазу
+материала. `--readback-out target/frame.raw` сохраняет последний кадр GPU.
+Без сохранённой камеры используется вид карты сверху.

- используйте оригинальную копию игры (диск или [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
+```text
+cargo fmt --all -- --check
+cargo test --workspace
+cargo check --workspace
 ```

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

-Локальный Stage 0 smoke запускает реальный `winit` lifecycle и Vulkan triangle path с включёнными validation layers. Успешный прогон обязан:
+Готовые SPIR-V шейдеры находятся рядом с исходниками GLSL.
+Vulkan SDK нужен только для их пересборки и проверки с `--validation`.
+При доступных в PATH инструментах SDK:

- отрисовать 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
+```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. Перед запуском убедитесь, что установлен Vulkan runtime
-от GPU vendor или LunarG Vulkan SDK и активный runtime предоставляет
-`VK_LAYER_KHRONOS_validation`. Linux, macOS/MoltenVK и их smoke-пути не входят в
-проектный scope.
+## Книга и исходники

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

-```bash
-cargo xtask ci
-```
-
-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)
-
-Основная разработка ведётся в self-hosted репозитории.
+`crates/` содержит форматы и игровые алгоритмы, `adapters/` — окно и Vulkan,
+`apps/fparkan-game` — исполняемое приложение.

 ## Лицензия

-Проект распространяется под лицензией **[GNU GPL v2](LICENSE.txt)**.
+[GNU GPL v2](LICENSE.txt).