149 lines
18 KiB
Markdown
149 lines
18 KiB
Markdown
# EBLAN ENGINE 3D
|
||
|
||
> **Выделенный независимый модульный игровой 2.5D движок на чистом x86 Ассемблере (MASM32)**
|
||
> Разработан для удобного создания ретро-игр (Wolfenstein 3D / Doom style) и комфортной совместной разработки с AI-агентами.
|
||
|
||
---
|
||
|
||
## ⚡ Особенности
|
||
- **100% чистый ассемблер (x86 MASM32)**: без сторонних зависимостей, DirectX, OpenGL или C-рантаймов.
|
||
- **Программный рендеринг (Software DIBits Raycaster)**:
|
||
- 320x240 внутренний буфер кадра, масштабируемый до 1280x960 через `StretchDIBits`.
|
||
- DDA-трассировка лучей (320 лучей на кадр, угол обзора ~67.5°).
|
||
- Текстурирование стен (128x128 32-bit BGRA).
|
||
- Коррекция эффекта рыбьего глаза (fish-eye correction).
|
||
- Глубинное затенение (дистанционный туман) и раздельное затенение граней стен для объема.
|
||
- Поддержка трехмерных билборд-спрайтов: текстурирование, сортировка far-to-near, z-буферизация (`depthBuffer`), хромакей-прозрачность, масштаб.
|
||
- **Процедурные текстуры из коробки**: генерируются на лету при старте (кирпич, дерево, камень, металл, двери, колонны, стекло, мрамор) — движок работает автономно без внешних файлов.
|
||
- **Внешний пак текстур (опционально)**: `assets/textures/texturepack.bin` (16 слотов 128×128 BGRA + заголовок `EBTX`) перекрывает процедурные. Генерация из атласа KAZIK: `python tools\make_texturepack.py`.
|
||
- **Интерактивная карта и физика**:
|
||
- Сетка 32x32, гладкое скольжение вдоль стен при столкновениях.
|
||
- Интерактивные двери (открытие/закрытие по клавише `E`).
|
||
- Перемещение на `W`/`A`/`S`/`D` (включая стрейф в стороны) + спринт на `Shift`.
|
||
- Поворот камеры на `Стрелочки влево/вправо`.
|
||
- **2D UI Оверлей и Радар**:
|
||
- Встроенный растровый шрифт 8x8 (вывод строк, чисел с тенью).
|
||
- Топ-даун радар/миникарта с отображением игрока, конуса взгляда и стен (переключение на `M`).
|
||
- Счетчик FPS со стабильным 60 FPS локером (`timeBeginPeriod`).
|
||
|
||
---
|
||
|
||
## 🚀 Быстрый старт и сборка
|
||
|
||
### Сборка одной командой
|
||
Запустите файл `build.bat`:
|
||
```cmd
|
||
build.bat
|
||
```
|
||
Скрипт автоматически найдет установленный MASM32 (в `D:\MASM32`, `C:\masm32`, `F:\MASM32`) или MSVC BuildTools (`ml.exe` и `link.exe`) и соберет исполняемый файл `engine.exe`.
|
||
|
||
### Запуск
|
||
```cmd
|
||
engine.exe
|
||
```
|
||
|
||
---
|
||
|
||
## 🎮 Управление в демо-уровне
|
||
| Клавиша | Действие |
|
||
|---|---|
|
||
| **W / S** | Движение вперед / назад |
|
||
| **A / D** | Стрейф (шаг) влево / вправо |
|
||
| **Стрелочки влево / вправо** | Поворот камеры |
|
||
| **Shift** | Спринт (ускорение) |
|
||
| **E / Пробел** | Взаимодействие (открыть/закрыть дверь перед собой) |
|
||
| **M** | Включить/выключить миникарту (радар) |
|
||
| **C** | Запустить или повторить кат-сцену текущей карты |
|
||
| **Tab** | Пропустить кат-сцену |
|
||
| **Escape** | Выход из игры |
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 🎨 Визуальный редактор уровней (EblanStudio)
|
||
|
||
Движок оснащен нативным высокопроизводительным визуальным редактором уровней в стиле Unity / Godot 4:
|
||
- Написан на **C++17 + Dear ImGui + DirectX 11**.
|
||
- Запуск в 1 клик через `run_editor.bat` или `editor/editor.exe`.
|
||
- **Мгновенный плейтест (F5)**: редактор создаёт временную копию связанных карт и ресурсов и запускает `engine.exe` с выбранной стартовой картой. Несохранённые изменения попадают в копию; исходные карты и путь текущего файла не меняются.
|
||
- **Undo/Redo (Ctrl+Z / Ctrl+Y)** — история до 64 действий (сетка, спавн, цвета, спрайты).
|
||
- **Кат-сцены (F6)** — таймлайн камеры, поворотов, субтитров, WAV, затемнений и переходов. Правки сцены также поддерживают Undo/Redo.
|
||
- **Игровой вид в редакторе** — режимы «Рядом», «Игровой вид» и «Карта». Изображение рисует тот же ASM-рендерер, что и игра; изменения стен, спрайтов, цветов и импортированных текстур видны без F5. Кликните по игровому виду для осмотра: WASD, стрелки, Shift; правая кнопка мыши поворачивает камеру. Обзор не меняет спавн или ключи кат-сцены.
|
||
- **Файловые диалоги Windows**: Ctrl+O (открыть), Ctrl+S (сохранить), Ctrl+Shift+S (сохранить как).
|
||
- Инструменты:
|
||
- **Кисть [B]**: рисование стен выбранного типа (Кирпич, Дерево, Камень, Металл, Дверь, Колонна, Стекло, Мрамор).
|
||
- **Ластик [E]**: очистка ячеек карты (или ПКМ на холсте).
|
||
- **Заливка [F]**: Flood Fill замкнутых областей карты.
|
||
- **Точка спавна игрока [P]**: клик для перемещения спавна игрока и ползунок угла обзора.
|
||
- **Спрайты [S]**: расстановка трехмерных объектов/билбордов (фонари, бочки, статуи), перетаскивание мышью по холсту.
|
||
- **Инспектор спрайтов**: позиция (суб-тайл), слот текстуры (1..15), масштаб (0.25x-4x), удаление.
|
||
- **Инспектор свойств**: настройка цветов потолка и пола в реальном времени, угла старта.
|
||
- **Навигация**: масштабирование колесиком мыши (Zoom), панорамирование зажатием средней кнопки мыши (MMB Pan).
|
||
|
||
Сборка редактора:
|
||
```cmd
|
||
cd editor
|
||
build_editor.bat
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Структура проекта
|
||
- `main.asm` — точка входа, цикл сообщений Win32, таймер 60 FPS, оркестрация кадра.
|
||
- `run_editor.bat` — запуск визуального редактора EblanStudio.
|
||
- `editor/` — исходники и билд-скрипт визуального C++ Dear ImGui редактора.
|
||
- `editor/src/level_format.h` — бинарный протокол карты (`EBLN`).
|
||
- `editor/src/editor_app.h` / `editor_app.cpp` — логика UI, холста, палитры, спавнов и запуска плейтеста.
|
||
- `editor/src/main.cpp` — DirectX 11 окно и интеграция Dear ImGui.
|
||
- `editor/build_editor.bat` — компиляция редактора через MSVC BuildTools.
|
||
- `include/engine_defs.inc` — размеры экрана, константы углов, цвета, коды клавиш, структуры.
|
||
- `include/engine_data.inc` — видеобуфер `screenBuffer`, z-буфер, координаты игрока, сетка карты, текстуры.
|
||
- `include/engine_math.inc` — генератор таблиц синусов/косинусов через FPU, RNG, 16.16 math.
|
||
- `include/engine_map.inc` — хранилище карты, загрузчик `assets/map.dat`, коллизии, двери.
|
||
- `include/engine_textures.inc` — встроенный процедурный генератор текстур стен.
|
||
- `include/engine_input.inc` — опрос клавиатуры через `GetAsyncKeyState`.
|
||
- `include/engine_physics.inc` — физика игрока, стрейф, скольжение по стенам.
|
||
- `include/engine_raycaster.inc` — ядро лучевого 2.5D рендера и отрисовка спрайтов.
|
||
- `include/engine_render2d.inc` — примитивы (DrawPixel, Rect, Outline), шрифт 8x8, миникарта.
|
||
- `include/font8x8.inc` — битовые маски ASCII-символов.
|
||
- `AGENTS.md` — подробное руководство для AI-агентов по написанию новых игр на этом движке.
|
||
|
||
|
||
## Переходы и проверка первых трёх этапов
|
||
|
||
Карты новых сохранений используют EBLN v5; существующие v1/v2/v3/v4 продолжают читаться. Связанные `.dat` лежат в одной папке. В портале задаётся ASCII-имя файла до 31 символа, целевой спавн, угол и затемнение. На карту доступно до 16 переходов. Заливка учитывает этот лимит целиком; удаление клетки удаляет её триггер. Чёрный пол и потолок поддерживаются.
|
||
|
||
Порталы имеют отдельную текстуру и не занимают слот фонаря. Первый импорт изображения создаёт недостающие папки и пакет со стандартными текстурами в остальных слотах. Повреждённый пакет не перезаписывается импортом; ошибка показывается в строке состояния. Неудачный переход сохраняет текущую комнату и показывает сообщение в игре.
|
||
|
||
Проверки без изменения карт проекта:
|
||
```cmd
|
||
python tools\test_regressions.py
|
||
```
|
||
Для сохранения тестовых кадров добавьте `--keep`. Нужны MASM32, MSVC BuildTools и Windows SDK.
|
||
|
||
## Кат-сцены: этапы 4 и 5
|
||
|
||
В EblanStudio нажмите **F6** и добавьте команды кнопками таймлайна. Для движения камеры укажите точку на карте и длительность в кадрах (60 кадров = секунда). Поворот, движение, субтитры и затемнение можно запускать одновременно. Ромбы перетаскиваются по времени; список «Команда» позволяет выбрать события с одинаковым временем. Параметры выбранной команды редактируются справа. Конец сцены добавляется автоматически.
|
||
|
||
«При входе» включает автозапуск после загрузки комнаты. Кнопка «Предпросмотр» и ползунок кадра показывают пролёт в игровом виде редактора, включая субтитры, чёрные полосы и затемнение. На карте одновременно видна траектория. Выбор «Камера сцены» возвращает вид к таймлайну после свободного осмотра. **F5** запускает полную игру с временной копией карт и звуков. Для команды перехода сначала создайте портал, затем выберите его в инспекторе. WAV можно импортировать через меню ассетов; имя файла должно быть ASCII.
|
||
|
||
Камера движется линейно между точками, поворачивается по кратчайшей дуге и во время пролёта проходит сквозь стены. Конечные точки должны лежать в свободных клетках. Доступна одна сцена на карту, до 128 команд и 32 строк по 95 символов CP1251. На экране помещаются 3 строки субтитров по 38 символов. Звуки используют один канал: новый WAV заменяет предыдущий, завершение или пропуск сцены останавливает его. Tab возвращает управление в текущей точке камеры.
|
||
|
||
Готовый пример: [examples/cutscene_demo/README.md](examples/cutscene_demo/README.md). После сборки запустите `examples\cutscene_demo\run_demo.bat`: вступление с русскими субтитрами, WAV и затемнением переводит камеру во вторую комнату. Пример хранится отдельно от основных карт проекта.
|
||
|
||
Предпросмотр останавливается на команде перехода в другую комнату; цепочка комнат и игровой ввод проверяются через F5. F5/F6 работают при фокусе интерфейса и текстовых полей. Ошибка запуска показывается отдельным сообщением. При старте редактор открывает карту проекта относительно своего файла, поэтому запуск из другой рабочей папки не ломает пути.
|
||
|
||
Формат v5 и параметры команд описаны в [AGENTS.md](AGENTS.md) и [архитектуре движка](docs/ENGINE_ARCHITECTURE.md). Сценарии регрессии также проверяют сохранение/загрузку трека, повреждённые команды, Undo/Redo, упаковку WAV для F5, горячие клавиши при фокусе в интерфейсе, покадровое совпадение состояния C++ с ASM, передачу кадров в DX11 и точное совпадение пикселей игрового вида с движком. Перед запуском проверок соберите `engine.exe` через `build.bat`.
|
||
|
||
## Постоянный и динамический свет
|
||
|
||
В палитре выберите «+ Источник света» и поставьте его на карте. Источники доступны также в дереве сцены. В инспекторе задайте тип, цвет, радиус, яркость, тени и мерцание; работают перемещение, копирование, удаление и Undo/Redo.
|
||
|
||
- **Постоянный**: выберите тип «Постоянный (запекание)», затем нажмите «Запечь постоянный свет». RGB-освещение и тени сохраняются в карте. После изменения геометрии, фонового света или постоянного источника инспектор покажет, что нужно запечь заново. При сохранении и F5 это происходит автоматически.
|
||
- **Динамический**: выберите точечный или пульсирующий источник и режим «Запечённый + динамический». Перемещение, цвет, яркость и мерцание сразу влияют на игровой вид. Перезапекать постоянный свет при этом не нужно.
|
||
- **Режимы**: «Без освещения», «Только запечённый», «Запечённый + динамический». Фоновый свет и параметры фонарика настраиваются в разделе «Освещение карты» инспектора. В игре F переключает фонарик, L — режим света.
|
||
|
||
До 13 источников карты; фонарик, вспышки оружия и взрывов используют отдельные места. Закрытые двери и стены перекрывают динамический свет. Статические тени остаются результатом последнего запекания. Цвета стен и спрайтов освещаются по RGB; освещение плоских потолка/пола берётся в точке камеры. Запечённая карта имеет разрешение 32×32 ячейки.
|
||
|
||
Новые сохранения используют EBLN v5. Старые карты сохраняют прежний вид без освещения, пока вы не добавите источники и не включите нужный режим. Свет каждой комнаты сохраняется независимо. Перед экспортом игры сохраните карты.
|