diff options
Diffstat (limited to 'docs/baseline')
| -rw-r--r-- | docs/baseline/current-project-audit.md | 83 | ||||
| -rw-r--r-- | docs/baseline/notion-reconciliation.md | 88 | ||||
| -rw-r--r-- | docs/baseline/vulkan-revision-plan.md | 158 |
3 files changed, 0 insertions, 329 deletions
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`. |