docs: align renderer and evidence status

2026-07-04 01:54:25 +04:00
parent 08550849c7
commit ff7993223f
7 changed files with 237 additions and 1 deletions
@@ -24,7 +24,17 @@ Open source проект с реализацией компонентов игр
 - [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), [apps/fparkan-viewer](apps/fparkan-viewer), [apps/fparkan-headless](apps/fparkan-headless), [apps/fparkan-game](apps/fparkan-game) — composition roots.
+- [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) — render-planning composition root; сейчас выдает planning report, а не живой отрисованный кадр.
+
+## Текущий статус рендера
+
+- `fparkan-vulkan-smoke` доказывает живой Stage 0 Vulkan triangle path с native window, swapchain и validation telemetry.
+- `VulkanPlanningBackend` и `fparkan-game` подтверждают только deterministic command planning/capture, а не draw пикселей.
+- `fparkan-viewer` пока является инспектором ассетов. Stage 3 GPU vertical slice для оригинального `MSH`/`Texm`/`WEAR`/`MAT0`/terrain еще не закрыт.
+- Truth table и evidence-артефакты вынесены в [`docs/rendering/renderer_truth_table.md`](docs/rendering/renderer_truth_table.md) и [`docs/evidence/`](docs/evidence).

 ## Тестирование

@@ -0,0 +1,56 @@
+# Original Engine Hashes
+
+Страница фиксирует минимальный статический baseline, на который должны
+ссылаться capture fixtures и Stage 4 evidence.
+
+## Scope
+
+- Источник: локальная статическая сверка Part 1 (`IS`) и Part 2 (`IS2`).
+- Метод: SHA-256, export/import tables, `objdump -p`, `strings`.
+- Эта страница не заменяет динамические traces: она задаёт only-if-match
+  binary baseline для дальнейших runtime captures.
+
+## Stable binaries across Part 1 / Part 2
+
+| Binary | SHA-256 | Size | Notes |
+| --- | --- | ---: | --- |
+| `Ngi32.dll` | `bab9840d94f4e4e74ffc26677724fa896cf4823845504d09a9e025f80016edf5` | 253952 | Shared low-level render/resource/audio boundary |
+| `World3D.dll` | `17e4a3089b2583a8cf2356c9db0390b1aba138356a09130d79b4e7e4791da61e` | 208896 | Shared gameplay/world/render lifecycle baseline |
+| `Terrain.dll` | `6d3e68f0e15b297f6c184af3113baf1f31e19c3326c18f0150dec659242ed667` | 708608 | Shared terrain/shade/world baseline |
+| `iron_3d.exe` / `iron_3d_p2.exe` | `f476af85c034a4b4f34f49d0806e4dff397b5da0ee26d382a7674231144979f7` | 36864 | Shared launcher binary |
+
+## Divergent binaries across Part 1 / Part 2
+
+Эти модули нельзя автоматически считать behavior-compatible между частями:
+
+- `AniMesh.dll`
+- `Effect.dll`
+- `iron3d.dll`
+- `services.dll`
+- `Control.dll`
+- `ArealMap.dll`
+
+## Practical use
+
+1. Frame-order traces для `World3D.dll`, `Terrain.dll` и `Ngi32.dll` можно
+   привязывать к shared profile, пока hash совпадает.
+2. Animation and FX captures обязаны храниться раздельно для Part 1 и Part 2,
+   потому что `AniMesh.dll` и `Effect.dll` отличаются.
+3. Любой runtime fixture должен записывать минимум:
+   - `game_part`
+   - `module_name`
+   - `module_sha256`
+   - `mission`
+   - `frame_or_tick`
+   - `schema_version`
+
+## Export / import focus for Stage 4
+
+- `World3D.dll`: `stdCalculateGame`, `stdRenderGame`, `sendEndOfRender`
+- `Terrain.dll`: `GetShade`, `GetWorld`, `stdSetCurrentCamera2`
+- `AniMesh.dll`: `LoadAgent`, `LoadAniMesh`
+- `Effect.dll`: `CreateFxManager`, `InitializeSettings`
+- `Ngi32.dll`: `niGet3DRender`, `n3dPrimitive`, `n3dEndScene`, `rsLoadTexture`, `rsLoadMultiTexture`
+
+Если будущий capture fixture не указывает, к какому hash он относится, такой
+fixture нельзя считать acceptance evidence.
@@ -0,0 +1,107 @@
+# Stage 4 Capture Schema
+
+Stage 4 нельзя закрывать набором ad-hoc логов. Нужна схема, по которой
+animation, FX и rendered frame captures сравниваются между Part 1, Part 2 и
+современной реализацией.
+
+## Goals
+
+- сделать captures пригодными для автоматического diff;
+- не хранить host-specific пути, временные каталоги и нестабильные handles;
+- связывать frame traces, command captures и pixel artifacts общим identity.
+
+## Common envelope
+
+```json
+{
+  "schema_version": "fparkan-stage4-capture-v1",
+  "capture_kind": "frame-trace | animation-pose | fx-lifecycle | render-frame",
+  "game_part": "part1 | part2",
+  "mission": "MISSIONS/.../data.tma",
+  "frame_id": 123,
+  "tick": 123,
+  "module_hashes": {
+    "World3D.dll": "sha256...",
+    "Terrain.dll": "sha256...",
+    "AniMesh.dll": "sha256...",
+    "Effect.dll": "sha256..."
+  },
+  "tool_version": "codex/manual/fixture version",
+  "notes": []
+}
+```
+
+## Capture kinds
+
+### `frame-trace`
+
+Используется для порядка фаз и внешних вызовов.
+
+Required fields:
+
+- `events`: ordered list of `{ phase, symbol, sequence, object_id?, fx_id?, camera_id? }`
+- `queue_counters`: deferred operations, visible objects, emitted FX, UI callbacks
+- `rng_state`: optional, if recoverable
+
+### `animation-pose`
+
+Используется для x87 / portable sampler parity.
+
+Required fields:
+
+- `clip_id`
+- `node_index`
+- `sample_time`
+- `numeric_profile`
+- `translation`
+- `rotation_quat`
+- `scale`
+- `matrix_hash`
+
+### `fx-lifecycle`
+
+Используется для create/update/emit/stop parity.
+
+Required fields:
+
+- `fx_id`
+- `instance_id`
+- `time`
+- `opcode_events`
+- `rng_calls`
+- `resource_refs`
+- `emissions`
+
+### `render-frame`
+
+Связывает backend-neutral snapshot с live Vulkan output.
+
+Required fields:
+
+- `camera`
+- `visible_object_ids`
+- `draws`
+- `pipeline_keys`
+- `resource_ids`
+- `validation`
+- `pixel_artifact`
+
+## Stability rules
+
+1. Не записывать абсолютные host paths.
+2. Не записывать raw pointer addresses как identity fields.
+3. `frame_id` должен совпадать между trace, command capture и pixel artifact.
+4. GPU-specific transient handles допустимы только внутри diagnostics fields и
+   не участвуют в canonical equality.
+5. Любой capture without `module_hashes` считается informational, а не
+   acceptance-grade.
+
+## Acceptance mapping
+
+- `S4-TRACE-*` rows читают `frame-trace`
+- `S4-ANIM-*` rows читают `animation-pose`
+- `S4-FX-*` rows читают `fx-lifecycle`
+- `S4-VK-*` и `S4-PIXEL-*` rows читают `render-frame`
+
+Эта схема intentionally минимальна. Новые поля можно добавлять, но нельзя
+ломать перечисленные identity and parity anchors без смены `schema_version`.
@@ -0,0 +1,39 @@
+# Renderer Truth Table
+
+Эта страница нужна для одной вещи: не позволять путям smoke, planning и capture
+выглядеть как «почти готовый renderer». Каждый путь доказывает разный класс
+свойств, и acceptance не должен смешивать их.
+
+## Краткая матрица
+
+| Path | Native window / swapchain | Draws pixels | Uses original assets | Acceptance class | Что доказывает | Чего не доказывает |
+| --- | --- | --- | --- | --- | --- | --- |
+| `fparkan-vulkan-smoke` / `VulkanSmokeRenderer` | Yes | Yes | No | `covered-gpu` for Stage 0 smoke-only IDs | Loader, instance, surface, swapchain, submit/present, validation-clean triangle path | Model upload, texture sampling, descriptors, terrain, gameplay rendering |
+| `VulkanPlanningBackend` | No | No | Optional CPU-side IDs only | `covered-planning` | Deterministic command validation, canonical capture, frame submission planning | Любой live GPU draw, pixel parity, validation-clean asset frame |
+| `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 |
+| 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
+
+1. IDs со смыслом `VK`, `GPU`, `DRAW`, `PIXEL`, `VALIDATION` или `RENDERED`
+   на Stage 3+ не могут закрываться через `NullBackend`, `RecordingBackend`
+   или `VulkanPlanningBackend`.
+2. `covered-planning` означает command planning/capture evidence. Этот статус
+   никогда не считается доказательством draw пикселей.
+3. `covered-stub` зарезервирован для явно помеченных `STUB` acceptance rows и
+   не считается compatibility closure для FX lifecycle.
+4. `covered-gpu` требует live native handles, реальный draw path и связанный
+   renderer artifact: report, capture или approved pixel.
+
+## Current repository status
+
+- Реальный Vulkan в репозитории есть, но только как smoke triangle path.
+- `apps/fparkan-game` сейчас выдает `render-planning` JSON report поверх
+  synthetic window descriptor и `VulkanPlanningBackend`.
+- `apps/fparkan-viewer` сейчас inspection-only CLI и не открывает live Vulkan
+  asset viewer.
+- Следующий реальный milestone для rendered acceptance: `VulkanAssetRenderer`
+  с upload/draw/capture path для хотя бы одной оригинальной модели и одного
+  terrain slice.
@@ -219,6 +219,13 @@ graph.
 текстурированную статическую модель из исходного архива. Красивый viewer всё ещё
 означает только asset compatibility, а не готовую игру.

+Текущее состояние репозитория нужно формулировать строже. `apps/fparkan-viewer`
+сейчас является inspection CLI и synthetic command producer, а не live Vulkan
+asset viewer. Реальный Vulkan в репозитории сегодня доказан только через
+Stage 0 smoke triangle path; Stage 3 GPU vertical slice для оригинального
+`MSH` + `Texm` + `WEAR/MAT0` + terrain остаётся блокером. Для различения
+smoke, planning и live GPU путей используйте [таблицу правды renderer paths](../rendering/renderer_truth_table.md).
+
 ### Этап 4. Анимация и эффекты

 - реализовать MSH type 8/type 19 sampling и hierarchy;
@@ -232,6 +239,13 @@ graph.
 923/1 065 FXID создаются без parser errors; перезапуск одинакового effect seed
 даёт идентичный список emitted primitives.

+Текущее состояние репозитория опять же уже, чем целевой этап. В коде есть
+portable reference sampler и детерминированный FX reference stub, но нет
+runtime-captured parity для lifecycle/opcode semantics и нет Stage 4 rendered
+acceptance поверх live Vulkan asset renderer. Поэтому rendered Stage 4 следует
+считать заблокированным входным gate Stage 3, а parallel Stage 4 work вести
+через captures, schemas и backend-neutral snapshots.
+
 ### Этап 5. Карта и мир

 - реализовать `Land.msh` и corrected `TerrainFace28` layout;
@@ -215,6 +215,13 @@ RVA используются только для сопоставления и
 implementation не должна встраивать их как постоянные игровые идентификаторы.
 Таблица внутренних RVA хранится по SHA-256 конкретного модуля.

+Операционные evidence-артефакты, которые должны оставаться синхронизированными
+с кодом и acceptance, вынесены в отдельные страницы:
+
+- [Hashes и import/export summary оригинального движка](../evidence/original_engine_hashes.md)
+- [Stage 4 capture schema](../evidence/stage4_capture_schema.md)
+- [Renderer truth table](../rendering/renderer_truth_table.md)
+
 Подтверждённые hashes неизменённых DLL:

 ```text
@@ -73,6 +73,9 @@ nav:
      - WEAR и MAT0: reference/materials.md
      - Texm: reference/texm.md
      - Render frame: reference/render-frame.md
+      - Renderer Truth Table: rendering/renderer_truth_table.md
+      - Original Engine Hashes: evidence/original_engine_hashes.md
+      - Stage 4 Capture Schema: evidence/stage4_capture_schema.md
  - Приложения:
      - Глоссарий: appendices/glossary.md
      - Границы знания: appendices/knowledge-boundaries.md