Подробный гайд: установка, настройка и разработка на QuakeForge

QuakeForge — современный open-source движок на базе Quake: Vulkan, OpenGL, Lua-скриптинг, моддинг и создание игр

Подробный гайд: установка, настройка и разработка на QuakeForge

Примечание:

QuakeForge — это активный open-source форк оригинального движка id Tech 1 (Quake). Он сохраняет архитектуру оригинала, но добавляет современные рендереры (OpenGL 3.3+/Vulkan), улучшенный сетевой стек, Lua-скриптинг, модульную структуру и инструменты для моддинга. Движок действительно развивается в сторону более универсальной платформы, но на текущий момент (2026) остаётся специализированным на FPS-логике и наследии Quake. Гайд охватывает установку, базовую работу, создание модов и стратегию расширения движка под свои задачи.

1. Подготовка и системные требования

Минимальные требования

ОС: Windows 10/11, Linux (x86_64), macOS 12+
CPU: x86_64, 2 ядра
RAM: 2 ГБ
GPU: Поддержка OpenGL 3.3 или Vulkan 1.1
Место: ~500 МБ (исходники + данные)

Зависимости для сборки из исходников

Платформа	Пакеты
Ubuntu/Debian	`build-essential cmake git libsdl2-dev libgl-dev libpng-dev libjpeg-dev libopenal-dev zlib1g-dev`
Fedora/RHEL	`@development-tools cmake git SDL2-devel mesa-libGL-devel libpng-devel libjpeg-turbo-devel openal-soft-devel zlib-devel`
macOS	`brew install cmake sdl2 libpng jpeg openal-soft`
Windows	MSVC 2019+/MinGW-w64, CMake, vcpkg или MSYS2 с пакетами `mingw-w64-x86_64-{sdl2,libpng,libjpeg,openal}`

Легальное использование данных

Движок не включает файлы оригинального Quake.

Вам потребуются:

pak0.pak, pak1.pak, pak2.pak (из Steam/GOG/Shareware)
Или бесплатные ресурсы из открытых архивов (например, quake1-shareware)

2. Установка

Вариант А: Готовые сборки (рекомендуется для быстрого старта)

Перейдите на GitHub Releases - github.com/QuakeForge/quakeforge/releases
Скачайте архив для вашей ОС (quakeforge-<version>-win64.zip, linux-x86_64.tar.gz и т.д.)
Распакуйте в удобную папку (например, C:\Games\QuakeForge или ~/QuakeForge)
Поместите pak*.pak в подпапку data/ или ~/.quakeforge/

Вариант Б: Компиляция из исходников

# 1. Клонирование репозитория
git clone https://github.com/QuakeForge/quakeforge.git
cd quakeforge

# 2. Создание директории сборки
mkdir build && cd build

# 3. Конфигурация CMake
cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DQF_RENDERER=gl \
         -DQF_ENABLE_LUA=ON \
         -DQF_ENABLE_VULKAN=OFF \
         -DQF_INSTALL_PREFIX=/usr/local

# 4. Компиляция
make -j$(nproc)  # Linux/macOS
# или cmake --build . --config Release  # Windows

# 5. Установка (опционально)
sudo make install

Совет:

Для отладки используйте -DCMAKE_BUILD_TYPE=Debug и флаг -DQF_DEBUG=ON.

3. Настройка и первый запуск

Структура директорий

quakeforge/
├── bin/          # бинарные файлы
├── data/         # pak-файлы, карты, модели
├── mods/         # пользовательские моды
├── config/       # конфиги
└── logs/         # qf.log, crash dumps

Запуск

# Linux/macOS
./quakeforge

# Windows
qf.exe

При первом запуске создастся ~/.quakeforge/config.cfg (или %APPDATA%\QuakeForge\).

Полезные параметры командной строки

Параметр	Описание
`-game mymod`	Загрузить мод из `mods/mymod/`
`-width 1920 -height 1080`	Разрешение
`-fullscreen`	Полный экран
`-renderer vulkan`	Использовать Vulkan (если включён при сборке)
`-condebug`	Вывод консоли в файл `qf_con.log`
`-dedicated`	Запуск выделенного сервера

Управление в игре

~ → открыть/закрыть консоль
Esc → главное меню
map e1m1 → загрузка карты
god, noclip, notarget → отладочные режимы
exec autoexec.cfg → выполнение пользовательского конфига

4. Основы работы с движком

Архитектура

QuakeForge разделён на модули:

client → графика, звук, ввод, HUD
server → логика игры, физика, сетевой код
game → сущности, правила, скрипты
common → утилиты, математика, файловый ввод-вывод

Консоль и переменные

set r_fullscreen 1
set sv_maxclients 8
bind g "god"
showstats  # FPS, память, сетевая статистика

Все переменные сохраняются в config.cfg. Для сброса: unbindall; exec default.cfg.

Логирование и отладка

Файл: ~/.quakeforge/qf.log
Уровни: 0 (ошибки), 1 (предупреждения), 2 (инфо), 3 (отладка)
Включение: set log_level 3 + перезапуск

5. Создание модификаций (пошагово)

5.1. Структура мода

mods/my_mod/
├── pak0.pak          # сжатый архив ресурсов
├── maps/             # .bsp файлы
├── models/           # .mdl, .md3
├── scripts/          # .lua файлы
├── sound/            # .wav, .ogg
└── config.cfg        # настройки мода

5.2. Компиляция карт

Используйте NetRadiant, GtkRadiant или TrenchBroom
Экспортируйте в .map → скомпилируйте через qbsp, vis, light
Поместите .bsp в mods/my_mod/maps/

5.3. Lua-скриптинг (современный подход)

QuakeForge поддерживает Lua 5.4 для игровой логики.

Пример `scripts/game.lua`:

-- Регистрация хука на спавн игрока
hook.Register("PlayerSpawn", function(player)
    player.health = 100
    player.armor = 0
    console.Print("Игрок заспавнен с ID: " .. player.id)
end)

-- Кастомная команда
cmd.Register("myweapon", function(player)
    player.giveWeapon("rocket_launcher")
end)

Загрузка скриптов: добавьте lua_load scripts/game.lua в autoexec.cfg мода.

5.4. Замена QuakeC на Lua

Старые .qc файлы всё ещё поддерживаются, но Lua предпочтительнее для новой логики
Lua API покрывает: работу с сущностями, триггеры, UI, сетевые события, таймеры
Документация: help lua в консоли или QuakeForge Lua API Reference - github.com/QuakeForge/quakeforge/wiki/Lua-API

5.5. Тестирование мода

./quakeforge -game my_mod +map my_map

Консоль: status (список игроков), listmodels, lua_eval print("test")
Горячие клавиши: F5 (сохранить), F9 (загрузить) в отладочных сборках

6. Движение в сторону универсального движка

QuakeForge действительно обладает потенциалом для расширения, но требует осознанного подхода:

Сильные стороны

Открытый C/C++ код с чистой модульной архитектурой
Кроссплатформенность (SDL2, CMake, Vulkan/GL)
Lua-скриптинг с горячей перезагрузкой (lua_reload)
Сетевой код с поддержкой демозаписей и античита
Совместимость с тысячами существующих карт/модов

Ограничения наследия

Лимит сущностей: ~1024 (можно увеличить патчем, но требует переработки памяти)
256-цветная палитра по умолчанию (обходится через современные текстуры + рендерер)
Фиксированный пайплайн BSP (не подходит для динамических открытых миров)
Отсутствие встроенного WYSIWYG-редактора

Как расширять движок

Замена подсистем: Рендерер (renderer/), физика (physics/), аудио (sound/) изолированы → можно подключать современные аналоги
ECS-компоненты: Внедрение Entity-Component-System поверх сущностей Quake (примеры в репозитории quakeforge-ecs)

3. Интеграция с внешними инструментами:

Blender + io_export_quake плагин → экспорт .mdl/.md3
ImGui → встраиваемый редактор уровней/настроек
LuaRocks → управление зависимостями скриптов

Сборка под новые платформы: Android/iOS через SDL2 + CMake (требует патчей на ввод/аудио)

Реалистичный совет:

QuakeForge отлично подходит для стилизованных инди-игр, кооперативных шутеров, ретро-ремейков и экспериментальных проектов. Для AAA-масштаба или сложных 3D-миров рассмотрите переход на Godot/Unreal после прототипирования на QF.

7. Ресурсы и сообщество

Ресурс	Ссылка
Официальный репозиторий	github.com/QuakeForge/quakeforge
Wiki & документация	github.com/QuakeForge/quakeforge/wiki
IRC	`#quakeforge` на Libera.Chat
Гайды по моддингу	QuakeWiki, ModDB, GitHub Discussions
Примеры модов	`mods/example_lua/`, `mods/coop_demo/` в репозитории

Полезные утилиты

qcc64 → современный компилятор QuakeC/Lua-биндингов
paktool → создание/распаковка .pak
qfmodelconv → конвертация .mdl → .obj/.gltf
qfbench → бенчмарк рендерера и сети

8. Заключение

QuakeForge — это не просто «запускатель старого Quake», а живая платформа, сочетающая ностальгию с современными инструментами разработки.

При грамотном использовании он позволяет:

Быстро прототипировать FPS-механики
Создавать кроссплатформенные моды с Lua
Интегрировать современные графические и звуковые подсистемы
Постепенно наращивать функционал до уровня небольшого игрового движка