VIMP Engine — руководство по созданию игр для LLM
Этот каталог — тонкий мета-слой для языковой модели, которой нужно создать игровой плагин с нуля (так устроен @vimp-games/tanks). Собственного текста контракта здесь нет: контракт описан в документации SDK, а этот слой говорит лишь что читать, в каком порядке и что с этим делать.
Всё, что требует контракт, — имена полей, значения по умолчанию, раскладки байтов, сигнатуры методов — есть в документации SDK. Если утверждение здесь и страница там расходятся, права страница (а код важнее обоих).
Что нужно построить
Игровой плагин: самостоятельный npm-пакет в собственном репозитории, который движок подгружает динамически во время работы. Движку принадлежат сеть, комнаты, раунды, чат, голосования, статистика, обвязка ввода, инфраструктура отрисовки и примитивы физики и кадра. Плагину принадлежат правила: какие есть сущности, как они движутся и сражаются, как выглядят и звучат.
Плагин — это четыре артефакта в одном dist/: хост-плагин (Worker, JS), клиент-плагин (главный поток, JS + PixiJS), WASM-ядро (Rust, обе половины в одном .wasm) и manifest.json с картами, звуками и картинками.
Каждый ресурс игры — ваш. Движок не раздаёт игровых файлов вообще: общей библиотеки тайлов нет, поэтому с самого начала планируйте рисовать или подбирать собственные картинки (maps-and-assets.md).
Порядок чтения
Прочитайте эти страницы, прежде чем что-либо спрашивать у пользователя; числа в них — значения контракта, а не примеры.
| Страница | Зачем |
|---|---|
overview.md | Что вы предоставляете, номера версий, что делает комната, ключевые инварианты |
plugin-api.md | GameManifest, HostPlugin, ClientPlugin, Wasm ABI, версионирование |
game-config.md | Дефолты хоста, игровая половина конфига хоста, клиентский конфиг, форма входа |
snapshot.md | Порты, кадр снапшота и его схема, форматы ввода и меты |
core.md | Rust-крейт, обобщённые трейты, детерминизм, предикция |
host-meta.md | Вызовы в ядро, правила движка, менеджеры и модули |
client-api.md | Цикл отрисовки, части, ClientCore, провайдеры, звук, ввод |
packaging.md | Раскладка пакета, манифест, две сборки Vite, wasm-pack |
maps-and-assets.md | JSON карт, конвейеры картинок и звуков |
scaffolding.md | npm create vimp-game — самое быстрое корректное стартовое дерево |
debugging.md | Headless-раннер, сценарии, проверки инвариантов |
pitfalls.md | Чек-лист всех тихих контрактов |
submitting.md | Публикация в npm и подача игры на платформу |
Процесс
- Прочитайте страницы выше по порядку.
- Проведите интервью с пользователем по
questionnaire.md. Говорите на том языке, на котором пишет пользователь. Спрашивайте блок за блоком, к каждому вопросу предлагайте вариант «как в tanks» и не переспрашивайте то, на что пользователь уже ответил неявно. - Спроектируйте: составьте документ-проект по ответам (в конце опросника есть соответствие ответ → артефакт) и получите подтверждение пользователя до генерации кода.
- Сгенерируйте плагин по
workflow.md: скаффолд → конфиги → Rust-ядро → клиент → тесты → сборка →npm run dev(standalone) →vimp-sim, с матрицей пересборки; затем опубликуйте и подайте игру (submitting.md). - Проверьте: гоняйте headless-раннер (
debugging.md), пока его проверки инвариантов не станут зелёными — текстовый цикл без браузера, — затем пройдитеpitfalls.md, прежде чем объявлять плагин готовым. - Задокументируйте игру: плагин поставляет собственные двуязычные доки, см. «Документация, которую обязан поставлять плагин» в
packaging.md.
Инварианты
- Числа — значения контракта.
ENGINE_API_VERSION = 4,PLAYER_STATE_LEN = 8,WORLD_VOICE_LIMIT = 30, раскладки байтов — плагин не может их менять. Если сгенерированный плагин с ними расходится, неправ плагин. - «Необязательно» — только там, где так сказано в документации SDK. Несколько полей выглядят необязательными, но обязательны; реальное требование указано на страницах.
- Отказ проявляется тишиной. Большинство нарушений не бросают исключений: получается чёрный холст, пропавшая ячейка панели, проигнорированная настройка комнаты, часть, которая так и не создана. Ради этого существуют
pitfalls.mdиvimp-contract. - Не читайте исходники движка и tanks, чтобы узнать контракт. Страниц достаточно; плагин никогда не импортирует код движка по пути.