diff --git a/docs/appendices/knowledge-boundaries.md b/docs/appendices/knowledge-boundaries.md index 18b6ca1..6f9553e 100644 --- a/docs/appendices/knowledge-boundaries.md +++ b/docs/appendices/knowledge-boundaries.md @@ -113,36 +113,22 @@ key, configuration, device profile, initial state, input/time script и верс ## Local evidence requests -На текущем рабочем месте закрыты статические, corpus и headless runtime gates. -Для локально воспроизводимого Desktop backend подтверждено только command/state trace -в существующем GL-воркфлоу: +Поддерживаемая desktop-платформа — только Windows/Vulkan. Локальный smoke +`fparkan-vulkan-smoke` уже подтверждает настоящий Win32 surface/swapchain, +300 кадров, controlled resize и отсутствие validation warnings/errors. +Это закрывает фундамент Stage 0, но не доказывает визуальный паритет игры. -- `fixtures/acceptance/macos-gl33-triangle-capture.json`; +Следующие доказательства всё ещё нужны именно для Iron3D-compatible рендера: -`S3-GL-001` пока не закрыт: текущая evidence не отражает полноценный -`winit`+`fparkan-render-vulkan` path с real surface/present pipeline. -Для закрытия требования требуется постоянный workspace-владельческий backend на -`winit`/`fparkan-platform-winit` + `fparkan-render-vulkan` с реальным -surface/present pipeline, command/state parity и licensed frame capture. +- capability-gated capture из оригинального GOG процесса с camera/matrix, + draw/state и frame-boundary provenance; +- фиксированные Windows Vulkan captures статической модели, lightmapped модели + и terrain после совпадения backend-neutral command capture; +- затем controlled captures анимации, FX, прозрачности, теней и атмосферы. -Для повышения `S3-GL-002` до `covered` всё ещё нужен воспроизводимый GLES2 -backend profile: GLES2 должен создать кадр, сохранить pixel capture и тот же -command/state trace. Локальный Docker probe существующего Rust image не нашёл -`libGL`, `libEGL`, `libGLES` или `libOSMesa`, поэтому закрытие этого gate требует -отдельно предоставленного Docker image с Rust + Mesa/EGL/OSMesa либо разрешения -на установку соответствующего проверочного окружения. - -Для текущей macOS-focused цели `S3-GL-002`, `L3-DEVICE-001` и `L5-RG40-001` -помечены как `omitted`: они остаются требованиями portable target scope, но не -блокируют локальный macOS acceptance-аудит. При возврате RG40XX/GLES2 в область -цели эти gates снова должны требовать внешнего evidence. - -`L3-DEVICE-001` и `L5-RG40-001` не закрываются локально без RG40XX H или -эквивалентного удалённого runner-а. Требуемое доказательство: запуск выбранной -миссии при 640x480 на целевом профиле, сохранённые stdout/stderr, build -fingerprint, manifest игрового каталога, frame/tick budget, memory budget и -итоговый pass/fail report. Desktop/headless результаты не считаются заменой -on-device smoke. +Linux/macOS, GLES2, RG40XX и удалённые portability runners не являются +acceptance-гейтами этого проекта. Они не должны появляться в списке блокеров +или подменять Windows evidence. ## Closure criteria diff --git a/docs/appendices/saves-campaign.md b/docs/appendices/saves-campaign.md new file mode 100644 index 0000000..f0b2d48 --- /dev/null +++ b/docs/appendices/saves-campaign.md @@ -0,0 +1,50 @@ +# Кампания, сохранения и восстановление сессии + +## Известная файловая поверхность + +Demo содержит `MISSIONS/dispatcher.ini` и `SAVE/saveslots.cfg`. +`dispatcher.ini` хранит campaign progression (в demo — `[COMPLETE]`), а +`saveslots.cfg` — ordered UI-метаданные slots, не полный snapshot мира. +В Части 2 slots 1 и 7 помечены занятыми без соответствующего payload; поэтому +проверяются независимо: наличие metadata record, физического файла и +format/version/integrity payload. + +Campaign различает существование миссии, её доступность, старт, успешное или +неуспешное завершение и уже применённый результат. Обработка одного +mission-complete event идемпотентна. Пустой slot и повреждённый существующий +payload — разные состояния. + +## Контракт standalone save + +Полный snapshot сохраняет campaign/mission context, time/pause/step phase, +stable object IDs, ownership, transforms, lifecycle/properties/cross-links, +world changes, Behavior/Control/AI/research/economy state, script variables/IP/ +timers, authoritative RNG, gameplay-relevant FX и queued messages. Camera/UI +можно сохранить как presentation context; GPU/audio handles и draw buffers +восстанавливаются, а не сериализуются. + +Снимок разрешён только после calculation и deferred operations, вне queue +traversal, после применённых network messages и до чтения mutable state +renderer-ом. Native pointers, vtable/allocator addresses и resource mapping +pointers запрещены: ссылки идут через stable IDs и resource keys. + +Новый формат — versioned chunks (`WORLD`, `OBJECTS`, `BEHAVIOR`, `PHYSICS`, +`AI`, `SCRIPT`, `RESEARCH`, `RNG`, `CAMERA_UI`, optional network) с magic, +format/profile/content fingerprint, size и checksum. Неизвестный optional +chunk пропускается; required chunk блокирует load. Это дизайн FParkan, не +утверждение о binary format оригинала. + +Запись транзакционна: временный файл → повторное чтение/checksum → fs sync → +атомарная замена payload → обновление slot metadata. Загрузка создаёт mission +и objects без публикации, восстанавливает IDs/cross-links/controllers/RNG, +регистрирует их, валидирует и только затем разрешает следующий tick. + +## Проверки и граница + +`save -> load` обязан давать тот же canonical state hash, OriginalObjectId, +cross-links и продолжение RNG. Corrupt required chunk не публикует частичный +мир; crash при записи не уничтожает старый slot; completion event идемпотентен. + +Для native format нужны controlled original saves, binary diffs и trace +serializer-а. До этого FParkan может иметь совместимую семантику собственных +saves, но не заявляет byte/network interoperability с оригинальными файлами. diff --git a/docs/appendices/script-vm.md b/docs/appendices/script-vm.md new file mode 100644 index 0000000..0664bdf --- /dev/null +++ b/docs/appendices/script-vm.md @@ -0,0 +1,50 @@ +# Сценарная VM, формулы и игровые свойства + +## Подтверждённый surface + +Миссионный сценарный слой задаёт стартовые события, completion/failure, +messages, teleports, задачи, research и campaign transitions. Точки входа и +файлы: `ai.dll: CreateSuperAI/GetSuperAI`, `MisLoad.dll: LoadResearch`, +`ArealMap.dll: CalcFullResearchCost`, `MISSIONS/SCRIPTS/*.scr`, `*.fml`, +`*.trf`, `varset.var`, `MISSIONS/dispatcher.ini`, `mission.cfg`, `messages.cfg` +и `briefing.cfg`. + +`.scr` — binary package с version checks, symbol/event sections и offsets; +полная opcode grammar не доказана. `.fml` — текстовый symbol/formula oracle; +`varset.var` задаёт `VAR(...)`/`STRING(...)` defaults; `.trf` — NRes tables, +чей framing подтверждён, а field semantics местами лишь consumer-inferred. + +## Безопасная модель исполнения + +Новая VM разделяет immutable package (bytecode, symbols, events, constants), +per-mission variables/timers/frames, bindings logical-name/ObjectId/clan/ +research key и typed commands к World3D/Behavior/UI/campaign. После varset +defaults и bindings она dispatches Init/start, на каждом tick обновляет timers, +ставит готовые events в стабильную очередь и исполняет bounded instruction +budget. Опасное удаление идёт через World3D queue и общий deferred lifecycle. + +До восстановления opcode table package mode читает header/strings/symbols/ +event offsets/raw bytecode losslessly. Disassembly mode использует подтверждённую +`ai.dll` jump table. Unknown opcode нельзя пропустить как один byte: это ломает +синхронизацию. Для каждого доказанного opcode фиксируются number, size, +operands, control flow, effects, errors и минимальный test. + +TMA properties остаются four raw `u32` words плюс имя, пока consumer/schema не +задаст тип (integer/float bits/ObjectId/enum/fixed-point/index). В том числе +сохраняются `NOT USED`; corpus подтверждает `Invulnerability`, life state, +`ClanID`, ore, speed и free-time properties. + +Research/economy работают в simulation: `LoadResearch` и +`CalcFullResearchCost` доказывают данные и вычислимую стоимость, но не полный +layout prerequisites/modifiers/unlocks. Formula evaluator требует strict +grammar/version, typed operands, deterministic numeric policy, bounded stack и +явных errors; x87-compatible rounding нужен там, где оно выбирает ветку. + +## Готовность + +Все demo packages должны проходить package/version checks, offsets оставаться +в bytecode, а confirmed disassembler — не терять синхронизацию. VM считается +готовой после deterministic Init/basic mission events, stable object bindings, +typed research/property tests и save/load script state. Для закрытия остаются +dispatcher/jump table, minimal differential packages и traces world/variable +effects; до них unknown opcode — явная unsupported branch, не no-op. diff --git a/docs/appendices/ui-shell.md b/docs/appendices/ui-shell.md new file mode 100644 index 0000000..d236e14 --- /dev/null +++ b/docs/appendices/ui-shell.md @@ -0,0 +1,74 @@ +# Shell, HUD, шрифты и локализация + +## Доказанная граница + +`iron_3d.exe` создаёт процесс и окно; `iron3d.dll` экспортирует `createShell`, +`deleteShell` и `getIShell`; `services.dll` предоставляет `getGUIServer` и +`getDisplay`. Поэтому меню, briefing, HUD и системные диалоги — отдельная +оболочка над World3D, а не игровые объекты, созданные ради отрисовки. + +```text +Win32 messages + -> shell/GUI input и manual events + -> simulation World3D + -> world render + -> shell/HUD overlay и presentation state +``` + +Точное положение legacy DirectDraw flip относительно последнего UI draw пока +требует API capture. Разделение world и UI pass доказано, но не следует +выдавать его за восстановленный layout классов виджетов. + +## Ресурсы и идентичность + +В demo найдены `ui/shell_ctrls.cfg`, `ui/menu_resources.cfg`, `ui/cursor.cfg`, +`ui/game_resources.cfg`, `ui/hq.cfg`, `DATA/TextRes.cfg`, `gamefont.rlb`, +`sprites.lib` и `Palettes.lib`. Конфигурации задают controls/resources/cursor, +overlays и HQ; `TextRes.cfg` связывает символические ключи с текстом. + +`gamefont.rlb` содержит две LZSS-записи (`0x040`), `sprites.lib` — 24 записи +raw Deflate (`0x100`). `sprites.lib::INTERF8.TEX` использует известный +`deflate_eof_plus_one` quirk. UI обязан пользоваться общим RsLi reader, а не +отдельной похожей распаковкой. + +Ключ ресурса, legacy path, локализованный текст и исходные bytes — четыре +разные идентичности. Archive keys остаются ASCII-casefold; `TextRes.cfg`, +briefing/messages и script strings могут требовать ANSI/CP1251 decoding. +Unicode-представление хранит raw bytes для roundtrip и diagnostics. + +`gamefont.rlb` и `sprites.lib` побайтно совпадают в Частях 1 и 2. Во второй +части добавлен `ui_factory.lib` (NRes с шестью Texm) и расширен +`ui/minimap.lib`; при этом пересобранные `iron3d.dll`/`services.dll` требуют +отдельной трассировки lifecycle и HUD state. + +## Контракт новой реализации + +UI scene хранит корневые widgets, focus, viewport/clip rectangles и modal +depth. Demo `640x480` — полезный baseline, но не доказанное универсальное +design resolution. Отдельно хранятся legacy-layout coordinates, реальный +viewport, scale/letterbox policy, mouse-to-layout transform, clipping и +z-order. Cursor, sprite и hit-test обязаны применять одно преобразование. + +Font contract включает glyph image, advance, bearing/offset, line height и +fallback glyph. Binary glyph metrics `gamefont.rlb` пока не восстановлены: +payload читается lossless через RsLi, а семантика устанавливается по consumer +trace. + +Нормализованное событие проходит modal widget, затем shell command map; лишь +разрешённая gameplay-команда превращается в World3D manual event. Held state и +axes попадают в calculation snapshot. Это не позволяет UI-click одновременно +исполнить команду мира. HUD только читает presentation view (selected object, +resources, mission text, timers, research/build state, camera mode); authority +остаётся у simulation. + +## Проверки и открытые вопросы + +- UI cfg читаются до EOF с сохранением неизвестных fields; symbolic key + разрешается в RsLi entry независимо от регистра. +- Visual rect и hit-test совпадают при разных viewport; modal scene блокирует + gameplay input; missing optional sprite/font имеет named fallback. +- UI-only и world-only command captures собираются раздельно. + +Не закрыты grammar всех `ui/*.cfg`, hierarchy original widgets, glyph metrics, +HUD state machine и pixel-perfect layout. Нужны GUI-factory hooks, event traces +и captures меню, briefing, HQ и игрового HUD. diff --git a/docs/baseline/notion-reconciliation.md b/docs/baseline/notion-reconciliation.md new file mode 100644 index 0000000..25af317 --- /dev/null +++ b/docs/baseline/notion-reconciliation.md @@ -0,0 +1,30 @@ +# Сверка локальной книги с 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 и все последующие уточнения ведутся только в +локальных файлах. diff --git a/docs/index.md b/docs/index.md index 09c3f90..ea17a63 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,9 +12,10 @@ Iron3D из *Parkan: Iron Strategy*. Она ведёт от запуска ор ## Источник истины и синхронизация Каталог `docs/` — единственный рабочий источник истины для FParkan. 18 июля -2026 года его постранично сопоставили с книгой FParkan в Notion: восемь томов -и приложения уже покрывают её 42 основные статьи, а актуальные локальные -материалы содержат и последующие результаты разработки. Notion больше не +2026 года его содержательно сопоставили с книгой FParkan в Notion; результат, +маршрутизация статей и сознательно исключённые цели зафиксированы в +[сверке](baseline/notion-reconciliation.md). Актуальные локальные материалы +содержат и последующие результаты разработки. Notion больше не является местом внесения изменений: новые факты, исправления и решения фиксируются только здесь, в томе, справочнике или evidence-документе, которому они принадлежат.