sync: restore source from Google Drive

2026-09-12 16:50:30 +05:00
1 parent e2d8247e91
commit 7063d1b1c9
@@ -0,0 +1,39 @@
+# Что можно заключить по этому тесту
+
+## Цель
+
+Получить реальные ошибки или успешные результаты **компиляции, полной native-линковки и APK-упаковки** KaM r16020 + FPC/CGE для Android. Отдельно проверить простейший запуск уже собранных APK. Ни desktop-сборка, ни полная игра для этой цели не нужны.
+
+## Границы свидетельств
+
+| Свидетельство | Подтверждает | Не подтверждает |
+|---|---|---|
+| `platform` compile/link | Сборочные настройки CGE/FPC для выбранного Android ABI | Совместимость KaM |
+| Корневой модуль compile/link | Этот исходник и активные транзитивные зависимости компилируются/линкуются при записанных defines | Правильность каждого метода, чтение всех ресурсов |
+| `integration` compile/link | Совместную линковку выбранных настоящих корней KaM и CGE | Старт миссии, simulation parity, готовность renderer |
+| APK inspection | Корректную оболочку ZIP/DEX, нужный ABI, сопоставление библиотеки и статически объявленных зависимостей | Все dynamic `dlopen` пути, запуск Android loader, подпись без отдельной проверки |
+| `apksigner` | Подпись конкретного артефакта при успешной проверке | Корректную работу приложения |
+| Runtime startup | Прохождение соответствующих инициализаторов и старт CGE UI | Полную игровую инициализацию |
+| Реальные point/stream smoke | Несколько конкретных штатных операций и размеров типов на Android | Все сценарии бинарной совместимости сохранений |
+| Procedural GPU image / кадры | Вызовы render/update в CGE; визуально — простой texture path | КаМ высоты, сортировку спрайтов, terrain, draw performance |
+| Лексический inventory | Места потенциальных зависимостей с файлами и строками | Активность ветви `ifdef` и наличие реальной ошибки компиляции |
+
+Флаг `elf_16k_alignment_candidate` — только статическое свойство сегментов ELF. Это не сертификат совместимости с 16 KB Android page size и не подтверждение требований Google Play. ZIP alignment и поведение на соответствующем устройстве отдельно этим флагом не проверены.
+
+## Принятие решения для документации
+
+`REUSE_CANDIDATE`: исходный модуль собрался без изменений. Формулировка для документации: «Переиспользуем, compile/link подтверждён на ABI X в окружении Y; runtime/поведение проверяются отдельно».
+
+`PLATFORM_ADAPTER_CANDIDATE`: ошибка на Windows/LCL/старом graphics/audio API. Сначала найти путь зависимости. Перенести конкретную платформенную операцию за границу, а не заменять loader или simulation module целиком.
+
+`DEPENDENCY_BUILD_OR_CONFIG`: отсутствующий unit/include/native symbol. Различать некомплектный исходный пакет, неверный search path, библиотеку без Android-варианта, CPU-specific assembler и действительно непереносимый API. Записанный triage — подсказка, не окончательный диагноз.
+
+`SOURCE_PATCH_CANDIDATE`: ошибка языка/RTL/ABI в настоящем исходнике. Нужна локальная проверяемая правка, её основание, повторный результат. Этот стенд намеренно хранит baseline неизменным и не делает такую правку автоматически.
+
+`NEW_IMPLEMENTATION`: **никогда не назначается автоматически** по одной ошибке компиляции. Нужны исследование существующего кода и явное обоснование, почему адаптация/подключение библиотеки не подходят. Новый мобильный UI и touch presentation ожидаемы, но это не довод переписывать core.
+
+## Что не входит в текущий запрос
+
+Не исполняются миссии, экономика, AI, строительство, боя, save/load игрового мира, кампании и библиотечные script-файлы. Их код входит в соответствующие dependency/link-пробы, но поведенческого покрытия от этого не появляется. Полный KaM renderer и мобильные игровые панели не реализованы. MAP/DAT форматы не менялись. Ресурсы не заменены синтетическими файлами «под KaM».
+
+После первого серверного запуска можно предметно описывать **сборочные и платформенные границы** проекта. Заявления о полной игровой совместимости потребуют других тестов; они не нужны для ответа на текущий вопрос «что мешает собрать нашу архитектуру под Android».
@@ -0,0 +1,8 @@
+# First server run diagnosis (2026-09-08)
+
+The first server report did **not** reach KaM portability errors. Two harness defects blocked it first.
+
+1. `tools/generate.py` passed `-Mdelphi` as a global FPC command-line option. This changed compilation mode for Castle Game Engine units too. `CastleLocalizationGetText` relies on its normal CGE/FPC mode and failed with `Variable identifier expected` and overload errors. KaM units do not need a global mode flag because `KaM_Remake.inc` contains `{$MODE Delphi}` under FPC. Fix: remove global `-Mdelphi`.
+2. `tools/source_audit.py` read UTF-8 files without BOM stripping. `src/game/KM_Game.pas` begins with a UTF-8 BOM, so the lexical `^unit` matcher did not index it and the simulation/integration profiles were incorrectly marked `Missing required original source units: KM_Game`. Fix: read with `utf-8-sig`.
+
+After these fixes, rerun the same Android profiles. New failures should be treated as the first meaningful evidence about KaM/FPC/Android dependencies.
@@ -0,0 +1,27 @@
+# Первичные источники
+
+Проверено при подготовке: 8 сентября 2026 года. Это ссылки для воспроизведения API/сборочных решений, не утверждение, что Android APK был собран в среде подготовки.
+
+## Зафиксированный KaM
+
+- База и исходники: https://github.com/reyandme/kam_remake/tree/962fb850324b79bbe5480e1c2087d98f83a60917
+- Переключатели FPC/существующий `DBG_SKIP_SECURE_AUTH`: https://github.com/reyandme/kam_remake/blob/962fb850324b79bbe5480e1c2087d98f83a60917/KaM_Remake.inc
+- Подмодуль PascalScript: https://github.com/reyandme/kam_remake/blob/962fb850324b79bbe5480e1c2087d98f83a60917/.gitmodules
+- Оригинальные координаты: https://github.com/reyandme/kam_remake/blob/962fb850324b79bbe5480e1c2087d98f83a60917/src/common/KM_Points.pas
+- Оригинальные потоки: https://github.com/reyandme/kam_remake/blob/962fb850324b79bbe5480e1c2087d98f83a60917/src/common/KM_CommonClasses.pas
+
+Upstream revision, blob SHA-1 и SHA-256 для всех реально используемых файлов записывает `tools/source_fetch.py`. Используется SHA gitlink подмодуля из закреплённого дерева, не его текущая ветка.
+
+## Castle / Android
+
+- Build tool, Android `--os/--cpu`, `--assume-compiled`, debug APK: https://castle-engine.io/build_tool
+- Формат manifest, game_units, search_paths, defines, custom_options: https://castle-engine.io/project_manifest
+- Официальный toolchain Docker image и его состав: https://castle-engine.io/docker
+- Android: https://castle-engine.io/android
+- Android assets: https://castle-engine.io/android_faq
+- Lifecycle callbacks: https://castle-engine.io/apidoc/html/CastleApplicationProperties.TCastleApplicationProperties.html
+- Файлы и config URLs: https://castle-engine.io/apidoc/html/CastleUriUtils.html
+- Android ABI: https://developer.android.com/ndk/guides/abis
+- Проверка реального устройства: https://developer.android.com/studio/run/device
+
+CGE API развивается. Именно поэтому первый реальный запуск сохраняет digest toolchain, а ошибка платформенного API в `platform` не называется ошибкой KaM. Default SDK/NDK берутся из выбранного CGE, а не из неподтверждённой собственной таблицы версий.
@@ -0,0 +1,45 @@
+# Разбор результатов
+
+## Не запускается Docker или нет места/доступа в сеть
+
+Это проблема окружения, не аргумент против FPC/Castle. Смотрите bootstrap report и `docker-pull.log`. Не запускайте скрипт через `sudo` автоматически: сначала настройте доступ к Docker и права на папку проекта. Образ содержит инструменты для многих целей; его размер не равен размеру нашего исходного ZIP.
+
+## `platform` не собрался
+
+Сначала смотреть `platform/compile-link.log`, `toolchain.json` и `platform/CastleEngineManifest.xml`. Это самостоятельная CGE/FPC проба без KaM. Причиной может быть версия API CGE, Android cross-compiler, NDK/linker либо ошибка кода самого стенда. Не приписывайте её KaM. Остальные пробы всё равно запускаются для сбора диагностик.
+
+## `Can't find unit Graphics / Forms / LCL...`
+
+Стенд не добавляет desktop LCL в Android автоматически и не создаёт пустую замену. Лексический `source-inventory.json` помогает найти места зависимости, но смотреть нужно активную цепочку в compile log. У нескольких проб может быть один общий блокер. Не считать каждый упавший профиль отдельной переписываемой системой.
+
+## Отсутствующий `.res`, generated include или native object
+
+Загрузчик намеренно выбирает только исходный текст, а не скомпилированные Windows-ресурсы/объекты. Такая ошибка может означать, что ресурс нужно штатно генерировать для Android или отделить платформенный модуль, а не что игровой формат несовместим. Запишите запросивший файл и найдите соответствующий upstream build step. Стенд не подменяет необходимый вход пустым файлом.
+
+## `No fresh Pascal unit artifact`
+
+Компилятор завершился, но стенд не нашёл ожидаемый `.ppu` внутри свежего проекта. Нельзя без проверки просто ослабить это условие: сначала установить, куда текущий CGE положил units, действительно ли собран именно исходный корень и не использован чужой cache. В `target.json` есть список источников и options. Это диагностическая проверка стенда, не обязательное свидетельство ошибки core.
+
+## Undefined symbols / native `.so` отсутствует в APK
+
+Проверка линковки специально строгая. Посмотреть библиотеку и ABI, транзитивные native зависимости и имеющийся вариант для Android. `extra-paths.json` позволяет явно добавить пути к проверенной библиотеке/исходникам. Не добавлять Windows DLL, desktop `.so` или заглушку с тем же именем unit. Настроить library search path недостаточно, если библиотека ещё должна отдельно упаковываться в APK: отчёт `DT_NEEDED` это обнаружит.
+
+## APK слинкован, но упаковка отказала из-за native identity
+
+Сравнение разрешает удаление неисполняемой debug-информации, но требует совпадения allocated sections и program headers. Другие изменения упаковщика требуют отдельного исследования. Не принимать произвольный `.apk` из старого `dist/` за новый. При нескольких разных APK outputs стенд консервативно отказывается выбирать случайный; изучите свежий target, прежде чем менять правило отбора.
+
+## Source modified / Unrecorded binary
+
+Baseline под `vendor/kam_remake/` проверяется по receipt до и после сборки. Не редактируйте его для получения «неизменённого upstream PASS». Для исследования адаптации нужна отдельная явно обозначенная копия/patch-ветка и запись разницы; текущий стенд проверяет as-is baseline. Повторная загрузка не затирает ваши изменения молча.
+
+## Код возврата 2 после platform-only
+
+Это ожидаемый `PARTIAL_SELECTION`. Смотрите индивидуальные статусы. Успешный platform-only запуск специально не делает глобальный architecture gate зелёным.
+
+## APK запускается и сразу закрывается
+
+Это может быть ошибка native loader, unit initialization или попытка штатного кода обратиться к данным до старта UI. `runtime.json` при раннем падении может не создаться. Сохраните журнал Android для этого package и библиотек. Device tool не засчитывает отсутствие отчёта за успех. Для полного crash stack может потребоваться отдельное чтение native crash log на устройстве.
+
+## Что передавать для следующего разбора
+
+`reports/runs/<build-id>/evidence.zip` содержит версии инструментов, source hashes, manifests, generated imports, compile/package logs и result. В нём нет игровых файлов, APK и полного upstream дерева. По нему можно выделить первый общий блокер. Для runtime дополнительно нужны файлы конкретного `reports/device/<timestamp>/`; сначала проверьте, нет ли в журналах нежелательных личных путей/данных.