synthesis/engine-analysis.md

Выбор движка для агентной разработки в Cursor

Критерии оценки

Для полностью агентной разработки (AI-агент в Cursor пишет весь код) критически важны:

Критерий	Почему
Качество генерации кода	AI должен хорошо знать язык и фреймворк
Всё-в-коде	Никаких визуальных редакторов — агент работает только с текстовыми файлами
Сборка/запуск из терминала	Агент запускает через Shell tool
Визуальная проверка	Агент может УВИДЕТЬ результат (критично для отладки графики)
Скорость итерации	Hot-reload, быстрый цикл «изменил → увидел»
Экосистема библиотек	Для химии, математики, процедурной генерации
Возможности 2D-движка	Тайлмапы, физика, частицы, шейдеры, камера

---

Кандидаты

1. TypeScript + Phaser 3 + bitECS + Vite

Язык: TypeScript — один из лучших для AI-генерации. Строгая типизация ловит ошибки до рантайма. Огромный объём обучающих данных у моделей.

Всё-в-коде: Полностью. Ни один файл не требует визуального редактора. Конфиги, сцены, уровни — всё на TypeScript/JSON.

Сборка/запуск: npm run dev → Vite поднимает сервер с HMR за <1 секунду.

Визуальная проверка: Killer feature — Cursor имеет встроенные Playwright browser tools. Агент может:

• Открыть localhost:5173 в браузере
• Сделать скриншот игры
• Прочитать console.log ошибки
• Кликнуть по элементам UI
• Проверить результат визуально

Ни один другой стек не даёт агенту такой обратной связи.

Скорость итерации: Vite HMR — изменения видны мгновенно, без перезапуска. Для игры это означает: поменял логику врага → сразу видишь в браузере.

Экосистема:

• bitecs — высокопроизводительная ECS (~5kb, TypedArrays, SoA-layout, до десятков тысяч сущностей)
• simplex-noise — шум для процедурной генерации
• Любые npm-библиотеки для математики, графов, pathfinding

2D-возможности Phaser 3:

• Спрайты, атласы, тайлмапы
• Arcade/Matter.js физика
• Система частиц
• Камеры, зум, следование
• Tweens и анимации
• WebGL-шейдеры (пайплайны)
• Ввод: клавиатура, мышь, тач, геймпад
• Аудио
• Scene-менеджер

Производительность: WebGL-рендер, батчинг до ~2000 спрайтов/batch. bitECS для логики — Structure of Arrays, итерация по компонентам на скорости, близкой к нативной. Web Workers для тяжёлой симуляции (экология, химия) в отдельном потоке.

Агентопригодность:  ██████████ 10/10
Визуальная отладка: ██████████ 10/10
Язык для AI:        ██████████ 10/10
Скорость итерации:  ██████████ 10/10
2D-возможности:     ████████░░  8/10
Производительность: ███████░░░  7/10
Экосистема:         █████████░  9/10
─────────────────────────────────────
ИТОГО:                         64/70

---

2. Godot 4 + GDScript

Язык: GDScript — Python-подобный, AI знает его удовлетворительно, но значительно хуже TypeScript/Python. Меньше обучающих данных. Ошибки чаще.

Всё-в-коде: Почти. .tscn и .tres файлы текстовые и генерируемые. Формат специфичен, но godot-mcp (MCP-сервер для Godot, 1.8k stars) снимает эту проблему: создание сцен, добавление нод, загрузка спрайтов — через MCP API без ручного конструирования .tscn.

Сборка/запуск: godot --headless --path . --script test.gd — работает. С godot-mcp — запуск/остановка проекта и захват debug output через MCP-инструменты. Логическая отладка решена.

Визуальная проверка: Остаётся слабым местом. godot-mcp не поддерживает скриншоты viewport — агент видит только console output. Альтернатива — HTML5-экспорт + Playwright, но цикл итерации длинный: сохранение → экспорт (секунды) → перезагрузка браузера → скриншот (~15-30 сек vs. ~1-2 сек у Phaser + Vite HMR). Для логики — достаточно. Для визуала (шейдеры, фракталы, анимации) — сильно уступает Phaser.

Watch list: если godot-mcp добавит viewport capture (Godot технически умеет сохранять viewport в изображение через get_viewport().get_texture().get_image().save_png()), разрыв с Phaser сократится радикально. Следить за развитием проекта.

Скорость итерации: Средняя. GDScript не компилируется, но перезапуск сцены — не мгновенный. С веб-экспортом цикл ещё длиннее.

2D-возможности: Лучшие в классе. Встроенные тайлмапы, физика, анимация, частицы, шейдеры, сигналы, scene tree.

Производительность: Отличная для 2D. GDNative/C# для критических участков.

Агентопригодность:  ███████░░░  7/10  (↑ благодаря godot-mcp)
Визуальная отладка: ████░░░░░░  4/10  (HTML5-экспорт; viewport capture пока нет)
Язык для AI:        ██████░░░░  6/10
Скорость итерации:  ██████░░░░  6/10
2D-возможности:     ██████████ 10/10
Производительность: █████████░  9/10
Экосистема:         ██████░░░░  6/10  (↑ godot-mcp как часть экосистемы)
─────────────────────────────────────
ИТОГО:                         48/70

---

3. Godot 4 + C#

Тот же Godot, но на C#.

Преимущество: C# AI знает отлично. Строгая типизация. NuGet-пакеты.

Недостаток: Компиляция медленнее GDScript. Требует .NET SDK. Визуальная проверка — через HTML5-экспорт (те же ограничения). godot-mcp работает и с C#-проектами.

Агентопригодность:  ███████░░░  7/10  (↑ благодаря godot-mcp)
Визуальная отладка: ████░░░░░░  4/10  (HTML5-экспорт; viewport capture пока нет)
Язык для AI:        ████████░░  8/10
Скорость итерации:  █████░░░░░  5/10
2D-возможности:     ██████████ 10/10
Производительность: █████████░  9/10
Экосистема:         ███████░░░  7/10
─────────────────────────────────────
ИТОГО:                         50/70

---

4. Python + Pygame-CE

Язык: Python — абсолютный лидер для AI-генерации кода. Максимальное качество.

Всё-в-коде: Полностью.

Визуальная проверка: Нет. Pygame рисует в собственном окне, которое Playwright не видит.

2D-возможности: Минимальные. Спрайты и рект — есть. Тайлмапы, физику, частицы, камеру — писать с нуля.

Экосистема: Лучшая для научных вычислений (numpy, scipy). Химическая симуляция на numpy будет быстрой.

Производительность: Потолок. Для тысяч сущностей без оптимизаций будет тормозить. Numpy помогает, но рендер — бутылочное горлышко.

Агентопригодность:  ████████░░  8/10
Визуальная отладка: ██░░░░░░░░  2/10
Язык для AI:        ██████████ 10/10
Скорость итерации:  ████████░░  8/10
2D-возможности:     ████░░░░░░  4/10
Производительность: █████░░░░░  5/10
Экосистема:         ██████████ 10/10
─────────────────────────────────────
ИТОГО:                         47/70

---

Вердикт

Победитель: TypeScript + Phaser 3 + bitECS + Vite

Решающий фактор — визуальная обратная связь через Playwright. Агент в Cursor может:

1. Написать код
2. HMR мгновенно применит изменения
3. Агент делает скриншот в браузере
4. Видит результат
5. Корректирует

Это замыкает цикл разработки полностью внутри агента. Ни один другой стек не даёт такой обратной связи для 2D-игры.

Архитектура проекта

synthesis/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── index.html
├── src/
│   ├── main.ts                   # Точка входа, инициализация Phaser
│   ├── config.ts                 # Конфигурация Phaser
│   │
│   ├── ecs/                      # Entity Component System (bitECS)
│   │   ├── world.ts              # Мир ECS
│   │   ├── components/           # Компоненты
│   │   │   ├── position.ts
│   │   │   ├── health.ts
│   │   │   ├── chemistry.ts      # Элементный состав сущности
│   │   │   ├── metabolism.ts     # Метаболизм
│   │   │   ├── behavior.ts       # Поведенческие параметры
│   │   │   └── lifecycle.ts      # Фаза жизненного цикла
│   │   └── systems/              # Системы
│   │       ├── movement.ts
│   │       ├── ecology.ts        # Популяционная динамика
│   │       ├── chemistry.ts      # Химические реакции
│   │       ├── lifecycle.ts      # Рождение → старение → смерть → разложение
│   │       └── ai.ts             # Поведение существ
│   │
│   ├── chemistry/                # Химический движок
│   │   ├── elements.ts           # Таблица элементов
│   │   ├── reactions.ts          # База реакций
│   │   ├── engine.ts             # Движок комбинаций
│   │   └── compounds.ts          # Справочник соединений
│   │
│   ├── world/                    # Генерация мира
│   │   ├── generator.ts          # Процедурная генерация
│   │   ├── biomes.ts             # Определения биомов
│   │   ├── tilemap.ts            # Тайлмап-система
│   │   └── mycelium.ts           # Система Мицелия
│   │
│   ├── scenes/                   # Phaser-сцены
│   │   ├── BootScene.ts
│   │   ├── GameScene.ts
│   │   ├── DeathScene.ts         # «Момент между» — фракталы
│   │   ├── CodexScene.ts         # Энциклопедия
│   │   └── UIScene.ts            # HUD поверх игры
│   │
│   ├── player/                   # Всё про игрока
│   │   ├── controller.ts
│   │   ├── inventory.ts
│   │   ├── abilities.ts
│   │   └── schools.ts            # Стартовые школы
│   │
│   ├── meta/                     # Мета-прогрессия (между ранами)
│   │   ├── codex.ts              # Кодекс знаний
│   │   ├── spores.ts             # Споры (валюта)
│   │   ├── persistence.ts        # Сохранение в localStorage/IndexedDB
│   │   └── cycles.ts             # Трекер малых/великих циклов
│   │
│   ├── rendering/                # Визуальные эффекты
│   │   ├── shaders/              # WebGL-шейдеры
│   │   │   ├── fractal.glsl      # Фрактальный шейдер для «Момента между»
│   │   │   ├── mycelium.glsl     # Визуал Мицелия
│   │   │   └── distortion.glsl   # Искажения при Микозе
│   │   └── particles/            # Конфиги частиц
│   │
│   ├── audio/                    # Звук
│   │   ├── loops.ts              # Музыкальные лупы
│   │   └── ambient.ts            # Эмбиент-система
│   │
│   └── data/                     # Статические данные
│       ├── elements.json         # Периодическая таблица
│       ├── reactions.json        # База химических реакций
│       ├── creatures.json        # Определения существ
│       ├── biomes.json           # Параметры биомов
│       └── lore/                 # Тексты лора
│           ├── diary.json        # Дневник Последнего Синтетика
│           └── codex-entries.json
│
├── assets/                       # Графика, звук
│   ├── sprites/
│   ├── tilesets/
│   ├── ui/
│   └── audio/
│
├── tests/                        # Тесты
│   ├── chemistry.test.ts         # Тесты химического движка
│   ├── ecology.test.ts           # Тесты экосимуляции
│   └── generation.test.ts        # Тесты генерации мира
│
└── docs/
    ├── synthesis-gdd.md          # Game Design Document
    └── engine-analysis.md        # Этот файл

Ключевые зависимости

{
  "dependencies": {
    "phaser": "^3.80.0",
    "bitecs": "^0.4.0"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "vite": "^5.4.0",
    "vitest": "^2.0.0"
  }
}

Дополнительные зависимости (подключаются по мере необходимости):

{
  "simplex-noise": "^4.0.0",       // Процедурная генерация ландшафта
  "ngraph.graph": "^20.0.0",       // Граф Мицелия
  "ngraph.path": "^1.4.0",         // Pathfinding (A*, NBA*)
  "rbush": "^4.0.0"                // Spatial index (R-tree) для коллизий и culling
}

Минималистичный стек. Никаких лишних абстракций. Всё, что нужно для «Синтеза»:

• Phaser = рендер, физика, ввод, камера, сцены
• bitECS = высокопроизводительная симуляция сущностей
• Vite = мгновенная сборка
• Vitest = тесты для химического движка и экосимуляции
• ngraph = граф Мицелия + pathfinding
• rbush = пространственная индексация для производительности при тысячах сущностей

Почему не Godot?

Godot — объективно лучший 2D-движок. godot-mcp существенно улучшил его агентопригодность: управление сценами, запуск проекта, захват debug output — всё через MCP. Но для «Синтеза» Godot проигрывает по двум параметрам:

1. Визуальная обратная связь. godot-mcp не поддерживает скриншоты viewport. Агент видит console output, но не экран игры. Для проекта с фрактальными шейдерами, психоделическими визуалами и сложным UI — это блокирующий минус. Альтернатива (HTML5-экспорт + Playwright) даёт цикл итерации ~15-30 сек vs. ~1-2 сек у Phaser + Vite HMR. На тысячах итераций — дни потерянного времени.

2. Качество генерации кода. GDScript агент знает хуже TypeScript. C# — хорошо, но компиляция добавляет задержку. godot-mcp снимает проблему .tscn-файлов, но не GDScript'а.

Точка пересмотра: если godot-mcp добавит viewport capture (технически реализуемо через Viewport.get_texture().get_image()), разрыв сократится до одного фактора — скорости итерации (HMR vs. перезапуск). На этом этапе Godot + C# (50/70) приблизится к Phaser (64/70) настолько, что выбор станет неоднозначным.

Сегодня — TypeScript + Phaser + browser tools = единственный стек с мгновенным замыканием цикла агентной разработки.

Почему не Pixi.js + bitECS?

Pixi.js — более производительный 2D-рендерер, чем Phaser, с меньшим оверхедом. Раз ECS внешний (bitECS), встроенные системы Phaser частично избыточны. Однако:

• Phaser даёт из коробки: физику (Arcade + Matter.js), камеру с зумом и следованием, систему ввода (клавиатура + мышь + геймпад), Scene Manager, загрузчик ассетов, аудио, tweens, систему частиц. С Pixi.js каждую из этих систем — реализовывать вручную или подбирать отдельную библиотеку.
• Для агентной разработки это критично: каждая дополнительная самописная система — источник багов, которые агент будет долго отлаживать.
• Производительность Phaser достаточна для вертикального среза и alpha. Если на этапе beta рендер станет бутылочным горлышком — миграция рендерера на Pixi.js возможна без переписывания ECS-логики (они уже разделены).

Вердикт: Phaser = скорость разработки. Pixi.js = запасной вариант для оптимизации рендера.

Риски и план действий

Риск	Вероятность	Влияние	Митигация
Потолок производительности браузера — тысячи сущностей с экосимуляцией + фрактальные шейдеры перегружают WebGL/JS	Средняя	Высокое	Web Workers для симуляции. Spatial partitioning. Culling невидимых сущностей. Если не хватит — вынос тяжёлой логики в WASM (Rust → wasm-pack)
Phaser 3 — проект одного разработчика (bus factor)	Низкая	Среднее	Phaser 3 стабилен и feature-complete. При необходимости — миграция рендера на Pixi.js, ECS-логика не затронута
Веб-стек не годится для консолей	Средняя	Среднее	Electron/Tauri для десктопа. Для Switch — потребуется порт (возможно, на этом этапе Godot с импортом логики)
Масштаб химической системы (2000 реакций) нагружает runtime	Низкая	Среднее	Реакции — табличный lookup (O(1)), не симуляция. База в JSON, индексация по реагентам. Узкое место — UI поиска, не вычисления
IndexedDB/localStorage — потолок для мета-прогрессии	Низкая	Низкое	IndexedDB вмещает сотни MB. Для «Синтеза» достаточно. При необходимости — экспорт в файл