From aa51f3574d3d4d4e0fa59653eedd718fceb5d1bd Mon Sep 17 00:00:00 2001 From: Valentin Popov Date: Sun, 6 Sep 2026 05:22:12 +0400 Subject: 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. --- docs/baseline/current-project-audit.md | 83 ----------------- docs/baseline/notion-reconciliation.md | 88 ------------------ docs/baseline/vulkan-revision-plan.md | 158 --------------------------------- 3 files changed, 329 deletions(-) delete mode 100644 docs/baseline/current-project-audit.md delete mode 100644 docs/baseline/notion-reconciliation.md delete mode 100644 docs/baseline/vulkan-revision-plan.md (limited to 'docs/baseline') diff --git a/docs/baseline/current-project-audit.md b/docs/baseline/current-project-audit.md deleted file mode 100644 index 0dcde93..0000000 --- a/docs/baseline/current-project-audit.md +++ /dev/null @@ -1,83 +0,0 @@ -# Current Project Audit - -Baseline command: - -```text -cargo xtask ci -``` - -Result on 2026-07-18: - -- canonical pipeline passes locally with Rust 1.97.1: formatting, policy, - shader provenance, workspace tests, `clippy`, docs and `cargo deny` are - executed through `cargo xtask ci`; -- `rust-toolchain.toml` pins Rust 1.97.1 and installs only the - `x86_64-pc-windows-msvc` target; Linux and macOS target installation is not - part of the default developer setup; -- internal path dependencies are version-pinned and the Windows-only winit - graph enables only `rwh_06`, excluding Unix window-system dependencies; -- `cargo deny` runs without advisory exceptions in the supported Windows graph. - -Native Vulkan evidence: - -- Windows x86_64 local smoke passed again on 2026-07-18 with Rust 1.97.1, the - system Vulkan loader 1.4.350, and an AMD Radeon Pro WX 3200 Series; -- the smoke created a Win32 surface and swapchain, presented 300 frames, - exercised a controlled resize (three observed resize events and two - swapchain recreations), and shut down with zero validation warnings and - errors; -- Windows is the sole supported runtime target for this project; Linux and - macOS smoke gates are explicitly out of scope. - -Scope labels: - -- Stage 0 codebase gates: locally evidenced. -- Stage 0 Windows native runtime: locally evidenced. -- Linux/macOS runtime and cross-platform hosted CI: out of scope. - -## Current architecture contract - -The standalone engine keeps binary formats, the resource graph, simulation, -animation math and backend-neutral render commands independent from the GPU -adapter. Windows presentation uses `winit`, `raw-window-handle`, `ash-window` -and `ash`; only the Vulkan/FFI adapters may contain narrowly documented -`unsafe` code. Raw Vulkan handles do not cross that boundary. - -The baseline is Vulkan 1.1 with surface, Win32-surface and swapchain support, -binary semaphores/fences and a classic render-pass path. Device capability is -queried at runtime; dynamic rendering, descriptor indexing, synchronization2, -timeline semaphores and extended dynamic state are optional capability-gated -enhancements, not requirements. The canonical initial texture upload is RGBA8 -UNORM. Headless builds remain independent of `winit`, Vulkan and a window -system. - -## Current stage model - -The canonical Vulkan-revision plan has six dependency-ordered stages numbered -0--5. Keeping its original numbering matters: Stage 4 is an evidence-gated -animation/FX runtime, while Stage 5 is the mission/world vertical slice that -depends on it. They must not be reported as one completed stage. - -0. reproducible Windows/Vulkan foundation; -1. paths, VFS and lossless archives; -2. prototype graph and prepared CPU assets; -3. static Vulkan model/terrain viewer; -4. animation and FX runtime, with reference-only semantics until runtime - captures close the x87 and effect-lifecycle evidence gaps; -5. transactional map, mission and world vertical slice, rendered from the - same immutable snapshot through Vulkan. - -This is a local, Windows-only adoption of the Notion page "План реализации -stage 0--5: Vulkan revision" (reviewed on 2026-07-18). Its former -Linux/macOS portability and hosted-CI goals are intentionally not imported: -they conflict with the current supported-platform boundary above. The -portable architectural rules that do apply -- backend-neutral commands, -runtime capability queries, narrow Vulkan/FFI `unsafe`, offline shader -validation, and command capture before pixel comparison -- are retained in -this audit and the rendering tome. - -Contract tests and failure tests precede implementation. Synthetic checks never -read licensed roots; licensed corpus checks use absolute paths from the local -manifest. Backend-neutral command capture precedes pixel comparison, and GPU -addresses, allocator addresses and driver timing are excluded from deterministic -state hashes. diff --git a/docs/baseline/notion-reconciliation.md b/docs/baseline/notion-reconciliation.md deleted file mode 100644 index 8cf2e5d..0000000 --- a/docs/baseline/notion-reconciliation.md +++ /dev/null @@ -1,88 +0,0 @@ -# Сверка локальной книги с FParkan в Notion - -Проверка выполнена 18 июля 2026 года по странице `FParkan`, её восьми томам, -плану Vulkan revision и приложениям A--D. Цель — не копировать структуру -Notion, а убедиться, что каждый доказательный контракт доступен в `docs/` и -остается применимым к Windows/Vulkan scope. - -| Notion | Локальное место | -| --- | --- | -| Статьи 1--3 | `tomes/01-guide.md` | -| Статьи 4--8 | `tomes/02-architecture.md` | -| Статьи 9--13 | `tomes/03-resources.md` и `reference/` | -| Статьи 14--18 | `tomes/04-world.md` и `reference/tma.md` | -| Статьи 19--27 | `tomes/05-render.md`, `reference/` и `rendering/` | -| Статьи 28--32 | `tomes/06-behavior.md` | -| Статьи 33--37 | `tomes/07-implementation.md` и `baseline/vulkan-revision-plan.md` | -| Статьи 38--42 | `tomes/08-evidence.md`, `appendices/glossary.md`, `evidence/` | -| Приложение A | этот audit, `baseline/current-project-audit.md` и тематические тома | -| Приложение B | `appendices/ui-shell.md` | -| Приложение C | `appendices/saves-campaign.md` | -| Приложение D | `appendices/script-vm.md` | - -В ходе сверки добавлены отсутствовавшие локальные контракты UI/Shell, -сохранений/campaign и Script VM. Повторы не переносились: форматы, ABI и -corpus statistics уже находятся рядом с соответствующими readers/consumers. - -Не перенесены только противоречащие утвержденному scope цели: Linux, macOS, -MoltenVK, GLES/RG40XX и hosted CI. Они не считаются пробелами. Текущие -доказательства Windows/Vulkan и все последующие уточнения ведутся только в -локальных файлах. - -## Повторная содержательная сверка (18 июля 2026) - -Повторная сверка проверяет не количество дочерних страниц в Notion, а -утверждения, которые они добавляют к реализации. Источником были корневая -страница `FParkan`, восемь оглавлений с 42 статьями, а также две специальные -страницы: `План реализации stage 0–5: Vulkan revision` (редакция 18 июля) и -`Ревью перехода на Vulkan: решение, доказательства и ограничения`. - -| Контракт из Notion | Локальное подтверждение | Результат | -| --- | --- | --- | -| Статьи 1–3: терминология, уровень доказательств, методика | `tomes/01-guide.md` | Полностью покрыто. | -| Статьи 4–8: bootstrap, DLL, frame loop, World3D | `tomes/02-architecture.md` | Полностью покрыто. | -| Статьи 9–13: VFS, NRes, RsLi, registry, unit и auxiliary formats | `tomes/03-resources.md` и `reference/` | Полностью покрыто. | -| Статьи 14–18: TMA, mission loader, Land, ArealMap и world construction | `tomes/04-world.md`, `reference/tma.md`, `reference/msh.md` | Полностью покрыто. | -| Статьи 19–27: Ngi32, MSH, animation, MAT0/WEAR/Texm, terrain и кадр | `tomes/05-render.md`, `reference/`, `rendering/` | Покрыто; локально дополнено более свежими evidence по D3D7 camera, Node38 и Terrain/GetShade. | -| Статьи 28–32: AI, control, camera, audio, network | `tomes/06-behavior.md`, `appendices/script-vm.md` | Полностью покрыто. | -| Статьи 33–37 и Vulkan revision: ports, stages, deterministic gates, Vulkan profile | `tomes/07-implementation.md`, `baseline/vulkan-revision-plan.md` | Полностью покрыто в Windows-only редакции. | -| Статьи 38–42 и приложения A–D: ABI, corpus, knowledge boundaries, glossary, shell, saves, VM | `tomes/08-evidence.md`, `appendices/`, `evidence/`, этот audit | Полностью покрыто. | - -Пропущенных применимых технических контрактов в этом срезе не найдено. В -частности, локальный Vulkan plan уже содержит независимость решений Vulkan и -`winit`, Vulkan 1.1 baseline, `ash`-изоляцию, SPIR-V manifest/hash, capability -gates, canonical RGBA8 upload и первичность backend-neutral command capture. -Не переносились только исторические cross-platform acceptance требования из -Notion: они прямо отменены текущим Windows-only scope, а не потеряны при -синхронизации. - -Следовательно, новые факты следует добавлять непосредственно в тематический -локальный документ; повторный перенос дерева или дублирование страниц Notion -не требуется. - -## Проверяемые источники и правило разрешения расхождений - -Содержательная сверка опирается не только на оглавления. Были прочитаны -корневая страница `FParkan`, оглавления томов I--VIII и актуальные специальные -страницы [Vulkan revision](https://app.notion.com/p/387e79f2db3981778f94cdf34db5f93f), -[Vulkan review](https://app.notion.com/p/388e79f2db39810eb649edbe90bca529), -а также исторические статьи 33--34. Это позволяет отличить контракт от -исторического статуса работы. - -- В локальной книге сохранены применимые контракты Vulkan revision: Windows - как единственная acceptance-платформа, Vulkan 1.1 baseline, изоляция - `ash`/raw handles в adapter-е, capability gates, offline SPIR-V и первичность - backend-neutral command capture. -- Не переносится прежний статус-аудит Notion (например, утверждения о - synthetic-only renderer или незакрытом Windows smoke): он описывал состояние - до последующих локальных captures и потому не является спецификацией. -- Не переносятся Linux, macOS/MoltenVK и portability-enumeration требования. - Это сознательно исключённая область, а не пробел документации. -- Если страница Notion и свежий локальный evidence расходятся, локальный - evidence с командой воспроизведения, артефактом и датой имеет приоритет; - спорный факт отмечается как граница знания, пока не будет перепроверен. - -Таким образом, на момент сверки не обнаружено пропущенных применимых -технических контрактов: содержательные добавления из Notion уже разнесены по -тематическим локальным документам, а новые результаты разработки должны -добавляться только локально. diff --git a/docs/baseline/vulkan-revision-plan.md b/docs/baseline/vulkan-revision-plan.md deleted file mode 100644 index 868f408..0000000 --- a/docs/baseline/vulkan-revision-plan.md +++ /dev/null @@ -1,158 +0,0 @@ -# План реализации: Vulkan revision (Windows) - -Это локальная, действующая редакция плана `stage 0--5`. Она была получена -вдумчивой сверкой с одноимённой страницей книги FParkan в Notion 18 июля -2026 года. В Notion оставлены исторические формулировки и кроссплатформенные -цели; этот документ сохраняет все применимые технические требования и -приводит их к текущему контракту: самостоятельный движок для Windows, -оригинальные файлы игры и Vulkan. - -## Неизменяемые решения - -- Vulkan — единственный GPU API. Он заменяет прежнюю DirectDraw/Direct3D - реализацию на уровне наблюдаемой семантики кадра, а не через эмуляцию COM - объектов или буквальный перевод старых вызовов. -- `winit` — отдельный adapter окна, ввода и event loop. Vulkan не является - заменой SDL2: это независимые слои. В текущем проекте SDL2 не используется. -- `ash`, `ash-window` и `raw-window-handle` остаются внутри Windows - platform/Vulkan adapters. Backend-neutral crates не экспортируют raw Vulkan - handles и сохраняют `#![forbid(unsafe_code)]`; каждый `unsafe` в adapter-е - имеет локальный safety contract, правило владения и regression test. -- Baseline: Vulkan 1.1, surface + Win32 surface + swapchain, classic render - pass, binary semaphores и fences. Format/queue/present/image-count/sampler - capabilities запрашиваются у конкретного устройства. Dynamic rendering, - descriptor indexing, synchronization2, timeline semaphores и extended - dynamic state допускаются только через capability gate. -- Исходные MSH, WEAR, MAT0 и Texm остаются CPU-форматами. Стартовый upload - путь — канонический RGBA8 UNORM; packed/native GPU formats допустимы только - после доказательства эквивалентности. Shader variants собираются offline в - SPIR-V и проверяются validator-ом, manifest-ом и hash. -- Первичный эталон — backend-neutral command capture. Сравнение пикселей - начинается лишь после совпадения draw order, pipeline key, resource IDs, - descriptor bindings, ranges и transforms. GPU handles, allocator addresses - и driver timing не входят в deterministic state hash. - -Windows — единственная runtime-платформа acceptance. Требования Notion к -Linux, macOS/MoltenVK, portability enumeration и hosted CI намеренно не -переносятся: они противоречат утверждённой области проекта, а не являются -пропуском документации. Headless сборка по-прежнему не зависит от окна, -Vulkan loader или `winit`. - -## Stage 0 — воспроизводимая Windows/Vulkan основа - -**Цель:** минимальный реальный Vulkan vertical slice без игровых assets и -локальные повторяемые gates. - -- Зафиксировать stable Rust/MSRV, `Cargo.lock` и `--locked`; расширять - `cargo xtask ci` форматированием, tests, clippy, документацией, policy для - licenses/advisories/sources и проверкой разрешённого `unsafe` allowlist. -- Synthetic gate не читает лицензированные каталоги и не может молча пропускать - тест. Licensed corpus запускается отдельно по абсолютным путям local - manifest. Hosted CI/CD в этот scope не входит. -- Поддерживать typed parsing конфигурации xtask и `cargo_metadata`, а не - ручную интерпретацию TOML; исключать устаревшие adapter names и Python - runtime components из policy. -- Поддерживать `fparkan-platform-winit` (lifecycle, resize/DPI, input, - suspend/resume, raw handles) и `fparkan-render-vulkan` (instance, - validation, device scoring, queues, swapchain, resize/out-of-date/suboptimal - handling, deterministic capability report). -- Acceptance: Windows smoke создаёт настоящее окно/swapchain, показывает не - менее 300 кадров с resize и завершается без validation errors; negative - cases проверяют loader/device/present-queue/surface-format failures. - -## Stage 1 — пути, VFS и архивы - -**Цель:** безопасный lossless resource substrate без GPU coupling. - -- Для каждого пути различать raw legacy bytes, normalized path, ASCII lookup - key и host path; strict и compatible policy не смешивать. -- Применить symlink-safe traversal и casefold-collision policy ко всем VFS. -- В каждый parser/decompressor внедрить общие `DecodeLimits` и - `AllocationBudget`; malformed offsets, counts и decompression bombs должны - завершаться bounded errors. -- Довести NRes и RsLi до lossless reader/editor/writer: сохранять unknown и - non-zero regions, stable directory order, все наблюдённые decode methods, - explicit compatibility profile и output limits. -- Resource repository обязан иметь generation handles, decoded-byte budget, - deterministic eviction, lock-free decompression section и структурированные - ошибки с archive/entry/path/offset/phase/cause chain. -- Acceptance: synthetic no-edit и edit roundtrip, stale handles, traversal, - symlink/casefold и byte-identical corpus reports; Part 1/Part 2 не дают - необъяснённых parser failures. - -## Stage 2 — prototype graph и CPU assets - -**Цель:** полный mission-reachable graph и typed prepared assets до GPU. - -- Разрешить `objects.rlb`, unit DAT, inheritance, BASE/resource variants и - все компоненты unit, сохраняя hierarchy, provenance и multi-component - composition. -- Каждый edge хранит typed provenance: mission object, component, prototype, - model, wear, material, texture, lightmap или effect. Циклы, depth limit, - optional fallback и corrupt reachable dependency имеют разные outcomes. -- `fparkan-assets` — единственный слой CPU preparation; apps и runtime не - парсят assets ad hoc. Assets immutable, имеют stable IDs, а graph failures - содержат полную parent chain. -- Acceptance: graph order/IDs стабильны; все mission-reachable requests - обеих частей завершаются с failures 0 и передают runtime только prepared - assets. - -## Stage 3 — статический Vulkan viewer - -**Цель:** доказуемый статический MSH/terrain render из оригинальных assets. - -- Закрыть validation streams/slots/batches/indices, Texm decode/mips/palettes/ - Page rectangles и WEAR/MAT0 fallback с раздельными texture/lightmap identity. -- Backend-neutral `LegacyPipelineState` и canonical `PipelineKey` выбираются - до GPU. Vulkan adapter владеет staging/device buffers, image transitions, - samplers/descriptors, pipeline cache, depth, diffuse/lightmap bindings, - alpha/depth/cull/blend mapping и lifecycle per-frame resources. -- Viewer/debug modes включают model, texture, material, wireframe, normals, - bounds, LOD/group и terrain; upload cache ограничен GPU budget. -- Acceptance: CPU golden vectors, descriptor/pipeline-key/row-stride tests, - command captures до GPU и fixed-camera captures модели, lightmapped модели - и terrain; Windows validation smoke остаётся clean. - -## Stage 4 — animation и FX runtime - -**Цель:** заменить reference stubs доказанным deterministic runtime. - -- Реализовать type 8/type 19 node sampling, fallback keys, hierarchy и - material timeline по подтверждённым modes/masks. Portable math не выдают за - x87-compatible: второй путь появляется только после captured vectors. -- FXID отделяет lifecycle/time/RNG gates от backend: неподтверждённые fields - сохраняются raw и не исполняются как догадки; emit формирует - backend-neutral primitive/audio commands. -- Pose/effect snapshots immutable per frame; Part 1/Part 2 profiles различают - только там, где это подтверждено differential captures. -- Acceptance: frame-by-frame poses имеют approved references, FXID corpus не - имеет parser errors, один seed даёт одинаковые commands. До этого semantic - статус строго `reference-only`, а не `runtime-compatible`. - -## Stage 5 — карта, миссия и мир - -**Цель:** транзакционно загрузить миссию, выполнить headless steps и показать -тот же immutable world snapshot через Vulkan. - -- Закрыть Land.msh/TerrainFace28, Land.map, grid/graph validation и runtime - spatial acceleration для surface/raycast/visibility queries. -- Loader выполняет `Context -> Map -> TMA -> Graph -> Assets -> Construct -> - Register`, откатывая любую ошибку. Он сохраняет raw transforms, properties, - original IDs и provenance всех mission components. -- World queue, generation handles, deferred deletion, deterministic clock и - snapshot contract проверяются replay/hash tests; terrain/navigation и render - читают один опубликованный snapshot, не mutable world. -- Acceptance: headless mission replay стабилен, transaction rollback не - оставляет частичного мира, а Windows Vulkan frame использует ту же snapshot - и имеет связанный command/pixel artifact. - -## Сверка с Notion - -Восемь томов локальной книги покрывают 42 основные статьи Notion по тем же -разделам I--VIII; приложения сведены в `appendices/` и том VIII. Специальное -Vulkan-ревью дополнительно внесло в локальные материалы следующие точные -факты: исходный Ngi32 dynamically resolves DirectDraw/Direct3D, современная -граница замены находится выше Vulkan, а совпадающий SHA-256 Ngi32 в Частях 1 и -2 позволяет использовать один backend contract. Детали доказательства и -текущие native captures находятся в `tomes/05-render.md`, -`evidence/original_engine_hashes.md` и `rendering/renderer_truth_table.md`. -- cgit v1.2.3