# План переработки Civilization III Atlants

Цель — максимально близкая к выбранной оригинальной поставке Atlants 2 браузерная игра. Первый целевой режим — **одиночная партия в настольном браузере с ИИ, редактором карт и редактором юнитов**. Обязательный ранний результат — целостная небольшая партия от основания города до победы на третьем рубеже.

Основой данных служит предоставленная поставка и её `Conquests/conquests.biq`: 413 типов юнитов, 236 технологий, 244 здания и чуда, 52 ресурса и 14 правительств. Это количество записей таблиц; доступность объектов зависит от условий и флагов. Подробности: [оригинальные правила](original-game/rules-and-scenarios.md).

Оригинальные изображения, анимации и звуки используем для прототипа. Допускается конвертация в подходящие браузеру форматы с сохранением внешнего вида, кадров, длительностей и звучания.

## Работа в текущей игре

Промежуточные изменения публикуются прямо в [текущей игре](https://civ3.ya-erm.ru/) небольшими итерациями внутри каждого рубежа. Существующий прототип допускается полностью переделывать с первых итераций.

- До заметного изменения кратко описываем ближайший шаг и ожидаемое поведение.
- После публикации сообщаем, что изменилось, как это проверить и какие части ещё в работе. Учитываем поступившие поправки до существенного расширения показанного решения.
- В начале разработки параллельно с ядром подключаем небольшой оригинальный визуальный фрагмент: панель, группу текстур или один тип юнита. Затем последовательно расширяем его.
- Внутренние изменения ядра отражаем в материалах разработки с результатами проверок; появление визуального результата отмечаем отдельно.
- Перед обновлением выполняем короткую проверку запуска и затронутого действия. Предыдущую сборку храним как внутреннюю резервную копию для технического отката.

Сайт показывает ход разработки. Публикация каждого изменения не требует отдельной приёмки или завершения всего рубежа.

## Четыре направления совместимости

| Направление | Что проверяем | Как фиксируем результат |
| --- | --- | --- |
| Правила | Стоимости, требования, формулы, округления и порядок расчётов | Контрольный случай с настройками оригинала, исходным состоянием, действиями и ожидаемым результатом |
| Представление | Изображения, палитры, направления, длительности анимаций и звуковые события | Эталонные изображения, кадры, временные параметры и сравнение воспроизведения |
| Управление | Приказы, доступность действий, состояния экранов, клавиши и уведомления | Сценарий взаимодействия от входа в экран до изменения состояния игры |
| Данные | Собственные сохранения, импорт профиля и карт BIQ, импорт состояния SAV | Версия формата, список восстановленных полей, проверка ссылок и продолжение игры |

Отчёт ведётся отдельно по каждому направлению, версии и проверенному случаю. Один общий процент готовности не заменяет эту матрицу. Техническая проверка извлечённой таблицы и подтверждение поведения в оригинальной игре отмечаются раздельно.

## Рубежи и зависимости

| Рубеж | Проверяемый результат | Зависимости |
| --- | --- | --- |
| **1. Эталон** | Закреплённая поставка, исполняемая версия, настройки партий, контрольные случаи и реестр неопределённостей | Предоставленные файлы и исследование оригинала |
| **2. Техническая основа** | Ядро без интерфейса, общий профиль, контракты команд, сохранения и проверочный набор оригинальных ресурсов | Паспорт эталона и исходные таблицы |
| **3. Целостная небольшая партия** | Основание города, развитие, дорога и ресурс, исследование, бой, захват и победа; человек и минимальный ИИ; сохранение и продолжение | Рабочие контракты, ограниченный поддерживаемый набор правил и ресурсов рубежа 2 |
| **4. Основные системы** | Расширенная экономика, государства, культура, торговля, дипломатия, генератор мира, экраны и редакторы; ИИ использует каждую новую механику | Пройденный полный цикл рубежа 3 |
| **5. Полный состав Atlants** | Дополнительные способности, контент, морские и воздушные системы, армии, специальные вооружения и остальные победы | Соответствующие основные системы и проверенная общая модель |

**Расширение до рубежа 4 начинается после проверяемой партии рубежа 3.** Подготовка ресурсов и проверка поведения оригинала продолжаются параллельно. Проверки совместимости и производительности выполняются внутри всех рубежей; отдельного заключительного этапа приёмки или переключения сайта нет.

## Рубеж 1 Эталон и проверка поведения оригинала

| Подзадача | Конкретный результат |
| --- | --- |
| **1.1 Паспорт поставки** | Пути и хеши EXE, BIQ и используемых ресурсов; сведения о версии исполняемого файла, модификациях и патчах. Надпись в Readme сама по себе не устанавливает версию поведения |
| **1.2 Настройки контрольных партий** | Сложность, цивилизации, стартовые условия, размер и замыкание карты, начальное зерно, включённые правила, ускоренное производство, условия победы и параметры сценария. Основная игра и выбранные сценарии получают отдельные записи |
| **1.3 Наблюдение оригинала** | Воспроизводимые контрольные ходы в Windows-оригинале: входное сохранение или описанное состояние, последовательность действий, результат, изображения и численные значения. Это самостоятельная обязательная работа, продолжающаяся при реализации механик |
| **1.4 Реестр неопределённостей** | Для спорного поля или правила — источник, предполагаемая семантика, версия, известное расхождение и способ проверки. Известные ошибки и изменения сторонних патчей отделяются от поведения выбранного эталона |

Первыми проверяются межходовой порядок, пища и рост, щиты и производство, наука и округления, движение, базовый бой, захват города и подключение ресурса. При невозможности пока провести контрольный ход соответствующая запись остаётся непроверенной.

## Рубеж 2 Ядро профиль сохранения и ресурсы

### Контракты игрового ядра

- **2.1 Команды и события.** Команда содержит игрока, тип действия и параметры. Единая проверка допустимости возвращает структурированную причину отказа. Отклонённая команда не меняет состояние. Интерфейс, ИИ и редакторы обращаются к общим правилам через определённые операции.
- **2.2 Расчёт и представление.** Игровой результат не зависит от скорости анимации, частоты кадров или загрузки ресурса. Анимации и звук воспроизводят события; их случайность не меняет случайность боя или генерации мира.
- **2.3 Информация игрока.** Интерфейс и ИИ получают представление мира с учётом видимости, разведанных сведений и дипломатических контактов. Закрытые сведения не передаются ИИ через обходной доступ к полному состоянию.
- **2.4 Общие запросы.** Предпросмотр доходов, маршрута, стоимости и доступности действия использует те же расчёты, что исполнение. Доступность юнита или здания определяется одной общей проверкой для производства, интерфейса, ИИ и редакторов.
- **2.5 Порядок хода.** Фазы, очередь команд и ожидающие решения заданы явно. Обработка экономики, рабочих заданий, роста, производства и побед выполняется в установленном порядке и сверяется с эталоном.

### Импорт профиля и выполнение правил

**2.6 Нормализовать таблицы Atlants.** Сохранить идентификаторы, единицы стоимости, связи, флаги, служебные технологии, варианты по эпохам и специальные способы появления объектов. Неизвестные поля сохраняются вместе с исходными значениями.

Для каждого свойства вести цепочку **извлечено → интерпретировано → реализовано → проверено**. Запись содержит объект, поле, источник и версию, толкование, обработчик движка, проверочный случай и известные ограничения. Загрузка всех таблиц завершает импорт данных, но не означает выполнения всех их свойств. Неподдерживаемые возможности явно включаются в отчёт совместимости.

OpenCiv3 используется как источник решений и примеров. Заимствованное правило проверяется отдельно для нашего эталона, особенно захват городов, торговля, культура и боевые исключения: [матрица ограничений OpenCiv3](openciv3/feature-matrix.md).

### Собственные сохранения и воспроизводимость

**2.7 Ввести версионированное сохранение.** Хранить версию схемы, идентификатор и версию профиля правил и набора ресурсов, состояние PRNG, фазу хода, сыгравшие стороны, незавершённые задания и производства, договоры, очередь команд и ожидающие решения игрока. Ссылки восстанавливаются по устойчивым идентификаторам.

Критерий ядра: **одинаковые исходное состояние и команды дают одинаковое итоговое состояние; сохранение и загрузка между командами результата не меняют**. Проверяются загрузки посреди хода и перед ожидающим решением. Воспроизводимость собственного движка не означает совпадения последовательности случайных чисел с оригиналом; такая совместимость требует отдельного подтверждения.

### Проверочный набор оригинальных ресурсов

**2.8 Подготовить небольшой набор до массовой конвертации:** наземный юнит, всадник, корабль, авиация, вариант по эпохе, юнит со смещённым холстом, составной AMB и проблемный контейнер. Дополнить его фрагментом местности, городом и панелью интерфейса.

Проверить все доступные направления, цвет двух цивилизаций, прозрачность, тени, смещения, длительности, переходы действий, кадры замыкания и синхронизацию звука. Неизвестный формат, отсутствующая ссылка, специальное пустое значение INI и допустимое отклонение контейнера получают разные статусы обработки.

Для `DEAD = .`, связи `Ship_of_the_Line` с каталогом `Ship of the Line` и нестандартных FLC принять явное решение по каждому случаю. Исходники сохраняются; совместимые допуски, псевдонимы и временные замены отражаются в манифесте и диагностике. Использование замены не засчитывается как проверенное воспроизведение оригинального ресурса. Основание: [особенности анимаций и привязок](original-game/units-and-animation.md).

**2.9 Измерить загрузку и память.** Учесть размеры подготовленных файлов, декодированных кадров, текстур и звука, время загрузки и освобождение кэша. Установить измеряемые бюджеты и загрузку по необходимости. Найденные **4 255 прямых ресурсов занимают 327 929 759 байт, около 328 МБ исходных файлов**, и представляют лишь часть комплекта; объём в памяти после декодирования измеряется отдельно. [Оценка исходных зависимостей](original-game/data/reference-footprint.json).

## Рубеж 3 Обязательная целостная партия

Объём фиксируется заранее: **небольшая фиксированная карта, две цивилизации, поселенец, рабочий, несколько боевых типов, рост и производство города, короткая ветка исследований, ресурс через дорогу, захват города, победа, сохранение и продолжение партии**. Используется ограниченный набор объектов с их правилами Atlants. Карта и набор поддерживаемых возможностей фиксируются в конфигурации этого среза.

| Подзадача | Обязательное поведение |
| --- | --- |
| **3.1 Мир и управление** | Соседство и слои клетки, видимость, выбор юнита, минимальная панель приказов, несколько объектов на клетке, расход движения и маршрут |
| **3.2 Основание и хозяйство** | Поселенец основывает город; горожане обрабатывают клетки; пища, рост, щиты, коммерция, содержание и заказ производства проходят межходовой расчёт. Для выбранного правительства учитываются коррупция, потери производства и влияние настроения на выработку. Общая клетка соседних городов не может одновременно обрабатываться дважды |
| **3.3 Рабочий и ресурсная сеть** | Рабочий строит дорогу; ресурс становится доступен при выполнении требований и связности. Разрыв дороги меняет доступность производства. Прогресс работ сохраняется |
| **3.4 Наука и доступность** | Короткая ветка исследований, бюджет, завершение открытия и открываемое производство используют общий профиль и общую проверку требований |
| **3.5 Наземный бой и захват** | Базовые раунды, здоровье и опыт, выбор защитника, необходимые бонусы, гибель и захват города. Условия войны и начальных отношений заданы конфигурацией; последствия захвата сверены с оригиналом |
| **3.6 Минимальный ИИ вместе с механиками** | Для каждой предыдущей подзадачи сразу добавляется простой выбор действий ИИ: основание города, работа, производство, исследование, движение и атака. Приказы проходят те же проверки и используют доступную игроку информацию |
| **3.7 Завершение партии** | Одно полноценное условие победы по завоеванию с корректной проверкой выбывания стороны и отображением результата. Повторный ход завершённой партии не начисляет доходы и производство |
| **3.8 Продолжение после загрузки** | Сохранение после части хода, во время строительства дороги и перед завершением исследования или производства. После загрузки отсутствуют повторные ходы ИИ, потерянные задания и двойные начисления |

**Критерий рубежа:** партию можно пройти от старта до победы вручную и с элементарным ИИ, включая продолжение после сохранения. Те же команды с вставленной загрузкой дают тот же итог. Основные переходы этого цикла имеют контрольные случаи оригинала, а расхождения перечислены по четырём направлениям совместимости.

## Рубеж 4 Расширение основных систем

Каждая новая механика вводится вместе с действиями человека, простым использованием ИИ, сохранением, предпросмотром результата и проверкой взаимодействия с уже работающей партией.

| Подзадача | Содержание и критерий |
| --- | --- |
| **4.1 Экономика городов** | Расширить коррупцию и потери щитов, специалистов, ускорение, здания, чудеса, их глобальные эффекты, автопроизводство и губернатора. Проверить настроение, беспорядки, голод, порядок роста/производства и ограничения общих клеток соседних городов |
| **4.2 Технологии и правительства** | Полное дерево, эпохи, специальные технологии, переходы правительств, анархия и золотой век. Предпосылки и недоступные записи корректно интерпретируются, эффекты отражаются в расчётах и экранах |
| **4.3 Культура и общество** | Границы, культурный переход, сопротивление, настроение, военная усталость, призыв, национальность и ассимиляция. Проверить сочетания с захватом, правительством и выработкой |
| **4.4 Торговля и дипломатия** | Расширить дорожную сеть морскими и воздушными связями по мере готовности; добавить контакты, посольства, мир, войну, договоры, обмены, репутацию и шпионаж. Разрыв сделки или сети отражается в экономике и доступности |
| **4.5 Среда и рабочие** | Остальные задания, железные дороги, улучшения, загрязнение, болезни и природные события выбранного профиля; взаимодействие с технологиями, ресурсами и занятостью клеток |
| **4.6 Генератор мира** | Отдельная задача: параметры создания карты, суша/вода, климат, температура, возраст, размеры и замыкание, реки, ресурсы и старты. Одинаковые параметры и зерно воспроизводят карту; проверяются допустимость соседств, ресурсы, проходимость и пригодность стартов. Совпадение генератора с оригиналом оценивается отдельно |
| **4.7 Игровые экраны** | Развивать город, производство, науку, дипломатию и советников по мере подключения систем. Добавлять оригинальные состояния кнопок, клавиши, подсказки, уведомления, настройки и Civilopedia. Для каждого экрана проверять полный сценарий управления |
| **4.8 Редакторы** | Карты со слоями, объектами и стартами; юниты с требованиями, способностями, улучшениями, анимациями и звуками. Импорт/экспорт и валидация используют общий профиль. Созданный набор проходит обычную партию |
| **4.9 Развитие стратегии ИИ** | Улучшать разведку, заселение, рабочие задания, производство, науку, оборону, наступление и сделки поверх уже подключённого минимального ИИ. Убрать привязки к названиям объектов, учитывать способности и настройки сложности |

## Рубеж 5 Полный состав Atlants

| Самостоятельная задача | Зависимости и проверка |
| --- | --- |
| **5.1 Морские действия и перевозка** | Морские маршруты и бой, загрузка, выгрузка, вместимость и ограничения перевозки. Зависит от движения, доменов, ресурсов и общего боя; проверяется на отдельных транспортных и боевых сценариях |
| **5.2 Авиация и противовоздушная оборона** | Базирование, переброска, перевозка самолётом и вертолётом, воздушный/парашютный десант, воздушные миссии, перехват, ПВО и бомбардировка. Отдельные проверки дальности, целей, потерь и взаимодействия с городами/флотом |
| **5.3 Армии лидеры и особые способности** | Состав армий, лидеры, порабощение, скрытая национальность и остальные особенности фактических типов. Возможности включаются по проверенным флагам и условиям появления |
| **5.4 Специальные вооружения и эффекты** | Ядерное оружие, особые цели, разрушения и связанные последствия. Зависит от боя, карты, дипломатии и состояния городов |
| **5.5 Дополнительные победы** | Культурная, дипломатическая, космическая, территориальная, по времени/очкам и сценарные условия включаются по мере готовности соответствующих систем. Значения берутся из выбранного профиля; ранняя победа рубежа 3 сохраняется |
| **5.6 Полнота контента** | Последовательно покрыть оставшиеся типы юнитов, зданий, чудес, правительств, специалистов и их сочетания. Для каждого свойства обновляется статус выполнения и проверки, а неподдерживаемое остаётся видимым в отчёте |

Эти задачи имеют отдельные зависимости и проверочные случаи. Их не объединяем с чтением файлов сохранений или отдельным выпуском сайта.

## Отдельные задачи совместимости данных

| Задача | Содержание | Когда выполняется |
| --- | --- | --- |
| **Д1 Собственные сохранения** | Версии, целостность ссылок, точное продолжение состояния, решений и случайности | С рубежа 2 и при добавлении каждой механики |
| **Д2 Импорт карт и сценариев BIQ** | Разделить импорт таблиц правил и импорт географии, слоёв, стартов, размещённых объектов, настроек и условий сценария. Выдать отчёт об ограничениях | После появления модели карты рубежа 3; расширять вместе с редакторами и сценарными механиками |
| **Д3 Импорт состояния SAV** | Самостоятельный проект восстановления партии; подзадачи ниже | После стабилизации собственной модели и сохранений; он не блокирует раннюю целостную партию |

Подзадачи импорта SAV:

1. Определить версию и сжатие; прочитать встроенные правила и сопоставить идентификаторы профиля.
2. Восстановить географию, клетки, видимость, игроков, города, жителей, здания и юниты.
3. Восстановить экономику, исследования, правительства, культуру, договоры, отношения, рабочие задания, очереди, фазу хода и ожидающие решения. Исследовать сохранённое случайное состояние и неизвестные поля.
4. Проверить ссылки и полноту восстановления; перечислить неподдерживаемые версии и поля, влияющие на продолжение.
5. Сопоставить импортированную партию и её следующий ход с выбранным оригиналом. Одного совпадения встроенных таблиц BIQ для такой проверки недостаточно.

Исследование уже подтвердило совпадение основных таблиц одного сохранения с профилем, но текущее состояние мира ещё не импортировано: [границы выполненного анализа](original-game/methods-and-validation.md).

## Постоянная проверка взаимодействия и производительности

Контрольные случаи оригинала, проверки ядра и браузерные сценарии сопровождают все рубежи. В первую очередь проверяются общий полный цикл, порядок расчётов, округления, разрыв ресурсной сети, рост и настроение, захват города и загрузка посреди хода.

Для каждого изменения фиксируются затронутые механики, контрольные случаи, результат и известные расхождения по четырём направлениям. Визуальная сверка, проверка чисел, проверка управления и импорт данных имеют собственные результаты.

Измеряются время обработки хода и решений ИИ, отзывчивость браузера, число видимых объектов, загрузка и память после декодирования. Массовая конвертация выполняется небольшими партиями с ограничением ресурсов сервера. Проверки и исправления выполняются по ходу разработки на обычной странице игры.