From decf49084d78e2a50c95aa77c24c80e326a30f79 Mon Sep 17 00:00:00 2001 From: Emil <65846814+emil28092005@users.noreply.github.com> Date: Fri, 18 Sep 2026 02:31:04 +0300 Subject: [PATCH] Use English README and define engine language and Vulkan boundary --- PLAN.md | 6 +++-- README.md | 56 ++++++++++++++++++++++++-------------------- docs/ARCHITECTURE.md | 7 +++++- docs/README.md | 2 ++ 4 files changed, 43 insertions(+), 28 deletions(-) diff --git a/PLAN.md b/PLAN.md index 696a5b7..8f159f2 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,6 +1,6 @@ # План разработки Faset Engine -Версия 1.0 · 18 сентября 2026 года. +Версия 1.1 · 18 сентября 2026 года. **Статус:** базовая архитектура принята; реализация движка и MVP ещё не началась. Выполнены исследование исходников, выбор архитектуры и создание карты документации. Все пункты реализации ниже открыты. Этот документ определяет порядок работ; контракты подсистем находятся в [ARCHITECTURE.md](docs/ARCHITECTURE.md). @@ -15,6 +15,7 @@ MVP — редактор и runtime, на которых можно заверш - MCP обслуживает только редактор и его сервисы авторинга, импорта и сборки. Play/Stop и логи — функции редактора; API чтения или изменения игрового мира через MCP не создаётся. Player и экспорт не содержат MCP. - C++ gameplay входит в MVP. Lua — обязательный следующий этап, но не условие MVP и не обязательная зависимость каждой игры. - Собственный retained-mode UI редактора имеет основную тёмную тему; Dear ImGui остаётся отладочным инструментом. +- Основной язык интерфейса редактора, встроенных команд, диагностик, публичного API и описаний CLI/MCP tools — английский. Пользовательский текст и проекты поддерживают Unicode; локализация редактора следует после MVP. - Базовый renderer требует Vulkan 1.3 и явно проверяемый набор возможностей; аппаратный RT, mesh shaders и виртуализированная геометрия не обязательны. - Blender используется без модификации исходников. Обычный импорт GLB работает без дополнения; дополнение обеспечивает удобный экспорт и устойчивые IDs. - Gameplay статически линкуется с Player в development и release. Изменение C++ требует stop/build/restart; сохранение состояния при горячей замене C++ не входит в MVP. @@ -68,7 +69,7 @@ Lua, C++ hot reload, Blender live link, встроенное изображен **Зависит от:** M0; загрузка сцены подключается к M1. - [ ] Подключить SDL3 через Faset Platform: окно, ввод, текст, DPI и Vulkan surface. -- [ ] Реализовать Vulkan 1.3 backend с проверкой features/limits/formats, ресурсами, синхронизацией и освобождением после завершения GPU. +- [ ] Реализовать Vulkan 1.3 backend с прямыми вызовами Vulkan API, проверкой features/limits/formats, ресурсами, синхронизацией и освобождением после завершения GPU; изолировать Vulkan handles и команды от gameplay и редакторских API. - [ ] Создать Render Graph на одной graphics queue с явными чтениями/записями и barriers; подключить validation и метки проходов. - [ ] Компилировать Slang в SPIR-V с закреплёнными layout/binding conventions; выгружать reflection в собственный формат. Проверить совместимый HLSL-пример. - [ ] Получить спрайты, прозрачность и слои для 2D; static meshes, текстуры, базовый PBR, свет и обычную shadow map для 3D. @@ -100,6 +101,7 @@ Lua, C++ hot reload, Blender live link, встроенное изображен - [ ] Подключить шрифты/shaping по выбору M0; проверить кириллицу, выделение/редактирование текста, clipboard, IME и разный DPI. - [ ] Разделить C++-поведение, декларативную компоновку и стили с тёмной темой; поддержать программное создание Inspector. - [ ] Реализовать кнопки, текстовые/числовые поля, списки/дерево, выбор ресурса, вкладки, панели и разделители. +- [ ] Оформить встроенные подписи, команды, подсказки и сообщения на английском; проверить, что Unicode-текст проекта отображается и редактируется независимо от языка интерфейса. - [ ] Добавить минимальный docking в одном окне и сохранение раскладки; дополнительные системные окна редактора отложить. - [ ] Перезагружать layout/styles с проверкой и сохранением рабочего состояния; ImGui использовать для диагностики. diff --git a/README.md b/README.md index cbec430..1287bd7 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,40 @@ # Faset Engine -Faset — проект независимого движка для десктопных 2D- и 3D-игр под **Linux и Windows**. В центре — удобный собственный редактор, его управление через MCP, работа с Blender и развитие современных графических технологий. +Faset is an independent engine project for desktop **2D and 3D games on Linux and Windows**. Its priorities are a custom editor that is comfortable to use by hand and through MCP, integration with Blender, and a path toward advanced graphics. -**Текущий статус: базовая архитектура согласована; реализация движка ещё не начата.** Здесь находятся принятые решения, план, исследования других движков и работающая браузерная карта документации. Наличие технологии в плане не означает, что она реализована или измерена. +**Current status: the core architecture is agreed; engine implementation has not started.** This repository contains the architecture decisions, development plan, source studies, and a working browser-based documentation map. A technology appearing in the plan does not mean it has been implemented or benchmarked. -## Начать здесь +## Start here -- [PLAN.md](PLAN.md) — этапы до MVP, критерии готовности и развитие после него. -- [Архитектура](docs/ARCHITECTURE.md) — принятые решения и границы подсистем. -- [Документация](docs/README.md) — навигация и правила актуализации. -- [Исследования](docs/studies/README.md) — Unreal Engine, Godot, Unity, Blender, ECS, графика, импорт и сборка. -- [Зависимости и независимость](docs/DEPENDENCIES.md) — библиотеки, инструменты и происхождение материалов. +- [Development plan](PLAN.md) — milestones through MVP, acceptance criteria, and development beyond MVP. +- [Architecture](docs/ARCHITECTURE.md) — accepted decisions and subsystem boundaries. +- [Documentation](docs/README.md) — navigation and maintenance rules. +- [Source studies](docs/studies/README.md) — Unreal Engine, Godot, Unity, Blender, ECS, graphics, asset import, and builds. +- [Dependencies and independence](docs/DEPENDENCIES.md) — libraries, tools, and source provenance. -## Принятый фундамент +## Language -- **C++** для ядра и первой версии gameplay. **Lua** добавляется после C++ отдельным модулем и необязателен для конкретной игры. -- Объекты, компоненты и вложенные сцены для авторинга; **EnTT** для runtime ECS. JSON, устойчивые ID и подготовленные бинарные данные для экспорта. -- Собственные **Vulkan 1.3** backend, Render Graph и renderer; **Slang** для SPIR-V и совместимого HLSL-кода. RT не требуется базовому режиму. -- **SDL3** за платформенным интерфейсом Faset; **Box2D** и **Box3D** для физики. -- Собственный retained-mode UI редактора: C++-поведение, декларативная компоновка, отдельные стили, основная тёмная тема. **Dear ImGui** — для отладки. -- **CMake + Ninja + Clang**; Windows использует clang-cl, Windows SDK и библиотеки MSVC. Первые сборки проверяются на целевой ОС. -- Отдельный **Player**, статически связанный с gameplay. Рабочий цикл C++ — остановка, инкрементальная сборка, повторный запуск. -- **MCP только в редакторе:** авторинг, ресурсы, импорт, сборка, экспорт, Play/Stop и диагностика редактора. В Player и экспортируемой игре MCP отсутствует. -- Обычный **Blender без изменения исходников**, glTF/GLB-импорт и дополнительный плагин для экспорта и устойчивых ID. +English is the primary language of the engine: editor UI, built-in commands, diagnostics, public API identifiers, and CLI/MCP tool descriptions. Project content and user-entered text support Unicode; the engine's interface language does not dictate the language of a game. -MVP заканчивается двумя небольшими 2D/3D-проектами, которые можно создать, сохранить, запустить и экспортировать под обе ОС. GPU-driven rendering, HZB, расширенные тени, temporal reconstruction и динамическая GI развиваются после базового результата. +This README is in English. The current planning documents, studies, and research map are primarily in Russian. Editor localization is a later milestone. -## Открыть карту исследований +## Accepted foundation -Нужен Node.js с npm. Из корня репозитория: +- **C++** for the core and the first gameplay implementation. **Lua** will follow as a separate module and will be optional for individual games. +- Objects, components, and nested scene templates for authoring; **EnTT** for the runtime ECS. JSON authoring data, stable IDs, and cooked binary assets for export. +- A custom **Vulkan 1.3** backend, RenderGraph, and renderer. The backend calls Vulkan directly; gameplay uses Faset APIs. **Slang** compiles shaders, including compatible HLSL, to SPIR-V. The baseline renderer does not require ray tracing. +- **SDL3** behind Faset's platform API; **Box2D** and **Box3D** for physics. +- A custom retained-mode editor UI with C++ behavior, declarative layout, separate styles, and a dark theme by default. **Dear ImGui** is reserved for debugging tools. +- **CMake + Ninja + Clang**; Windows uses clang-cl, the Windows SDK, and MSVC runtime libraries. Initial builds are tested on their target OS. +- A separate **Player** process, statically linked with gameplay. The C++ iteration cycle is stop, incrementally rebuild, and restart. +- **Editor-only MCP:** authoring, assets, import, builds, export, Play/Stop, and editor diagnostics. MCP is absent from the Player and exported games. +- Standard, **unmodified Blender**, glTF/GLB import, and an optional add-on for convenient export and stable IDs. + +MVP is complete when two small games, one 2D and one 3D, can be created, saved, played, and exported for both operating systems. GPU-driven rendering, HZB, advanced shadows, temporal reconstruction, and dynamic global illumination follow the baseline. + +## Run the research map + +Requires Node.js and npm. From the repository root: ```sh cd docs/studies/map @@ -38,10 +44,10 @@ npm run build npm start ``` -Карта доступна на [localhost:4178](http://localhost:4178). Это просмотрщик документации, а не веб-редактор Faset. Подробности — в [README карты](docs/studies/map/README.md). +Open [localhost:4178](http://localhost:4178). The map is a documentation viewer, not a web version of the Faset editor. See the [map README](docs/studies/map/README.md) for details. -## Публичное содержимое +## Repository contents -Документация, исследования, манифест источников и код карты хранятся в Git. Сторонние движки, установленные зависимости, результаты сборки и кэши в репозиторий не включены. Ссылки на изученный код закреплены на research commits; Unreal может требовать доступа Epic. +Documentation, studies, the source manifest, and the map's code are tracked in Git. Third-party engine source trees, installed dependencies, build outputs, and caches are excluded. Source links are pinned to the commits examined during research; Unreal Engine links may require access through Epic. -Состав публикации и статус лицензии собственного содержимого описаны в [публикационных заметках](docs/PUBLICATION.md). У сторонних проектов сохраняются их собственные условия. +See the [publication notes](docs/PUBLICATION.md) for publication scope and licensing status. A license for Faset's own content has not yet been selected. Third-party projects retain their own license terms. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 01af419..73777bd 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Faset Engine — архитектура -Редакция 1.0 · 18 сентября 2026 · **принятый проект, реализация ещё не начата**. +Редакция 1.1 · 18 сентября 2026 · **принятый проект, реализация ещё не начата**. Этот файл фиксирует решения пользователя. **Принято** означает выбранное направление реализации, а не существующую или проверенную возможность движка. Код Faset Engine ещё не создан, тесты и измерения движка не проводились. Этапы до MVP и после него, зависимости работ и критерии готовности находятся в [PLAN.md](../PLAN.md). @@ -10,6 +10,8 @@ **Faset Engine** предназначен для десктопных **2D- и 3D-игр под Linux и Windows**. Важны удобное ручное редактирование, полноценная работа с проектом через MCP, передовая графика, интеграция с обычным Blender и экспорт самостоятельной игры. Независимость означает собственные форматы и API на границах движка, контролируемые зависимости и отсутствие обязательных облачных сервисов; это не обещание реализации всех библиотек с нуля или отсутствия платформенных SDK. +**Основной язык движка — английский:** интерфейс редактора, встроенные команды, диагностические сообщения, идентификаторы публичного API и описания CLI/MCP tools. Пользовательский текст и содержимое проектов поддерживают Unicode; язык создаваемых игр не ограничивается английским. Локализация редактора относится к развитию после MVP. Текущие исследования и проектная документация могут оставаться на русском; публичный корневой README ведётся на английском. + **MCP существует только в Editor и его headless-сервисах.** Он работает с авторскими документами, импортом, сборкой, запуском/остановкой Play и журналами редактора. MCP не читает и не изменяет runtime world, entities, компоненты или physics state. В Player, экспортной игре и SchemaExporter нет MCP-сервера, адаптера, зависимостей или транзитивного обхода этой границы через Editor. ## 2. Принятый стек @@ -79,6 +81,8 @@ Catch-up ограничен числом ticks за проход главног Собственный Vulkan 1.3 renderer получает подготовленный snapshot, не обходит изменяемый EnTT registry с render thread. RenderGraph описывает reads/writes ресурсов, порядок проходов, barriers и lifetimes. Первым нужен проверяемый raster-путь 2D/3D без обязательных RT/mesh shaders; GPU-driven visibility и другие передовые механизмы добавляются по измеримым этапам из [плана](../PLAN.md). +**Vulkan API вызывается напрямую внутри собственного backend Faset.** Он владеет Vulkan handles, созданием GPU-ресурсов и pipelines, записью команд, синхронизацией и отправкой в очереди. Renderer и RenderGraph используют небольшой внутренний интерфейс ресурсов и команд Faset; Vulkan-типы и вызовы `vk*` не входят в gameplay API или команды редактора. SDL3 обеспечивает окно и создание Vulkan surface, но не заменяет графический backend; Slang отвечает за компиляцию шейдеров. Универсальная абстракция нескольких графических API не является задачей MVP. + Slang компилирует шейдеры в SPIR-V и выдаёт сведения для согласования CPU/GPU данных. Совместимый HLSL проходит выбранный pipeline; поддержка любого существующего HLSL-кода не обещается. Cook учитывает compiler/version, includes, defines и GPU profile. Nanite/Lumen-подобные системы остаются исследовательскими направлениями, не готовыми возможностями MVP. ## 8. Blender и ассеты — принято @@ -102,5 +106,6 @@ Development и release Player содержат runtime, выбранные иг - **17.09.2026:** выбраны имя Faset Engine, Linux/Windows desktop 2D/3D, ручная работа и MCP, интеграция с Blender, Box2D и Box3D; подготовлены исследования. - **18.09.2026:** принят порядок C++ → Lua, затем EnTT, собственный retained UI, SDL3, Vulkan 1.3/RenderGraph/Slang и CMake/Ninja/Clang. - **18.09.2026:** утверждены процессы и linkage, явная metadata registration/schema export, JSON/binary formats, вложенные шаблоны/sparse overrides, lifecycle, фиксированный tick и последовательный scheduler; граница MCP ограничена Editor/headless authoring services. +- **18.09.2026:** английский принят основным языком интерфейса, диагностик и публичного API; уточнена граница прямых Vulkan-вызовов внутри собственного backend. Реализация идёт по [PLAN.md](../PLAN.md). Последующие изменения принятых контрактов фиксируются здесь с причиной и способом проверки. diff --git a/docs/README.md b/docs/README.md index e4444ab..f7c88c4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,8 @@ C++ с последующим Lua; EnTT; Vulkan 1.3, Render Graph и Slang; SDL3 **MCP принадлежит только редактору и его сервисам.** Обычный Blender остаётся внешним инструментом; дополнительный плагин не является модификацией Blender. Сборка первой версии под каждую ОС проверяется на этой ОС. +Основной язык движка — **английский**: UI редактора, встроенные команды, диагностика, публичный API и описания CLI/MCP tools. Это не ограничивает Unicode-текст проектов и языки игр. Корневой README ведётся на английском; текущая проектная документация, исследования и карта остаются преимущественно на русском. Локализация редактора запланирована после MVP. + ## Дальнейшие изменения У изменения контракта должны быть причина, влияние на данные/API и проверяемый результат. Версии библиотек, стандарт C++, минимальные версии ОС и вспомогательные библиотеки фиксируются на M0 как реализационные параметры, а не повторный выбор архитектуры.