Архитектура C++ проектов: Создание редактора уровней на Raylib

Основы организации: файловая структура, CMake и разделение на модули

Добро пожаловать в курс «Архитектура C++ проектов: Создание редактора уровней на Raylib». Вы здесь, потому что хотите перестать писать «спагетти-код» и научиться создавать инструменты, которые не стыдно показать коллегам и удобно поддерживать самому.

Многие начинающие разработчики сталкиваются с одной и той же проблемой: проект начинается с одного файла main.cpp. Затем появляется player.cpp, потом enemy.cpp, и внезапно папка проекта превращается в свалку из десятков файлов, в которых невозможно ориентироваться. Когда вы пытаетесь написать редактор уровней — инструмент сложный и требующий строгой логики — такой хаос становится фатальным.

В этой статье мы заложим фундамент вашего будущего редактора. Мы не напишем ни строчки игровой логики сегодня, но мы сделаем кое-что более важное: создадим профессиональный каркас проекта.

Почему структура важна?

Представьте, что вы строите дом. Если вы свалите кирпичи, доски и цемент в одну кучу, дом построить не получится. В программировании то же самое. Хорошая структура проекта обеспечивает:

1. Масштабируемость: Добавление новых фич не ломает старые.
2. Читаемость: Вы (и другие) знаете, где искать конкретный код.
3. Переносимость: Проект легко собрать на Windows, Linux или macOS.

Стандартная файловая структура C++ проекта

В индустрии сложился определенный стандарт организации папок. Мы будем придерживаться современной структуры, разделяющей исходный код, заголовки и сторонние библиотеки.

Разберем назначение каждой директории:

• src/ (Source): Здесь лежат файлы реализации с расширением .cpp. Это «мясо» вашего проекта.
• include/ (Include): Здесь хранятся заголовочные файлы .h или .hpp. Это публичный интерфейс ваших модулей.
• external/ или libs/: Место для сторонних библиотек (в нашем случае здесь будет жить Raylib).
• assets/: Ресурсы игры — текстуры, звуки, шрифты и файлы конфигурации.
• build/: Папка для артефактов сборки. Мы никогда не коммитим её в git, так как она содержит временные файлы компилятора.

Хорошая архитектура — это не когда нечего добавить, а когда нечего убрать, и при этом всё лежит на своих местах.

Система сборки: Почему CMake?

Вы упомянули, что хотите «нормальную структуру». В мире C++ это практически синоним использования CMake. Это мета-система сборки, которая генерирует инструкции для нативной системы сборки вашей ОС (Makefile для Linux, Solution для Visual Studio, Project для Xcode).

Базовый CMakeLists.txt

В корне вашего проекта всегда должен лежать файл CMakeLists.txt. Вот минимальный шаблон для нашего редактора:

cmake_minimum_required(VERSION 3.14)

# Название проекта и язык
project(RaylibLevelEditor VERSION 1.0 LANGUAGES CXX)

# Указываем стандарт C++ (C++17 — золотая середина для геймдева сейчас)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Добавляем папку с исходниками
add_subdirectory(src)

# Создаем исполняемый файл
add_executable(RaylibLevelEditor src/main.cpp)

Однако, просто создать файл недостаточно. Нам нужно подключить библиотеку Raylib.

Интеграция Raylib через CMake

Есть много способов подключить библиотеку: скачать бинарники, использовать git submodules или пакетные менеджеры (Conan, Vcpkg). Для учебного проекта самым надежным и простым способом является FetchContent. Это модуль CMake, который сам скачает исходники Raylib и подключит их к проекту при первой сборке.

Обновим наш CMakeLists.txt:

cmake_minimum_required(VERSION 3.14)
project(RaylibLevelEditor VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# --- Подключение Raylib ---
include(FetchContent)
FetchContent_Declare(
    raylib
    GIT_REPOSITORY https://github.com/raysan5/raylib.git
    GIT_TAG master
)
FetchContent_MakeAvailable(raylib)
# --------------------------

# Настройка путей к заголовкам
include_directories(include)

# Собираем все .cpp файлы из папки src
file(GLOB_RECURSE SOURCES "src/*.cpp")

add_executable(RaylibLevelEditor ${SOURCES})

# Линкуем (связываем) нашу программу с raylib
target_link_libraries(RaylibLevelEditor PRIVATE raylib)

Что здесь происходит?

1. FetchContent_Declare: Мы говорим CMake, откуда скачать Raylib.
2. FetchContent_MakeAvailable: CMake скачивает, настраивает и готовит библиотеку к использованию.
3. target_link_libraries: Мы говорим компилятору: «Когда будешь собирать наш редактор, используй код из Raylib».

Разделение на модули: Отказ от монолита

Главная ошибка при создании редакторов — писать код игры и код редактора вперемешку. Редактор уровней — это программа, которая использует движок вашей игры, но также имеет свой собственный интерфейс (UI).

Мы разделим проект на три логических слоя:

1. Core (Ядро): Обертки над Raylib, управление окном, входными данными (Input), ресурсами. Этот код ничего не знает об игре.
2. Game (Игра): Логика сущностей, физика, рендеринг игрового мира. Этот код использует Core.
3. Editor (Редактор): UI инструменты, панели выбора тайлов, сетка, сохранение/загрузка. Этот код управляет Game и использует Core.

Пример организации кода

Вместо того чтобы писать всё в main.cpp, мы создадим класс приложения.

Файл include/app.h:

#pragma once

class App {
public:
    void Run();

private:
    void Update();
    void Draw();
    void Load();
};

Файл src/app.cpp:

#include "app.h"
#include "raylib.h"

void App::Run() {
    InitWindow(800, 600, "Level Editor");
    SetTargetFPS(60);
    Load();

    while (!WindowShouldClose()) {
        Update();
        Draw();
    }
    CloseWindow();
}

void App::Load() {
    // Загрузка ресурсов
}

void App::Update() {
    // Логика обновления кадров
}

void App::Draw() {
    BeginDrawing();
    ClearBackground(RAYWHITE);
    DrawText("Editor Initialized!", 10, 10, 20, DARKGRAY);
    EndDrawing();
}

И, наконец, наш src/main.cpp становится предельно чистым:

#include "app.h"

int main() {
    App app;
    app.Run();
    return 0;
}

Зачем нужен #pragma once?

В примере выше вы видели директиву #pragma once. Это страж включения (header guard). Если вы случайно подключите один и тот же .h файл в нескольких местах (что неизбежно в больших проектах), компилятор без этой директивы попытается объявить одни и те же классы дважды и выдаст ошибку. #pragma once гарантирует, что файл будет обработан компилятором только один раз.

Практическое задание: Сборка проекта

Теперь ваша задача — воспроизвести эту структуру на своем компьютере.

1. Создайте папку RaylibEditor.
2. Внутри создайте подпапки src, include, assets.
3. Создайте файл CMakeLists.txt с кодом, приведенным выше (версия с FetchContent).
4. Создайте src/main.cpp, src/app.cpp и include/app.h.
5. Запустите конфигурацию CMake:
   • Создайте папку build.
   • Откройте терминал в папке build.
   • Выполните cmake ...
   • После завершения выполните cmake --build . (или откройте сгенерированный проект в IDE).

Если вы увидели окно с надписью "Editor Initialized!" — поздравляю! Вы создали профессиональную заготовку для вашего будущего редактора уровней.

В следующей статье мы займемся наполнением слоя Core и создадим надежную обертку для работы с окном и входными данными, чтобы наш редактор мог корректно обрабатывать события мыши и клавиатуры.

Архитектура приложения: отделение движка Raylib от логики редактора

В предыдущей статье мы настроили систему сборки CMake и создали базовую структуру папок. Теперь у нас есть фундамент, но сам код всё ещё уязвим. Если мы начнем писать логику редактора, напрямую вызывая функции Raylib (например, InitWindow или IsKeyDown) внутри классов игровых сущностей, мы создадим жесткую зависимость (tight coupling).

Сегодня мы займемся архитектурной гигиеной. Мы создадим слой абстракции Core, который отделит «железо» и библиотеку Raylib от высокоуровневой логики вашего редактора. Это ключевой шаг, отличающий любительскую поделку от профессионального инструмента.

Проблема прямых зависимостей

Представьте, что вы пишете класс Player. В плохой архитектуре он выглядит так:

// Плохой пример
#include "raylib.h"

class Player {
public:
    void Update() {
        if (IsKeyDown(KEY_SPACE)) {
            // Прыжок
        }
    }
};

Почему это плохо?

1. Загрязнение глобального пространства: Подключая raylib.h в заголовочные файлы игры, вы тянете за собой сотни констант и функций во все файлы, которые включают player.h.
2. Невозможность подмены: Если завтра вы захотите портировать редактор на SDL2 или SFML, вам придется переписывать каждый файл, где упоминается Raylib.
3. Сложность тестирования: Вы не сможете протестировать логику игрока без создания реального окна и контекста OpenGL.

Решение: Слой Core

Мы внедрим промежуточный слой. Наша архитектура будет выглядеть как слоеный пирог, где зависимости идут только сверху вниз.

Слой Core будет предоставлять интерфейсы для:

• Управления окном (Window)
• Обработки ввода (Input)
• Работы с ресурсами (ResourceManager)

Абстракция окна (Window Wrapper)

Начнем с создания класса, который будет отвечать за жизненный цикл окна. Вместо того чтобы вызывать InitWindow в main.cpp, мы делегируем это классу Core::Window.

Создайте файл include/core/window.h:

#pragma once
#include <string>

namespace Core {

    class Window {
    public:
        Window(int width, int height, const std::string& title);
        ~Window();

        // Запрещаем копирование окна
        Window(const Window&) = delete;
        Window& operator=(const Window&) = delete;

        bool ShouldClose() const;
        void BeginFrame();
        void EndFrame();

        int GetWidth() const;
        int GetHeight() const;
    };

}

И реализацию в src/core/window.cpp:

#include "core/window.h"
#include "raylib.h"

namespace Core {

    Window::Window(int width, int height, const std::string& title) {
        InitWindow(width, height, title.c_str());
        SetTargetFPS(60);
    }

    Window::~Window() {
        CloseWindow();
    }

    bool Window::ShouldClose() const {
        return WindowShouldClose();
    }

    void Window::BeginFrame() {
        BeginDrawing();
        ClearBackground(RAYWHITE);
    }

    void Window::EndFrame() {
        EndDrawing();
    }

    int Window::GetWidth() const {
        return GetScreenWidth();
    }

    int Window::GetHeight() const {
        return GetScreenHeight();
    }
}

Что мы получили? Теперь наш main.cpp или класс App не знают, что под капотом используется Raylib. Мы используем идиому RAII (Resource Acquisition Is Initialization): окно создается в конструкторе и уничтожается в деструкторе.

Абстракция ввода (Input System)

Это самая важная часть. Мы не хотим использовать KEY_SPACE (константу Raylib) в коде редактора. Мы создадим свой собственный перечень клавиш.

Файл include/core/input_keys.h:

#pragma once

namespace Core {
    enum class Key {
        Unknown = 0,
        Space,
        Escape,
        W, A, S, D,
        Enter,
        // Добавьте остальные необходимые клавиши
    };
}

Теперь создадим класс Input, который будет транслировать наши клавиши в клавиши Raylib. Файл include/core/input.h:

#pragma once
#include "core/input_keys.h"

namespace Core {
    class Input {
    public:
        static bool IsKeyPressed(Key key);
        static bool IsKeyDown(Key key);
        // Методы для мыши можно добавить позже
    };
}

В реализации src/core/input.cpp нам придется сделать маппинг (сопоставление). Это немного рутинная работа, но её нужно сделать один раз.

#include "core/input.h"
#include "raylib.h"

namespace Core {

    // Внутренняя функция для конвертации
    static int KeyToRaylib(Key key) {
        switch (key) {
            case Key::Space: return KEY_SPACE;
            case Key::Escape: return KEY_ESCAPE;
            case Key::W: return KEY_W;
            case Key::A: return KEY_A;
            case Key::S: return KEY_S;
            case Key::D: return KEY_D;
            case Key::Enter: return KEY_ENTER;
            default: return 0;
        }
    }

    bool Input::IsKeyPressed(Key key) {
        return ::IsKeyPressed(KeyToRaylib(key));
    }

    bool Input::IsKeyDown(Key key) {
        return ::IsKeyDown(KeyToRaylib(key));
    }
}

Интеграция в приложение

Теперь обновим наш класс App, который мы создали в прошлой статье. Теперь он будет владеть объектом Window и использовать Input.

Файл include/app.h:

#pragma once
#include <memory>
#include "core/window.h"

class App {
public:
    App();
    void Run();

private:
    void Update();
    void Render();

    // Используем умный указатель для управления временем жизни окна
    std::unique_ptr<Core::Window> m_window;
};

Файл src/app.cpp:

#include "app.h"
#include "core/input.h"
#include <iostream>

App::App() {
    // Инициализация окна происходит здесь
    m_window = std::make_unique<Core::Window>(1280, 720, "Raylib Level Editor");
}

void App::Run() {
    while (!m_window->ShouldClose()) {
        Update();
        Render();
    }
    // Деструктор m_window вызовется автоматически и закроет окно
}

void App::Update() {
    // Пример использования нашей системы ввода
    if (Core::Input::IsKeyPressed(Core::Key::Escape)) {
        std::cout << "Escape pressed!" << std::endl;
    }
}

void App::Render() {
    m_window->BeginFrame();

    // Здесь будет рендеринг редактора

    m_window->EndFrame();
}

Преимущества такого подхода

1. Чистота кода: В App и будущих классах редактора нет ни одного #include "raylib.h". Логика чиста от деталей реализации графики.
2. Безопасность: Мы не можем случайно вызвать EndDrawing() дважды или забыть CloseWindow(), так как это контролируется классом Window.
3. Расширяемость: Если нам понадобится логирование всех нажатий клавиш, мы добавим это в одно место — в метод Core::Input::IsKeyPressed, и это заработает во всем проекте сразу.

Итог

Мы успешно изолировали библиотеку Raylib внутри слоя Core. Наш редактор теперь общается с внешним миром через строго определенные интерфейсы. Это может показаться излишним усложнением на старте, но когда ваш проект вырастет до 50+ файлов, эта структура спасет вас от хаоса.

В следующей статье мы займемся реализацией игрового цикла (Game Loop) и созданием базовой системы сцен, чтобы переключаться между режимом редактирования и режимом игры.

Управление сущностями: менеджеры объектов и базовый полиморфизм

В предыдущих статьях мы заложили фундамент нашего редактора: настроили систему сборки CMake и отделили низкоуровневый код работы с окном (Core) от остальной программы. Теперь у нас есть чистое окно и система ввода, но наш мир пуст. В нём нет ни игрока, ни врагов, ни платформ.

Сегодня мы займемся наполнением этого мира. Мы спроектируем архитектуру системы сущностей (Entity System). Это сердце любого игрового движка или редактора уровней. Мы научимся хранить, обновлять и отрисовывать сотни объектов, не зная заранее, чем именно они являются.

Проблема разнородных объектов

Представьте, что вы пишете игру без продуманной архитектуры. Скорее всего, вы начнете с создания списков для каждого типа объектов:

std::vector<Player> players;
std::vector<Enemy> enemies;
std::vector<Coin> coins;
std::vector<Door> doors;

Для игры это может сработать (хотя и с трудом), но для редактора уровней такой подход фатален. Редактор должен уметь загружать, перемещать и сохранять любой объект, который вы поместите на сцену. Если вы добавите новый тип врага, вам не захочется переписывать код редактора, добавляя новый std::vector.

Нам нужен способ хранить всё в одном контейнере:

std::vector<Something> allObjects;

Здесь нам на помощь приходит полиморфизм.

Базовый класс Entity

Все объекты на сцене имеют общие черты: у них есть позиция, их нужно обновлять каждый кадр, и их нужно рисовать. Вынесем это в абстрактный базовый класс Entity.

Создайте файл include/game/entity.h:

#pragma once
#include "raylib.h" // Используем Vector2 из Raylib для удобства

class Entity {
public:
    // Виртуальный деструктор обязателен для полиморфизма!
    virtual ~Entity() = default;

    // Чисто виртуальные методы: наследники ОБЯЗАНЫ их реализовать
    virtual void Update(float deltaTime) = 0;
    virtual void Render() = 0;

    // Общие данные для всех сущностей
    Vector2 position = {0.0f, 0.0f};
    Vector2 size = {32.0f, 32.0f};
    Color color = WHITE;
};

Почему деструктор виртуальный?

Это критически важный момент в C++. Если вы удаляете объект производного класса через указатель на базовый класс (а мы будем делать именно так), и деструктор базового класса не виртуальный, то вызовется только деструктор Entity. Деструктор Player или Enemy вызван не будет. Это приведет к утечке памяти и ресурсов.

Реализация конкретных сущностей

Теперь мы можем создать классы, которые наследуются от Entity. Например, создадим простого игрока.

Файл include/game/player.h:

#pragma once
#include "game/entity.h"
#include "core/input.h"

class Player : public Entity {
public:
    Player() {
        position = {100, 100};
        color = BLUE;
    }

    void Update(float deltaTime) override {
        // Простая логика движения
        float speed = 200.0f;
        if (Core::Input::IsKeyDown(Core::Key::D)) position.x += speed * deltaTime;
        if (Core::Input::IsKeyDown(Core::Key::A)) position.x -= speed * deltaTime;
        if (Core::Input::IsKeyDown(Core::Key::W)) position.y -= speed * deltaTime;
        if (Core::Input::IsKeyDown(Core::Key::S)) position.y += speed * deltaTime;
    }

    void Render() override {
        DrawRectangleV(position, size, color);
    }
};

Обратите внимание: класс Player реализует методы Update и Render по-своему. Это и есть суть полиморфизма.

Менеджер сущностей (EntityManager)

Теперь нам нужен «дирижер», который будет управлять этим оркестром объектов. Класс EntityManager будет владеть всеми сущностями, следить за их жизненным циклом и обновлять их.

Выбор контейнера

Какой контейнер использовать? std::vector<Entity> не сработает из-за срезки объектов (object slicing) и невозможности хранить абстрактные классы. Нам нужны указатели.

Лучший выбор для современного C++ — std::vector<std::unique_ptr<Entity>>.

• std::vector: Динамический массив, быстрый доступ.
• std::unique_ptr: Умный указатель, который гарантирует, что у объекта есть только один владелец (наш менеджер). Когда вектор очищается, unique_ptr автоматически удаляет сущности. Никаких delete вручную!

Файл include/game/entity_manager.h:

#pragma once
#include <vector>
#include <memory>
#include "game/entity.h"

class EntityManager {
public:
    // Добавление любой сущности, наследника Entity
    void AddEntity(std::unique_ptr<Entity> entity);

    void Update(float deltaTime);
    void Render();

private:
    std::vector<std::unique_ptr<Entity>> m_entities;
};

Файл src/game/entity_manager.cpp:

#include "game/entity_manager.h"

void EntityManager::AddEntity(std::unique_ptr<Entity> entity) {
    // std::move передает владение указателем в вектор
    m_entities.push_back(std::move(entity));
}

void EntityManager::Update(float deltaTime) {
    for (auto& entity : m_entities) {
        entity->Update(deltaTime);
    }
}

void EntityManager::Render() {
    for (auto& entity : m_entities) {
        entity->Render();
    }
}

Математика движения: Delta Time

В коде Player вы видели переменную deltaTime. Это фундаментальное понятие в разработке игр. Компьютеры имеют разную производительность. У кого-то игра выдает 60 кадров в секунду (FPS), у кого-то 144.

Если мы будем просто прибавлять position.x += 5 каждый кадр, то на быстром компьютере игрок будет двигаться в 2-3 раза быстрее, чем на медленном. Чтобы скорость была постоянной в мире, а не в кадрах, мы используем формулу движения:

$$P_{new} = P_{old} + V \cdot \Delta t$$

Где:

• $P_{new}$ — новая позиция объекта.
• $P_{old}$ — текущая позиция объекта.
• $V$ — скорость объекта (в пикселях или метрах в секунду).
• $\Delta t$ — время, прошедшее с последнего кадра (в секундах).

Если $V = 100$ пикселей/сек, а кадр рисовался 0.016 секунды (60 FPS), то объект сдвинется на $100 \cdot 0.016 = 1.6$ пикселя. Если кадр рисовался 0.1 секунды (10 FPS), сдвиг составит $100 \cdot 0.1 = 10$ пикселей. В итоге за одну секунду объект пройдет ровно 100 пикселей на любом компьютере.

Интеграция в App

Осталось собрать всё вместе в нашем главном классе App.

Обновим include/app.h:

#pragma once
#include <memory>
#include "core/window.h"
#include "game/entity_manager.h"

class App {
public:
    App();
    void Run();

private:
    void Update();
    void Render();

    std::unique_ptr<Core::Window> m_window;
    EntityManager m_entityManager;
};

И src/app.cpp:

#include "app.h"
#include "game/player.h"

App::App() {
    m_window = std::make_unique<Core::Window>(800, 600, "Level Editor");

    // Создаем игрока и передаем его менеджеру
    // make_unique создает объект Player в куче
    m_entityManager.AddEntity(std::make_unique<Player>());
}

void App::Update() {
    // Получаем время кадра от Raylib
    float dt = GetFrameTime();
    m_entityManager.Update(dt);
}

void App::Render() {
    m_window->BeginFrame();
    m_entityManager.Render();
    m_window->EndFrame();
}

Итоги

Что мы получили благодаря этой архитектуре?

1. Расширяемость: Чтобы добавить врага, платформу или ловушку, нам нужно просто создать новый класс, наследуемый от Entity. Нам не нужно менять код App или EntityManager.
2. Управление памятью: EntityManager и unique_ptr берут на себя всю грязную работу по удалению объектов.
3. Чистота: Главный цикл приложения (Run) остается простым и понятным. Он просто делегирует задачи менеджеру.

В следующей статье мы сделаем наш редактор по-настоящему интерактивным: научимся выделять объекты мышью и перемещать их по сцене, используя простую физику столкновений AABB.

Интеграция пользовательского интерфейса и паттерн Команда для отмены действий

В предыдущих частях курса мы проделали большую работу: настроили профессиональную структуру проекта на CMake, отделили движок от логики и создали систему управления сущностями. Теперь наш редактор умеет отображать объекты, но взаимодействовать с ними пока сложно. Мы всё ещё хардкодим создание объектов в коде.

Настало время превратить нашу программу в настоящий инструмент. Для этого нам понадобятся две вещи:

1. Пользовательский интерфейс (UI): Кнопки и панели для выбора объектов.
2. Система отмены действий (Undo/Redo): Возможность исправить ошибку, нажав Ctrl+Z.

Сегодня мы внедрим библиотеку raygui и реализуем один из самых важных паттернов проектирования для редакторов — паттерн Команда (Command).

Выбор UI библиотеки: Почему Immediate Mode?

Для C++ существует множество GUI-библиотек: Qt, wxWidgets, ImGui. Для игровых инструментов стандартом де-факто стал подход Immediate Mode GUI (IMGUI). В отличие от классического (Retained Mode) подхода, где вы создаете объекты кнопок и храните их в памяти, в IMGUI интерфейс перерисовывается и обрабатывается каждый кадр заново.

Для Raylib идеальным компаньоном является библиотека raygui. Это легковесная библиотека, состоящая из одного заголовочного файла, которая работает поверх Raylib.

Подключение raygui

Так как raygui — это header-only библиотека, её интеграция предельно проста. Скачайте файл raygui.h из официального репозитория и положите его в папку include/external/ или src/vendor/.

В одном (и только одном!) .cpp файле (например, в src/core/gui_impl.cpp) вы должны реализовать библиотеку:

#define RAYGUI_IMPLEMENTATION
#include "external/raygui.h"

Теперь в любом месте кода вы можете просто подключить заголовок и нарисовать кнопку:

#include "external/raygui.h"

// Внутри цикла отрисовки:
if (GuiButton((Rectangle){ 10, 10, 100, 30 }, "Place Player")) {
    // Логика нажатия
}

Это невероятно удобно для редактора: не нужно создавать сложные иерархии классов для UI, вы просто пишете if (Button...) там, где это нужно.

Архитектурная проблема: Спагетти из событий

Самый простой способ обработать нажатие кнопки — написать логику прямо внутри if:

if (GuiButton(rect, "Create Enemy")) {
    entityManager.AddEntity(std::make_unique<Enemy>(...));
}

Это работает, но создает тупик. Что если пользователь поставил врага не туда? Ему придется удалять его вручную. А если он случайно удалил пол-уровня? Без функции «Отмена» (Undo) ваш редактор будет вызывать только раздражение.

Чтобы реализовать Undo/Redo, нам нужно перестать воспринимать действия как функции и начать воспринимать их как объекты.

Паттерн Команда (Command)

Паттерн Команда инкапсулирует запрос в виде объекта. Это позволяет параметризовать клиенты с разными запросами, ставить запросы в очередь и, самое главное, поддерживать отмену операций.

Суть проста: любое изменение состояния редактора (создание, удаление, перемещение) должно проходить через специальный класс.

Интерфейс Команды

Создадим абстрактный базовый класс. Файл include/commands/command.h:

#pragma once

class Command {
public:
    virtual ~Command() = default;

    // Выполнить действие
    virtual void Execute() = 0;

    // Отменить действие
    virtual void Undo() = 0;
};

Конкретная команда: Размещение сущности

Давайте реализуем команду добавления объекта. Чтобы отменить добавление, нужно удалить объект. Чтобы повторить (Redo) — добавить снова.

Файл include/commands/place_entity_command.h:

#pragma once
#include "commands/command.h"
#include "game/entity_manager.h"
#include "game/entity.h"
#include <memory>

class PlaceEntityCommand : public Command {
public:
    PlaceEntityCommand(EntityManager& manager, std::unique_ptr<Entity> entity)
        : m_manager(manager), m_entity(std::move(entity)) {}

    void Execute() override {
        // В реальном коде EntityManager должен уметь возвращать ID или указатель
        // Для простоты примера представим, что AddEntity возвращает ID
        m_entityID = m_manager.AddEntity(std::move(m_entity));
    }

    void Undo() override {
        // Забираем владение сущностью обратно из менеджера
        m_entity = m_manager.RemoveEntity(m_entityID);
    }

private:
    EntityManager& m_manager;
    std::unique_ptr<Entity> m_entity; // Храним сущность, пока она не в сцене
    int m_entityID = -1;
};

Обратите внимание на красоту решения: команда владеет данными, необходимыми для восстановления состояния. Когда мы делаем Undo, сущность не уничтожается, а перемещается из EntityManager обратно в PlaceEntityCommand.

История команд (Command History)

Нам нужен менеджер, который будет хранить стопку выполненных команд. Это классический стек, но с возможностью движения вперед-назад.

Математически состояние редактора $S$ в момент времени $t$ можно описать как последовательное применение команд $C$ к начальному состоянию $S_0$:

$$S_t = C_t(C_{t-1}(...C_1(S_0)...))$$

Где:

• $S_t$ — состояние системы в момент времени $t$.
• $C_i$ — $i$-я команда в истории.
• $S_0$ — пустое (начальное) состояние сцены.

Операция Undo — это применение обратной функции $C^{-1}$ (метода Undo):

$$S_{t-1} = C_t^{-1}(S_t)$$

Где:

• $S_{t-1}$ — предыдущее состояние системы.
• $C_t^{-1}$ — отмена последней команды.

Реализуем этот механизм в классе CommandProcessor.

Файл include/commands/command_processor.h:

#pragma once
#include "commands/command.h"
#include <vector>
#include <memory>

class CommandProcessor {
public:
    void ExecuteCommand(std::unique_ptr<Command> command) {
        // Если мы сделали новое действие после нескольких Undo,
        // мы должны отрезать "будущее", которое стало неактуальным
        if (m_currentCommandIndex < m_history.size()) {
            m_history.resize(m_currentCommandIndex);
        }

        command->Execute();
        m_history.push_back(std::move(command));
        m_currentCommandIndex++;
    }

    void Undo() {
        if (m_currentCommandIndex > 0) {
            m_currentCommandIndex--;
            m_history[m_currentCommandIndex]->Undo();
        }
    }

    void Redo() {
        if (m_currentCommandIndex < m_history.size()) {
            m_history[m_currentCommandIndex]->Execute();
            m_currentCommandIndex++;
        }
    }

private:
    std::vector<std::unique_ptr<Command>> m_history;
    size_t m_currentCommandIndex = 0;
};

Интеграция всего вместе

Теперь обновим наш класс Editor (или App), чтобы связать UI, ввод и команды.

// В методе Update класса App

// 1. Обработка горячих клавиш
if (IsKeyDown(KEY_LEFT_CONTROL)) {
    if (IsKeyPressed(KEY_Z)) m_commandProcessor.Undo();
    if (IsKeyPressed(KEY_Y)) m_commandProcessor.Redo();
}

// 2. Отрисовка UI панели
if (GuiButton((Rectangle){ 10, 50, 120, 30 }, "Add Player")) {
    // Создаем команду, но не выполняем её сразу вручную
    auto cmd = std::make_unique<PlaceEntityCommand>(
        m_entityManager,
        std::make_unique<Player>(100, 100) // Начальная позиция
    );

    // Передаем процессору
    m_commandProcessor.ExecuteCommand(std::move(cmd));
}

Важные нюансы реализации

1. Состояние "грязного" файла

Паттерн Команда отлично подходит для отслеживания изменений. Вы можете запомнить индекс команды, на котором было последнее сохранение (m_savedIndex).

$$\text{IsDirty} = (m\_currentCommandIndex \neq m\_savedIndex)$$

Где:

• $\text{IsDirty}$ — флаг, показывающий, есть ли несохраненные изменения.
• $m\_currentCommandIndex$ — текущая позиция в истории команд.
• $m\_savedIndex$ — позиция в истории, когда файл был сохранен на диск.

Если индексы не равны, значит, пользователь что-то изменил, и нужно предложить сохранение при выходе.

2. Лимит истории

Бесконечная история команд может съесть всю оперативную память, если редактор работает долго. Обычно реализуют кольцевой буфер или просто удаляют старые команды из начала вектора, если их количество превышает, например, 100 штук.

Заключение

Сегодня мы сделали огромный шаг вперед. Наш редактор перестал быть просто «рисовалкой» и стал приложением с состоянием. Мы:

1. Подключили raygui для быстрого создания интерфейса.
2. Изолировали логику изменений в классы Command.
3. Реализовали Undo/Redo, что критически важно для любого творческого инструмента.

Теперь вы можете добавлять новые типы команд: MoveCommand (перемещение), DeleteCommand (удаление), ChangeColorCommand (изменение свойств). Архитектура готова к масштабированию.

В следующей статье мы займемся сериализацией: научимся сохранять наш уровень в файл (JSON или бинарный формат) и загружать его обратно, чтобы ваш труд не пропадал после закрытия программы.

Сериализация данных: грамотное сохранение и загрузка уровней

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

Как только вы закрываете программу, ваш шедевральный уровень исчезает. Вся работа пропадает в небытие, так как данные живут только в оперативной памяти (RAM). Чтобы превратить нашу программу в полноценный инструмент, нам нужно научить её сериализации.

Сегодня мы разберем, как сохранить состояние игрового мира в файл и восстановить его обратно, не нарушая принципов ООП и архитектуры, которую мы так старательно выстраивали.

Что такое сериализация?

Сериализация — это процесс перевода структуры данных или объекта в формат, который можно сохранить (в файл, в базу данных) или передать по сети. Обратный процесс называется десериализацией.

Представьте, что ваш уровень — это собранный из LEGO замок. Чтобы отправить его другу по почте в маленьком конверте, вам нужно разобрать его на кирпичики и написать инструкцию: «Красный кубик 2x4 стоит на координатах (10, 5)». Друг, получив письмо, читает инструкцию и собирает замок заново.

В нашем случае:

• Замок — это список сущностей std::vector<std::unique_ptr<Entity>>.
• Инструкция — это файл сохранения.
• Друг — это функция загрузки уровня.

Выбор формата: Бинарный или Текстовый?

Перед тем как писать код, нужно решить, как мы будем хранить данные.

1. Бинарный формат

Вы просто копируете байты из памяти в файл.

• Плюсы: Максимальная скорость, минимальный размер файла.
• Минусы: Нечитаемо для человека. Если вы измените класс (добавите поле), старые сохранения перестанут работать без сложной конвертации. Сложно отлаживать.

2. Текстовый формат (JSON, XML, YAML)

Данные сохраняются в структурированном тексте.

• Плюсы: Человекочитаемость (можно править уровень в Блокноте), легкость отладки, совместимость с системами контроля версий (git).
• Минусы: Файл весит больше, парсинг (чтение) занимает время.

Для редакторов уровней и инструментов разработки JSON является золотым стандартом. Удобство разработки и поддержки важнее, чем экономия пары килобайт на диске.

Мы выберем JSON (JavaScript Object Notation).

Подключение библиотеки nlohmann/json

В C++ нет встроенной поддержки JSON. Писать свой парсер — плохая идея (это долго и чревато ошибками). Мы воспользуемся стандартом де-факто в мире современного C++ — библиотекой nlohmann/json.

Добавим её в наш проект через CMake, используя уже знакомый нам FetchContent. Откройте ваш корневой CMakeLists.txt:

# ... (предыдущие настройки)

# Подключение nlohmann_json
FetchContent_Declare(
    json
    GIT_REPOSITORY https://github.com/nlohmann/json.git
    GIT_TAG v3.11.2
)
FetchContent_MakeAvailable(json)

# ... (настройка исполняемого файла)

# Линкуем библиотеку к нашему проекту
target_link_libraries(RaylibLevelEditor PRIVATE raylib nlohmann_json::nlohmann_json)

Теперь в коде мы можем использовать заголовок:

#include <nlohmann/json.hpp>
using json = nlohmann::json;

Архитектура сохранения: Интерфейс Serializable

Главная сложность — полиморфизм. У нас есть список указателей на Entity, но там могут лежать Player, Enemy или Platform. Каждый из них имеет свои уникальные поля.

Нам нужно научить каждую сущность сохранять себя. Добавим чисто виртуальные методы в базовый класс Entity.

Файл include/game/entity.h:

#pragma once
#include "raylib.h"
#include <nlohmann/json.hpp>
#include <string>

using json = nlohmann::json;

class Entity {
public:
    virtual ~Entity() = default;
    virtual void Update(float deltaTime) = 0;
    virtual void Render() = 0;

    // Новые методы для сериализации
    // 1. Возвращает JSON-объект с данными сущности
    virtual json ToJson() const = 0;

    // 2. Возвращает строковый идентификатор типа (нужен для загрузки)
    virtual std::string GetType() const = 0;

    // Общие данные
    Vector2 position = {0.0f, 0.0f};
    Vector2 size = {32.0f, 32.0f};
    Color color = WHITE;
};

Теперь реализуем это в классе Player. Файл include/game/player.h:

class Player : public Entity {
public:
    // ... (Update и Render)

    std::string GetType() const override {
        return "Player";
    }

    json ToJson() const override {
        // Создаем JSON объект
        json j;
        j["type"] = GetType();
        j["x"] = position.x;
        j["y"] = position.y;
        // Можно сохранить и другие специфичные для игрока поля, например здоровье
        return j;
    }

    // Статический метод для восстановления из JSON
    static std::unique_ptr<Player> FromJson(const json& j) {
        auto player = std::make_unique<Player>();
        if (j.contains("x")) player->position.x = j["x"];
        if (j.contains("y")) player->position.y = j["y"];
        return player;
    }
};

Класс LevelSerializer

Теперь создадим класс, который будет отвечать за запись всего уровня в файл и чтение из него. Это отдельный модуль, который не должен быть частью EntityManager (принцип единственной ответственности).

Файл include/game/level_serializer.h:

#pragma once
#include <string>
#include "game/entity_manager.h"

class LevelSerializer {
public:
    static void SaveLevel(const EntityManager& manager, const std::string& filename);
    static void LoadLevel(EntityManager& manager, const std::string& filename);
};

Реализация сохранения (Save)

Здесь всё просто: мы проходим по всем сущностям, просим их превратиться в JSON и складываем в массив.

Файл src/game/level_serializer.cpp:

#include "game/level_serializer.h"
#include <fstream>
#include <iostream>

void LevelSerializer::SaveLevel(const EntityManager& manager, const std::string& filename) {
    json levelJson;
    levelJson["entities"] = json::array();

    // EntityManager должен предоставить доступ к сущностям (например, через геттер)
    const auto& entities = manager.GetEntities();

    for (const auto& entity : entities) {
        levelJson["entities"].push_back(entity->ToJson());
    }

    // Запись в файл
    std::ofstream file(filename);
    if (file.is_open()) {
        // Аргумент 4 добавляет красивые отступы (pretty print)
        file << levelJson.dump(4);
        file.close();
        std::cout << "Level saved to " << filename << std::endl;
    } else {
        std::cerr << "Failed to open file for saving!" << std::endl;
    }
}

Реализация загрузки (Load) и проблема Фабрики

С загрузкой сложнее. Мы читаем файл, видим объект {"type": "Player", ...}. Как нам создать именно Player? C++ не умеет создавать классы по строковому названию "из коробки" (в отличие от C# или Java, где есть рефлексия).

Нам нужен паттерн Фабрика или простой реестр. В простейшем случае это серия if-else.

#include "game/player.h"
// Подключите заголовки других сущностей

void LevelSerializer::LoadLevel(EntityManager& manager, const std::string& filename) {
    std::ifstream file(filename);
    if (!file.is_open()) {
        std::cerr << "Failed to open file for loading!" << std::endl;
        return;
    }

    json levelJson;
    file >> levelJson;

    manager.Clear(); // Очищаем текущий уровень перед загрузкой

    if (levelJson.contains("entities")) {
        for (const auto& entityJson : levelJson["entities"]) {
            std::string type = entityJson["type"];
            std::unique_ptr<Entity> newEntity = nullptr;

            // --- Примитивная фабрика ---
            if (type == "Player") {
                newEntity = Player::FromJson(entityJson);
            }
            // else if (type == "Enemy") { ... }
            // ---------------------------

            if (newEntity) {
                manager.AddEntity(std::move(newEntity));
            } else {
                std::cerr << "Unknown entity type: " << type << std::endl;
            }
        }
    }
    std::cout << "Level loaded from " << filename << std::endl;
}

Интеграция в UI

Осталось добавить кнопки в наш редактор. Вернемся в App::Update или туда, где вы рисуете GUI.

// Панель управления файлами
if (GuiButton((Rectangle){ 10, 10, 60, 30 }, "Save")) {
    LevelSerializer::SaveLevel(m_entityManager, "level.json");
}

if (GuiButton((Rectangle){ 80, 10, 60, 30 }, "Load")) {
    LevelSerializer::LoadLevel(m_entityManager, "level.json");
}

Теперь, запустив редактор, вы можете расставить объекты, нажать "Save", закрыть программу, открыть её снова, нажать "Load" — и вуаля! Ваш мир восстановлен.

Продвинутые техники (на будущее)

Решение с if (type == "Player") работает для малых проектов. Но если у вас 100 типов врагов, этот if станет гигантским. В профессиональных движках используют автоматическую регистрацию типов.

Идея в том, чтобы создать std::map, где ключом является строка (имя типа), а значением — функция, создающая этот тип.

// Пример (псевдокод)
std::map<std::string, std::function<std::unique_ptr<Entity>(json)>> factoryMap;

// Регистрация
factoryMap["Player"] = [](json j) { return Player::FromJson(j); };

// Использование
if (factoryMap.count(type)) {
    newEntity = factoryMap[type](entityJson);
}

Это позволяет добавлять новые классы врагов, не меняя код LevelSerializer.

Заключение

Мы добавили критически важную функцию в наш редактор. Теперь это не просто игрушка, а инструмент, сохраняющий результаты труда.

Мы использовали:

1. JSON для хранения данных (читаемость и удобство).
2. Библиотеку nlohmann/json для парсинга.
3. Виртуальные методы для полиморфного сохранения.
4. Паттерн Фабрика (в упрощенном виде) для восстановления объектов.

В следующей статье мы займемся оптимизацией рендеринга. Когда вы нарисуете на уровне тысячи тайлов, ваш FPS может упасть. Мы узнаем, что такое Batch Rendering и как заставить Raylib рисовать миллионы объектов без тормозов.