From a152fd3bcf5943502c9762db9f7f3669aeac264d Mon Sep 17 00:00:00 2001 From: Nikita Date: Sun, 16 Aug 2026 07:47:34 +0400 Subject: [PATCH 01/45] =?UTF-8?q?docs:=20=D0=B7=D0=B0=D0=B2=D0=B5=D1=81?= =?UTF-8?q?=D1=82=D0=B8=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8E=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82?= =?UTF-8?q?=D0=B0=20=D0=B8=20=D0=BA=D0=B0=D1=82=D0=B0=D0=BB=D0=BE=D0=B3=20?= =?UTF-8?q?=D1=81=D0=BA=D0=B8=D0=BB=D0=BB=D0=BE=D0=B2=20=D0=B0=D0=B3=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/: index, INSTALL, PROJECT_STRUCTURE, SYSTEM_DESIGN, DEV_RULES, USER_RULES, SKILLS, IMPLEMENTATION_PLAN - .claude/skills/cpp-style: скилл по CodingConvention.md со спецификой SGCore - зафиксированы расхождения README с фактическими CMake-пресетами и состояние тестов/CI --- .claude/skills/cpp-style/SKILL.md | 167 ++++++++++++++++++ docs/DEV_RULES.md | 276 ++++++++++++++++++++++++++++++ docs/IMPLEMENTATION_PLAN.md | 146 ++++++++++++++++ docs/INSTALL.md | 198 +++++++++++++++++++++ docs/PROJECT_STRUCTURE.md | 219 ++++++++++++++++++++++++ docs/SKILLS.md | 149 ++++++++++++++++ docs/SYSTEM_DESIGN.md | 184 ++++++++++++++++++++ docs/USER_RULES.md | 257 ++++++++++++++++++++++++++++ docs/index.md | 52 ++++++ 9 files changed, 1648 insertions(+) create mode 100644 .claude/skills/cpp-style/SKILL.md create mode 100644 docs/DEV_RULES.md create mode 100644 docs/IMPLEMENTATION_PLAN.md create mode 100644 docs/INSTALL.md create mode 100644 docs/PROJECT_STRUCTURE.md create mode 100644 docs/SKILLS.md create mode 100644 docs/SYSTEM_DESIGN.md create mode 100644 docs/USER_RULES.md create mode 100644 docs/index.md diff --git a/.claude/skills/cpp-style/SKILL.md b/.claude/skills/cpp-style/SKILL.md new file mode 100644 index 00000000..c334adcf --- /dev/null +++ b/.claude/skills/cpp-style/SKILL.md @@ -0,0 +1,167 @@ +--- +name: cpp-style +description: >- + Когда использовать: любой C++/заголовки в SungearEngine — модули SGCore + (ECS, Render, Serde, UI, Physics и др.), SGEntry, плагины редактора, тесты. + Соглашение о кодировании Pixelfield: именование файлов и типов + (UpperCamelCase), функций и локальных переменных (lowerCamelCase), префиксы + m_/s_ у членов, lower_snake_case для constexpr/using/typedef, правила + пробелов и скобок, порядок членов структуры, инклуды <> vs "", запрет + using namespace, смарт-поинтеры и RAII, C++23. + Triggers: naming convention, UpperCamelCase, lowerCamelCase, m_ prefix, + s_ prefix, snake_case, brace style, member order, include style, using + namespace, smart pointers, header file naming, CodingConvention, C++ style, + clang-format. +--- + +# C++: соглашение о кодировании Pixelfield + +Стиль кода для всего C++ в репозитории. Первоисточник — +[`CodingConvention.md`](../../../CodingConvention.md) в корне; при конфликте +этого скилла с ним выигрывает первоисточник, а скилл нужно поправить. + +⚠️ `.clang-format` в репозитории нет — стиль автоматикой не проверяется, +соблюдение целиком на авторе и ревью. + +--- + +## 📋 Структура документа +- [Именование](#именование) +- [Пробелы и скобки](#пробелы-и-скобки) +- [Порядок членов структуры](#порядок-членов-структуры) +- [Инклуды](#инклуды) +- [Практики](#практики) +- [Как это ложится на Sungear Engine](#как-это-ложится-на-sungear-engine) + +--- + +## Именование + +| Что | Стиль | Пример | +|-----|-------|--------| +| Файлы C++ (.h/.cpp) | UpperCamelCase, по главной структуре файла | `Position.h` / `Position.cpp` | +| Файл без главной структуры | имя по назначению | `DataTypes.h` | +| Типы: struct/class/enum/union/namespace | UpperCamelCase | `struct MyStruct`, `namespace MyNamespace` | +| Функции | lowerCamelCase | `void moveTo(...)` | +| Локальные переменные | lowerCamelCase | `float myLocalVariable { };` | +| Нестатические члены | префикс `m_` + lowerCamelCase | `float m_x { };` | +| Статические члены | префикс `s_` + lowerCamelCase | `static inline float s_counter { };` | +| События и коллбеки | lowerCamelCase **без префикса** | `Event onClicked;` | +| Шаблонные параметры | UpperCamelCase; `T`-префикс, если имя совпадает с именем возможной переменной | `template` | +| Макросы | UPPER_SNAKE_CASE или lower_snake_case | `#define MY_MACRO_0` | +| constexpr, using, typedef | lower_snake_case | `using my_type = T;`, `static constexpr inline std::size_t num_dimensions = 3;` | + +### Аббревиатуры + +- В **начале** имени — строчными: `m_aabbMember`, `void aabbFunc()`. +- В **середине/конце** — прописными: `m_parentAABB`, `void resizeAABB(AABB& aabb)`. + +--- + +## Пробелы и скобки + +- После `(` и перед `)` пробелов нет: `doSomething(float a)`. +- Перед `;` пробела нет, после — есть: `for(int i = 0; i < 3; ++i)`. + Обратите внимание: **между `for`/`if`/`while`/`catch` и `(` пробела нет** — + так во всех примерах конвенции. +- Бинарные операторы (`+ - * / = == !=`) — по одному пробелу с обеих сторон. +- `[`, `]`, `<`, `>` — без внутренних пробелов: `std::unordered_map`. +- Запятая: пробела до нет, после — есть. +- Двоеточие — пробел до и после: `for(const auto& v : values)`. +- Инициализация фигурными скобками — пробел внутри: `auto myVar = { 3, 4, 5 };`, + пустая инициализация — `float m_x { };`. +- **Скобки тела** функций, классов, структур, неймспейсов, юнионов — + **на новой строке**: + +```cpp +namespace MyNamespace +{ + struct MyString + { + void doSomething() + { + } + }; +} +``` + +- Лямбды — скобка на той же строке или на новой, обе формы допустимы; + однострочная лямбда — пробелы внутри скобок: `auto f = []() { return 2 + 2; };` +- Обращение к неймспейсам/статике — без пробелов вокруг `::`: + `Core::Internal::doSomethingOther();` + +--- + +## Порядок членов структуры + +Публичные члены — **сверху**, приватные — **внизу**. Внутри каждого блока: + +1. Вложенные типы (под-структуры, enum'ы). +2. Переменные, using'и, typedef'ы. +3. Функции. + +```cpp +struct MyStruct +{ + struct MySubStruct { }; + + using type = float; + static constexpr int my_constexpr_var = 4; + float m_myVar = 3.14f; + + void doSomething(); + +private: + float m_myInternalVariable = 9.8f; + + void doSomethingInternal(); +}; +``` + +--- + +## Инклуды + +- Сторонние библиотеки — треугольные скобки: `#include `. +- Файлы текущего проекта — кавычки: `#include "MyProject/Test.h"`. + +В движке встречаются оба стиля для SGCore-заголовков (`"SGCore/..."` внутри +ядра, `` из внешних потребителей вроде плагинов) — это соответствует +правилу: для плагина SGCore — сторонний проект. + +--- + +## Практики + +1. **Не использовать `using namespace`.** +2. **Смарт-поинтеры** — при разделяемом владении или когда нужен RAII; + следить за циклическими ссылками (`weak_ptr` для обратных связей). +3. **Избегать итерации по map'ам** (`std::map`, `std::unordered_map` и любым + другим) — это правило конвенции; горячие пути строить на векторах/пулах + (в ECS данные и так лежат в пулах EnTT). +4. Стандарт — **C++23** (`CMAKE_CXX_STANDARD 23`, REQUIRED): корутины, + концепты и прочие возможности стандарта использовать можно, ломать сборку + более старым стилем «на всякий случай» не нужно. + +--- + +## Как это ложится на Sungear Engine + +Раздел для проектной специфики — дополняется по мере разбора граблей. + +- **Ядро — разделяемая библиотека.** Публичные классы SGCore экспортируются + через макросы из `Sources/sgcore_export.h`; новый публичный класс ядра без + экспорта не будет виден из SGEntry/плагинов на Windows. +- **Платформенные ветки** — только через макросы вида `SG_PLATFORM_OS_WINDOWS` + (в коде) и `SG_TARGET_OS_*` (в CMake, из `cmake/platform.cmake`). +- **Debug-код** — под `SUNGEAR_DEBUG` (определяется при `CMAKE_BUILD_TYPE=Debug`). +- **Не удалять дефайны-костыли** из корневого `CMakeLists.txt` (`NOGDI`, + `NOMINMAX`, `WIN32_LEAN_AND_MEAN`): они закрывают конфликт WinAPI-макросов + с ANTLR4 (`ParseTreeType::ERROR`) и `std::min/max`. +- **Инициализация членов** — фигурными скобками с пробелами: `float m_x { };` + (см. примеры в конвенции); не оставлять члены неинициализированными. +- **Компоненты ECS** — данные без тяжёлой логики; логика — в системах, + обходящих `Registry`. Визиторы компонентов — `SGCore/ECS/Visitors.h`. +- Новые файлы кладутся в модуль по подсистеме (`Sources/SGCore//`); + список модулей и их назначение — в + [`docs/PROJECT_STRUCTURE.md`](../../../docs/PROJECT_STRUCTURE.md#ядро-движка-sgcore). diff --git a/docs/DEV_RULES.md b/docs/DEV_RULES.md new file mode 100644 index 00000000..b7610e46 --- /dev/null +++ b/docs/DEV_RULES.md @@ -0,0 +1,276 @@ +# 🛠️ DEV_RULES — Правила разработки проекта + +## 📋 Оглавление + +1. [Общие правила](#общие-правила) +2. [Роли ИИ](#роли-ии) +3. [Стандарты кода C++](#стандарты-кода-c) +4. [Правила CMake и зависимостей](#правила-cmake-и-зависимостей) +5. [Ресурсы и шейдеры](#ресурсы-и-шейдеры) +6. [Тестирование](#тестирование) +7. [Git и CI](#git-и-ci) + +--- + +## 📜 Общие правила + +### Принципы разработки + +| Принцип | Описание | Применение | +|---------|----------|------------| +| **DRY** | Don't Repeat Yourself | Избегай дублирования кода | +| **KISS** | Keep It Simple, Stupid | Простые решения лучше сложных | +| **YAGNI** | You Ain't Gonna Need It | Не добавляй функционал «на будущее» | +| **Data-oriented** | ECS-мышление | Данные в компонентах, логика в системах; не тащить ООП-иерархии туда, где хватает компонента | +| **Convention over Configuration** | Следование конвенциям | [CodingConvention.md](../CodingConvention.md) обязателен для всех проектов Pixelfield | + +### 🔄 Инициатива по улучшению документации + +**Важное правило**: если ИИ в процессе работы считает, что для качества +выполнения задачи необходимо: +- Изменить существующие документы (USER_RULES, DEV_RULES, PROJECT_STRUCTURE, SYSTEM_DESIGN, IMPLEMENTATION_PLAN, INSTALL) +- Создать новые документы или разделы +- Удалить устаревшую информацию +- Исправить противоречия в документации + +**Тогда ИИ должен:** +1. ⚠️ **Явно предложить** пользователю эти изменения в конце ответа +2. 📝 **Кратко обосновать** необходимость изменений +3. 🔗 **Указать конкретный документ** и раздел, который требует изменений +4. ✍️ **Предложить формулировку** для добавления/изменения + +**Пример формата предложения:** + +``` +--- +💡 ПРЕДЛОЖЕНИЕ ПО УЛУЧШЕНИЮ ДОКУМЕНТАЦИИ: + +📄 Документ: SYSTEM_DESIGN.md +📍 Раздел: Рендер +⚠️ Проблема: Описание PBR-пайплайна разошлось с кодом после рефакторинга RenderPipelinesManager +✅ Предложение: Обновить раздел по фактическому составу Render/PBRRP + +Хотите, чтобы я внёс эти изменения? +``` + +### Структура коммитов + +``` +(): + + + +