diff --git a/docs/baseline/current-project-audit.md b/docs/baseline/current-project-audit.md index 04d32e3..deca5df 100644 --- a/docs/baseline/current-project-audit.md +++ b/docs/baseline/current-project-audit.md @@ -34,3 +34,35 @@ 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 active implementation plan has five dependency-ordered stages: + +1. reproducible Windows/Vulkan foundation; +2. paths, VFS and lossless archives; +3. prototype graph and prepared CPU assets; +4. static Vulkan model/terrain viewer; +5. animation/FX runtime and transactional map/mission/world vertical slice. + +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/index.md b/docs/index.md index 2775ed7..765f4bd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,6 +9,21 @@ Iron3D из *Parkan: Iron Strategy*. Она ведёт от запуска ор используется как быстрый доступ к форматам, проверочным правилам и границам доказанного знания. +## Источник истины и синхронизация + +Каталог `docs/` — единственный рабочий источник истины для FParkan. 18 июля +2026 года его постранично сопоставили с книгой FParkan в Notion: восемь томов +и приложения уже покрывают её 42 основные статьи, а актуальные локальные +материалы содержат и последующие результаты разработки. Notion больше не +является местом внесения изменений: новые факты, исправления и решения +фиксируются только здесь, в томе, справочнике или evidence-документе, которому +они принадлежат. + +При расхождении приоритет имеют более новое локальное доказательство и текущий +scope проекта: самостоятельный runtime ориентирован исключительно на Windows и +Vulkan. Исторические упоминания других ОС в старых внешних заметках не +расширяют поддерживаемую платформу. + ## Как читать Если вы впервые разбираете игровой движок, начните с тома I и II. Там вводится diff --git a/docs/rendering/renderer_truth_table.md b/docs/rendering/renderer_truth_table.md index 2e3449f..cbbaa88 100644 --- a/docs/rendering/renderer_truth_table.md +++ b/docs/rendering/renderer_truth_table.md @@ -13,7 +13,7 @@ | `RecordingBackend` | No | No | Optional CPU-side IDs only | `covered-planning` | Stable command capture for backend-neutral tests | Native window, Vulkan, GPU resource lifetime, pixels | | `NullBackend` | No | No | Optional CPU-side IDs only | Usually `covered` for validation-only rows | Command stream framing and bounds validation | Capture stability, GPU execution, pixels | | `VulkanAssetRenderer` | Yes | Yes | Yes | `covered-gpu` | Static original asset rendering: MSH/Texm/WEAR/MAT0/terrain through Vulkan | Animation/FX parity unless explicitly wired | -| `fparkan-game --backend static-vulkan` | Yes, GOG/Part 1/Part 2 `Autodemo.00` | Yes, merged static MSH component draws | All prepared MSH components from first mission root; first MAT0 diffuse TEXM per source selector | `covered-gpu` only for the narrow static-preview bridge | Opt-in mission-to-native-window bootstrap, component mesh merge, preview-local selector remap, diffuse descriptor upload and synchronized teardown telemetry | Full mission scene, later MAT0 phases/animation, lightmaps, placed transforms/orientation, camera, gameplay, original-runtime parity | +| `fparkan-game --backend static-vulkan` | Yes, GOG `Autodemo.00` | Yes, full static AutoDemo preview | Eight mission objects, 66 MSH components, original diffuse TEXM and Land2 terrain base layer | `covered-gpu` for the bounded static-scene bridge | Captured legacy camera, placed translation/scale/Z Euler transform, fallback node hierarchy, source-world geometry, 32-bit GPU indices, diffuse descriptors, terrain base draws and synchronized teardown telemetry | Material phases, Land1 blend/microtexture/lightmaps, animated keys, FX, camera control and gameplay parity | | Future rendered `fparkan-game` mode | Yes | Yes | Yes | `covered-gpu` plus original-evidence IDs | Mission-driven render snapshot execution and pixel capture | Original-runtime parity for animation/FX/x87 without dedicated captures | ## Rules @@ -32,21 +32,17 @@ - Реальный Vulkan в репозитории имеет smoke triangle path и узкий static asset bridge. `VulkanStaticDrawRange` сохраняет исходный `Batch20.material_index`; когда smoke запускается с `--wear-root`, `--wear-archive`, `--wear-name` без override, он дедуплицирует selectors, проходит каждый через `WEAR → MAT0 → Textures.lib`, создаёт по одному image/descriptor set и бинит set непосредственно перед соответствующим indexed draw. Direct TEXM и `--material-index` — намеренно однотекстурные compatibility modes. Fresh GOG `fortif.rlb::FR_L_MTP.msh` подтверждает 237 batch draws, но его selectors все `0`, поэтому live report содержит один binding `MTP_01.0`; unit contract подтверждает точное сопоставление двух разных selectors с разными descriptor sets. Это не доказывает material phase animation, lightmaps, alpha/depth/cull state, terrain, camera/node transforms или pixel approval. - Lightmap остаётся отдельным, не реализованным contract: оригинальный `World3D.dll` экспортирует самостоятельный `SetLightMapLib` наряду с `SetTexturesLib` и `SetMaterialLib`; WEAR содержит независимый блок `LIGHTMAPS`. Текущая документация не подтверждает связь этих slots с `Batch20.material_index` или их UV/channel semantics, поэтому viewer не подменяет lightmap diffuse texture и не добавляет недоказанное binding. -- `apps/fparkan-game` по умолчанию выдает `render-planning` JSON report поверх +- `apps/fparkan-game` по умолчанию выдаёт `render-planning` JSON report поверх synthetic window descriptor и `VulkanPlanningBackend`. Opt-in `--backend static-vulkan` - уже создаёт native `winit` window и передаёт все подготовленные MSH-компоненты первого root в - `VulkanSmokeRenderer`. Каждый исходный `Batch20.material_index` сначала разрешается внутри - собственного WEAR/MAT0 visual, затем получает уникальный preview-local selector и первый - diffuse TEXM. Режим использует - отдельный first-root preview loader: normal `load_mission` по-прежнему готовит все reachable - assets и весь graph, тогда как preview строит graph и готовит assets только для первого - mission root. `--load-progress ` writes the last entered loader phase synchronously for - timeout diagnosis. Fresh GOG `MISSIONS/Autodemo.00/data.tma` run passed in 38.7 seconds with - one presented frame, native 1280×720 swapchain (2 images), 14 mesh components and 14 original - diffuse material descriptors, 7,372,800-byte readback hash `16595193636416981301`, and - validation warnings/errors `0/0`. Part 1 matches that artifact; Part 2 passes validation with - 14/14 but has a distinct hash `18268338333658342130`. This is `covered-gpu` evidence for that - narrow static-preview bridge only, not full-scene or original-renderer parity. + создаёт native `winit` window. Для GOG `MISSIONS/Autodemo.00/data.tma` он уже + рендерит весь статический набор из восьми mission objects и 66 MSH components с + captured legacy camera, доказанным `Rz * Ry * Rx` placement transform, + fallback node hierarchy и Land2 base terrain. Последний validation-clean + трёхкадровый запуск имел 67 material descriptors, `clip_visible_vertices=3415` + и readback hash `1275533143935640133`. Это `covered-gpu` для ограниченного + static-scene bridge, но не pixel parity и не доказательство material phase, + Land1 blend, microtexture, lightmap, dynamic animation, FX, live camera + selection или gameplay rendering. - `apps/fparkan-viewer` сейчас inspection-only CLI и не открывает live Vulkan asset viewer. - Следующий реальный milestone для rendered acceptance: `VulkanAssetRenderer`