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:

build.bat

Скрипт автоматически найдет установленный MASM32 (в D:\MASM32, C:\masm32, F:\MASM32) или MSVC BuildTools (ml.exe и link.exe) и соберет исполняемый файл engine.exe.

Запуск

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).

Сборка редактора:

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 переходов. Заливка учитывает этот лимит целиком; удаление клетки удаляет её триггер. Чёрный пол и потолок поддерживаются.

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

Проверки без изменения карт проекта:

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\run_demo.bat: вступление с русскими субтитрами, WAV и затемнением переводит камеру во вторую комнату. Пример хранится отдельно от основных карт проекта.

Предпросмотр останавливается на команде перехода в другую комнату; цепочка комнат и игровой ввод проверяются через F5. F5/F6 работают при фокусе интерфейса и текстовых полей. Ошибка запуска показывается отдельным сообщением. При старте редактор открывает карту проекта относительно своего файла, поэтому запуск из другой рабочей папки не ломает пути.

Формат v5 и параметры команд описаны в AGENTS.md и архитектуре движка. Сценарии регрессии также проверяют сохранение/загрузку трека, повреждённые команды, Undo/Redo, упаковку WAV для F5, горячие клавиши при фокусе в интерфейсе, покадровое совпадение состояния C++ с ASM, передачу кадров в DX11 и точное совпадение пикселей игрового вида с движком. Перед запуском проверок соберите engine.exe через build.bat.

Постоянный и динамический свет

В палитре выберите «+ Источник света» и поставьте его на карте. Источники доступны также в дереве сцены. В инспекторе задайте тип, цвет, радиус, яркость, тени и мерцание; работают перемещение, копирование, удаление и Undo/Redo.

• Постоянный: выберите тип «Постоянный (запекание)», затем нажмите «Запечь постоянный свет». RGB-освещение и тени сохраняются в карте. После изменения геометрии, фонового света или постоянного источника инспектор покажет, что нужно запечь заново. При сохранении и F5 это происходит автоматически.
• Динамический: выберите точечный или пульсирующий источник и режим «Запечённый + динамический». Перемещение, цвет, яркость и мерцание сразу влияют на игровой вид. Перезапекать постоянный свет при этом не нужно.
• Режимы: «Без освещения», «Только запечённый», «Запечённый + динамический». Фоновый свет и параметры фонарика настраиваются в разделе «Освещение карты» инспектора. В игре F переключает фонарик, L — режим света.

До 13 источников карты; фонарик, вспышки оружия и взрывов используют отдельные места. Закрытые двери и стены перекрывают динамический свет. Статические тени остаются результатом последнего запекания. Цвета стен и спрайтов освещаются по RGB; освещение плоских потолка/пола берётся в точке камеры. Запечённая карта имеет разрешение 32×32 ячейки.

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