10bd67c951
- Phaser 3 + bitECS 0.4 + TypeScript + Vite stack - BootScene with title screen - 6 cursor rules (project context, agent workflow, ECS, chemistry, Phaser, data) - Vitest configured with happy-dom - GDD, engine analysis, implementation plan, progress tracking Co-authored-by: Cursor <cursoragent@cursor.com>
329 lines
23 KiB
Markdown
329 lines
23 KiB
Markdown
# Выбор движка для агентной разработки в 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](https://github.com/Coding-Solo/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 # Этот файл
|
||
```
|
||
|
||
### Ключевые зависимости
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"phaser": "^3.80.0",
|
||
"bitecs": "^0.4.0"
|
||
},
|
||
"devDependencies": {
|
||
"typescript": "^5.4.0",
|
||
"vite": "^5.4.0",
|
||
"vitest": "^2.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Дополнительные зависимости** (подключаются по мере необходимости):
|
||
|
||
```json
|
||
{
|
||
"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](https://github.com/Coding-Solo/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. Для «Синтеза» достаточно. При необходимости — экспорт в файл |
|