FOnline Engine

FOnline — открытый движок на C++20 под лицензией MIT для создания сетевых многопользовательских RPG в классическом изометрическом стиле Fallout 1/2/Tactics и Arcanum. Единая кодовая база предоставляет авторитетный сервер, игровой клиент, редактор карт, конвейер контента и упаковку для настольных, мобильных и браузерных платформ. Сама игра остаётся за вами: контент, скрипты и правила находятся в отдельном репозитории, который встраивает движок.

Движок непрерывно развивается с 2006 года и используется многопользовательскими RPG сообщества. Актуальный пример — Last Frontier, постапокалиптическая MMO на его основе.

Почему FOnline?

• Многопользовательская архитектура прежде всего. Это не одиночный движок с добавленной впоследствии сетью: авторитетный сервер, реплицируемое состояние сущностей и разделение клиента и сервера заложены в основу модели сущностей.
• Полный вертикальный стек. Сервер, клиент, mapper, редактор, resource baker, компилятор скриптов, runner тестов и автообновление собираются из одних исходников единым конвейером CMake.
• Чистое разделение движка и игры. Движок остаётся переиспользуемым подмодулем; игра владеет контентом, скриптами, конфигурацией, брендом и политикой выпуска. Обновления движка не переносят в игру его продуктовую политику.
• Контент на основе данных. Прототипы, карты, диалоги, локализация и GUI создаются как текстовые ресурсы и запекаются в runtime-пакеты, удобные для diff, review и инструментов.
• Работает там, где находятся игроки. Нативные Windows, Linux и macOS, Android и iOS, а также WebAssembly-клиент, работающий в браузере через WebSocket.

Основные возможности

Многопользовательское ядро

• Авторитетная серверная среда с менеджерами сущностей, проверкой клиента и защищённым разбором недоверенного клиентского ввода.
• Общая модель сущностей, свойств и прототипов со сгенерированными типобезопасными wrapper свойств и автоматической репликацией клиентам.
• Сменные сетевые транспорты: TCP-сокеты, включая сервер на Asio, WebSocket для браузерной игры, упорядоченный UDP-канал и внутрипроцессный транспорт для тестов и встроенных клиентов.
• Сменные backend постоянного хранения — JSON-файлы, SQLite, MongoDB или память — за единым фасадом базы данных с асинхронной очередью commit и журналами восстановления.
• Встроенное автообновление клиента: тонкий клиентский host, заменяемая runtime, возобновляемая передача файлов и серверный backend обновления.

Скрипты

• Игровые скрипты AngelScript и Managed C# поверх независимой от backend скриптовой системы; Native scripting остаётся зарезервированным placeholder.
• Нативный API экспортируется в скрипты генератором кода из аннотаций ///@: методы, свойства, события, remote call и enum автоматически остаются согласованными с исходниками C++.
• Nullability контролируется на границе скриптов и нативного кода: скриптовый T? соответствует нативным контрактам ptr<T>/nptr<T>, которые проверяются анализаторами и runtime assert.
• Отладка скриптов рядом с нативной отладкой.

Отрисовка и представление

• Backend отрисовки: OpenGL, Direct3D, Vulkan и SDL_GPU, а также headless/null режимы для серверов и CI.
• Эффекты пишутся один раз на GLSL, компилируются через glslang в SPIR-V и переводятся для каждого backend с помощью SPIRV-Cross.
• Изометрические миры на основе спрайтов, 3D-модели персонажей FBX, частицы, видео и звук в современных Ogg/Vorbis и классических форматах Fallout.
• Оконный, безрамочный полноэкранный и виртуальный многооконный режимы клиента с общей моделью разрешения и letterbox; инструменты разработчика на ImGui.

Мир и карты

• Геометрия с шестиугольной и квадратной сеткой и общими функциями расстояния, направления и окрестности.
• Поиск пути, трассировка линий, контексты движения и модель блокировки, рассчитанные на авторитетный многопользовательский сервер.

Конвейер контента и инструменты

• Конвейер запекания превращает авторские прототипы, карты, диалоги, локализованные тексты, эффекты, изображения, модели и скрипты в версионированные пакеты runtime-ресурсов.
• Импорт классических 2D-форматов Fallout FRM, Arcanum ART и других устаревших форматов рядом с PNG/TGA.
• Интерактивные инструменты на самом движке: Mapper с окнами карт и контента и редактированием SPARK, а также отдельные viewer анимаций и запечённых частиц.

Инженерное качество

• Unit-тесты Catch2 со сгенерированными целями отдельных suite, запусками sanitizer и покрытием кода.
• Clang Thread Safety Analysis применяется как -Werror на каждом Clang toolchain; строгие словари smart pointer и nullability проверяются во всей кодовой базе.
• Постоянные stack trace, детерминированные правила exception safety и модель terminate-on-OOM вместо частично изменённого состояния.
• Интеграция Tracy profiler для capture клиента и сервера.

Архитектура в одном взгляде

Your game repository                      FOnline engine (this repo, embedded as Engine/)
────────────────────                      ────────────────────────────────────────────────
content: protos, maps,            ┌──►    Applications — client/server/tool entry points
dialogs, texts, GUI               │       Client & Server runtimes — views vs. authority
AngelScript / C# game logic embeds │      Common model — entities, properties, protos,
.fomain configuration      ───────┤                      maps, networking, config
native extensions                 │       Frontend — windows, input, audio, renderers
CMake presets, CI,                │       Scripting — AngelScript + Managed C# bridges + generated API
release policy                    └──►    Tools & BuildTools — bakers, mapper, editor,
                                                     CMake stages, codegen, packaging

Движок владеет переиспользуемой технологией, а игра — продуктом. Игровой репозиторий добавляет движок как подмодуль Engine/, направляет его стадийный конвейер CMake на собственную конфигурацию и получает именованные проектом цели сборки для каждого приложения. Полная карта слоёв находится в Архитектура движка, а контракт встраивания — в Встраивание FOnline в игровой проект:

GameProject/
├── Engine/                 # this repository as a git submodule
├── CMakeLists.txt          # project entry point that includes engine build logic
├── CMakePresets.json       # project presets and platform variants
├── GameName.fomain         # master project configuration
├── Scripts/                # game AngelScript or Managed C# modules
├── SourceExt/              # optional project-native C++ extensions
├── Critters/ Items/ Maps/  # game content and prototypes
└── Dialogs/ Texts/         # dialogs and localization

Начало работы

• Запустите первый проект движка: Первый headless-проект FOnline — сконфигурируйте, соберите, запеките, запустите, проверьте и остановите минимальный headless-сервер.
• Изучите канонический scaffold: Examples/MinimalProject/README.ru.md — полный проект и контракт smoke-проверки CI.
• Изучите исполняемую галерею контента: Examples/ContentShowcase/README.ru.md — исходные материалы, baking, native/Web-проверки, происхождение, бюджеты и воспроизводимые доказательства захвата.
• Соберите первый игровой срез: первый игровой клиент, первое изменение контента и первый автоматизированный тест — подключите клиент, измените локализованный контент и расширьте исполняемые проверки.
• Настройте и сопровождайте проект: Конфигурация игрового проекта, Generated Content Workflow и руководство по обновлению Engine — владение .fomain, пакетами ресурсов, сгенерированными результатами, миграциями и обновлениями Engine.
• Доказательно выбирайте release-цели: матрица поддержки и сгенерированная матрица — различайте возможности исходников, обязательные сборки, process smoke и квалификацию проекта или устройства.
• Планируйте и проверяйте публичные примеры: Публичные репозитории с примерами и сгенерированный реестр — владение, точные Engine pin, compatibility lane, шаблон репозитория, поддержка и происхождение ресурсов.
• Просматривайте сгенерированный нативный API: Docs/ru/reference/script-api/index.md — методы, свойства, события, типы, настройки, миграции и ссылки на исходники.
• Создавайте прототипы: Формат прототипов и сгенерированный справочник — точный синтаксис, наследование, встроенные свойства, ссылки, миграции и проверка.
• Создавайте карты: Docs/ru/how-to/content/map-format.md и сгенерированный справочник — секции .fomap, placement ID, владение, нормализация Mapper, запекание по сторонам и загрузка во время выполнения.
• Создавайте локализованный текст: Текст и локализация и сгенерированный справочник — синтаксис .fotxt, нормализация языков, $Text прототипов, runtime lookup, цветовые теги и граница игрового форматирования.
• Создавайте изображения и sprite sheet: форматы изображений и спрайтов и сгенерированный справочник — PNG/TGA и устаревший импорт, композиция FOFRM, запекание, runtime factory, атласы, cache и проверка.
• Создавайте shader-эффекты: Effect Format и сгенерированный справочник — секции .fofx, проходы, render state, shader resources, результаты backend, runtime selection и скриптовые значения.
• Создавайте частицы: Формат и исполнение частиц и сгенерированный справочник — выбор SPARK/Effekseer, авторинг .spark/.efkproj, запекание .spk/.efk, инструменты Mapper, runtime route и интеграция с моделями и скриптами.
• Создавайте bitmap-шрифты и раскладывайте текст: форматы шрифтов и компоновка текста и сгенерированный справочник - дескрипторы FOFNT/BMFont, привязка slot, масштабирование, измерение, перенос, флаги отрисовки, цвета и проверка.
• Изучайте контракты интеграции проекта: справочник CMake, справочник BuildTools CLI, справочник helper CLI, справочник нативных расширений, справочник пакетов и реестр публичных примеров — точные поверхности CMake, основного и вспомогательного BuildTools, нативных расширений, упаковки и программы примеров.
• Безопасно добавляйте нативный C++ проекта: Нативные расширения — роли исходников, хуки, экспорт в скрипты, владение состоянием, совместимость и исполняемая проверка.
• Просматривайте сгенерированный интерфейс CMake: Docs/ru/reference/cmake/index.md — опции проекта, строгие стадии и hook, выбранные helper, значения по умолчанию и ссылки на исходники.
• Измеряйте производительность клиента и сервера: Профилирование — режимы сборки Tracy, изолированные границы capture, воспроизводимые нагрузки и сопоставимый анализ результатов.
• Публикуйте документацию: руководство по публикации сайта — сгенерированные navigation/search/route, rolling version и locale policy, локальный Jekyll preview, проверка rendered route и доступности, артефакты CI и существующий GitHub Pages маршрут fonline.ru.
• Используйте документацию для AI и offline: llms.txt, llms-full.txt и docs-manifest.json — сгенерированные маршруты, ограниченный контекст, canonical/source URL, provenance и хэши контента из того же Markdown-манифеста.
• Если вы впервые знакомитесь с движком: Начало работы — первый маршрут: что читать, что собирать и кому что принадлежит.
• Если вы начинаете или изучаете игровой проект: Встраивание FOnline в игровой проект — ожидаемая структура репозитория и правила владения.
• Если вы собираете проект: Процесс сборки — предварительные требования, пресеты и стратегия проверки. Обычно сборка запускается из встраивающего игрового репозитория, а не из checkout движка.
• Инструкции для AI-сопровождения: AGENTS.md — прочитайте перед изменением кода или документации движка.

FOnline имеет профили сборки для Windows, Linux, macOS, Android, iOS и WebAssembly, но поддержка ограничена доказательствами. Сверяйтесь с матрицей поддержки: cross-build или headless smoke не квалифицирует renderer, устройство, пакет, сервис или маршрут магазина.

Структура репозитория

• Source/ — исходники движка: точки входа Applications/, runtime клиента и сервера, общая модель Common/, платформенный и render-слой Frontend/, bridge скриптов, baker и редакторы Tools/, низкоуровневое ядро Essentials/, unit-тесты Tests/.
• BuildTools/ — стадийный конвейер CMake, генерация кода, платформенные toolchain, подготовка workspace и пакетов.
• Resources/ — принадлежащие движку runtime и build resources.
• ThirdParty/ — поставляемые зависимости SDL, AngelScript, Asio, ImGui, glslang, SPIRV-Cross, Tracy и другие; процесс сопровождения описан в разделе Сопровождение ThirdParty.
• Docs/ — сопровождаемая документация движка.

Документация

Сопровождаемый индекс — Docs/ru/index.md. Подробные руководства по темам:

Когда поведение заметно меняется, документ-владелец обновляется в том же изменении. Документация сопровождается как основанный на исходниках справочник, а не как запоздалое дополнение.

Проект и сообщество

• Сайт: https://fonline.ru
• GitHub: https://github.com/cvet/fonline
• Лицензия: MIT