sticks

Многомодульный игровой проект на C++20 с интеграцией vcpkg (manifest mode), Google Test и Doxygen. Сборка построена на строго target-based CMake — без глобальных include_directories()/link_directories().

Проект включает ECS-движок на Flecs, рендерер на Vulkan 1.3 (через volk), загрузку и скелетную анимацию моделей, редактор игровых данных, компиляцию игровых данных в FlatBuffers, встроенный MCP-отладочный сервер, модули ввода, ивент-шины, локализации, реактивных свойств, UI-виджетов, а также два приложения: графическое sticks_gui и консольное sticks_tui.

Возможности

• ECS-движок (libs/engine) на Flecs: миры/пауза/timeScale (WorldManager), единая конвенция осей Y-up, системы движения/направления.
• Рендерер Vulkan 1.3 (libs/render, WorldRenderer, ModelRenderer): bindless-текстуры, depth, пакетный рендер текста (MTSDF), vertex-skinning скелетной модели, единый GPU-батч UI, Dear ImGui для дебажных интерфейсов.
• Скелетная анимация (libs/animation): AnimationPlayer/ClipSampler, секторный поворот (TurnStateMachine), кроссфейд поз (PoseMixer), поступательный root motion и дискретное движение по тайлам (LocomotionController).
• Модели (libs/models): единый models.pak (GNU tar + zstd) и загрузка через fastgltf с ref-count/pin текстур.
• Редактор данных (libs/editor_core + каркас в sticks_gui, --editor): документы локаций/тайлсетов/каталогов, JSON-IO с guard'ом, op-based undo/redo, пикинг по лучу и компиляция world data.
• Отладочный MCP-сервер (libs/control, опция STICKS_ENABLE_DEBUG_SERVER): HTTP-MCP (stateless, JSON-only), телеметрия (логи/validation/сущности/ввод), скриншоты и probe_pixel, инъекция ввода, управление игрой, ожидания и golden-диффы.
• Headless-режим (ST-59): offscreen-рендер без окна/surface/swapchain.
• Сценарные регрессии (tests/scenario_runner.py): прогон *.json-сценариев поверх MCP, опционально (STICKS_ENABLE_SCENARIO_TESTS).
• Ивент-шина (libs/events) — обёртка над EnTT dispatcher.
• Ввод (libs/input) — физические клавиши, маппинг действий, контексты.
• Реактивные свойства (libs/reactive) — Property<T>/Signal<EventT>.
• Локализация (libs/localization) — бинарный формат .loc, plural-правила.
• Игровые данные (libs/world_data) и правила (libs/game_rules) — JSON → FlatBuffers с валидацией, шаблоны/вариации, ранги/редкость.
• UI-виджеты (libs/ui) — retained-mode дерево виджетов + JSON-конфигурация.
• Платформа (libs/platform) — read-only MappedFile; логирование (libs/log) через spdlog; отложенное удаление GPU-ресурсов (libs/gpu_deletion).
• Конвейер ассетов — текстуры KTX2 (.pak), шрифты MSDF (.arfont), шейдеры GLSL → SPIR-V (.spv), модели (models.pak).
• Профилирование Tracy (опционально, только в Debug).

Требования

• CMake ≥ 3.21, компилятор с поддержкой C++20, Ninja (для пресетов). Для сборки GUI-сервера Tracy нужен CMake ≥ 3.25.
• vcpkg — переменная окружения VCPKG_ROOT (или vcpkg в PATH/$HOME/vcpkg).
• Vulkan SDK (или пакет shaderc) — glslc для компиляции шейдеров.
• ImageMagick (magick v7 или convert v6) — для resize_textures.
• KTX-Software v5 (ktx) — для конвертации текстур.
• Python 3 — локали и сценарные регрессии (scenario_runner.py).
• Blender — только для export_models (опционально).
• Doxygen — опционально, для таргета doc.
• Node.js — опционально, для npx @modelcontextprotocol/inspector.

Быстрый старт

# 1. Клонирование с сабмодулями
git clone <repo-url> sticks
cd sticks
git submodule update --init --recursive

# 2. Конфигурация (vcpkg-тулчейн подключается автоматически из VCPKG_ROOT)
export VCPKG_ROOT=/path/to/vcpkg
cmake -S . -B build

# 3. Сборка всех таргетов (engine, sticks_gui, sticks_tui, run_tests)
cmake --build build

# 4. Быстрые тесты (без метки integration)
ctest --test-dir build --output-on-failure -LE integration

Либо через пресеты из CMakePresets.json:

cmake --list-presets
cmake --preset linux-release
cmake --build --preset linux-release

Запуск приложений

# Графическое приложение (Vulkan)
./build/apps/sticks_gui/sticks_gui

# Консольный TUI (FTXUI)
./build/apps/sticks_tui/sticks_tui

# Редактор данных: EditorScene вместо меню, --data-dir задаёт корень данных
# (приоритет: CLI > env STICKS_DATA_DIR > assets/data от CWD, иначе код 2)
./build/apps/sticks_gui/sticks_gui --editor --data-dir assets/data
./scripts/run_editor.sh            # то же удобнее: автопоиск build, --build при необходимости

# Headless (без окна/surface/swapchain)
env -u DISPLAY -u WAYLAND_DISPLAY \
    ./build/apps/sticks_gui/sticks_gui --headless --exit-after-frames 300

Ключевые CLI-флаги sticks_gui: --headless/--windowed, --resolution WxH, --fixed-dt S, --max-fps N, --exit-after-frames N, --exit-after-seconds S, --editor, --data-dir <path>, --help.

Встроенный MCP-сервер

cmake -S . -B build -DSTICKS_ENABLE_DEBUG_SERVER=ON
cmake --build build
STICKS_DEBUG_SERVER=1 ./build/apps/sticks_gui/sticks_gui &
cat sticks_mcp.port    # default 47381

Структура проекта

├── CMakeLists.txt                  # корневой: vcpkg-интеграция, C++20, enable_testing()
├── CMakePresets.json               # пресеты конфигурации/сборки/тестов (linux/windows/macos)
├── vcpkg.json                      # манифест зависимостей
├── vcpkg-configuration.json        # baseline реестра + overlay-ports
├── vcpkg-overlay-ports/            # overlay-порт imgui (volk вместо Vulkan-лоадера)
├── cmake/                          # Data, Doxygen, Fonts, Install, Localization, Models,
│                                   #   MsdfAtlasGen, Shaders, Textures, WorldData
├── third_party/                    # submodules: artery-font-format, tracy (+ CMake-обёртка)
├── scripts/                        # конвейер ассетов, export_models, dist.sh, run_editor.sh,
│                                   #   build_tracy_server.sh, apply_agents_draft.py
├── tools/                          # world_data_compiler; msdf-atlas-gen (FetchContent, .gitignore)
├── assets/                         # shaders, data (ui + world), textures, fonts, localization,
│                                   #   models, blender
├── libs/
│   ├── animation/                  # проигрыватель скелетных анимаций, поза/кроссфейд, локомоция
│   ├── control/                    # ядро MCP-сервера + HTTP-транспорт
│   ├── editor_core/                # CPU-ядро редактора данных (C++23 эффективно)
│   ├── engine/                     # ECS-движок (Flecs)
│   ├── events/                     # ивент-шина (EnTT)
│   ├── game_rules/                 # ранги/редкость, вариации (header-only)
│   ├── gpu_deletion/               # отложенное уничтожение GPU-ресурсов
│   ├── input/                      # ввод (маппинг действий)
│   ├── localization/               # локализация (.loc)
│   ├── log/                        # логирование (spdlog)
│   ├── models/                     # загрузка моделей из models.pak (fastgltf)
│   ├── platform/                   # MappedFile (mmap/Windows)
│   ├── profiling/                  # обёртка над Tracy (header-only)
│   ├── reactive/                   # реактивные свойства (header-only)
│   ├── render/                     # камеры OrthoCamera/IsometricCamera (header-only)
│   ├── scene/                      # управление сценами
│   ├── ui/                         # UI-виджеты
│   └── world_data/                 # игровые данные (JSON → FlatBuffers)
├── apps/
│   ├── sticks_gui/                 # графическое приложение (Vulkan; окно/headless/редактор)
│   └── sticks_tui/                 # консольный TUI (FTXUI)
└── tests/                          # юнит-тесты (GTest) + Python-тесты и сценарный раннер

Конвейер ассетов

Ассеты проходят несколько стадий обработки и упаковываются в плоские .pak (обычный GNU tar) с сгенерированными заголовками:

• Текстуры: assets/textures → resize → KTX2 → build/assets/textures/*.pak (+ sticks_textures.h).
• Шрифты: .ttf/.otf → .arfont (msdf-atlas-gen, MTSDF) → build/assets/fonts/*.pak (+ sticks_fonts.h).
• Модели: .glb → models.pak (zstd, GNU tar) → build/assets/models/ (+ sticks_models.h). Экспорт из Blender — export_models (вне ALL).
• Шейдеры: GLSL → SPIR-V (glslc) → build/assets/shaders/*.spv.
• Локали: JSON → бинарные .loc → build/assets/localization/.
• Игровые данные: JSON → FlatBuffers world-data.dat → build/assets/world/.

Примеры:

cmake --build build --target resize_textures
cmake --build build --target generate_ktx2
cmake --build build --target pack_textures
cmake --build build --target generate_arfont    # нужен tools/msdf-atlas-gen
cmake --build build --target pack_fonts
cmake --build build --target compile_shaders
cmake --build build --target compile_localization
cmake --build build --target compile_world_data
cmake --build build --target export_models      # Blender headless, вне ALL
cmake --build build --target pack_models

Дистрибутив

./scripts/dist.sh                    # релизная сборка + CPack package
./scripts/dist.sh --install          # релизная сборка + дерево в build/stage
./scripts/dist.sh --preset=linux-debug --install

Установленный дистрибутив: <prefix>/bin/{sticks_gui,sticks_tui}, <prefix>/lib/lib*.a, <prefix>/share/sticks/assets/....

Рантайм-разрешение каталогов ассетов — apps/sticks_gui/src/app_paths.hpp (установленный расклад → дерево сборки → assets от CWD). Переопределение:

• ресурсы: STICKS_PAK_DIR, STICKS_SHADER_DIR, STICKS_FONT_DIR, STICKS_MODEL_DIR, STICKS_LOCALIZATION_DIR, STICKS_UI_CONFIG_DIR, STICKS_WORLD_DATA_DIR;
• редактор: STICKS_DATA_DIR;
• режим: STICKS_HEADLESS=1;
• отладочный сервер: STICKS_DEBUG_SERVER=1, STICKS_DEBUG_SERVER_PORT, STICKS_DEBUG_SERVER_PORT_FILE;
• логи: STICKS_LOG_DIR, STICKS_LOG_LEVEL.

Тесты

# Быстрый набор (исключает медленные сценарные регрессии)
ctest --test-dir build --output-on-failure -LE integration

# Только сценарные регрессии — требуют debug-server + SCENARIO_TESTS
ctest --test-dir build -L integration --output-on-failure

Сценарные регрессии (mcp_scenario) и golden-диффы включаются опт-ин:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
    -DSTICKS_ENABLE_DEBUG_SERVER=ON -DSTICKS_ENABLE_SCENARIO_TESTS=ON

Опции CMake

• STICKS_ENABLE_CLANG_TIDY (OFF) — статический анализ при сборке.
• STICKS_ENABLE_PROFILING (OFF) — Tracy, только Debug.
• STICKS_ENABLE_DEBUG_SERVER (OFF) — MCP-сервер в sticks_gui.
• STICKS_ENABLE_SCENARIO_TESTS (OFF) — CTest mcp_scenario.
• STICKS_ENABLE_HEADLESS (OFF) — метрики в headless даже в Release (сам режим включается в рантайме --headless/STICKS_HEADLESS=1).
• STICKS_BUILD_MSDF_ATLAS_GEN (OFF) — сборка msdf-atlas-gen из исходников (FetchContent, нужна сеть).

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

Вынесенные справочные материалы живут в docs/rules/:

• docs/rules/project-structure.md — полное дерево проекта.
• docs/rules/build.md — сборка, доп. таргеты, LSP.
• docs/rules/assets-pipeline.md — текстуры, шрифты, шейдеры, экспорт моделей.
• docs/rules/models-pipeline.md — models.pak и fastgltf.
• docs/rules/distribution.md — установка, CPack, dist.sh.
• docs/rules/render-scenes-gpu.md — рендер мира, модели, сцены, GPU-выгрузка.
• docs/rules/input-window.md — ввод, окно, реактивные свойства.
• docs/rules/data-and-platform.md — локализация, файлы, world data, game_rules.
• docs/rules/editor.md — CPU-ядро редактора и каркас в sticks_gui.
• docs/rules/ui-imgui.md — UI-виджеты, JSON-конфиг UI, Dear ImGui.
• docs/rules/debug-profiling.md — Tracy и отладочные метрики.
• docs/rules/debug-agent.md — встроенный MCP-отладочный сервер.
• docs/rules/events.md — ивент-шина.
• docs/rules/logging.md — детали системы логирования.
• docs/rules/flecs_rules.md — правила архитектуры ECS-кода.
• docs/rules/pixel_rules.md — правила для пиксель-арта.
• docs/rules/render-screenshot-validation.md — валидация рендера по скриншотам.
• docs/rules/agents-md-draft.md — стейджинг правок AGENTS.md.
• Doxygen: cmake --build build --target doc → build/docs/html.

Соглашения по коду

• C++20, #pragma once, базовый неймспейс sticks + имя модуля (snake_case); libs/editor_core эффективно собирается как C++23 (glaze тянет cxx_std_23).
• Target-based CMake: target_compile_features(<tgt> ... cxx_std_20).
• Fixed-width целочисленные типы из <cstdint> для сериализуемых данных.
• PCH через нативный target_precompile_headers (без XXX_IMPLEMENTATION-заголовков).
• clang-tidy (опционально): cmake -S . -B build -DSTICKS_ENABLE_CLANG_TIDY=ON.
• Профилирование Tracy: -DSTICKS_ENABLE_PROFILING=ON (только Debug).

Лицензия

Пока не определена.